create-macostack 0.6.1 → 0.6.2

package/bin/create-macostack.ts

@@ -15,7 +15,9 @@ import {
     mkdirSync,
     mkdtempSync,
     readdirSync,
+    readFileSync,
     rmSync,
+    writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
@@ -80,6 +82,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 +103,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 +125,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 +166,110 @@ 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;
+};
+
+// 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 +386,16 @@ 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", 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 +408,44 @@ 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: "member-invites",
+                validate: (v) =>
+                    validName(v ?? "") ? undefined : "lowercase letters, digits and dashes — e.g. member-invites",
+            }),
+        );
+        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") {
+        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 +499,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 +522,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 +703,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 +726,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.2",
     "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"
     }
 }