claude-setup 1.0.0 → 1.1.2

package/dist/doctor.js

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync } from "fs";
 import { execSync } from "child_process";
+import { join } from "path";
 import { readManifest } from "./manifest.js";
 import { readState } from "./state.js";
+import { detectOS } from "./os.js";
+import { c, statusLine, section } from "./output.js";
 function tryExec(cmd) {
     try {
         return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
@@ -20,53 +23,286 @@ function readIfExists(filePath) {
         return null;
     }
 }
-function line(icon, label, detail) {
-    console.log(`  ${icon} ${label}${detail ? ` — ${detail}` : ""}`);
+function safeJsonParse(content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
 }
-export async function runDoctor() {
+export async function runDoctor(verbose = false) {
+    const os = detectOS();
     const manifest = await readManifest();
     const state = await readState();
-    console.log("claude-setup doctor\n");
-    // Claude Code installed?
+    const counts = { critical: 0, warnings: 0, healthy: 0 };
+    console.log(`${c.bold("claude-setup doctor")} — ${new Date().toISOString().split("T")[0]} | OS: ${os}\n`);
+    // --- Check 1: Claude Code version ---
+    section("Environment");
     const cv = tryExec("claude --version");
-    line(cv ? "✅" : "❌", "Claude Code", cv?.trim() ?? "not found");
-    // Manifest?
+    if (cv) {
+        statusLine("✅", "Claude Code", cv.trim());
+        counts.healthy++;
+    }
+    else {
+        statusLine("🔴", "Claude Code", c.red("not found in PATH"));
+        counts.critical++;
+    }
+    // --- Check 2: Manifest integrity ---
     const lastRun = manifest?.runs.at(-1);
-    line(manifest ? "✅" : "⚠️ ", ".claude/claude-setup.json", manifest ? `last: ${lastRun?.command} at ${lastRun?.at}` : "not found — run: npx claude-setup init");
-    // Files from last run still on disk?
-    if (lastRun?.filesRead.length) {
-        console.log("\nFiles from last run (sample):");
-        for (const f of lastRun.filesRead.slice(0, 8)) {
-            line(existsSync(f) ? "✅" : "⚠️ ", f, existsSync(f) ? "" : "not found on disk");
+    if (manifest) {
+        const staleCheck = lastRun ? checkStaleness(lastRun.at) : null;
+        const detail = lastRun
+            ? `last: ${lastRun.command} at ${lastRun.at}${staleCheck ? ` ${staleCheck}` : ""}`
+            : "empty runs array";
+        statusLine("✅", "Manifest", detail);
+        counts.healthy++;
+    }
+    else {
+        statusLine("⚠️ ", "Manifest", c.yellow("not found — run: npx claude-setup init"));
+        counts.warnings++;
+    }
+    // --- Check 3: OS/MCP format mismatch ---
+    if (state.mcpJson.content) {
+        section("MCP servers");
+        const mcp = safeJsonParse(state.mcpJson.content);
+        if (mcp && typeof mcp.mcpServers === "object" && mcp.mcpServers !== null) {
+            const servers = mcp.mcpServers;
+            for (const [name, config] of Object.entries(servers)) {
+                const cmd = config.command;
+                if (!cmd) {
+                    statusLine("⚠️ ", name, c.yellow("no command field"));
+                    counts.warnings++;
+                    continue;
+                }
+                if (os === "Windows" && cmd === "npx") {
+                    statusLine("🔴", name, c.red(`BROKEN: Windows can't execute npx directly — use cmd /c npx`));
+                    counts.critical++;
+                }
+                else if (os !== "Windows" && cmd === "cmd") {
+                    statusLine("⚠️ ", name, c.yellow(`UNNECESSARY: cmd wrapper not needed on ${os}`));
+                    counts.warnings++;
+                }
+                else {
+                    statusLine("✅", name, `valid, OS-format correct (${cmd})`);
+                    counts.healthy++;
+                }
+            }
+        }
+        else if (mcp) {
+            // Check for flat structure (some .mcp.json files use flat keys)
+            if (verbose)
+                statusLine("⚠️ ", ".mcp.json", "no mcpServers key found");
+        }
+    }
+    else if (verbose) {
+        section("MCP servers");
+        statusLine("⏭ ", ".mcp.json", "does not exist");
+    }
+    // --- Check 4: Hook quoting bugs ---
+    if (state.settings.content) {
+        section("Hooks");
+        const settings = safeJsonParse(state.settings.content);
+        if (settings) {
+            const hookCategories = [
+                "PreToolUse", "PostToolUse", "PreCompact", "PostCompact",
+                "Notification", "Stop", "SubagentStop"
+            ];
+            let foundHooks = false;
+            for (const category of hookCategories) {
+                const hooks = settings[category];
+                if (!hooks || !Array.isArray(hooks))
+                    continue;
+                for (const hook of hooks) {
+                    if (typeof hook !== "object" || !hook)
+                        continue;
+                    const h = hook;
+                    const hookCmd = h.command;
+                    const args = h.args;
+                    if (!hookCmd || !args)
+                        continue;
+                    foundHooks = true;
+                    // Check for bash -c quoting bugs
+                    if (hookCmd === "bash" && args[0] === "-c" && args[1]) {
+                        const shellStr = args[1];
+                        const quotingIssue = checkBashQuoting(shellStr);
+                        if (quotingIssue) {
+                            statusLine("🔴", `${category} hook`, c.red(`quoting bug: ${quotingIssue}`));
+                            counts.critical++;
+                        }
+                        else {
+                            statusLine("✅", `${category} hook`, "quoting clean");
+                            counts.healthy++;
+                        }
+                    }
+                    else {
+                        statusLine("✅", `${category} hook`, "valid");
+                        counts.healthy++;
+                    }
+                }
+            }
+            if (!foundHooks && verbose) {
+                statusLine("⏭ ", "Hooks", "none configured");
+            }
         }
     }
-    // Env vars in .mcp.json present in env template?
+    else if (verbose) {
+        section("Hooks");
+        statusLine("⏭ ", "settings.json", "does not exist");
+    }
+    // --- Check 5: Env var coverage ---
     if (state.mcpJson.content) {
         const refs = [...state.mcpJson.content.matchAll(/\$\{?([A-Z_][A-Z0-9_]+)\}?/g)]
             .map(m => m[1]);
         const unique = [...new Set(refs)];
         if (unique.length) {
-            const template = readIfExists(".env.example") ?? readIfExists(".env.sample") ?? "";
-            console.log("\nMCP environment variables:");
+            const template = readIfExists(".env.example") ?? readIfExists(".env.sample") ?? readIfExists(".env.template") ?? "";
+            section("Env vars");
             for (const v of unique) {
-                line(template.includes(v) ? "✅" : "⚠️ ", v, template.includes(v) ? "found in env template" : "missing from .env.example");
+                if (template.includes(v)) {
+                    statusLine("✅", `\${${v}}`, "found in env template");
+                    counts.healthy++;
+                }
+                else {
+                    statusLine("⚠️ ", `\${${v}}`, c.yellow("used in .mcp.json but missing from .env.example"));
+                    counts.warnings++;
+                }
             }
         }
     }
-    // Workflow secrets
+    // --- Check 6: Workflow secret coverage ---
     if (state.workflows.length) {
         const secrets = new Set();
         for (const wf of state.workflows) {
             const content = readIfExists(wf) ?? "";
-            for (const m of content.matchAll(/\$\{\{\s*secrets\.([A-Z_]+)\s*\}\}/g)) {
+            for (const m of content.matchAll(/\$\{\{\s*secrets\.([A-Z_][A-Z0-9_]*)\s*\}\}/g)) {
                 secrets.add(m[1]);
             }
         }
         if (secrets.size) {
-            console.log("\nWorkflow secrets (add to GitHub Settings → Secrets):");
-            for (const s of secrets)
-                console.log(`  ⚠️  ${s}`);
+            section("Workflow secrets");
+            const readme = readIfExists("README.md") ?? "";
+            const envTemplate = readIfExists(".env.example") ?? readIfExists(".env.sample") ?? "";
+            for (const s of secrets) {
+                if (readme.includes(s) || envTemplate.includes(s)) {
+                    statusLine("✅", s, "documented");
+                    counts.healthy++;
+                }
+                else {
+                    statusLine("⚠️ ", s, c.yellow("needs GitHub Settings → Secrets"));
+                    counts.warnings++;
+                }
+            }
         }
     }
-    console.log("\n✅ Done.");
+    // --- Check 7: Stale skill paths ---
+    if (state.skills.length) {
+        section("Skills");
+        for (const skillPath of state.skills) {
+            const content = readIfExists(skillPath);
+            if (!content) {
+                statusLine("⚠️ ", skillPath, c.yellow("skill file not readable"));
+                counts.warnings++;
+                continue;
+            }
+            // Extract file/dir references from skill content
+            const pathRefs = extractPathReferences(content);
+            const staleRefs = pathRefs.filter(ref => !existsSync(ref) && !existsSync(join(process.cwd(), ref)));
+            if (staleRefs.length) {
+                statusLine("⚠️ ", skillPath, c.yellow(`stale paths: ${staleRefs.join(", ")}`));
+                counts.warnings++;
+            }
+            else {
+                statusLine("✅", skillPath, "valid");
+                counts.healthy++;
+            }
+        }
+    }
+    else if (verbose) {
+        section("Skills");
+        statusLine("⏭ ", "Skills", "none installed");
+    }
+    // --- Check 8: Files from last run still on disk ---
+    // Filter __digest__ — it's a virtual key, not a real file
+    if (lastRun?.filesRead.length && verbose) {
+        section("Files from last run");
+        const realFiles = lastRun.filesRead.filter(f => f !== "__digest__" && f !== ".env");
+        for (const f of realFiles.slice(0, 8)) {
+            if (existsSync(f)) {
+                statusLine("✅", f, "");
+                counts.healthy++;
+            }
+            else {
+                statusLine("⚠️ ", f, c.yellow("not found on disk"));
+                counts.warnings++;
+            }
+        }
+        if (realFiles.length > 8) {
+            console.log(c.dim(`  ... +${realFiles.length - 8} more`));
+        }
+    }
+    // --- Summary ---
+    console.log("");
+    section("Summary");
+    if (counts.critical > 0)
+        console.log(`  🔴 ${c.red(`${counts.critical} critical`)} (will break Claude Code)`);
+    if (counts.warnings > 0)
+        console.log(`  ⚠️  ${c.yellow(`${counts.warnings} warning(s)`)} (degraded behavior)`);
+    console.log(`  ✅ ${c.green(`${counts.healthy} healthy`)}`);
+    if (counts.critical > 0) {
+        console.log(`\n${c.red("Fix critical issues first.")} Run ${c.cyan("npx claude-setup sync")} after fixing.`);
+    }
+    else {
+        console.log(`\n${c.green("✅ Done.")}`);
+    }
+}
+// --- Helpers ---
+function checkStaleness(lastRunDate) {
+    try {
+        const last = new Date(lastRunDate).getTime();
+        const now = Date.now();
+        const daysSince = Math.floor((now - last) / (1000 * 60 * 60 * 24));
+        if (daysSince > 7)
+            return c.yellow(`(${daysSince} days ago — may be stale)`);
+    }
+    catch { /* invalid date */ }
+    return null;
+}
+function checkBashQuoting(shellStr) {
+    // Check for unescaped double quotes inside the command string
+    // The -c "..." outer string must never contain a bare " character
+    let inSingleQuote = false;
+    let prevChar = "";
+    for (let i = 0; i < shellStr.length; i++) {
+        const ch = shellStr[i];
+        if (ch === "'" && prevChar !== "\\") {
+            inSingleQuote = !inSingleQuote;
+        }
+        // Unescaped double quote inside single-quoted context is a problem
+        // when the outer wrapper is double quotes
+        if (ch === '"' && !inSingleQuote && prevChar !== "\\") {
+            // Check for patterns like ["'] which mix quote types
+            if (i > 0 && shellStr[i - 1] === "[") {
+                return `mixed quotes in character class at position ${i}: ...${shellStr.slice(Math.max(0, i - 10), i + 10)}...`;
+            }
+        }
+        prevChar = ch;
+    }
+    // Check for unmatched brackets in grep patterns
+    const bracketCount = (shellStr.match(/\[/g) || []).length;
+    const closeBracketCount = (shellStr.match(/\]/g) || []).length;
+    if (bracketCount !== closeBracketCount) {
+        return "unmatched brackets in pattern";
+    }
+    return null;
+}
+function extractPathReferences(skillContent) {
+    const paths = [];
+    // Match file/directory references in skill content
+    // Look for patterns like src/, lib/, *.ts references
+    const pathPatterns = skillContent.matchAll(/(?:^|\s)((?:src|lib|app|cmd|bin|pkg|internal|api|core|test|tests|spec)\/[\w/.\\-]*)/gm);
+    for (const m of pathPatterns) {
+        paths.push(m[1].trim());
+    }
+    return paths;
 }

package/dist/index.js

@@ -5,20 +5,42 @@ import { runInit } from "./commands/init.js";
 import { runAdd } from "./commands/add.js";
 import { runSync } from "./commands/sync.js";
 import { runStatus } from "./commands/status.js";
-import { runDoctor } from "./commands/doctor.js";
+import { runDoctorCommand } from "./commands/doctor.js";
 import { runRemove } from "./commands/remove.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
 const program = new Command();
 program
     .name("claude-setup")
-    .description("Setup layer for Claude Code")
+    .description("Setup layer for Claude Code — reads your project, writes command files, Claude Code does the rest")
     .version(pkg.version);
-program.command("init").description("Full project setup — new or existing").action(runInit);
-program.command("add").description("Add a multi-file capability").action(runAdd);
-program.command("sync").description("Update setup after project changes").action(runSync);
-program.command("status").description("Show current setup (instant)").action(runStatus);
-program.command("doctor").description("Validate environment").action(runDoctor);
-program.command("remove").description("Remove a capability cleanly").action(runRemove);
-program.action(runInit);
+program
+    .command("init")
+    .description("Full project setup — new or existing")
+    .option("--dry-run", "Preview what would be written without writing")
+    .action((opts) => runInit({ dryRun: opts.dryRun }));
+program
+    .command("add")
+    .description("Add a multi-file capability")
+    .action(runAdd);
+program
+    .command("sync")
+    .description("Update setup after project changes")
+    .option("--dry-run", "Preview changes without writing")
+    .action((opts) => runSync({ dryRun: opts.dryRun }));
+program
+    .command("status")
+    .description("Show current setup state (instant, no file reads)")
+    .action(runStatus);
+program
+    .command("doctor")
+    .description("Validate environment — OS, MCP, hooks, env vars, skills")
+    .option("-v, --verbose", "Show passing checks too")
+    .action((opts) => runDoctorCommand({ verbose: opts.verbose }));
+program
+    .command("remove")
+    .description("Remove a capability cleanly")
+    .action(runRemove);
+// Default action when no command given
+program.action(() => runInit({}));
 program.parse();

package/dist/os.d.ts

@@ -0,0 +1,20 @@
+export type DetectedOS = "Windows" | "macOS" | "Linux";
+/**
+ * Detect OS once per session. Order per spec:
+ * 1. COMSPEC set → Windows
+ * 2. OS === "Windows_NT" → Windows
+ * 3. process.platform === "win32" → Windows
+ * 4. uname() === "Darwin" → macOS
+ * 5. default → Linux
+ */
+export declare function detectOS(): DetectedOS;
+/** MCP command format per OS */
+export declare function mcpCommandFormat(os: DetectedOS, pkg: string): {
+    command: string;
+    args: string[];
+};
+/** Hook shell format per OS */
+export declare function hookShellFormat(os: DetectedOS, cmd: string): {
+    command: string;
+    args: string[];
+};

package/dist/os.js

@@ -0,0 +1,38 @@
+import { execSync } from "child_process";
+/**
+ * Detect OS once per session. Order per spec:
+ * 1. COMSPEC set → Windows
+ * 2. OS === "Windows_NT" → Windows
+ * 3. process.platform === "win32" → Windows
+ * 4. uname() === "Darwin" → macOS
+ * 5. default → Linux
+ */
+export function detectOS() {
+    if (process.env.COMSPEC)
+        return "Windows";
+    if (process.env.OS === "Windows_NT")
+        return "Windows";
+    if (process.platform === "win32")
+        return "Windows";
+    try {
+        const uname = execSync("uname", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        if (uname === "Darwin")
+            return "macOS";
+    }
+    catch { /* not unix — unlikely to reach here */ }
+    return "Linux";
+}
+/** MCP command format per OS */
+export function mcpCommandFormat(os, pkg) {
+    if (os === "Windows") {
+        return { command: "cmd", args: ["/c", "npx", pkg] };
+    }
+    return { command: "npx", args: [pkg] };
+}
+/** Hook shell format per OS */
+export function hookShellFormat(os, cmd) {
+    if (os === "Windows") {
+        return { command: "cmd", args: ["/c", cmd] };
+    }
+    return { command: "bash", args: ["-c", cmd] };
+}

package/dist/output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Terminal output helpers — no dependencies.
+ * Raw ANSI codes. Falls back gracefully if NO_COLOR or piped.
+ */
+export declare const c: {
+    bold: (t: string) => string;
+    dim: (t: string) => string;
+    red: (t: string) => string;
+    green: (t: string) => string;
+    yellow: (t: string) => string;
+    blue: (t: string) => string;
+    cyan: (t: string) => string;
+    gray: (t: string) => string;
+};
+/** Print a status line: icon + label + optional detail */
+export declare function statusLine(icon: string, label: string, detail?: string): void;
+/** Print a section header */
+export declare function section(title: string): void;

package/dist/output.js

@@ -0,0 +1,40 @@
+/**
+ * Terminal output helpers — no dependencies.
+ * Raw ANSI codes. Falls back gracefully if NO_COLOR or piped.
+ */
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const codes = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+};
+function wrap(code, text) {
+    if (!supportsColor)
+        return text;
+    return `${code}${text}${codes.reset}`;
+}
+export const c = {
+    bold: (t) => wrap(codes.bold, t),
+    dim: (t) => wrap(codes.dim, t),
+    red: (t) => wrap(codes.red, t),
+    green: (t) => wrap(codes.green, t),
+    yellow: (t) => wrap(codes.yellow, t),
+    blue: (t) => wrap(codes.blue, t),
+    cyan: (t) => wrap(codes.cyan, t),
+    gray: (t) => wrap(codes.gray, t),
+};
+/** Print a status line: icon + label + optional detail */
+export function statusLine(icon, label, detail) {
+    const detailStr = detail ? ` — ${detail}` : "";
+    console.log(`  ${icon} ${label}${detailStr}`);
+}
+/** Print a section header */
+export function section(title) {
+    console.log(`\n${c.bold(title)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-setup",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "description": "Setup layer for Claude Code — reads your project, writes command files, Claude Code does the rest",
   "type": "module",
   "bin": {

package/templates/add.md

@@ -1,18 +1,9 @@
-<!-- Generated by claude-setup add — {{DATE}} -->
-<!-- Run /stack-add in Claude Code -->
+<!-- claude-setup add {{DATE}} -->
 
-The developer wants to add this to their Claude Code setup:
-"{{USER_INPUT}}"
-
----
+Add to Claude Code setup: "{{USER_INPUT}}"
 
 ## Project context
-
-{{CONFIG_FILES}}
-
-{{SOURCE_FILES}}
-
----
+{{PROJECT_CONTEXT}}
 
 ## Current setup — read before writing anything
 
@@ -27,38 +18,20 @@ The developer wants to add this to their Claude Code setup:
 {{/if}}
 
 {{#if HAS_SETTINGS}}
-### .claude/settings.json
+### settings.json
 {{SETTINGS_CONTENT}}
 {{/if}}
 
-Skills installed:   {{SKILLS_LIST}}
-Commands installed: {{COMMANDS_LIST}}
-
----
-
-## Your job
-
-Figure out which files need to change to fulfill the request.
-Adding a capability to Claude Code is rarely one file — it usually means touching
-CLAUDE.md, possibly an MCP entry, possibly a skill, possibly a hook.
-
-For every file you touch:
-- Read its current content above first
-- Merge and append only
-- Do not duplicate what already exists
-- Extend existing files rather than creating parallel ones
-
-If the request mentions something not evidenced in the project files: say so and ask
-whether they want to add it generically or need to add the underlying service first.
-
----
-
-## Output format — strict
-
-Updated:
-  ✅ [path] — [what changed and why]
+Skills: {{SKILLS_LIST}} | Commands: {{COMMANDS_LIST}}
 
-Skipped:
-  ⏭  [path] — [why not needed for this request]
+## Rules
+- Read current content above before writing. Merge/append only.
+- If request mentions something not evidenced in project files: ask first.
+- OS detected: {{DETECTED_OS}}. Use correct command format for MCP/hooks:
+  - Windows: `{ "command": "cmd", "args": ["/c", "npx", "<pkg>"] }`
+  - macOS/Linux: `{ "command": "npx", "args": ["<pkg>"] }`
+- All env var refs use `${VARNAME}` syntax. Document new vars in .env.example.
 
-One line per file. Nothing else.
+## Output — one line per file
+Updated: ✅ [path] — [what and why]
+Skipped: ⏭ [path] — [why not needed for this request]