559db303e1
Schema revisions per user review 2026-04-22 (all 6 open questions resolved — see §Decision log in SUBSTRATE-SCHEMA.md): - #3 side_effects: string tags → structured { op, domain } objects (user: "лучше сразу с запасом") - #4 capabilities.toml: DROPPED entirely (user: "почему не мд?"). SSoT is atoms/*.md. Crate-level metadata moves to Cargo.toml [package.metadata.keisei] — Cargo-native, no drift, no build.rs, no generated files to commit. kei-sage + kei-runtime walk atoms/*.md directly. - #5 atom template: shipped in this PR (user: "ui же параллельно! создавай все!") so Streams B/C/D can scaffold atoms from day 0 without waiting for Stream A (kei-forge UI). - #1/#2/#6 confirmed as drafted (draft-07, `::` separator, per-atom errors). New files: - _templates/atom/ — 5-file template set with placeholder substitution (__CRATE__, __VERB__, __KIND__, __DESCRIPTION__ etc). Covers atoms/<verb>.md, schemas/<verb>-{input,output}.json, src/atoms/<verb>.rs, tests/<verb>_smoke.rs. Each file is a minimal working skeleton. - scripts/new-atom.sh — POSIX bash generator (bash for $'\n' / readonly / trap). Validates verb is lowercase kebab-case, kind is one of command|query|stream|transform. Refuses to overwrite existing files. Rolls back on any failure (trap ERR deletes all generated files so no half-scaffolded state). Tested: produces 5 files, placeholder substitution correct on smoke-test crate. Stream B (atoms refactor) updated to drop the "generates capabilities.toml via build.rs" wording — now just "writes atoms/*.md + updates Cargo.toml [package.metadata.keisei]". Stream D reads atoms/*.md + Cargo.toml, not capabilities.toml. Schema status: revisions applied, decision log complete. Ready for SCHEMA-LOCKED.md marker commit once user signs off on revised doc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
30 lines
1.3 KiB
Markdown
30 lines
1.3 KiB
Markdown
# Atom template
|
|
|
|
Used by `scripts/new-atom.sh <crate> <verb> [kind]` to scaffold a new atom. Placeholder substitution map:
|
|
|
|
| Placeholder | Example | Source |
|
|
|---|---|---|
|
|
| `__CRATE__` | `kei-task` | argv 1 (kebab-case) |
|
|
| `__CRATE_SNAKE__` | `kei_task` | argv 1 → underscores |
|
|
| `__VERB__` | `add-dependency` | argv 2 (kebab-case) |
|
|
| `__VERB_SNAKE__` | `add_dependency` | argv 2 → underscores |
|
|
| `__KIND__` | `command` | argv 3 or default `command` |
|
|
| `__DESCRIPTION__` | free-form one-liner | prompted at runtime |
|
|
|
|
Schema SSoT: [SUBSTRATE-SCHEMA.md](../../docs/SUBSTRATE-SCHEMA.md).
|
|
|
|
Template covers the 4 files a new atom always needs:
|
|
|
|
- `atoms/<verb>.md` — human doc + YAML frontmatter (machine-parsed by kei-sage + kei-runtime)
|
|
- `atoms/schemas/<verb>-input.json` — JSON Schema draft-07
|
|
- `atoms/schemas/<verb>-output.json` — JSON Schema draft-07
|
|
- `src/atoms/<verb>.rs` — Rust impl skeleton with Input/Output/Error + `pub fn run`
|
|
- `tests/<verb>_smoke.rs` — smoke test placeholder
|
|
|
|
Postconditions the generator enforces:
|
|
|
|
1. `cargo check -p <crate>` passes (skeleton compiles)
|
|
2. `kei-schema-lint <crate>` passes (frontmatter + schema paths valid)
|
|
3. New atom appears in `kei-runtime list-atoms --crate <crate>`
|
|
|
|
If any postcondition fails, the generator rolls back (deletes the generated files) so there is no half-scaffolded state.
|