Document V1 public contract

Author: TDanks2000

docs/cli.md

@@ -19,6 +19,19 @@ bun run src/index.ts add --cwd <project-directory> [options]
 
 The npm package exposes `create-electrobun-stack` from the built `dist/index.mjs` file. Plain npm and npx execution require Node.js `>=20.19.0`; `bunx --bun create-electrobun-stack@latest` forces Bun to run the same bin. Use `npm install -g create-electrobun-stack` if you want the global command.
 
+## V1 Public Contract
+
+V1 supports two command shapes:
+
+- `create-electrobun-stack <project-name> [options]`
+- `create-electrobun-stack add [options]`
+
+The supported operational flags are `--dry-run`, `--yes`, `--cwd`, `--app-id`, `--install`, `--no-install`, `--git`, `--no-git`, `--list-templates`, `--version`, and `--help`.
+
+The supported stack flags are the flags listed in the Stack Options and Electrobun Feature Options tables below. New flags may be added in minor releases, but V1-compatible generators should not silently change or remove these command shapes.
+
+For V1, `minimal` is the canonical template. `standard` and `full` remain accepted aliases for compatibility and manifest identity, but they intentionally render the same file set as `minimal`.
+
 ## Commands
 
 ### Create

docs/options.md

@@ -13,6 +13,34 @@ Some categories are intentionally narrow for V1:
 - `--database sqlite` and `--orm drizzle` are the only persistence stack with generated files because they map cleanly to Bun SQLite and local desktop storage.
 - `--template standard` and `--template full` are accepted compatibility aliases for the same V1 template source as `minimal`; they are not advertised as distinct stacks until their generated output differs and has release-gate coverage.
 
+## V1 Option Depth Decisions
+
+| Category | V1 decision |
+| --- | --- |
+| Template | `minimal` is canonical; `standard` and `full` are accepted aliases only. |
+| Frontend | Fixed to React for V1. Additional renderers are post-V1 work. |
+| Router | `tanstack-router`, `react-router`, and `none` are distinct supported choices. |
+| Query | `tanstack-query` and `none` are enough for V1. |
+| Styling | Tailwind CSS and plain CSS cover framework and no-framework styling. |
+| UI | shadcn config and `none` are supported; generated components are left to the app. |
+| Auth | `app-lock` is a local UI lock, not remote auth; deeper auth is post-V1 work. |
+| Database | SQLite is the V1 persistence target because it is local and Bun-native. |
+| ORM | Drizzle is the V1 ORM option; another ORM needs clear desktop value before inclusion. |
+| DB setup | Seed data and `none` are the V1 setup choices. |
+| Settings | JSON and database-backed settings are both supported through the same typed RPC surface. |
+| Package manager | Bun, npm, pnpm, and Yarn are supported for install/run command text. |
+| Testing | Bun tests and `none` are supported; desktop E2E testing is post-V1 work. |
+| Addons | Turborepo and `none` are supported. |
+| Examples | RPC example and `none` are supported; option-specific examples are post-V1 work. |
+| API | Electrobun RPC and static/no-RPC modes are supported. |
+| App menu | Native Edit menu and `none` are supported. |
+| Build env | `dev`, `canary`, and `stable` map directly to Electrobun build flags. |
+| Build targets | `current` and `all` map directly to Electrobun build flags. |
+| Navigation | Local-only navigation rules and `none` are supported. |
+| Native utils | File dialogs and `none` are supported. More utilities are post-V1 work. |
+| Window style | Native and hidden inset titlebar modes are supported. |
+| Runtime | Fixed to Bun for V1 because Electrobun runs the native process through Bun. |
+
 ## Core App
 
 ### `--template minimal|standard|full`

docs/v1-plan.md

@@ -30,6 +30,8 @@ The release is ready when:
 
 Goal: decide what V1 promises and avoid accidental breaking changes after release.
 
+Status: completed in the repo. Evidence lives in `docs/cli.md`, `docs/options.md`, `docs/manifest.md`, `docs/add-command.md`, `src/cli.ts`, `src/prompts.ts`, and `tests/cli.test.ts`.
+
 - Freeze the V1 CLI command shape:
   - `create-electrobun-stack <project>`
   - `create-electrobun-stack add`
@@ -52,6 +54,8 @@ Exit criteria:
 
 Goal: make the stack chooser feel complete before V1 without adding new categories or padding the CLI with weak options.
 
+Status: scoped for V1. The option set includes multiple meaningful choices in the categories that are ready for V1, and intentionally narrow categories are documented in `docs/options.md`. Post-V1 option expansion is tracked in GitHub issue #3.
+
 Use these rules for the V1 option depth pass:
 
 - Add options only inside existing categories.
@@ -104,6 +108,8 @@ Exit criteria:
 
 Goal: test real generated projects, not just renderer template output.
 
