Initial Commit

packages/api-stack/api/create-suaveplan-plugin/src/prompt/index.ts

@@ -0,0 +1,11 @@
+export {
+    answersForFixture,
+    PromptAnswersSchema,
+    validateAnswers,
+} from "./prompt.js";
+export type {
+    CapabilitySelection,
+    DatabaseEngine,
+    IsolationTier,
+    PromptAnswers,
+} from "./prompt.types.js";

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.

packages/api-stack/api/create-suaveplan-plugin/src/prompt/prompt.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { SCAFFOLD_CODES, ScaffoldError } from "../error-codes.js";
+import {
+    answersForFixture,
+    PromptAnswersSchema,
+    validateAnswers,
+} from "./prompt.js";
+import type { PromptAnswers } from "./prompt.types.js";
+
+const VALID: PromptAnswers = {
+    name: "my-plugin",
+    isolation: "trusted",
+    database: "postgres",
+    capabilities: {
+        rest: true,
+        graphql: false,
+        ws: false,
+        sse: false,
+        sagas: false,
+        twoPhaseCommit: false,
+        perTenantJobs: false,
+    },
+};
+
+describe("validateAnswers", () => {
+    it("accepts a valid name", { timeout: 5000 }, () => {
+        const a = validateAnswers(VALID);
+        expect(a.name).toBe("my-plugin");
+        expect(Object.isFrozen(a)).toBe(true);
+        expect(Object.isFrozen(a.capabilities)).toBe(true);
+    });
+
+    it("uppercase name raises SCAFFOLD_INVALID_NAME", { timeout: 5000 }, () => {
+        expect(() => validateAnswers({ ...VALID, name: "Foo" })).toThrowError(
+            ScaffoldError
+        );
+        try {
+            validateAnswers({ ...VALID, name: "Foo" });
+        } catch (err) {
+            expect(err).toBeInstanceOf(ScaffoldError);
+            expect((err as ScaffoldError).code).toBe(
+                SCAFFOLD_CODES.INVALID_NAME
+            );
+        }
+    });
+
+    it("rejects names starting with a dot", { timeout: 5000 }, () => {
+        expect(() => validateAnswers({ ...VALID, name: ".foo" })).toThrow();
+    });
+
+    it("rejects names starting with an underscore", { timeout: 5000 }, () => {
+        expect(() => validateAnswers({ ...VALID, name: "_foo" })).toThrow();
+    });
+
+    it("accepts scoped package names", { timeout: 5000 }, () => {
+        const a = validateAnswers({ ...VALID, name: "@scope/pkg" });
+        expect(a.name).toBe("@scope/pkg");
+    });
+
+    it("PromptAnswersSchema parses a valid answer", { timeout: 5000 }, () => {
+        const a = PromptAnswersSchema.parse(VALID);
+        expect(a.isolation).toBe("trusted");
+    });
+});
+
+describe("answersForFixture", () => {
+    it("returns full capability set for trusted+postgres+full", {
+        timeout: 5000,
+    }, () => {
+        const a = answersForFixture("trusted-postgres-full", "demo");
+        expect(a.capabilities.rest).toBe(true);
+        expect(a.capabilities.graphql).toBe(true);
+        expect(a.capabilities.twoPhaseCommit).toBe(true);
+        expect(a.database).toBe("postgres");
+    });
+
+    it("returns REST-only set for isolated+sqlite", { timeout: 5000 }, () => {
+        const a = answersForFixture("isolated-sqlite-rest-only", "demo");
+        expect(a.capabilities.rest).toBe(true);
+        expect(a.capabilities.graphql).toBe(false);
+        expect(a.database).toBe("sqlite");
+    });
+
+    it("returns REST-only set for sandboxed+none", { timeout: 5000 }, () => {
+        const a = answersForFixture("sandboxed-none-rest-only", "demo");
+        expect(a.capabilities.rest).toBe(true);
+        expect(a.database).toBe("none");
+        expect(a.isolation).toBe("sandboxed");
+    });
+});

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

