first commit

docs/api-stack/api/create-suaveplan-plugin/src/generator/generator.md

@@ -0,0 +1,69 @@
+# generator
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module turns a validated `PromptAnswers` record into either an
+in-memory list of `GeneratedFile` records (`generate`) or a tree
+materialised on disk (`scaffold`). Splitting the two lets snapshot tests
+inspect the rendered tree byte-for-byte without touching the filesystem,
+and lets the bin entrypoint stream the same tree out to disk through a
+single typed failure surface.
+
+## Features
+
+- Pure `generate(options)` returns a deterministic, ordered list of
+  files for snapshot comparison.
+- `scaffold(options)` writes the tree atomically, raising
+  `SCAFFOLD.DIRECTORY_EXISTS` when the target is non-empty (unless
+  `force` is set) and `SCAFFOLD.WRITE_FAILED` for every fs error.
+- Engine validation raises `SCAFFOLD.UNKNOWN_ENGINE` for any database
+  value outside the closed vocabulary.
+
+## Usage
+
+### Basic example
+
+```ts
+import { scaffold, answersForFixture } from "create-suaveplan-plugin";
+
+const answers = answersForFixture("isolated-sqlite-rest-only", "my-plugin");
+scaffold({ answers, targetDir: "./my-plugin" });
+```
+
+### Advanced example
+
+```ts
+import { generate, answersForFixture } from "create-suaveplan-plugin";
+
+const tree = generate({
+    answers: answersForFixture("trusted-postgres-full", "billing"),
+});
+for (const file of tree) {
+    console.log(file.path, file.content.length);
+}
+```
+
+## API Reference
+
+- `generate(options: GenerateOptions): readonly GeneratedFile[]` — pure
+  in-memory render. Validates answers first.
+- `scaffold(options: ScaffoldOptions): ScaffoldResult` — writes to disk.
+- `GeneratedFile` — `{ readonly path: string; readonly content: string }`.
+- `ScaffoldOptions` — `{ answers, targetDir, force? }`.
+- `ScaffoldResult` — `{ files: readonly string[] }` (relative paths).
+
+## Implementation Notes
+
+- `directoryIsNonEmpty` swallows ENOENT — a missing target is treated
+  as empty so the first-time path needs no special case.
+- Errors during write are wrapped in `ScaffoldError` with `cause` set
+  to the original `fs` error, so callers retain the original stack via
+  the standard `Error.cause` chain.
+- The path order returned by `generate` is stable; snapshot tests rely
+  on this when asserting tree equality.
+- Coverage is enforced at 100% by the snapshot fixtures plus the
+  explicit error-path tests in `generator.test.ts`.