first commit

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

@@ -0,0 +1,81 @@
+# templates
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module owns the per-file render functions that produce the
+scaffolded plugin tree. Every output file (manifest, source, tests,
+configs, migrations, README, package.json, tsconfig, .gitignore) lives
+here as a typed string-producer keyed off the validated `PromptAnswers`.
+Keeping the templates in TypeScript (not as opaque `.tmpl` files) means
+the type system can refuse a render that references a capability the
+prompt vocabulary doesn't know about.
+
+## Features
+
+- One `renderTree(answers)` entrypoint returning the ordered file list.
+- Per-capability handler stubs in `src/index.ts.tmpl` so generated test
+  files compile against real handler exports on first run.
+- Conditional emission of integration test + integration vitest config
+  + migrations when a DB engine other than `none` is selected.
+- Generated `vitest.config.ts` always wires `@suaveplan/testing/config`
+  (the `createTestConfig` factory, never `baseVitestConfig`+`mergeConfig`).
+
+## Usage
+
+### Basic example
+
+```ts
+import { renderTree, answersForFixture } from "create-suaveplan-plugin";
+
+const files = renderTree(
+    answersForFixture("sandboxed-none-rest-only", "demo"),
+);
+for (const f of files) console.log(f.path);
+```
+
+### Advanced example
+
+```ts
+import { renderTree, validateAnswers } from "create-suaveplan-plugin";
+
+const files = renderTree(
+    validateAnswers({
+        name: "billing",
+        isolation: "trusted",
+        database: "postgres",
+        capabilities: {
+            rest: true,
+            graphql: true,
+            ws: true,
+            sse: true,
+            sagas: true,
+            twoPhaseCommit: true,
+            perTenantJobs: true,
+        },
+    }),
+);
+const migration = files.find((f) =>
+    f.path === "migrations/postgres/0001-init.sql",
+);
+```
+
+## API Reference
+
+- `renderTree(answers: PromptAnswers): readonly GeneratedFile[]` —
+  deterministic, ordered file list.
+
+## Implementation Notes
+
+- Path order is stable, which the snapshot tests depend on; do not
+  reorder file emission when adding new templates.
+- Every emitted file ends with a trailing newline so they round-trip
+  through editors that auto-append one.
+- The generated `package.json` declares no external runtime deps so
+  `bun test` against the produced tree works without `bun install`
+  resolving anything.
+- Integration tests use `vitest` rather than `bun:test` since real
+  testcontainer fixtures are vitest-native.