stackloom-cli 1.0.0

package/src/blueprint/schema.js

@@ -0,0 +1,78 @@
+/**
+ * Blueprint schema — the contract a Starter Template publishes so the CLI can
+ * scaffold into it without hardcoding any one architecture.
+ *
+ * A blueprint lives at `<project>/.loom/blueprint.json`. The CLI also ships a
+ * built-in default (`default.blueprint.json`) describing the MERN kit, used as
+ * a fallback when a project has no blueprint of its own.
+ */
+import { object, record, string, enumOf, arrayOf } from "./schema-kit.js";
+
+/** Schema versions this CLI build understands. Bump on breaking blueprint changes. */
+export const SUPPORTED_SCHEMA_VERSIONS = ["1.0"];
+
+const namingStyle = () => enumOf("kebab", "camel", "pascal", "snake");
+
+/**
+ * A named root directory (e.g. "backend", "frontend"). The CLI walks `detect`
+ * candidates, confirms each with `marker`, and falls back to `default`.
+ */
+const rootSchema = object({
+  detect: arrayOf(string(), { min: 1 }),
+  marker: string(),
+  default: string(),
+});
+
+/**
+ * An injection point. `strategy` describes *how* the CLI splices generated
+ * snippets in; `pattern` is the regex/literal the strategy keys off. `comment`
+ * is the literal anchor comment a template may carry so future versions can
+ * migrate from pattern-matching to explicit markers.
+ */
+const anchorSchema = object({
+  file: string(),
+  strategy: enumOf(
+    "before-line",
+    "before-match",
+    "after-last-match",
+    "array-append",
+    "marker-comment",
+  ),
+  pattern: string(),
+  comment: string().optional(),
+});
+
+const conventionsSchema = object({
+  naming: object({
+    module: namingStyle().default("kebab"),
+    component: namingStyle().default("pascal"),
+    route: namingStyle().default("kebab"),
+  }).default({}),
+  language: object({
+    detect: enumOf("typescript", "none").default("typescript"),
+    default: enumOf("javascript", "typescript").default("javascript"),
+  }).default({}),
+}).default({});
+
+export const blueprintSchema = object({
+  schemaVersion: string(),
+  architecture: object({
+    id: string(),
+    name: string(),
+    description: string().optional(),
+  }),
+  engine: object({
+    minCliVersion: string().optional(),
+  }).optional(),
+  /** Named directory roots, resolved per-project. */
+  roots: record(rootSchema),
+  conventions: conventionsSchema,
+  /** Named path templates. Tokens like `{backend}` resolve against `roots`. */
+  paths: record(string()),
+  /** Named injection points for mounting routes, nav entries, etc. */
+  anchors: record(anchorSchema).default({}),
+  /** Named recipe references (path to a recipe manifest, relative to project root). */
+  recipes: record(string()).default({}),
+  /** Named preset file locations (themes, layouts, ...). */
+  presets: record(string()).default({}),
+});

