create-macostack 0.6.2 → 0.6.4

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

@@ -6,6 +6,7 @@ import {
     multiselect,
     note,
     outro,
+    password,
     select,
     spinner,
     text,
@@ -17,10 +18,11 @@ import {
     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.
@@ -133,6 +135,7 @@ Flags:
 Auth (templates are private):
   export GITHUB_TOKEN=github_pat_…   or   gh auth login
   (fine-grained token, Contents: Read-only is enough)
+  No token configured? I'll ask for one when it's needed.
 `);
     process.exit(0);
 }
@@ -157,9 +160,40 @@ const answered = <T>(value: T | symbol): T => {
 const githubToken = (): string | null => {
     const fromEnv = Bun.env.GITHUB_TOKEN ?? Bun.env.GH_TOKEN;
     if (fromEnv) return fromEnv;
-    const gh = Bun.spawnSync(["gh", "auth", "token"], { stdout: "pipe", stderr: "pipe" });
-    const token = gh.exitCode === 0 ? gh.stdout.toString().trim() : "";
-    return token || null;
+    try {
+        const gh = Bun.spawnSync(["gh", "auth", "token"], { stdout: "pipe", stderr: "pipe" });
+        const token = gh.exitCode === 0 ? gh.stdout.toString().trim() : "";
+        return token || null;
+    } catch {
+        return null; // gh isn't installed
+    }
+};
+
+// Resolve a GitHub token, or ask for one when nothing is configured. In --yes
+// mode there's nobody to ask, so it bails with instructions instead.
+const requireGithubToken = async (purpose: string): Promise<string> => {
+    const found = githubToken();
+    if (found) return found;
+    if (flags.yes) {
+        bail(
+            `I need GitHub access to ${purpose} (the repos are private).\n` +
+                "   Easiest: gh auth login\n" +
+                "   Or:      export GITHUB_TOKEN=github_pat_…  (Contents: Read-only)",
+        );
+    }
+    note(
+        `I need GitHub access to ${purpose} (the repos are private).\n` +
+            "A fine-grained token with Contents: Read-only is enough.\n" +
+            "Tip: gh auth login (or export GITHUB_TOKEN=…) skips this question next time.",
+        "GitHub access",
+    );
+    const typed = answered(
+        await password({
+            message: "Paste your GitHub token (input is hidden)",
+            validate: (v) => (v?.trim() ? undefined : "I need a token to continue"),
+        }),
+    );
+    return typed.trim();
 };
 
 const isEmptyDir = (dir: string) =>
@@ -254,6 +288,75 @@ const scaffoldDocs = async (
     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 => {
@@ -394,7 +497,10 @@ if (present.length > 0) {
 
     const actions = [
         ...(hasDocs
-            ? [{ value: "feature", label: "Start a new feature", hint: "SPEC → DESIGN → TASKS in docs/features/" }]
+            ? [
+                  { 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" })),
@@ -412,9 +518,9 @@ if (present.length > 0) {
         const feature = answered(
             await text({
                 message: "Feature name?",
-                placeholder: "member-invites",
+                placeholder: "your-feature-name",
                 validate: (v) =>
-                    validName(v ?? "") ? undefined : "lowercase letters, digits and dashes — e.g. member-invites",
+                    validName(v ?? "") ? undefined : "lowercase letters, digits and dashes — e.g. dark-mode",
             }),
         );
         const err = scaffoldFeature(targetRoot, feature);
@@ -426,16 +532,14 @@ if (present.length > 0) {
         outro(`${appName} — ready to spec ✨`);
         process.exit(0);
     }
+    if (action === "docs-update") {
+        const syncToken = await requireGithubToken("fetch the docs system");
+        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 docsToken = await requireGithubToken("download the docs system");
         const ok = await scaffoldDocs(docsToken, targetRoot, appName, null);
         if (ok) {
             note(
@@ -484,15 +588,7 @@ if (!selected) {
 // 3. GitHub access — checked before anything is created.
 const owner = flags.owner ?? DEFAULT_OWNER;
 const ref = flags.ref ?? DEFAULT_REF;
-const token = githubToken();
-if (!token) {
-    bail(
-        "I need GitHub access to download the templates (they're private).\n" +
-            "   Easiest: gh auth login\n" +
-            "   Or:      export GITHUB_TOKEN=github_pat_…  (Contents: Read-only)",
-    );
-    throw ""; // unreachable
-}
+const token = await requireGithubToken("download the templates");
 for (const p of selected) {
     p.repo = (p.id === "server" ? flags["server-repo"] : flags["client-repo"]) ?? p.repo;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-macostack",
-    "version": "0.6.2",
+    "version": "0.6.4",
     "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": {