create-macostack 0.6.2 → 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

@@ -17,10 +17,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.
@@ -254,6 +255,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 +464,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 +485,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,6 +499,20 @@ if (present.length > 0) {
         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) {

package/package.json

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