claude-setup 1.1.1 → 1.1.2

package/README.md

@@ -1,45 +1,119 @@
-# claude-setup
-
-Setup layer for Claude Code. Reads your project, writes command files, Claude Code does the rest.
-
-## Install
-
-```bash
-npx claude-setup init
-```
-
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `npx claude-setup init` | Full project setup — new or existing |
-| `npx claude-setup add` | Add a multi-file capability |
-| `npx claude-setup sync` | Update setup after project changes |
-| `npx claude-setup status` | Show current setup |
-| `npx claude-setup doctor` | Validate environment |
-| `npx claude-setup remove` | Remove a capability cleanly |
-
-## How it works
-
-1. **CLI collects** — reads project files (configs, source samples) with strict cost controls
-2. **CLI writes command files** — assembles markdown instructions into `.claude/commands/`
-3. **Claude Code executes** — you run `/stack-init` (or `/stack-sync`, etc.) in Claude Code
-
-The CLI has zero intelligence. All reasoning is delegated to Claude Code via the command files.
-
-## Three project states
-
-- **Empty project** — Claude Code asks 3 discovery questions, then sets up a tailored environment
-- **In development** — reads existing files, writes setup that references actual code patterns
-- **Production** — same as development; merge rules protect existing Claude config (append only, never rewrite)
-
-## What it creates
-
-- `CLAUDE.md` — project-specific context for Claude Code
-- `.mcp.json` — MCP server connections (only if evidenced by project files)
-- `.claude/settings.json` — hooks (only if warranted)
-- `.claude/skills/` — reusable patterns (only if recurring)
-- `.claude/commands/` — project-specific slash commands
-- `.github/workflows/` — CI workflows (only if `.github/` exists)
-
-
+# claude-setup
+
+Setup layer for Claude Code. Reads your project, writes command files, Claude Code does the rest.
+
+**The CLI has zero intelligence.** All reasoning is delegated to Claude Code via the command files. The CLI reads files. Claude Code decides.
+
+## Install & Quick Start
+
+```bash
+npx claude-setup init
+```
+
+Then open Claude Code and run `/stack-init`.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `npx claude-setup init` | Full project setup — new or existing. Detects empty projects automatically. |
+| `npx claude-setup add` | Add a multi-file capability (MCP + hooks + skills together) |
+| `npx claude-setup sync` | Update setup after project changes (uses diff, not full re-scan) |
+| `npx claude-setup status` | Show current setup state — OS, servers, hooks, staleness |
+| `npx claude-setup doctor` | Validate environment — OS/MCP format, hook quoting, env vars, stale skills |
+| `npx claude-setup remove` | Remove a capability cleanly with dangling reference detection |
+
+### Flags
+
+```bash
+npx claude-setup init --dry-run    # Preview without writing
+npx claude-setup sync --dry-run    # Show changes without writing
+npx claude-setup doctor --verbose  # Include passing checks in output
+```
+
+## How it works
+
+1. **CLI collects** — reads project files (configs, source samples) with strict token cost controls
+2. **CLI writes command files** — assembles markdown instructions into `.claude/commands/`
+3. **Claude Code executes** — you run `/stack-init` (or `/stack-sync`, etc.) in Claude Code
+
+## Three project states
+
+- **Empty project** — Claude Code asks 3 discovery questions, then sets up a tailored environment
+- **In development** — reads existing files, writes setup that references actual code patterns
+- **Production** — same as development; merge rules protect existing Claude config (append only, never rewrite)
+
+## What it creates
+
+- `CLAUDE.md` — project-specific context for Claude Code
+- `.mcp.json` — MCP server connections (only if evidenced by project files, OS-correct format)
+- `.claude/settings.json` — hooks (only if warranted, OS-correct shell format)
+- `.claude/skills/` — reusable patterns (only if recurring, with `applies-when` frontmatter)
+- `.claude/commands/` — project-specific slash commands
+- `.github/workflows/` — CI workflows (only if `.github/` exists)
+
+## Token cost controls
+
+Every byte injected into command files costs tokens. The CLI enforces:
+
+| Control | Default |
+|---------|---------|
+| Init token budget | 12,000 |
+| Sync token budget | 6,000 |
+| Add token budget | 3,000 |
+| Remove token budget | 2,000 |
+| Max source files sampled | 15 |
+| Max file size | 80KB |
+| Max depth | 6 levels |
+
+### File-specific truncation
+
+| File | Strategy |
+|------|----------|
+| `package-lock.json` | Extract `{ name, version, lockfileVersion }` only |
+| `Dockerfile` | First 50 lines |
+| `docker-compose.yml` | First 100 lines if > 8KB |
+| `pom.xml`, `build.gradle*` | First 80 lines |
+| `setup.py` | First 60 lines |
+| `*.config.{js,ts,mjs}` | First 100 lines |
+
+## Configuration
+
+Create `.claude-setup.json` in your project root to customize:
+
+```json
+{
+  "maxSourceFiles": 15,
+  "maxDepth": 6,
+  "maxFileSizeKB": 80,
+  "tokenBudget": {
+    "init": 12000,
+    "sync": 6000,
+    "add": 3000,
+    "remove": 2000
+  },
+  "digestMode": true,
+  "extraBlockedDirs": ["my-custom-dir"],
+  "sourceDirs": ["src", "lib"]
+}
+```
+
+## Digest mode
+
+When `digestMode` is enabled (default), the CLI extracts compact signal instead of dumping raw file content:
+
+- **Config files found** — just names, not content
+- **Dependencies** — extracted from any package manifest
+- **Scripts** — available commands/tasks
+- **Env vars** — names from `.env.example`
+- **Directory tree** — compact structure (3 levels deep)
+- **Source signatures** — imports, exports, declarations (not full content)
+
+## OS detection
+
+The CLI detects your OS and ensures command files tell Claude Code to use the correct format:
+
+- **Windows**: `{ "command": "cmd", "args": ["/c", "npx", "<package>"] }`
+- **macOS/Linux**: `{ "command": "npx", "args": ["<package>"] }`
+
+`doctor` checks for mismatches and reports them as critical issues.

