create-macostack 0.6.1 → 0.6.3

package/README.md

@@ -14,6 +14,8 @@ An interactive wizard walks you through the rest:
 
 The CLI then downloads each template without its git history, installs dependencies, runs each template's own setup (app name, fresh secrets, module wiring), and leaves every part as its own independent git repository, ready to push.
 
+Finally it scaffolds the **docs system**: `AGENTS.md` (the agent orchestrator), a `docs/` folder (product, architecture, API contract, testing strategy, current plan, ADRs, and per-feature SPEC → DESIGN → TASKS templates), and matching slash commands (`/spec`, `/design`, `/tasks`, `/implement`, `/review`) for **both Claude Code and OpenCode**. The workspace root becomes its own git repo that versions the docs — `client/` and `server/` stay independent.
+
 ## Requirements
 
 - [Bun](https://bun.sh) 1.x
@@ -38,21 +40,26 @@ Result:
 
 ```txt
 my-app/
-├── server/    # Bun + Hono + Postgres API — its own git repo
-└── client/    # TanStack web app — its own git repo
+├── AGENTS.md     # how AI agents work here (Claude Code & OpenCode)
+├── CLAUDE.md     # Claude Code adapter → AGENTS.md
+├── docs/         # product, architecture, contracts, features (SPEC/DESIGN/TASKS)
+├── server/       # Bun + Hono + Postgres API — its own git repo
+└── client/       # TanStack web app — its own git repo
 ```
 
-The root folder is intentionally **not** a git repository: server and client are designed to live and deploy as separate repos.
+The root is the **workspace repo**: it versions `docs/` and the orchestration files, while `server/` and `client/` are ignored — each lives and deploys as its own separate repo.
 
 ### Managing an existing app
 
-Run the CLI again inside an app it created to add the missing part or toggle feature modules on and off — it detects the existing setup and switches to manage mode:
+Run the CLI again inside an app it created — it detects the existing setup and switches to manage mode:
 
 ```bash
 cd my-app
 bun create macostack .
 ```
 
+From there you can **start a new feature** (scaffolds `docs/features/<name>/` with SPEC, DESIGN and TASKS — then run `/spec <name>` in your agent), **update the docs system** (syncs AGENTS.md, slash commands, cheat sheet and feature templates from the template repo — your project's own docs are never touched), **add the docs system** to an app created before it existed, add a missing part, or toggle feature modules on and off.
+
 ### Flags
 
 | Flag | Description |
@@ -63,8 +70,10 @@ bun create macostack .
 | `--ref <ref>` | Branch or tag to download (default: `main`) |
 | `--server-repo <name>` | Server template repo (default: `macostack-server`) |
 | `--client-repo <name>` | Client template repo (default: `macostack-client`) |
+| `--docs-repo <name>` | Docs system repo (default: `macostack-docs`) |
 | `--skip-install` | Skip `bun install` |
 | `--skip-setup` | Skip each template's setup wizard |
+| `--skip-docs` | Skip the docs system (AGENTS.md + docs/) |
 | `--help` | Print usage |
 
 ### Environment variables
@@ -75,6 +84,7 @@ bun create macostack .
 | `MACOSTACK_GITHUB_OWNER` | Default template owner |
 | `MACOSTACK_SERVER_REPO` | Default server template repo |
 | `MACOSTACK_CLIENT_REPO` | Default client template repo |
+| `MACOSTACK_DOCS_REPO` | Default docs system repo |
 | `MACOSTACK_REF` | Default branch or tag |
 
 ## Bring your own templates

package/bin/create-macostack.ts

@@ -15,10 +15,13 @@ import {
     mkdirSync,
     mkdtempSync,
     readdirSync,
+    readFileSync,
     rmSync,
+    statSync,
+    writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 
 // create-macostack — start a new app from the macostack templates.
@@ -80,6 +83,11 @@ const PARTS: Part[] = [
     },
 ];
 
+// The docs system: AGENTS.md + docs/ + slash commands for Claude Code and
+// OpenCode. Lands at the WORKSPACE ROOT (not inside a part) and becomes its own
+// git repo — its .gitignore excludes client/ and server/.
+const DOCS_REPO = Bun.env.MACOSTACK_DOCS_REPO ?? "macostack-docs";
+
 //////////////////////////////////////////////////////////////////
 // FLAGS
 //////////////////////////////////////////////////////////////////
@@ -96,8 +104,10 @@ const parsed = parseArgs({
         ref: { type: "string" },
         "server-repo": { type: "string" },
         "client-repo": { type: "string" },
+        "docs-repo": { type: "string" },
         "skip-install": { type: "boolean", default: false },
         "skip-setup": { type: "boolean", default: false },
+        "skip-docs": { type: "boolean", default: false },
     },
 });
 const flags = parsed.values;
@@ -116,8 +126,10 @@ Flags:
   --ref <ref>           branch or tag to pull (default: ${DEFAULT_REF})
   --server-repo <name>  server template repo
   --client-repo <name>  client template repo
+  --docs-repo <name>    docs system repo (default: ${DOCS_REPO})
   --skip-install        don't run bun install
   --skip-setup          don't run each template's setup wizard
+  --skip-docs           don't scaffold the docs system (AGENTS.md + docs/)
 
 Auth (templates are private):
   export GITHUB_TOKEN=github_pat_…   or   gh auth login
@@ -155,6 +167,179 @@ const isEmptyDir = (dir: string) =>
     !existsSync(dir) ||
     readdirSync(dir).filter((e) => e !== ".DS_Store").length === 0;
 
+const ghFetch = (token: string, path: string) =>
+    fetch(`https://api.github.com${path}`, {
+        headers: {
+            Accept: "application/vnd.github+json",
+            Authorization: `Bearer ${token}`,
+            "User-Agent": "create-macostack",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+
+// Download a repo tarball (no git history) and unpack it into dest.
+// Returns an error message, or null on success.
+const downloadInto = async (
+    token: string,
+    ownerName: string,
+    repo: string,
+    refName: string,
+    dest: string,
+): Promise<string | null> => {
+    const tmp = mkdtempSync(join(tmpdir(), "create-macostack-"));
+    try {
+        const res = await ghFetch(token, `/repos/${ownerName}/${repo}/tarball/${refName}`);
+        if (!res.ok) return `GitHub refused the download (HTTP ${res.status})`;
+        const archive = join(tmp, "template.tar.gz");
+        await Bun.write(archive, await res.arrayBuffer());
+        mkdirSync(dest, { recursive: true });
+        const tar = Bun.spawnSync(
+            ["tar", "-xzf", archive, "-C", dest, "--strip-components=1"],
+            { stdout: "pipe", stderr: "pipe" },
+        );
+        if (tar.exitCode !== 0) return `couldn't unpack: ${tar.stderr.toString().slice(0, 200)}`;
+        return null;
+    } finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+};
+
+// Bring the docs system into the workspace root: AGENTS.md, docs/, and the
+// /spec /design /tasks /implement /review commands for BOTH agents. Stamps the
+// placeholders and turns the root into its own git repo (its .gitignore
+// excludes client/ and server/ — each part stays an independent repo).
+const scaffoldDocs = async (
+    token: string,
+    root: string,
+    name: string,
+    modules: string[] | null,
+): Promise<boolean> => {
+    const docsOwner = flags.owner ?? DEFAULT_OWNER;
+    const docsRef = flags.ref ?? DEFAULT_REF;
+    const docsRepo = flags["docs-repo"] ?? DOCS_REPO;
+    const s = spinner();
+    s.start(`Docs — downloading ${docsOwner}/${docsRepo}@${docsRef}`);
+    const err = await downloadInto(token, docsOwner, docsRepo, docsRef, root);
+    if (err) {
+        s.stop("Docs — download failed");
+        note(
+            `The app itself is fine — only the docs system is missing (${err}).\n` +
+                "  Add it later by running me again in this folder.",
+            "Heads up",
+        );
+        return false;
+    }
+
+    const stamp = (rel: string, replacements: Record<string, string>) => {
+        const p = resolve(root, rel);
+        if (!existsSync(p)) return;
+        let txt = readFileSync(p, "utf8");
+        for (const [k, v] of Object.entries(replacements)) txt = txt.replaceAll(k, v);
+        writeFileSync(p, txt);
+    };
+    const modulesText =
+        modules && modules.length > 0
+            ? modules.map((m) => `- ${m}`).join("\n")
+            : "Configuración por defecto del template.";
+    stamp("README.md", { "{{APP_NAME}}": name });
+    stamp("docs/PRODUCT.md", { "{{APP_NAME}}": name });
+    stamp("docs/ARCHITECTURE.md", { "{{MODULES}}": modulesText });
+
+    // The workspace root becomes its own repo: docs + orchestration, versioned.
+    if (!existsSync(resolve(root, ".git"))) {
+        Bun.spawnSync(["git", "init", "-b", "main"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+        Bun.spawnSync(["git", "add", "-A"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+        Bun.spawnSync(["git", "commit", "-m", "init: docs workspace"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    }
+    s.stop("Docs — AGENTS.md + docs/ + slash commands ready (Claude Code & OpenCode)");
+    return true;
+};
+
+// The docs-system files that a sync may replace. STRICT whitelist: process and
+// templates only — never the project's own content (PRODUCT, CURRENT_PLAN,
+// DECISIONS, ARCHITECTURE, real features), which lives outside these paths.
+const DOCS_SYNC_PATHS = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "docs/CHEATSHEET.md",
+    "docs/features/_template",
+    ".claude/commands",
+    ".opencode/commands",
+];
+
+// Bring an existing project's docs SYSTEM up to date with the template repo.
+// Downloads the repo to a temp dir and copies only DOCS_SYNC_PATHS over the
+// local files, reporting exactly what changed. Nothing is committed — the
+// workspace repo shows the diff for review.
+const updateDocs = async (token: string, root: string): Promise<void> => {
+    const docsOwner = flags.owner ?? DEFAULT_OWNER;
+    const docsRef = flags.ref ?? DEFAULT_REF;
+    const docsRepo = flags["docs-repo"] ?? DOCS_REPO;
+    const s = spinner();
+    s.start(`Docs — fetching ${docsOwner}/${docsRepo}@${docsRef}`);
+    const tmp = mkdtempSync(join(tmpdir(), "macostack-docs-sync-"));
+    try {
+        const err = await downloadInto(token, docsOwner, docsRepo, docsRef, tmp);
+        if (err) {
+            s.stop("Docs — download failed");
+            bail(err);
+        }
+        const changed: string[] = [];
+        const syncFile = (rel: string) => {
+            const src = join(tmp, rel);
+            const next = readFileSync(src, "utf8");
+            const dst = resolve(root, rel);
+            if (existsSync(dst) && readFileSync(dst, "utf8") === next) return;
+            mkdirSync(dirname(dst), { recursive: true });
+            writeFileSync(dst, next);
+            changed.push(rel);
+        };
+        const syncDir = (rel: string) => {
+            for (const e of readdirSync(join(tmp, rel), { withFileTypes: true })) {
+                const childRel = `${rel}/${e.name}`;
+                if (e.isDirectory()) syncDir(childRel);
+                else syncFile(childRel);
+            }
+        };
+        for (const p of DOCS_SYNC_PATHS) {
+            const src = join(tmp, p);
+            if (!existsSync(src)) continue;
+            if (statSync(src).isDirectory()) syncDir(p);
+            else syncFile(p);
+        }
+        s.stop(
+            changed.length === 0
+                ? "Docs — already up to date"
+                : `Docs — updated ${changed.length} file${changed.length === 1 ? "" : "s"}`,
+        );
+        if (changed.length > 0) {
+            note(
+                changed.map((f) => `• ${f}`).join("\n") +
+                    "\n\nYour project's own docs (PRODUCT, CURRENT_PLAN, features…) were not touched.\nReview with git diff, then commit when happy.",
+                "Docs system updated",
+            );
+        }
+    } finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+};
+
+// Scaffold docs/features/<name>/ from the _template folder (SPEC → DESIGN →
+// TASKS). Returns an error message, or null on success.
+const scaffoldFeature = (root: string, feature: string): string | null => {
+    const templateDir = resolve(root, "docs", "features", "_template");
+    const dest = resolve(root, "docs", "features", feature);
+    if (!existsSync(templateDir))
+        return "docs/features/_template is missing — add the docs system first.";
+    if (existsSync(dest)) return `docs/features/${feature} already exists.`;
+    mkdirSync(dest, { recursive: true });
+    for (const f of readdirSync(templateDir)) {
+        const txt = readFileSync(join(templateDir, f), "utf8").replaceAll("<nombre>", feature);
+        writeFileSync(join(dest, f), txt);
+    }
+    return null;
+};
+
 //////////////////////////////////////////////////////////////////
 // WIZARD
 //////////////////////////////////////////////////////////////////
@@ -271,10 +456,19 @@ if (present.length > 0) {
         bail(`${displayRoot} already has macostack in it — run me without --yes to manage it.`);
     }
     const missing = PARTS.filter((p) => !present.includes(p));
-    const stateLine = PARTS.map((p) => `${p.label}: ${present.includes(p) ? "✓ installed" : "— not yet"}`).join("   ");
+    const hasDocs = existsSync(resolve(targetRoot, "AGENTS.md"));
+    const stateLine =
+        PARTS.map((p) => `${p.label}: ${present.includes(p) ? "✓ installed" : "— not yet"}`).join("   ") +
+        `   Docs: ${hasDocs ? "✓ installed" : "— not yet"}`;
     note(stateLine, "You already have macostack here");
 
     const actions = [
+        ...(hasDocs
+            ? [
+                  { value: "feature", label: "Start a new feature", hint: "SPEC → DESIGN → TASKS in docs/features/" },
+                  { value: "docs-update", label: "Update the docs system", hint: "sync AGENTS.md, commands and templates — your content stays" },
+              ]
+            : [{ value: "docs", label: "Add the docs system", hint: "AGENTS.md + docs/ + /spec /design /tasks commands" }]),
         ...missing.map((p) => ({ value: `add:${p.id}`, label: `Add the ${p.label.toLowerCase()}`, hint: p.hint })),
         ...present.map((p) => ({ value: `adjust:${p.id}`, label: `Adjust ${p.label.toLowerCase()} modules`, hint: "turn things on or off" })),
         { value: "exit", label: "Nothing — just looking", hint: "leaves everything untouched" },
@@ -287,6 +481,58 @@ if (present.length > 0) {
         outro("All good — nothing was touched. 👋");
         process.exit(0);
     }
+    if (action === "feature") {
+        const feature = answered(
+            await text({
+                message: "Feature name?",
+                placeholder: "your-feature-name",
+                validate: (v) =>
+                    validName(v ?? "") ? undefined : "lowercase letters, digits and dashes — e.g. dark-mode",
+            }),
+        );
+        const err = scaffoldFeature(targetRoot, feature);
+        if (err) bail(err);
+        note(
+            `docs/features/${feature}/ created (SPEC, DESIGN, TASKS).\nNext: open your agent here and run  /spec ${feature}`,
+            "Feature",
+        );
+        outro(`${appName} — ready to spec ✨`);
+        process.exit(0);
+    }
+    if (action === "docs-update") {
+        const syncToken = githubToken();
+        if (!syncToken) {
+            bail(
+                "I need GitHub access to fetch the docs system (the repo is private).\n" +
+                    "   Easiest: gh auth login\n" +
+                    "   Or:      export GITHUB_TOKEN=github_pat_…  (Contents: Read-only)",
+            );
+            throw ""; // unreachable
+        }
+        await updateDocs(syncToken, targetRoot);
+        outro(`${appName} is up to date ✨`);
+        process.exit(0);
+    }
+    if (action === "docs") {
+        const docsToken = githubToken();
+        if (!docsToken) {
+            bail(
+                "I need GitHub access to download the docs system (the repo is private).\n" +
+                    "   Easiest: gh auth login\n" +
+                    "   Or:      export GITHUB_TOKEN=github_pat_…  (Contents: Read-only)",
+            );
+            throw ""; // unreachable
+        }
+        const ok = await scaffoldDocs(docsToken, targetRoot, appName, null);
+        if (ok) {
+            note(
+                `Open Claude Code or OpenCode in ${displayRoot}/ — it reads AGENTS.md.\nFirst: fill docs/PRODUCT.md, then  /spec your-first-feature`,
+                "Next",
+            );
+        }
+        outro(`${appName} is up to date ✨`);
+        process.exit(0);
+    }
     const [verb, partId] = (action as string).split(":");
     const part = PARTS.find((p) => p.id === partId)!;
     if (verb === "adjust") {
@@ -340,15 +586,7 @@ for (const p of selected) {
 
 // Preflight every selected template so a typo'd repo or missing access fails
 // BEFORE any folders exist.
-const gh = (path: string) =>
-    fetch(`https://api.github.com${path}`, {
-        headers: {
-            Accept: "application/vnd.github+json",
-            Authorization: `Bearer ${token}`,
-            "User-Agent": "create-macostack",
-            "X-GitHub-Api-Version": "2022-11-28",
-        },
-    });
+const gh = (path: string) => ghFetch(token, path);
 for (const p of selected) {
     const res = await gh(`/repos/${owner}/${p.repo}`);
     if (!res.ok) {
@@ -371,26 +609,10 @@ for (const p of selected) {
     const dest = resolve(targetRoot, p.folder);
     const s = spinner();
     s.start(`${p.label} — downloading ${owner}/${p.repo}@${ref}`);
-    const tmp = mkdtempSync(join(tmpdir(), "create-macostack-"));
-    try {
-        const res = await gh(`/repos/${owner}/${p.repo}/tarball/${ref}`);
-        if (!res.ok) {
-            s.stop(`${p.label} — download failed`);
-            bail(`GitHub refused the download (HTTP ${res.status}). Try again, or check --ref ${ref}.`);
-        }
-        const archive = join(tmp, "template.tar.gz");
-        await Bun.write(archive, await res.arrayBuffer());
-        mkdirSync(dest, { recursive: true });
-        const tar = Bun.spawnSync(
-            ["tar", "-xzf", archive, "-C", dest, "--strip-components=1"],
-            { stdout: "pipe", stderr: "pipe" },
-        );
-        if (tar.exitCode !== 0) {
-            s.stop(`${p.label} — extract failed`);
-            bail(`Couldn't unpack the template: ${tar.stderr.toString().slice(0, 200)}`);
-        }
-    } finally {
-        rmSync(tmp, { recursive: true, force: true });
+    const err = await downloadInto(token, owner, p.repo, ref, dest);
+    if (err) {
+        s.stop(`${p.label} — download failed`);
+        bail(`${err}. Try again, or check --ref ${ref}.`);
     }
     s.stop(`${p.label} — downloaded into ${displayRoot}/${p.folder}`);
 
@@ -568,6 +790,14 @@ for (const s of setups) {
     ready.push(p);
 }
 
+// Phase 4 — the docs system: AGENTS.md + docs/ + slash commands for Claude
+// Code and OpenCode, stamped with this app's choices. The root becomes the
+// workspace repo (docs + orchestration; client/ and server/ stay independent).
+let docsReady = existsSync(resolve(targetRoot, "AGENTS.md"));
+if (!flags["skip-docs"] && !docsReady) {
+    docsReady = await scaffoldDocs(token, targetRoot, appName, chosenModules);
+}
+
 //////////////////////////////////////////////////////////////////
 // DONE
 //////////////////////////////////////////////////////////////////
@@ -583,6 +813,11 @@ if (server) {
 if (client) {
     steps.push(`Start the web app:\n  cd ${displayRoot}/client\n  bun dev`);
 }
+if (docsReady) {
+    steps.push(
+        `Define the product:\n  open Claude Code or OpenCode in ${displayRoot}/ — they read AGENTS.md\n  first session: fill docs/PRODUCT.md, then /spec <your-first-feature>`,
+    );
+}
 steps.push(
     `When you're ready to publish (each part is its own repo):\n` +
         ready

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-macostack",
-    "version": "0.6.1",
+    "version": "0.6.3",
     "description": "Scaffold a production-ready full-stack app from the macostack templates: Bun + Hono + Postgres backend and TanStack web app, each as its own git repo.",
     "license": "MIT",
     "repository": {
@@ -38,6 +38,6 @@
     },
     "devDependencies": {
         "@types/bun": "^1.3.14",
-        "typescript": "^6.0.3"
+        "typescript": "^7.0.2"
     }
 }