@@ -0,0 +1,135 @@
+import z from "zod";
+import { SCAFFOLD_CODES, ScaffoldError } from "../error-codes.js";
+import type {
+    CapabilitySelection,
+    DatabaseEngine,
+    IsolationTier,
+    PromptAnswers,
+} from "./prompt.types.js";
+
+/**
+ * Strict npm-package-name validation.
+ *
+ * Rules (RFC 1035 + npm): all lowercase, 1-214 chars, may not start with
+ * `.` or `_`, may contain a single optional `@scope/` prefix, the body
+ * matches `[a-z0-9][a-z0-9._-]*`.
+ */
+const NAME_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+const isolationSchema: z.ZodType<IsolationTier> = z.enum([
+    "trusted",
+    "isolated",
+    "sandboxed",
+]);
+
+const databaseSchema: z.ZodType<DatabaseEngine> = z.enum([
+    "postgres",
+    "sqlite",
+    "surrealdb",
+    "none",
+]);
+
+const capabilitySchema: z.ZodType<CapabilitySelection> = z.object({
+    rest: z.boolean(),
+    graphql: z.boolean(),
+    ws: z.boolean(),
+    sse: z.boolean(),
+    sagas: z.boolean(),
+    twoPhaseCommit: z.boolean(),
+    perTenantJobs: z.boolean(),
+});
+
+export const PromptAnswersSchema: z.ZodType<PromptAnswers> = z.object({
+    name: z.string().min(1).max(214),
+    isolation: isolationSchema,
+    database: databaseSchema,
+    capabilities: capabilitySchema,
+});
+
+/**
+ * Validate and freeze a complete prompt-answer set.
+ *
+ * Throws `SCAFFOLD.INVALID_NAME` when the supplied name violates
+ * npm-package-name rules. Throws `SCAFFOLD.UNKNOWN_ENGINE` when the
+ * database engine falls outside the closed vocabulary (defensive — the
+ * Zod schema catches the same case, but we want the typed error for
+ * programmatic recovery).
+ */
+export function validateAnswers(input: PromptAnswers): PromptAnswers {
+    const parsed = PromptAnswersSchema.parse(input);
+    if (
+        !NAME_RE.test(parsed.name) ||
+        parsed.name.startsWith(".") ||
+        parsed.name.startsWith("_")
+    ) {
+        throw new ScaffoldError(
+            SCAFFOLD_CODES.INVALID_NAME,
+            `scaffold.invalid_name:${parsed.name}`
+        );
+    }
+    return Object.freeze({
+        ...parsed,
+        capabilities: Object.freeze({ ...parsed.capabilities }),
+    });
+}
+
+/**
+ * Resolve the canonical capability set for a fixture shorthand. Used
+ * primarily by tests and the snapshot fixture set, but exported because
+ * downstream tooling occasionally wants the same shorthand → answers
+ * mapping (e.g. for in-process orchestration).
+ */
+export function answersForFixture(
+    fixture:
+        | "trusted-postgres-full"
+        | "isolated-sqlite-rest-only"
+        | "sandboxed-none-rest-only",
+    name: string
+): PromptAnswers {
+    if (fixture === "trusted-postgres-full") {
+        return validateAnswers({
+            name,
+            isolation: "trusted",
+            database: "postgres",
+            capabilities: {
+                rest: true,
+                graphql: true,
+                ws: true,
+                sse: true,
+                sagas: true,
+                twoPhaseCommit: true,
+                perTenantJobs: true,
+            },
+        });
+    }
+    if (fixture === "isolated-sqlite-rest-only") {
+        return validateAnswers({
+            name,
+            isolation: "isolated",
+            database: "sqlite",
+            capabilities: {
+                rest: true,
+                graphql: false,
+                ws: false,
+                sse: false,
+                sagas: false,
+                twoPhaseCommit: false,
+                perTenantJobs: false,
+            },
+        });
+    }
+    return validateAnswers({
+        name,
+        isolation: "sandboxed",
+        database: "none",
+        capabilities: {
+            rest: true,
+            graphql: false,
+            ws: false,
+            sse: false,
+            sagas: false,
+            twoPhaseCommit: false,
+            perTenantJobs: false,
+        },
+    });
+}

packages/api-stack/api/create-suaveplan-plugin/src/prompt/prompt.types.ts

@@ -0,0 +1,28 @@
+/**
+ * Public prompt-answer surface for the create-suaveplan-plugin scaffold.
+ *
+ * Every union member is exhaustive — adding a new isolation tier or
+ * database engine is a breaking change that must propagate through the
+ * generator + template set at the same time.
+ */
+
+export type IsolationTier = "trusted" | "isolated" | "sandboxed";
+
+export type DatabaseEngine = "postgres" | "sqlite" | "surrealdb" | "none";
+
+export interface CapabilitySelection {
+    readonly rest: boolean;
+    readonly graphql: boolean;
+    readonly ws: boolean;
+    readonly sse: boolean;
+    readonly sagas: boolean;
+    readonly twoPhaseCommit: boolean;
+    readonly perTenantJobs: boolean;
+}
+
+export interface PromptAnswers {
+    readonly name: string;
+    readonly isolation: IsolationTier;
+    readonly database: DatabaseEngine;
+    readonly capabilities: CapabilitySelection;
+}