+Status: implemented locally. `tests/cli.test.ts` keeps the fast parser, manifest, add-command, and template-render behavior covered. `scripts/validate-generated-projects.ts` scaffolds the representative matrix below; `bun run validate:render` runs the fast render check in CI, and `bun run validate` runs dependency install plus typecheck, lint, tests when present, and build for release validation.
+
 - Add integration tests that scaffold representative projects into temp directories.
 - For each representative project, run:
   - dependency installation with the selected package manager when practical,
@@ -133,6 +139,8 @@ Exit criteria:
 
 Goal: make npm release boring.
 
+Status: implemented locally, pending an actual workflow dry run from GitHub. `bun run pack:check` verifies package contents, and `bun run pack:smoke` packs the tarball, installs it into a temp consumer project, checks `--version`, dry-runs a scaffold, and scaffolds a real app without installing generated dependencies. The publish workflow supports GitHub releases and `workflow_dispatch` dry runs.
+
 - Confirm `npm pack --dry-run` includes only intended files.
 - Add package smoke tests against the packed tarball:
   - install the tarball into a temp project,
@@ -154,6 +162,8 @@ Exit criteria:
 
 Goal: make the first-run path clear and keep generated project docs accurate.
 
+Status: in progress, with the V1 public contract, option boundaries, manifest compatibility, generated-project lifecycle, troubleshooting notes, release checks, and changelog now represented in docs. The final pass should be repeated after RC feedback and before `1.0.0`.
+
 - Verify root README commands against the packed package.
 - Keep `docs/cli.md` aligned with `parseArgs`.
 - Keep `docs/options.md` aligned with `src/options.ts`.

src/cli.ts

@@ -99,8 +99,8 @@ const createAppIdentifier = (packageName: string): string => {
 const printTemplates = (): void => {
   logger.heading("Templates");
   logger.info("  minimal   implemented, default");
-  logger.info("  standard  implemented profile");
-  logger.info("  full      implemented profile");
+  logger.info("  standard  accepted alias for minimal in V1");
+  logger.info("  full      accepted alias for minimal in V1");
 };
 
 const printHelp = (): void => {

src/prompts.ts

@@ -21,12 +21,12 @@ const templateChoices = [
   {
     value: "standard",
     label: "Standard",
-    hint: "standard profile using the stable scaffold",
+    hint: "V1 alias for the stable minimal scaffold",
   },
   {
     value: "full",
     label: "Full",
-    hint: "full profile using the stable scaffold",
+    hint: "V1 alias for the stable minimal scaffold",
   },
 ] satisfies Array<Option<TemplateName>>;
 

tests/cli.test.ts

@@ -260,6 +260,20 @@ describe("CLI process", () => {
     expect(result.stderr).toBe("");
   });
 
+  test("--list-templates describes standard and full as V1 aliases", async () => {
+    const result = await runCliProcess(["--list-templates"]);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("minimal   implemented, default");
+    expect(result.stdout).toContain(
+      "standard  accepted alias for minimal in V1",
+    );
+    expect(result.stdout).toContain(
+      "full      accepted alias for minimal in V1",
+    );
+    expect(result.stderr).toBe("");
+  });
+
   test("--dry-run does not create the target directory", async () => {
     const root = await makeTempRoot();
     const result = await runCliProcess([
@@ -503,6 +517,49 @@ describe("final screen", () => {
 });
 
 describe("generated minimal template", () => {
+  test("records accepted template aliases while rendering the same stable source", async () => {
+    const root = await makeTempRoot();
+    const stack = { ...defaultStackOptions, testing: "none" };
+    const templates = ["minimal", "standard", "full"] as const;
+
+    for (const template of templates) {
+      await scaffoldProject({
+        appIdentifier: "dev.electrobun.sampleapp",
+        packageName: "sample-app",
+        projectName: "sample-app",
+        stack,
+        targetDirectory: join(root, template),
+        template,
+      });
+    }
+
+    const minimalHome = await readGenerated(
+      join(root, "minimal"),
+      "src/views/main/home.tsx",
+    );
+    const standardHome = await readGenerated(
+      join(root, "standard"),
+      "src/views/main/home.tsx",
+    );
+    const fullHome = await readGenerated(
+      join(root, "full"),
+      "src/views/main/home.tsx",
+    );
+    const standardManifest = await readGeneratedManifest(
+      join(root, "standard"),
+    );
+    const fullManifest = await readGeneratedManifest(join(root, "full"));
+
+    expect(standardHome).toBe(minimalHome);
+    expect(fullHome).toBe(minimalHome);
+    expect(standardManifest.template).toBe("standard");
+    expect(standardManifest.reproducibleCommand).toContain(
+      "--template standard",
+    );
+    expect(fullManifest.template).toBe("full");
+    expect(fullManifest.reproducibleCommand).toContain("--template full");
+  });
+
   test("renders Biome-clean representative projects", async () => {
     const representativeStacks = [
       { ...defaultStackOptions },