first commit

docs/api-stack/api/create-suaveplan-plugin/README.md

@@ -0,0 +1,85 @@
+# create-suaveplan-plugin
+
+Interactive scaffold for new Suaveplan API plugins. Generates a complete,
+immediately-testable plugin skeleton — `plugin.json`, `definePlugin`
+body, host test, optional integration test wired to the matching
+`testing-integration-{postgres,sqlite,surrealdb}` fixture, both vitest
+configs, migrations, and a README — tailored to the selected isolation
+tier, capability set, and DB engine.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [bin](./src/bin/create-suaveplan-plugin.md) — This module is the executable entry-point for the `create-suaveplan-plugin` scaffolder. It parses argv into a `ParsedAr…
+  - [create-suaveplan-plugin](./src/bin/create-suaveplan-plugin.md) — This module is the executable entry-point for the `create-suaveplan-plugin` scaffolder. It parses argv into a `ParsedAr…
+- [generator](./src/generator/generator.md) — This module turns a validated `PromptAnswers` record into either an in-memory list of `GeneratedFile` records (`generat…
+  - [generator](./src/generator/generator.md) — This module turns a validated `PromptAnswers` record into either an in-memory list of `GeneratedFile` records (`generat…
+- [prompt](./src/prompt/prompt.md) — This module defines the closed prompt-answer surface for the scaffold (`PromptAnswers`, `IsolationTier`, `DatabaseEngin…
+  - [prompt](./src/prompt/prompt.md) — This module defines the closed prompt-answer surface for the scaffold (`PromptAnswers`, `IsolationTier`, `DatabaseEngin…
+- [templates](./src/templates/templates.md) — This module owns the per-file render functions that produce the scaffolded plugin tree. Every output file (manifest, so…
+  - [templates](./src/templates/templates.md) — This module owns the per-file render functions that produce the scaffolded plugin tree. Every output file (manifest, so…
+- [error-codes](./src/error-codes.md) — This module declares the frozen, namespaced registry of every failure code the `create-suaveplan-plugin` scaffold can r…
+<!-- end:auto-docs -->
+
+## Quick start
+
+```bash
+bunx create-suaveplan-plugin my-plugin --fixture trusted-postgres-full
+cd my-plugin
+bun test
+```
+
+Three fixtures cover the canonical permutations:
+
+| Fixture | Isolation | Database | Capabilities |
+| --- | --- | --- | --- |
+| `trusted-postgres-full` | `trusted` | `postgres` | rest, graphql, ws, sse, sagas, twoPhaseCommit, perTenantJobs |
+| `isolated-sqlite-rest-only` | `isolated` | `sqlite` | rest |
+| `sandboxed-none-rest-only` | `sandboxed` | `none` | rest |
+
+## CLI flags
+
+- `<name>` — positional plugin name (validated against npm rules).
+- `--fixture <id>` — one of the three fixtures above (default
+  `sandboxed-none-rest-only`).
+- `--dir <path>` — explicit target directory (default `<cwd>/<name>`).
+- `--force` — overwrite an existing non-empty target.
+
+## Programmatic API
+
+```ts
+import { scaffold, answersForFixture } from "create-suaveplan-plugin";
+
+scaffold({
+    answers: answersForFixture("isolated-sqlite-rest-only", "billing-plugin"),
+    targetDir: "./billing-plugin",
+    force: false,
+});
+```
+
+## Error codes
+
+The scaffold raises only typed `ScaffoldError`s. Every code is namespaced
+as `SCAFFOLD.*`:
+
+- `SCAFFOLD.INVALID_NAME` — name violates npm-package-name rules.
+- `SCAFFOLD.DIRECTORY_EXISTS` — target is non-empty and `--force` was not given.
+- `SCAFFOLD.WRITE_FAILED` — fs write failed; original error attached via `cause`.
+- `SCAFFOLD.UNKNOWN_ENGINE` — engine outside the closed vocabulary.
+
+## Verification
+
+The package ships three verification surfaces:
+
+1. **Unit tests** — every render branch, every prompt validation case.
+2. **Snapshot tests** — byte-for-byte against the committed
+   `tests/scaffold-output/snapshots/<fixture>/**` trees.
+3. **Scaffold-and-run** — for each fixture, scaffold to a temp dir and
+   run `bun test` against it. Exit code must be 0.
+
+Run the full gate via:
+
+```bash
+bunx --bun turbo lint typecheck test:coverage --filter=create-suaveplan-plugin
+```
+