package/dist/builder.js

@@ -2,6 +2,7 @@ import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { loadConfig } from "./config.js";
+import { detectOS } from "./os.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, "..", "templates");
 function estimateTokens(content) {
@@ -63,6 +64,9 @@ function formatSourceContext(source) {
 }
 // --- Template variable building ---
 function buildVars(collected, state) {
+    const skippedList = collected.skipped.length > 0
+        ? collected.skipped.map(s => `- ${s.path} — ${s.reason}`).join("\n")
+        : "";
     return {
         VERSION: getVersion(),
         DATE: new Date().toISOString().split("T")[0],
@@ -81,11 +85,14 @@ function buildVars(collected, state) {
         COMMANDS_LIST: formatList(state.commands),
         WORKFLOWS_LIST: formatList(state.workflows),
         HAS_GITHUB_DIR: state.hasGithubDir ? "yes" : "no",
+        SKIPPED_LIST: skippedList,
+        DETECTED_OS: detectOS(),
     };
 }
 function buildFlags(_collected, state) {
     return {
         HAS_SOURCE: _collected.source.length > 0,
+        HAS_SKIPPED: _collected.skipped.length > 0,
         HAS_CLAUDE_MD: state.claudeMd.exists,
         HAS_MCP_JSON: state.mcpJson.exists,
         HAS_SETTINGS: state.settings.exists,
@@ -162,9 +169,10 @@ export function buildAtomicSteps(collected, state) {
     const version = getVersion();
     const date = new Date().toISOString().split("T")[0];
     const vars = buildVars(collected, state);
+    const os = detectOS();
     const header = `<!-- claude-setup ${version} ${date} -->\n`;
-    const check = `Check if target already has this content. If yes: print "SKIPPED" and stop. Write only what's missing.\n\n`;
-    // Shared context block — written once to a reference file, not duplicated
+    const preamble = `Before writing: check if what you are about to write already exists in the target file (current content provided below if it exists). If already up to date: print "SKIPPED — already up to date" and stop. Write only what is genuinely missing.\n\nRead /stack-0-context for full project info.\n\n`;
+    // Shared context block — written once, referenced by all steps
     const sharedContext = header +
         `## Project\n\n${vars.PROJECT_CONTEXT}\n\n` +
         `{{#if HAS_SOURCE}}## Source samples\n\n${vars.SOURCE_CONTEXT}\n{{/if}}`;
@@ -174,57 +182,148 @@ export function buildAtomicSteps(collected, state) {
             filename: "stack-0-context.md",
             content: sharedContextProcessed,
         },
+        // --- Step 1: CLAUDE.md ---
         {
             filename: "stack-1-claude-md.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: CLAUDE.md\n` +
+            content: header + preamble +
+                `## Target: CLAUDE.md\n\n` +
                 (state.claudeMd.exists
-                    ? `Current content (append only, never rewrite):\n${vars.CLAUDE_MD_CONTENT}\n\n`
-                    : `Does not exist. Create it.\n\n`) +
-                `Write CLAUDE.md specific to this project. Reference actual paths and patterns. No generic boilerplate.`,
+                    ? `### Current content — APPEND ONLY, never rewrite, never remove:\n${vars.CLAUDE_MD_CONTENT}\n\n`
+                    : `Does not exist — create it.\n\n`) +
+                `### What to write\n` +
+                `CLAUDE.md is the most valuable artifact. Make it specific to THIS project:\n` +
+                `- **Purpose**: one sentence describing what this project does\n` +
+                `- **Runtime**: language, framework, key dependencies from /stack-0-context\n` +
+                `- **Key dirs**: reference actual directory paths from the project tree\n` +
+                `- **Run/test/build commands**: extract from scripts in /stack-0-context\n` +
+                `- **Non-obvious conventions**: patterns you see in the source samples\n\n` +
+                `### Rules\n` +
+                `- Every line must reference something you actually saw in /stack-0-context\n` +
+                `- No generic boilerplate. Two different projects must produce two different CLAUDE.md files\n` +
+                `- If it exists above: read it fully, add only what is genuinely missing\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ CLAUDE.md — [one clause: what you wrote and why]\n` +
+                `Skipped: ⏭ CLAUDE.md — [why not needed]\n`,
         },
+        // --- Step 2: .mcp.json ---
         {
             filename: "stack-2-mcp.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .mcp.json\n` +
+            content: header + preamble +
+                `## Target: .mcp.json\n\n` +
                 (state.mcpJson.exists
-                    ? `Current (merge only, never remove):\n${vars.MCP_JSON_CONTENT}\n\n`
-                    : `Does not exist. Create only if services are evidenced.\n\n`) +
-                `No evidence = no server. Valid JSON only.`,
+                    ? `### Current content — MERGE ONLY, never remove existing entries:\n${vars.MCP_JSON_CONTENT}\n\n`
+                    : `Does not exist.\n\n`) +
+                `### When to create/update\n` +
+                `Add an MCP server ONLY if you find evidence in /stack-0-context:\n` +
+                `- Import statement referencing an external service\n` +
+                `- docker-compose service (database, cache, queue)\n` +
+                `- Env var name in .env.example matching a known service pattern\n` +
+                `- Explicit dependency on an MCP-compatible package\n\n` +
+                `No evidence = no server. Do not invent services.\n\n` +
+                `### OS-correct format (detected: ${os})\n` +
+                (os === "Windows"
+                    ? `Use: \`{ "command": "cmd", "args": ["/c", "npx", "<package>"] }\`\n`
+                    : `Use: \`{ "command": "npx", "args": ["<package>"] }\`\n`) +
+                `\n### Rules\n` +
+                `- All env var refs use \`\${VARNAME}\` syntax\n` +
+                `- Produce valid JSON only\n` +
+                `- If creating: document every new env var in .env.example\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ .mcp.json — [what server and evidence source]\n` +
+                `Skipped: ⏭ .mcp.json — checked [files], found [nothing], no action\n`,
         },
+        // --- Step 3: .claude/settings.json ---
         {
             filename: "stack-3-settings.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .claude/settings.json\n` +
+            content: header + preamble +
+                `## Target: .claude/settings.json\n\n` +
                 (state.settings.exists
-                    ? `Current (merge only, never remove hooks):\n${vars.SETTINGS_CONTENT}\n\n`
-                    : `Does not exist. Create only if hooks earn their cost.\n\n`) +
-                `Every hook runs on every action. Only add if clearly justified.`,
+                    ? `### Current content — MERGE ONLY, never remove existing hooks:\n${vars.SETTINGS_CONTENT}\n\n`
+                    : `Does not exist.\n\n`) +
+                `### When to create/update\n` +
+                `Add a hook ONLY if it runs on a pattern that repeats every session AND the cost is justified.\n` +
+                `Every hook adds overhead on every Claude Code action. Only add if clearly earned.\n\n` +
+                `### OS-correct hook format (detected: ${os})\n` +
+                (os === "Windows"
+                    ? `Use: \`{ "command": "cmd", "args": ["/c", "<command>"] }\`\n`
+                    : `Use: \`{ "command": "bash", "args": ["-c", "<command>"] }\`\n` +
+                        `**Bash quoting rule**: never use bare \`"\` inside \`-c "..."\` — use \`\\x22\` instead.\n` +
+                        `Replace \`'\` with \`\\x27\`, \`$\` in character classes with \`\\x24\`.\n`) +
+                `\n### Rules\n` +
+                `- If it exists above: audit quoting of existing hooks first, fix broken ones\n` +
+                `- Only add hooks for patterns that genuinely recur for this project type\n` +
+                `- Produce valid JSON only\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ settings.json — [hook name and justification]\n` +
+                `Skipped: ⏭ settings.json — [why no hooks warranted]\n`,
         },
+        // --- Step 4: .claude/skills/ ---
         {
             filename: "stack-4-skills.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .claude/skills/\nInstalled: ${vars.SKILLS_LIST}\n\n` +
-                `Only for recurring patterns. Use applies-when frontmatter. Empty is fine.`,
+            content: header + preamble +
+                `## Target: .claude/skills/\n` +
+                `Installed: ${vars.SKILLS_LIST}\n\n` +
+                `### When to create\n` +
+                `Create a skill ONLY if:\n` +
+                `- A recurring multi-step project-specific pattern exists in /stack-0-context\n` +
+                `- It is NOT something Claude already knows (standard patterns don't need skills)\n` +
+                `- It will save time across multiple Claude Code sessions\n\n` +
+                `### Rules\n` +
+                `- Use \`applies-when:\` frontmatter so skills load only when relevant, not every message\n` +
+                `- If a similar skill already exists above: extend it, don't create a parallel one\n` +
+                `- Empty is valid — no skills is better than useless skills\n\n` +
+                `### Output\n` +
+                `Created: ✅ .claude/skills/[name] — [what pattern it captures]\n` +
+                `Skipped: ⏭ skills — checked [patterns], found [nothing project-specific]\n`,
         },
+        // --- Step 5: .claude/commands/ ---
         {
             filename: "stack-5-commands.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .claude/commands/ (not stack-*.md)\nInstalled: ${vars.COMMANDS_LIST}\n\n` +
-                `Only useful commands for this project type. No duplicates.`,
+            content: header + preamble +
+                `## Target: .claude/commands/ (excluding stack-*.md — those are setup artifacts)\n` +
+                `Installed: ${vars.COMMANDS_LIST}\n\n` +
+                `### When to create\n` +
+                `Create a command ONLY for project-specific multi-step workflows a developer repeats:\n` +
+                `- Deploy sequences\n` +
+                `- Database migration + seed\n` +
+                `- Release workflows\n` +
+                `- Environment setup for a new contributor\n\n` +
+                `Do NOT create commands for things expressible as a single shell alias.\n` +
+                `Look at the scripts in /stack-0-context for evidence of multi-step workflows.\n\n` +
+                `### Rules\n` +
+                `- If existing commands cover the same workflow: skip\n` +
+                `- Commands should be specific to this project, not generic\n\n` +
+                `### Output\n` +
+                `Created: ✅ .claude/commands/[name].md — [what workflow and why useful]\n` +
+                `Skipped: ⏭ commands — [why no project-specific workflows found]\n`,
         },
+        // --- Step 6: .github/workflows/ ---
         {
             filename: "stack-6-workflows.md",
-            content: header + check +
-                `## Target: .github/workflows/\n.github/ exists: ${vars.HAS_GITHUB_DIR}\nInstalled: ${vars.WORKFLOWS_LIST}\n\n` +
+            content: header +
+                `## Target: .github/workflows/\n` +
+                `.github/ exists: ${vars.HAS_GITHUB_DIR}\n` +
+                `Installed: ${vars.WORKFLOWS_LIST}\n\n` +
                 (state.hasGithubDir
-                    ? `Only warranted workflows. Don't touch existing ones.`
-                    : `Only create if clearly warranted.`),
+                    ? (`### What to do\n` +
+                        `Check /stack-0-context for CI evidence: tests dir, Dockerfile, CI-related scripts.\n` +
+                        `If evidence found, print EXACTLY:\n\n` +
+                        `\`\`\`\n` +
+                        `⚙️  CI/CD GATE — action required\n\n` +
+                        `Evidence found:\n` +
+                        `  [list each piece of evidence]\n\n` +
+                        `Two questions before I proceed:\n` +
+                        `  1. Set up CI/CD? (yes / no / later)\n` +
+                        `  2. Connected to a remote GitHub repo? (yes / no)\n\n` +
+                        `I will not write .github/workflows/ until you answer.\n` +
+                        `\`\`\`\n\n` +
+                        `### Rules\n` +
+                        `- NEVER create or modify workflows without explicit developer confirmation\n` +
+                        `- If existing workflows exist: do not touch them\n` +
+                        `- Secrets must use \`\${{ secrets.VARNAME }}\` syntax only\n`)
+                    : (`### .github/ does not exist\n` +
+                        `Do not create workflows. Print:\n` +
+                        `Skipped: ⏭ .github/workflows/ — .github/ directory does not exist\n`)),
         },
     ];
     return steps;

