Initial Commit

packages/api-stack/api/create-suaveplan-plugin/src/prompt/prompt.md

@@ -0,0 +1,78 @@
+# prompt
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module defines the closed prompt-answer surface for the scaffold
+(`PromptAnswers`, `IsolationTier`, `DatabaseEngine`, `CapabilitySelection`),
+the Zod schema that validates inputs at the package boundary, and the
+helper that resolves a fixture shorthand to a full answer set. The
+prompt surface is the only public contract between any interactive
+front-end (TTY prompt, web UI, programmatic harness) and the generator.
+
+## Features
+
+- Strict npm-package-name validation (`@scope/`-aware) that runs before
+  any filesystem work happens.
+- Zod-derived `PromptAnswersSchema` for boundary validation. Every union
+  member is exhaustive — the scaffold tracks the closed vocabulary of
+  isolation tiers and database engines explicitly.
+- `answersForFixture(name, fixture)` produces a deterministic answer
+  set for each of the three snapshot fixtures.
+
+## Usage
+
+### Basic example
+
+```ts
+import { validateAnswers } from "create-suaveplan-plugin";
+
+const answers = validateAnswers({
+    name: "my-plugin",
+    isolation: "trusted",
+    database: "postgres",
+    capabilities: {
+        rest: true,
+        graphql: false,
+        ws: false,
+        sse: false,
+        sagas: false,
+        twoPhaseCommit: false,
+        perTenantJobs: false,
+    },
+});
+```
+
+### Advanced example
+
+```ts
+import { answersForFixture, scaffold } from "create-suaveplan-plugin";
+
+const answers = answersForFixture("trusted-postgres-full", "billing-plugin");
+scaffold({ answers, targetDir: "./billing-plugin", force: false });
+```
+
+## API Reference
+
+- `validateAnswers(input: PromptAnswers): PromptAnswers` — returns the
+  frozen, validated answer set. Throws `SCAFFOLD.INVALID_NAME` for any
+  name that fails the npm-package-name rules.
+- `answersForFixture(fixture, name): PromptAnswers` — shorthand
+  resolver for the three snapshot fixtures.
+- `PromptAnswersSchema: z.ZodType<PromptAnswers>` — boundary schema.
+
+## Implementation Notes
+
+- The Zod schema runs first because it produces clearer errors for
+  shape mismatches; the npm-name regex layer runs second specifically
+  to raise the typed `SCAFFOLD.INVALID_NAME` code which downstream
+  tooling branches on.
+- `Object.freeze` is applied at the answer level AND at the nested
+  `capabilities` level so neither shape can be mutated between
+  validation and template rendering.
+- The fixture shorthand is exported because the scaffold-output snapshot
+  tests rely on a deterministic answer set per fixture; consumers may
+  also use it for in-process orchestration.