create-macostack 0.6.0 → 0.6.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 macobits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,53 +1,99 @@
 # create-macostack
 
-Orquestador mínimo para crear ventures macostack desde templates privados.
+Scaffold a production-ready full-stack app from the macostack templates — a Bun + Hono + Postgres backend and a TanStack (React) web app — with a single command.
 
 ```bash
-export GITHUB_TOKEN="github_pat_..." # fine-grained, Contents: Read-only
-bun create macostack mi-tienda
+bun create macostack my-app
 ```
 
-Salida esperada:
+An interactive wizard walks you through the rest:
 
-```txt
-mi-tienda/
-    server/    # repo git propio
-    client/    # repo git propio
+1. **Pick the parts** your app needs — backend API, web app, or both.
+2. **Choose a deploy target and feature modules.** Each template declares its own questions; the CLI merges them so every feature is asked exactly once for the whole app.
+3. **Optionally prefill environment values** — your primary domain (CORS, cookie scope, and the web app's API URL) and a Resend API key for transactional email.
+
+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.
+
+## Requirements
+
+- [Bun](https://bun.sh) 1.x
+- GitHub access to the template repositories (they are private by default):
+
+```bash
+gh auth login
+# or
+export GITHUB_TOKEN=github_pat_…   # fine-grained token, Contents: Read-only
 ```
 
-La raíz no se inicializa como git. El CLI descarga tarballs privados, instala con
-`bun install`, delega `bun run setup` cuando existe, y asegura un repo git por
-mitad si el setup no lo creó.
+Access is verified before anything is written to disk — a typo'd repo or missing permission fails cleanly, with no half-created folders.
 
-## Desarrollo local
+## Usage
 
 ```bash
-bun install
-bun run dev mi-tienda
+bun create macostack my-app     # scaffold into ./my-app
+bun create macostack .          # scaffold into the current (empty) directory
 ```
 
-## Configuración
+Result:
 
-Defaults:
+```txt
+my-app/
+├── server/    # Bun + Hono + Postgres API — its own git repo
+└── client/    # TanStack web app — its own git repo
+```
 
-- owner: `macobits`
-- server repo: `macostack-server`
-- client repo: `macostack-client`
-- ref: `main`
+The root folder is intentionally **not** a git repository: server and client are designed to live and deploy as separate repos.
 
-Flags útiles:
+### 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:
 
 ```bash
-bun run dev mi-tienda --owner macobits --ref main
-bun run dev mi-api --server --skip-setup
-bun run dev mi-web --client --skip-install
+cd my-app
+bun create macostack .
 ```
 
-También puedes usar env vars:
+### Flags
+
+| Flag | Description |
+| --- | --- |
+| `--server` / `--client` | Scaffold only that part (default: interactive) |
+| `--yes` | Non-interactive: both parts, template defaults |
+| `--owner <org>` | GitHub owner of the template repos (default: `macobits`) |
+| `--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`) |
+| `--skip-install` | Skip `bun install` |
+| `--skip-setup` | Skip each template's setup wizard |
+| `--help` | Print usage |
+
+### Environment variables
+
+| Variable | Description |
+| --- | --- |
+| `GITHUB_TOKEN` / `GH_TOKEN` | Token used to download the templates (falls back to `gh auth token`) |
+| `MACOSTACK_GITHUB_OWNER` | Default template owner |
+| `MACOSTACK_SERVER_REPO` | Default server template repo |
+| `MACOSTACK_CLIENT_REPO` | Default client template repo |
+| `MACOSTACK_REF` | Default branch or tag |
+
+## Bring your own templates
+
+The orchestrator is deliberately template-agnostic: it never hardcodes which features exist. Point `--owner`, `--server-repo`, and `--client-repo` at your own repositories, and expose a `setup` script in each template's `package.json`:
+
+- `bun run setup --questions` prints a JSON spec of the questions the template supports (feature modules, optional deploy target).
+- `bun run setup --yes --name <app> [--modules a,b] [--runtime x] [--domain d]` applies the answers.
+
+Anything the template declares, the CLI renders — nothing more.
+
+## Development
 
 ```bash
-MACOSTACK_GITHUB_OWNER=macobits
-MACOSTACK_SERVER_REPO=macostack-server
-MACOSTACK_CLIENT_REPO=macostack-client
-GITHUB_TOKEN=github_pat_...
+bun install
+bun run dev my-app --skip-install   # run the CLI from source
+bun run typecheck
 ```
+
+## License
+
+[MIT](./LICENSE) © macobits

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
 //////////////////////////////////////////////////////////////////
@@ -187,7 +302,7 @@ if (scaffoldHere) {
     }
 } else if (positional) {
     if (!validName(positional)) {
-        bail("App names use lowercase letters, digits and dashes — e.g. soccer-app");
+        bail("App names use lowercase letters, digits and dashes — e.g. my-app");
     }
     appName = positional;
 } else if (flags.yes) {
@@ -197,9 +312,9 @@ if (scaffoldHere) {
     appName = answered(
         await text({
             message: "What should we call your app?",
-            placeholder: "soccer-app",
+            placeholder: "my-app",
             validate: (v) =>
-                validName(v ?? "") ? undefined : "lowercase letters, digits and dashes — e.g. soccer-app",
+                validName(v ?? "") ? undefined : "lowercase letters, digits and dashes — e.g. my-app",
         }),
     );
 }
@@ -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,7 +1,22 @@
 {
     "name": "create-macostack",
-    "version": "0.6.0",
-    "description": "Private macostack scaffold orchestrator for detached server/client repos.",
+    "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": {
+        "type": "git",
+        "url": "git+https://github.com/macobits/create-macostack.git"
+    },
+    "keywords": [
+        "create",
+        "scaffold",
+        "template",
+        "bun",
+        "hono",
+        "tanstack",
+        "fullstack",
+        "macostack"
+    ],
     "type": "module",
     "bin": {
         "create-macostack": "./bin/create-macostack.ts"
@@ -23,6 +38,6 @@
     },
     "devDependencies": {
         "@types/bun": "^1.3.14",
-        "typescript": "^6.0.3"
+        "typescript": "^7.0.2"
     }
 }