diff --git a/docs/generator-access.md b/docs/generator-access.md index b3ac3e5..0f1d3c2 100644 --- a/docs/generator-access.md +++ b/docs/generator-access.md @@ -84,9 +84,11 @@ Create a fine-grained PAT as described in Option C above, then: ```bash export SPECFUSE_TOKEN=github_pat_xxx -specfuse authoring generate +specfuse authoring generate generate --group "" -project.json ``` +Everything after `specfuse authoring generate` goes to the generator unchanged, so name the generator's own command (`generate`, `validate`, `baseline`, …) first. Its `--group` takes one group per run. + In CI, store it as a secret and export it for the generate step only. ### What happens on first run diff --git a/docs/getting-started.md b/docs/getting-started.md index e248ca1..c85d1a1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -107,9 +107,11 @@ Inside Claude Code, the kit's skills validate your specs against the handbook ru The generator turns your validated specs into backend, frontend, and worker artifacts: ```bash -specfuse authoring generate +specfuse authoring generate generate --group "" -project.json ``` +Everything after `specfuse authoring generate` goes to the generator unchanged, so name the generator's own command (`generate`, `validate`, `baseline`, …) first. Its `--group` takes one group per run. + On first run the CLI resolves the generator pinned for your kit version (see [`generator.lock`](../generator.lock)), downloads it, **verifies its SHA-256**, caches it under `~/.specfuse/jars/`, and runs it. Subsequent runs use the cache. ## 6. Generator access (token setup) diff --git a/plugins/specfuse-authoring/skills/generate/SKILL.md b/plugins/specfuse-authoring/skills/generate/SKILL.md index 224267c..cfdda36 100644 --- a/plugins/specfuse-authoring/skills/generate/SKILL.md +++ b/plugins/specfuse-authoring/skills/generate/SKILL.md @@ -1,6 +1,6 @@ --- name: generate -description: "Generate frontend (Flutter) and backend (C#) code, workers, and Markdown documentation artifacts from the API specifications. Use when you want to produce generated code and docs from validated specs; runs the project generate scripts and reports each step's outcome." +description: "Generate code and Markdown documentation from the API specifications for the artifact groups the project file declares (any language — C#, Python, Dart, TypeScript, Markdown). Use when you want to produce generated code and docs from validated specs; bundles the specs, runs the pinned generator once per selected group, and reports each group's outcome." --- -Generate frontend and backend code artifacts from the API specifications. +Generate code and documentation artifacts from the API specifications, one artifact group at a time. *Enforces: (general — no single handbook)* @@ -20,13 +20,21 @@ Generate frontend and backend code artifacts from the API specifications. ## Steps -Artifact groups are declared in the project config; generate the ones the project defines. `specfuse authoring generate` passes its arguments through to the generator. - -1. **Generate backend (C#)** — Run `specfuse authoring generate --group "" -project.json` -2. **Generate frontend (Flutter)** — Run `specfuse authoring generate --group "" -project.json` -3. **Generate workers (C#)** — If `asyncSpecifications` is defined in the project config, run `specfuse authoring generate --group "" -project.json` -4. **Generate documentation (Markdown)** — Run `./scripts/specfuse/generate-scenario-docs.sh`. It bundles the specs, then calls the CLI for both markdown artifact groups defined in the project config: +Artifact groups are declared in the project config's `groups` array; generate the ones the project defines, never a fixed set. + +1. **List the groups.** Read `groups[]` from `-project.json` and show each group's `name`, `language`, `destination`, and whether it sets `cleanGenerated`. If the user named groups, select those; otherwise ask which to generate. Treat "all" as an explicit opt-in, never the default. +2. **Check the destinations before writing.** A `destination` outside the project (for example `../Backend/`) writes into another repo, and `cleanGenerated: true` deletes that group's generated tree before rewriting it. For each such destination, confirm the target repo has no uncommitted changes and is on a branch the user expects to receive the regen. Stop and ask if not. +3. **Bundle the specs** (the project file reads the bundled output): + - `./scripts/specfuse/bundle-spec.sh api/specs/v1/openapi.yaml output/openapi-bundled.yaml` + - If `asyncSpecifications` is set: `./scripts/specfuse/bundle-async-spec.sh api/specs/v1/asyncapi.yaml output/asyncapi-bundled.yaml` +4. **Generate each selected code group**, one invocation per group (the generator's `--group` takes a single name), from the project root: + ```bash + specfuse authoring generate generate --progress --group "" -project.json + ``` + The word `generate` appears twice on purpose: `specfuse authoring generate` launches the pinned generator and passes everything after it through verbatim, so the generator's own `generate` command must follow. Without it the generator prints `Unknown option: --group` and its usage text, and generates nothing. +5. **Run language post-steps** for groups that need them. Dart: the generator writes `part '*.g.dart'` / `part '*.freezed.dart'` directives but does not run `source_gen`, so run `dart pub get && dart run build_runner build --delete-conflicting-outputs` in the generated package before analysing it. +6. **Generate documentation (Markdown)** — if a Markdown group is selected, run `./scripts/specfuse/generate-scenario-docs.sh` instead of step 4 for it. It bundles the specs, then generates the two Markdown groups the scaffold defines, then adds cross-links and the index: - `Documentation - Scenarios` → `scenarioDocument`, `scenarioIndex` (output: `./api/docs`) - `Documentation - Technical References` → `recipeDocumentation`, `entityDiagram`, `eventCatalog`, `channelTopology`, `docsIndex` (output: `./docs/generated`) -Report the outcome of each step. If generation fails, analyze the error output and suggest fixes. +Report the outcome of each group: generator exit code `0` is success, `3` is a generation failure with a structured error, `1`/`2` are validation or system errors. If generation fails, analyze the error output and suggest fixes. For each group written into another repo, name the repo and remind the user that the regen is reviewed and merged there before `.specfuse/state` baselines are advanced.