package/src/branding/__tests__/branding.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { writeFileSync, rmSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { branding, defaultBranding, loadBrandingFrom, saveBrandingTo } from "../index.js";
+
+const tmp = () =>
+  path.join(os.tmpdir(), `branding-${Math.random().toString(36).slice(2)}.json`);
+
+describe("branding", () => {
+  it("ships sensible defaults", () => {
+    expect(defaultBranding.binName).toBe("loom");
+    expect(defaultBranding.stateDirName).toBe(".loom");
+  });
+
+  it("loads the effective branding from branding.json", () => {
+    expect(branding.binName).toBe("loom");
+    expect(branding.displayName).toBe("Stackloom");
+  });
+
+  it("falls back to defaults when the file is missing", () => {
+    expect(loadBrandingFrom(tmp())).toEqual({ ...defaultBranding });
+  });
+
+  it("falls back to defaults on invalid JSON instead of throwing", () => {
+    const file = tmp();
+    writeFileSync(file, "{ not json");
+    expect(loadBrandingFrom(file)).toEqual({ ...defaultBranding });
+    rmSync(file, { force: true });
+  });
+
+  it("layers a partial file over the defaults", () => {
+    const file = tmp();
+    writeFileSync(file, JSON.stringify({ binName: "acme" }));
+    const loaded = loadBrandingFrom(file);
+    expect(loaded.binName).toBe("acme");
+    expect(loaded.stateDirName).toBe(".loom");
+    rmSync(file, { force: true });
+  });
+
+  it("round-trips through saveBrandingTo", () => {
+    const file = tmp();
+    saveBrandingTo(file, { binName: "acme", displayName: "ACME" }, defaultBranding);
+    const loaded = loadBrandingFrom(file);
+    expect(loaded.binName).toBe("acme");
+    expect(loaded.displayName).toBe("ACME");
+    rmSync(file, { force: true });
+  });
+});

package/src/branding/index.js

@@ -0,0 +1,48 @@
+/**
+ * Branding — the single source of truth for the CLI's own identity.
+ *
+ * Every place that would otherwise hardcode "loom" (the bin name, help text,
+ * output prefixes, the state-dir name) reads from here instead, so the whole
+ * tool can be rebranded by editing one JSON file or running `loom rename`.
+ *
+ * `loadBrandingFrom` / `saveBrandingTo` are pure (path-injected) so they can be
+ * tested without touching the real config.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** branding.json lives at the CLI package root (two levels up from src/branding/). */
+export const brandingPath = path.join(__dirname, "..", "..", "branding.json");
+
+/** Shipped defaults — also the fallback when branding.json is missing or invalid. */
+export const defaultBranding = Object.freeze({
+  binName: "loom",
+  displayName: "Stackloom",
+  description: "Stackloom — weave production-ready full-stack apps from a single command",
+  tagline: "Weave full-stack apps from a single command",
+  stateDirName: ".loom",
+  packageName: "stackloom",
+});
+
+/** Load branding from a file, layered over the shipped defaults. Never throws. */
+export function loadBrandingFrom(file) {
+  if (!existsSync(file)) return { ...defaultBranding };
+  try {
+    return { ...defaultBranding, ...JSON.parse(readFileSync(file, "utf-8")) };
+  } catch {
+    return { ...defaultBranding };
+  }
+}
+
+/** Persist branding updates to a file, layered over `base`. Returns the written object. */
+export function saveBrandingTo(file, updates, base = defaultBranding) {
+  const next = { ...base, ...updates };
+  writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+  return next;
+}
+
+/** The effective branding for this CLI install. */
+export const branding = loadBrandingFrom(brandingPath);

package/src/commands/__tests__/commands.test.js

@@ -0,0 +1,83 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { Reporter } from "../../services/index.js";
+import check from "../check.js";
+import env, { parseEnvKeys } from "../env.js";
+
+const tmp = (label) =>
+  path.join(os.tmpdir(), `${label}-${Math.random().toString(36).slice(2)}`);
+// A Reporter that swallows output — commands stay silent under test.
+const silent = () =>
+  new Reporter({ stdout: { write() {}, isTTY: false }, stderr: { write() {} }, env: {} });
+
+// Commands legitimately set process.exitCode to signal CI failures; reset between tests.
+afterEach(() => {
+  process.exitCode = 0;
+});
+
+describe("loom check", () => {
+  it("passes on a well-formed project", async () => {
+    const root = tmp("chk-ok");
+    const write = (rel, content) => {
+      const abs = path.join(root, rel);
+      mkdirSync(path.dirname(abs), { recursive: true });
+      writeFileSync(abs, content);
+    };
+    write("backend/package.json", "{}");
+    write("backend/src/routes/index.js", "module.exports = router;\n");
+    write("frontend/src/main.jsx", "");
+    write("frontend/src/routes/AppRouter.jsx", 'const X = lazy(() => 0);\n<Route path="*" />\n');
+    write("frontend/src/config/app-preset.js", "const p = { navigation: [] };\n");
+
+    const result = await check({ projectRoot: root, reporter: silent() });
+    expect(result.ok).toBe(true);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("fails when a blueprint anchor file is missing", async () => {
+    const root = tmp("chk-bad");
+    mkdirSync(path.join(root, "backend"), { recursive: true });
+    writeFileSync(path.join(root, "backend", "package.json"), "{}");
+    const result = await check({ projectRoot: root, reporter: silent() });
+    expect(result.ok).toBe(false);
+    expect(result.checks.some((c) => c.name.startsWith("anchor:") && !c.ok)).toBe(true);
+    rmSync(root, { recursive: true, force: true });
+  });
+});
+
+describe("loom env", () => {
+  it("parseEnvKeys ignores comments and blank lines", () => {
+    expect(parseEnvKeys("# c\n\nPORT=3000\nDB_URL=mongodb://x\n  \n")).toEqual(["PORT", "DB_URL"]);
+  });
+
+  it("reports missing keys and appends them with --sync", async () => {
+    const root = tmp("env-sync");
+    mkdirSync(root, { recursive: true });
+    writeFileSync(path.join(root, ".env.example"), "PORT=3000\nDB_URL=\nJWT_SECRET=\n");
+    writeFileSync(path.join(root, ".env"), "PORT=4000\n");
+
+    const before = await env({ projectRoot: root, reporter: silent() });
+    expect(before.missing).toEqual(["DB_URL", "JWT_SECRET"]);
+    expect(before.synced).toBe(false);
+
+    const after = await env({ projectRoot: root, sync: true, reporter: silent() });
+    expect(after.synced).toBe(true);
+    const envText = readFileSync(path.join(root, ".env"), "utf-8");
+    expect(envText).toMatch(/DB_URL=/);
+    expect(envText).toMatch(/JWT_SECRET=/);
+
+    const final = await env({ projectRoot: root, reporter: silent() });
+    expect(final.missing).toEqual([]);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("is a graceful no-op when there is no .env.example", async () => {
+    const root = tmp("env-none");
+    mkdirSync(root, { recursive: true });
+    const result = await env({ projectRoot: root, reporter: silent() });
+    expect(result.missing).toEqual([]);
+    rmSync(root, { recursive: true, force: true });
+  });
+});

package/src/commands/check.js

@@ -0,0 +1,71 @@
+/**
+ * `loom check` — project + environment health check.
+ *
+ * Verifies the things that silently break generation later: a stale Node, a
+ * malformed blueprint, or a blueprint anchor that points at a file the project
+ * no longer has. Pure (path + reporter injectable) so it is fully testable.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { blueprintLoader } from "../blueprint/index.js";
+import { reporterFromOptions } from "../services/index.js";
+
+const MIN_NODE_MAJOR = 18;
+
+/**
+ * Run the health check.
+ * @param {object} [options] - global flags (quiet/json/...) plus:
+ * @param {string} [options.projectRoot] - defaults to cwd
+ * @param {object} [options.reporter] - injected Reporter (tests)
+ * @returns {Promise<{ ok: boolean, checks: Array<{name,ok,detail}> }>}
+ */
+export default async function check(options = {}) {
+  const reporter = options.reporter ?? reporterFromOptions(options);
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const checks = [];
+  const record = (name, ok, detail) => checks.push({ name, ok, detail });
+
+  // 1. Node runtime.
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  record(
+    "node-version",
+    nodeMajor >= MIN_NODE_MAJOR,
+    `Node ${process.versions.node} (requires >= ${MIN_NODE_MAJOR})`,
+  );
+
+  // 2. Blueprint loads + validates.
+  let blueprint = null;
+  try {
+    blueprint = await blueprintLoader.load(projectRoot);
+    record("blueprint", true, blueprint.describe());
+  } catch (err) {
+    record("blueprint", false, err.message);
+  }
+
+  // 3. Anchor integrity — every declared injection point must exist.
+  if (blueprint) {
+    for (const anchorName of Object.keys(blueprint.data.anchors)) {
+      const file = blueprint.resolveAnchorFile(anchorName, projectRoot);
+      record(`anchor:${anchorName}`, existsSync(file), path.relative(projectRoot, file));
+    }
+  }
+
+  // 4. Env file present when an example exists.
+  if (existsSync(path.join(projectRoot, ".env.example"))) {
+    record("env-file", existsSync(path.join(projectRoot, ".env")), ".env (copy from .env.example)");
+  }
+
+  const failed = checks.filter((c) => !c.ok);
+  for (const c of checks) {
+    if (c.ok) reporter.info(`${c.name}: ${c.detail}`);
+    else reporter.error(`${c.name}: ${c.detail}`);
+  }
+  reporter.result({ ok: failed.length === 0, checks });
+  if (failed.length === 0) reporter.success(`All ${checks.length} checks passed`);
+  else {
+    reporter.error(`${failed.length} of ${checks.length} checks failed`);
+    process.exitCode = 1;
+  }
+  reporter.flush();
+  return { ok: failed.length === 0, checks };
+}

package/src/commands/cleanup.js

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+
+/**
+ * `loom cleanup` — prepare a generated project for handoff.
+ *
+ * The `production` preset performs a *full de-brand*: after it runs, nothing in
+ * the project reveals that it started life as the starter kit — no `.loom/`
+ * metadata, no STARTER-KIT/TODO-Customize comments, no AUTO-GENERATED marker
+ * blocks, no starter meta-docs, no bundled CLI package, generic package names.
+ *
+ * Safety: cleanup refuses to run unless the working directory looks like a
+ * project root (has both `backend/` and `frontend/`). It is destructive — it
+ * must never run against an arbitrary directory.
+ */
+import path from "path";
+import fs from "fs-extra";
+import chalk from "chalk";
+import ora from "ora";
+import inquirer from "inquirer";
+
+const CLEANUP_PRESETS = {
+  minimal: {
+    description: "Remove demo content and obvious branding",
+    actions: ["removeDemoContent", "replaceBranding", "resetPackageIdentity"],
+  },
+  production: {
+    description: "Full de-brand — no trace of the starter kit remains",
+    // removeStarterMetadata runs first so later steps never walk the bundled CLI.
+    actions: [
+      "removeStarterMetadata",
+      "removeDemoContent",
+      "stripSourceComments",
+      "replaceBranding",
+      "resetPackageIdentity",
+      "rewriteReadme",
+    ],
+  },
+  template: {
+    description: "Extract reusable parts into a .template/ archive",
+    actions: ["createTemplateArchive", "resetPackageIdentity"],
+  },
+};
+
+// Files / dirs that exist only because this is the starter kit. Relative to root.
+const STARTER_METADATA = [
+  ".loom",
+  ".fsk",
+  "packages",
+  "CHANGELOG.md",
+  "CONTRIBUTING.md",
+  "CODE_OF_CONDUCT.md",
+  "SPLIT.md",
+  "frontend/src/config/DESIGN_PRESETS.md",
+];
+
+// Branding tokens, assembled from parts so this source file never contains the
+// contiguous strings it searches for (it cannot corrupt itself if ever walked).
+const KIT = ["MERN Fullstack", "Fullstack", "MERN"]
+  .map((prefix) => [new RegExp(`${prefix} Starter Kit`, "g"), "Project"])
+  .concat([
+    [/MERN Starter/g, "Project"],
+    [new RegExp(["Starter", "Kit"].join(" "), "g"), "Project"],
+  ]);
+const BRANDING_REPLACEMENTS = [
+  ...KIT,
+  [/fullstack-starter-kit/g, "my-project"],
+  [/mern-starter-backend/g, "backend"],
+  [/mern-starter-frontend/g, "frontend"],
+  [new RegExp("@fullstack-starter\\/cli", "g"), "my-project-cli"],
+  [/\bstackloom\b/g, "my-project-cli"],
+  [/\bStackloom\b/g, "Project"],
+];
+
+// Comment lines that should never ship to a handed-off project.
+const STARTER_COMMENT_PATTERNS = [
+  /^\s*\/\/\s*STARTER-KIT:.*$/gm,
+  /^\s*\/\/\s*TODO:\s*Customize.*$/gm,
+  /^\s*\/\/\s*fsk:anchor.*$/gm,
+  /^\s*\{\/\*\s*fsk:anchor.*?\*\/\}\s*$/gm,
+  /^\s*\/\/\s*loom:anchor.*$/gm,
+  /^\s*\{\/\*\s*loom:anchor.*?\*\/\}\s*$/gm,
+];
+
+const TEXT_EXTENSIONS = new Set([
+  ".js", ".jsx", ".ts", ".tsx", ".json", ".md", ".yaml", ".yml", ".env", ".html", ".css",
+]);
+
+/** Guard: a destructive command must only run at a real project root. */
+async function assertProjectRoot(projectRoot) {
+  const hasBackend = await fs.pathExists(path.join(projectRoot, "backend"));
+  const hasFrontend = await fs.pathExists(path.join(projectRoot, "frontend"));
+  if (!hasBackend || !hasFrontend) {
+    console.log(
+      chalk.red(
+        `✖ cleanup must run from a project root (with backend/ and frontend/).\n  Current directory: ${projectRoot}`,
+      ),
+    );
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+export default async function cleanupCmd(preset) {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+
+  if (!(await assertProjectRoot(projectRoot))) return;
+
+  if (!preset || !CLEANUP_PRESETS[preset]) {
+    const answers = await inquirer.prompt([
+      {
+        type: "list",
+        name: "preset",
+        message: "Select cleanup mode:",
+        choices: Object.entries(CLEANUP_PRESETS).map(([key, val]) => ({
+          name: `${key} — ${val.description}`,
+          value: key,
+        })),
+      },
+    ]);
+    preset = answers.preset;
+  }
+
+  const config = CLEANUP_PRESETS[preset];
+  if (!config) {
+    console.log(
+      chalk.red(
+        `✖ Unknown cleanup preset: "${preset}". Use one of: ${Object.keys(CLEANUP_PRESETS).join(", ")}`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (preset === "production") {
+    const { confirm } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "confirm",
+        message:
+          "Production cleanup permanently removes .loom/, the bundled CLI, and starter docs. Continue?",
+        default: false,
+      },
+    ]);
+    if (!confirm) {
+      console.log(chalk.gray("✖ cancelled."));
+      return;
+    }
+  }
+
+  spinner.start(`Running ${preset} cleanup...`);
+  let processed = 0;
+  for (const action of config.actions) {
+    processed += await runCleanupAction(projectRoot, action, spinner);
+  }
+  spinner.succeed(`Cleanup complete — ${processed} item(s) processed`);
+  console.log(chalk.green("\n✓ Project cleaned successfully"));
+  printNextSteps(preset);
+}
+
+async function runCleanupAction(projectRoot, action, spinner) {
+  const actions = {
+    removeDemoContent,
+    replaceBranding,
+    resetPackageIdentity,
+    removeStarterMetadata,
+    stripSourceComments,
+    rewriteReadme,
+    createTemplateArchive,
+  };
+  const fn = actions[action];
+  if (!fn) return 0;
+  spinner.text = `Running ${action}...`;
+  return fn(projectRoot);
+}
+
+/** Recursively collect files matching a predicate, skipping node_modules / .git. */
+async function findFiles(dir, predicate) {
+  const results = [];
+  if (!(await fs.pathExists(dir))) return results;
+  for (const entry of await fs.readdir(dir)) {
+    if (entry === "node_modules" || entry === ".git") continue;
+    const full = path.join(dir, entry);
+    const stat = await fs.stat(full);
+    if (stat.isDirectory()) results.push(...(await findFiles(full, predicate)));
+    else if (predicate(full)) results.push(full);
+  }
+  return results;
+}
+
+/** Remove demo pages, example components, and the demo `products` module. */
+async function removeDemoContent(projectRoot) {
+  const targets = [
+    "frontend/src/pages/demo",
+    "frontend/src/pages/examples",
+    "frontend/src/components/demo",
+    "backend/src/modules/products",
+    "frontend/src/api/products.api.js",
+  ];
+  let count = 0;
+  for (const rel of targets) {
+    const full = path.join(projectRoot, rel);
+    if (await fs.pathExists(full)) {
+      await fs.remove(full);
+      count++;
+    }
+  }
+  return count;
+}
+
+/** Replace every starter-kit branding string across all text files. */
+async function replaceBranding(projectRoot) {
+  const files = await findFiles(projectRoot, (f) => TEXT_EXTENSIONS.has(path.extname(f)));
+  let count = 0;
+  for (const file of files) {
+    let content = await fs.readFile(file, "utf-8");
+    const original = content;
+    for (const [pattern, replacement] of BRANDING_REPLACEMENTS) {
+      content = content.replace(pattern, replacement);
+    }
+    if (content !== original) {
+      await fs.writeFile(file, content);
+      count++;
+    }
+  }
+  return count;
+}
+
+/** Reset package.json `name` fields (and remove descriptions) to generic values. */
+async function resetPackageIdentity(projectRoot) {
+  const pkgFiles = [
+    ["package.json", "my-project"],
+    ["backend/package.json", "backend"],
+    ["frontend/package.json", "frontend"],
+  ];
+  let count = 0;
+  for (const [rel, name] of pkgFiles) {
+    const full = path.join(projectRoot, rel);
+    if (!(await fs.pathExists(full))) continue;
+    const pkg = await fs.readJson(full);
+    if (pkg.name !== name || pkg.description) {
+      pkg.name = name;
+      delete pkg.description;
+      await fs.writeJson(full, pkg, { spaces: 2 });
+      count++;
+    }
+  }
+  return count;
+}
+
+/** Delete everything that only exists because this is the starter kit. */
+async function removeStarterMetadata(projectRoot) {
+  let count = 0;
+  for (const rel of STARTER_METADATA) {
+    const full = path.join(projectRoot, rel);
+    if (await fs.pathExists(full)) {
+      await fs.remove(full);
+      count++;
+    }
+  }
+  return count;
+}
+
+/** Strip STARTER-KIT / TODO-Customize / loom:anchor (legacy fsk:anchor) comments and marker blocks. */
+async function stripSourceComments(projectRoot) {
+  const roots = [path.join(projectRoot, "backend", "src"), path.join(projectRoot, "frontend", "src")];
+  let count = 0;
+  for (const root of roots) {
+    const files = await findFiles(root, (f) =>
+      [".js", ".jsx", ".ts", ".tsx"].includes(path.extname(f)),
+    );
+    for (const file of files) {
+      let content = await fs.readFile(file, "utf-8");
+      const original = content;
+      for (const pattern of STARTER_COMMENT_PATTERNS) {
+        content = content.replace(pattern, "");
+      }
+      // Remove AUTO-GENERATED marker rules/headers (keep the code between them).
+      content = content
+        .replace(/^\s*\/\/═+\s*$/gm, "")
+        .replace(/^\s*\/\/\s*AUTO-GENERATED.*$/gm, "")
+        .replace(/^\s*\/\/\s*END AUTO-GENERATED.*$/gm, "")
+        .replace(/^\s*\/\/\s*✎ CUSTOM CODE ZONE.*$/gm, "")
+        .replace(/\n{3,}/g, "\n\n");
+      if (content !== original) {
+        await fs.writeFile(file, content);
+        count++;
+      }
+    }
+  }
+  return count;
+}
+
+/** Replace the starter-kit README with a minimal project README. */
+async function rewriteReadme(projectRoot) {
+  const readmePath = path.join(projectRoot, "README.md");
+  const pkgPath = path.join(projectRoot, "package.json");
+  let name = "My Project";
+  if (await fs.pathExists(pkgPath)) {
+    const pkg = await fs.readJson(pkgPath);
+    if (pkg.name) name = pkg.name;
+  }
+  const content = `# ${name}
+
+A full-stack web application.
+
+## Getting started
+
+\`\`\`bash
+pnpm install
+pnpm dev
+\`\`\`
+
+## Structure
+
+- \`backend/\` — Express + MongoDB API
+- \`frontend/\` — React + Vite client
+`;
+  await fs.writeFile(readmePath, content);
+  return 1;
+}
+
+/** Extract reusable building blocks into a .template/ archive directory. */
+async function createTemplateArchive(projectRoot) {
+  const templateDir = path.join(projectRoot, ".template");
+  await fs.ensureDir(templateDir);
+  for (const rel of ["frontend/src/components/ui", "frontend/src/lib", "backend/src/utils"]) {
+    const src = path.join(projectRoot, rel);
+    if (await fs.pathExists(src)) {
+      await fs.copy(src, path.join(templateDir, rel), { overwrite: true });
+    }
+  }
+  return 1;
+}
+
+function printNextSteps(preset) {
+  console.log(chalk.cyan("\nNext steps:"));
+  if (preset === "template") {
+    console.log(chalk.gray("  1. Review .template/ for reusable components"));
+    console.log(chalk.gray("  2. Distribute the archive to your team"));
+  } else {
+    console.log(chalk.gray("  1. Review remaining files for any customizations"));
+    console.log(chalk.gray("  2. Run 'pnpm install' to refresh dependencies"));
+    console.log(chalk.gray("  3. Commit — the project is now fully your own"));
+  }
+}