package/dist/collect.js

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync, statSync, readdirSync } from "fs";
 import { glob } from "glob";
 import { join, extname, basename, dirname } from "path";
-import { loadConfig } from "./config.js";
+import { loadConfig, applyTruncation } from "./config.js";
 // --- Blocklists ---
 const BLOCKED_DIRS = new Set([
     "node_modules", "vendor", ".venv", "venv", "env", "__pypackages__",
@@ -22,7 +22,7 @@ const BLOCKED_EXTENSIONS = new Set([
 ]);
 const BLOCKED_FILES = new Set([
     "go.sum", "poetry.lock", "Pipfile.lock", "composer.lock",
-    ".DS_Store", "Thumbs.db", "package-lock.json",
+    ".DS_Store", "Thumbs.db",
 ]);
 const SOURCE_EXTENSIONS = new Set([
     ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
@@ -35,7 +35,8 @@ const ENTRY_DIRS = [".", "src", "app", "cmd", "bin"];
 const PRIMARY_SOURCE_DIRS = ["src", "app", "lib", "core", "pkg", "internal", "api", "cmd"];
 // Config files the CLI knows how to find — but NOT what they mean
 const KNOWN_CONFIG_FILES = [
-    "package.json", "pyproject.toml", "setup.py", "requirements.txt", "Pipfile",
+    "package.json", "package-lock.json", "pyproject.toml", "setup.py",
+    "requirements.txt", "Pipfile",
     "go.mod", "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts",
     "composer.json", "Gemfile", "turbo.json", "nx.json", "pnpm-workspace.yaml",
     "lerna.json", ".env.example", ".env.sample", ".env.template",
@@ -441,18 +442,52 @@ function truncateSource(content) {
 }
 // --- Legacy raw config collection ---
 async function collectRawConfigs(cwd, configs, skipped) {
+    const config = loadConfig(cwd);
     for (const name of KNOWN_CONFIG_FILES) {
         const p = join(cwd, name);
         if (existsSync(p)) {
             try {
-                const content = readFileSync(p, "utf8");
-                configs[name] = content.length > 4000 ? content.slice(0, 4000) + "\n[... truncated]" : content;
+                const raw = readFileSync(p, "utf8");
+                // Dynamic truncation — driven by config, not hardcoded
+                configs[name] = applyTruncation(name, raw, config);
             }
             catch {
                 skipped.push({ path: name, reason: "could not read" });
             }
         }
     }
+    // Scan for *.config.{js,ts,mjs} at root level — truncation from config
+    try {
+        for (const ext of ["js", "ts", "mjs"]) {
+            const matches = await glob(`*.config.${ext}`, { cwd, nodir: true });
+            for (const match of matches) {
+                if (configs[match])
+                    continue;
+                const p = join(cwd, match);
+                try {
+                    const content = readFileSync(p, "utf8");
+                    configs[match] = applyTruncation(match, content, config);
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    catch { /* skip */ }
+    // Scan for *.csproj at root level
+    try {
+        const csprojFiles = await glob("*.csproj", { cwd, nodir: true });
+        for (const match of csprojFiles) {
+            if (configs[match])
+                continue;
+            const p = join(cwd, match);
+            try {
+                const content = readFileSync(p, "utf8");
+                configs[match] = applyTruncation(match, content, config);
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* skip */ }
 }
 // --- Source file discovery ---
 async function findSourceFiles(cwd, maxDepth, blocked) {

package/dist/commands/add.js

@@ -4,6 +4,7 @@ import { collectProjectFiles } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
 import { buildAddCommand } from "../builder.js";
+import { c } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
@@ -18,6 +19,8 @@ async function promptFreeText(question) {
     });
 }
 // Conservative — only redirect when unambiguously single-file
+// False negatives (multi-step for single-file request) are fine
+// False positives (redirecting a genuinely multi-file request) are bad
 function isSingleFileOperation(input) {
     return (/to \.mcp\.json\s*$/i.test(input) ||
         /to settings\.json\s*$/i.test(input) ||
@@ -30,12 +33,12 @@ export async function runAdd() {
         return;
     }
     if (isSingleFileOperation(userInput)) {
-        console.log(`
-For single changes, Claude Code is faster:
-  Just tell it: "${userInput}"
-
-Use claude-setup add when the change spans multiple files —
-capabilities that need documentation, MCP servers, skills, and hooks together.
+        console.log(`
+For single changes, Claude Code is faster:
+  Just tell it: "${userInput}"
+
+Use ${c.cyan("claude-setup add")} when the change spans multiple files —
+capabilities that need documentation, MCP servers, skills, and hooks together.
     `);
         return;
     }
@@ -46,5 +49,5 @@ capabilities that need documentation, MCP servers, skills, and hooks together.
     ensureDir(".claude/commands");
     writeFileSync(".claude/commands/stack-add.md", content, "utf8");
     await updateManifest("add", collected, { input: userInput });
-    console.log(`\n✅ Ready. Open Claude Code and run:\n   /stack-add\n`);
+    console.log(`\n${c.green("✅")} Ready. Open Claude Code and run:\n   ${c.cyan("/stack-add")}\n`);
 }

package/dist/commands/doctor.d.ts

@@ -1 +1,5 @@
-export { runDoctor } from "../doctor.js";
+import { runDoctor } from "../doctor.js";
+export { runDoctor };
+export declare function runDoctorCommand(opts?: {
+    verbose?: boolean;
+}): Promise<void>;

package/dist/commands/doctor.js

@@ -1 +1,5 @@
-export { runDoctor } from "../doctor.js";
+import { runDoctor } from "../doctor.js";
+export { runDoctor };
+export async function runDoctorCommand(opts = {}) {
+    return runDoctor(opts.verbose ?? false);
+}

package/dist/commands/init.d.ts

@@ -1 +1,3 @@
-export declare function runInit(): Promise<void>;
+export declare function runInit(opts?: {
+    dryRun?: boolean;
+}): Promise<void>;

package/dist/commands/init.js

@@ -4,39 +4,70 @@ import { collectProjectFiles, isEmptyProject } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
 import { buildEmptyProjectCommand, buildAtomicSteps, buildOrchestratorCommand, } from "../builder.js";
+import { c } from "../output.js";
+import { ensureConfig } from "../config.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
 }
-export async function runInit() {
+export async function runInit(opts = {}) {
+    const dryRun = opts.dryRun ?? false;
+    // Auto-generate .claude-setup.json if it doesn't exist
+    // Developer can edit it anytime to tune token budgets, truncation rules, etc.
+    const configCreated = ensureConfig();
+    if (configCreated) {
+        console.log(`${c.dim("Created .claude-setup.json — edit to tune token budgets and truncation rules")}`);
+    }
     const state = await readState();
     const collected = await collectProjectFiles(process.cwd(), "deep");
-    ensureDir(".claude/commands");
     if (isEmptyProject(collected)) {
         const content = buildEmptyProjectCommand();
+        if (dryRun) {
+            console.log(c.bold("[DRY RUN] Would write:\n"));
+            console.log(`  .claude/commands/stack-init.md (${content.length} chars, ~${Math.ceil(content.length / 4)} tokens)`);
+            console.log(`\n${c.dim("--- preview ---")}`);
+            console.log(content.slice(0, 500));
+            if (content.length > 500)
+                console.log(c.dim(`\n... +${content.length - 500} chars`));
+            return;
+        }
+        ensureDir(".claude/commands");
         writeFileSync(".claude/commands/stack-init.md", content, "utf8");
         await updateManifest("init", collected);
         console.log(`
-✅ New project detected.
+${c.green("✅")} New project detected.
 
 Open Claude Code and run:
-   /stack-init
+   ${c.cyan("/stack-init")}
 
 Claude Code will ask 3 questions, then set up your environment.
     `);
         return;
     }
-    // Standard init — 6 atomic steps + orchestrator
+    // Standard init — atomic steps + orchestrator
     const steps = buildAtomicSteps(collected, state);
+    const orchestrator = buildOrchestratorCommand(steps);
+    if (dryRun) {
+        console.log(c.bold("[DRY RUN] Would write:\n"));
+        for (const step of steps) {
+            const tokens = Math.ceil(step.content.length / 4);
+            console.log(`  .claude/commands/${step.filename} (${step.content.length} chars, ~${tokens} tokens)`);
+        }
+        console.log(`  .claude/commands/stack-init.md (orchestrator)`);
+        const totalTokens = steps.reduce((sum, s) => sum + Math.ceil(s.content.length / 4), 0);
+        console.log(`\n${c.dim(`Total: ~${totalTokens} tokens across ${steps.length} files`)}`);
+        return;
+    }
+    ensureDir(".claude/commands");
     for (const step of steps) {
         writeFileSync(join(".claude/commands", step.filename), step.content, "utf8");
     }
-    writeFileSync(".claude/commands/stack-init.md", buildOrchestratorCommand(steps), "utf8");
+    writeFileSync(".claude/commands/stack-init.md", orchestrator, "utf8");
     await updateManifest("init", collected);
     console.log(`
-✅ Ready. Open Claude Code and run:
-   /stack-init
+${c.green("✅")} Ready. Open Claude Code and run:
+   ${c.cyan("/stack-init")}
 
-Runs 6 atomic steps. If one fails, re-run only that step.
+Runs ${steps.length - 1} atomic steps. If one fails, re-run only that step.
   `);
 }

package/dist/commands/remove.js

@@ -4,6 +4,7 @@ import { collectProjectFiles } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
 import { buildRemoveCommand } from "../builder.js";
+import { c } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
@@ -29,5 +30,5 @@ export async function runRemove() {
     ensureDir(".claude/commands");
     writeFileSync(".claude/commands/stack-remove.md", content, "utf8");
     await updateManifest("remove", collected, { input: userInput });
-    console.log(`\n✅ Ready. Open Claude Code and run:\n   /stack-remove\n`);
+    console.log(`\n${c.green("✅")} Ready. Open Claude Code and run:\n   ${c.cyan("/stack-remove")}\n`);
 }