claude-setup 1.0.0 → 1.1.1

package/README.md

@@ -1,51 +1,45 @@
-# 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)
-
-## Cost controls
-
-Every byte in a command file costs tokens. The CLI enforces:
-- Source file sampling (max 10 files, smallest first)
-- Hard truncation per file (150/400 line thresholds)
-- Token budget cap (20,000 tokens max per command file)
-- Universal blocklist (node_modules, dist, binaries, etc.)
+# 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)
+
+

package/dist/builder.js

@@ -1,17 +1,15 @@
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { loadConfig } from "./config.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, "..", "templates");
-const TOKEN_SOFT_WARN = 8_000;
-const TOKEN_HARD_CAP = 20_000;
 function estimateTokens(content) {
     return Math.ceil(content.length / 4);
 }
 function loadTemplate(name) {
     return readFileSync(join(TEMPLATES_DIR, name), "utf8");
 }
-// Simple {{VARIABLE}} replacement
 function replaceVars(template, vars) {
     let result = template;
     for (const [key, value] of Object.entries(vars)) {
@@ -19,56 +17,57 @@ function replaceVars(template, vars) {
     }
     return result;
 }
-// Conditional blocks: {{#if VAR}}...{{else}}...{{/if}} and {{#if VAR}}...{{/if}}
 function processConditionals(template, flags) {
-    // Handle {{#if VAR}}...{{else}}...{{/if}}
     let result = template;
-    const ifElseRegex = /\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{else\}\}\n?([\s\S]*?)\{\{\/if\}\}/g;
-    result = result.replace(ifElseRegex, (_match, key, ifBlock, elseBlock) => {
-        return flags[key] ? ifBlock : elseBlock;
-    });
-    // Handle {{#if VAR}}...{{/if}} (no else)
-    const ifRegex = /\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{\/if\}\}/g;
-    result = result.replace(ifRegex, (_match, key, block) => {
-        return flags[key] ? block : "";
-    });
+    // {{#if VAR}}...{{else}}...{{/if}}
+    result = result.replace(/\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{else\}\}\n?([\s\S]*?)\{\{\/if\}\}/g, (_m, key, ifBlock, elseBlock) => flags[key] ? ifBlock : elseBlock);
+    // {{#if VAR}}...{{/if}}
+    result = result.replace(/\{\{#if\s+(\w+)\}\}\n?([\s\S]*?)\{\{\/if\}\}/g, (_m, key, block) => flags[key] ? block : "");
     return result;
 }
-function formatConfigFiles(configs) {
-    if (Object.keys(configs).length === 0)
-        return "(no config files found)";
-    return Object.entries(configs)
-        .map(([path, content]) => {
-        return `#### ${path}\n\`\`\`\n${content}\n\`\`\``;
-    })
-        .join("\n\n");
+function formatList(items) {
+    return items.length === 0 ? "none" : items.join(", ");
+}
+function getVersion() {
+    try {
+        return JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
 }
-function formatSourceFiles(source) {
+// --- Project context formatter ---
+// This is the key optimization: instead of dumping raw files, we format
+// the digest compactly. Full file content only when truly needed.
+function formatProjectContext(collected) {
+    const lines = [];
+    // Digest (compact signal extraction)
+    const digest = collected.configs["__digest__"];
+    if (digest) {
+        lines.push(digest);
+    }
+    // Additional config files that kept full content (docker-compose, etc.)
+    for (const [name, content] of Object.entries(collected.configs)) {
+        if (name === "__digest__" || name === ".env")
+            continue;
+        lines.push(`\n### ${name}\n\`\`\`\n${content}\n\`\`\``);
+    }
+    return lines.join("\n") || "(no config files found)";
+}
+function formatSourceContext(source) {
     if (source.length === 0)
-        return "(no source files sampled)";
+        return "";
     return source
-        .map(({ path, content }) => {
-        return `#### ${path}\n\`\`\`\n${content}\n\`\`\``;
-    })
+        .map(({ path, content }) => `### ${path}\n\`\`\`\n${content}\n\`\`\``)
         .join("\n\n");
 }
-function formatSkippedFiles(skipped) {
-    return skipped.map(({ path, reason }) => `- ${path} — ${reason}`).join("\n");
-}
-function formatList(items) {
-    if (items.length === 0)
-        return "none";
-    return items.join(", ");
-}
+// --- Template variable building ---
 function buildVars(collected, state) {
-    const version = getVersion();
-    const date = new Date().toISOString().split("T")[0];
     return {
-        VERSION: version,
-        DATE: date,
-        CONFIG_FILES: formatConfigFiles(collected.configs),
-        SOURCE_FILES: formatSourceFiles(collected.source),
-        SKIPPED_LIST: formatSkippedFiles(collected.skipped),
+        VERSION: getVersion(),
+        DATE: new Date().toISOString().split("T")[0],
+        PROJECT_CONTEXT: formatProjectContext(collected),
+        SOURCE_CONTEXT: formatSourceContext(collected.source),
         CLAUDE_MD_CONTENT: state.claudeMd.content
             ? `\`\`\`\n${state.claudeMd.content}\n\`\`\``
             : "",
@@ -84,158 +83,148 @@ function buildVars(collected, state) {
         HAS_GITHUB_DIR: state.hasGithubDir ? "yes" : "no",
     };
 }
-function buildFlags(collected, state) {
+function buildFlags(_collected, state) {
     return {
-        HAS_SKIPPED: collected.skipped.length > 0,
+        HAS_SOURCE: _collected.source.length > 0,
         HAS_CLAUDE_MD: state.claudeMd.exists,
         HAS_MCP_JSON: state.mcpJson.exists,
         HAS_SETTINGS: state.settings.exists,
         HAS_GITHUB_DIR: state.hasGithubDir,
     };
 }
-function getVersion() {
-    try {
-        const pkgPath = join(__dirname, "..", "package.json");
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        return pkg.version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
-function fitToTokenBudget(content, sources) {
-    if (estimateTokens(content) <= TOKEN_HARD_CAP)
+// --- Token budget enforcement ---
+function fitToTokenBudget(content, sources, hardCap) {
+    if (estimateTokens(content) <= hardCap)
         return content;
-    // Progressively remove source files, largest first
+    // Remove source files largest-first until under budget
     const sorted = [...sources].sort((a, b) => b.content.length - a.content.length);
     for (const remove of sorted) {
-        const sourceBlock = `#### ${remove.path}\n\`\`\`\n${remove.content}\n\`\`\``;
-        content = content.replace(sourceBlock, `[${remove.path} — removed to fit token budget]`);
-        if (estimateTokens(content) <= TOKEN_HARD_CAP)
+        const block = `### ${remove.path}\n\`\`\`\n${remove.content}\n\`\`\``;
+        content = content.replace(block, `[${remove.path} — trimmed]`);
+        if (estimateTokens(content) <= hardCap)
             break;
     }
     return content;
 }
-function applyTemplate(templateName, collected, state, extraVars = {}) {
+function applyTemplate(templateName, collected, state, extraVars = {}, budgetKey = "init") {
+    const config = loadConfig();
+    const budget = config.tokenBudget[budgetKey];
     const template = loadTemplate(templateName);
     const vars = { ...buildVars(collected, state), ...extraVars };
     const flags = buildFlags(collected, state);
     let content = replaceVars(template, vars);
     content = processConditionals(content, flags);
     const tokens = estimateTokens(content);
-    if (tokens > TOKEN_SOFT_WARN) {
-        console.warn(`⚠️  Command file is ${tokens} tokens (soft limit: ${TOKEN_SOFT_WARN})`);
+    if (tokens > budget) {
+        content = fitToTokenBudget(content, collected.source, budget);
+        const finalTokens = estimateTokens(content);
+        if (finalTokens > budget) {
+            console.warn(`⚠️  ${templateName}: ${finalTokens} tokens (budget: ${budget})`);
+        }
     }
-    content = fitToTokenBudget(content, collected.source);
     return content;
 }
+// --- Public API ---
 export function buildInitCommand(collected, state) {
-    return applyTemplate("init.md", collected, state);
+    return applyTemplate("init.md", collected, state, {}, "init");
 }
 export function buildEmptyProjectCommand() {
     const template = loadTemplate("init-empty.md");
-    const version = getVersion();
-    const date = new Date().toISOString().split("T")[0];
-    return replaceVars(template, { VERSION: version, DATE: date });
+    return replaceVars(template, { VERSION: getVersion(), DATE: new Date().toISOString().split("T")[0] });
 }
 export function buildAddCommand(input, collected, state) {
-    return applyTemplate("add.md", collected, state, { USER_INPUT: input });
+    return applyTemplate("add.md", collected, state, { USER_INPUT: input }, "add");
 }
 export function buildSyncCommand(diff, collected, state) {
-    const lastRun = state.manifest?.runs.at(-1);
+    // Compact diff format — paths + one-line summary, not full content
     const addedStr = diff.added.length > 0
-        ? diff.added.map(f => `#### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``).join("\n\n")
+        ? diff.added.map(f => `- **${f.path}** (new) — ${f.content.split("\n").length} lines`).join("\n")
         : "(none)";
     const modifiedStr = diff.changed.length > 0
-        ? diff.changed.map(f => `#### ${f.path}\n\`\`\`\n${f.current}\n\`\`\``).join("\n\n")
+        ? diff.changed.map(f => `- **${f.path}** (modified)`).join("\n")
         : "(none)";
     const deletedStr = diff.deleted.length > 0
         ? diff.deleted.map(f => `- ${f}`).join("\n")
         : "(none)";
+    const lastRun = state.manifest?.runs.at(-1);
     return applyTemplate("sync.md", collected, state, {
         LAST_RUN_DATE: lastRun?.at ?? "unknown",
         ADDED_FILES: addedStr,
         MODIFIED_FILES: modifiedStr,
         DELETED_FILES: deletedStr,
-    });
+    }, "sync");
 }
 export function buildRemoveCommand(input, state) {
-    // Remove uses a minimal collected set — no project files needed
     const emptyCollected = { configs: {}, source: [], skipped: [] };
-    return applyTemplate("remove.md", emptyCollected, state, { USER_INPUT: input });
+    return applyTemplate("remove.md", emptyCollected, state, { USER_INPUT: input }, "remove");
 }
 export function buildAtomicSteps(collected, state) {
-    const fullContent = buildInitCommand(collected, state);
-    const vars = buildVars(collected, state);
-    const flags = buildFlags(collected, state);
     const version = getVersion();
     const date = new Date().toISOString().split("T")[0];
-    const preamble = `<!-- Generated by claude-setup ${version} on ${date} — DO NOT hand-edit -->\n`;
-    const idempotentCheck = `\nBefore writing: check if what you are about to write already exists in the target file\n(current content provided below). If yes: print "SKIPPED — already up to date" and stop.\nWrite only what is genuinely missing.\n\n`;
-    // Each step gets project context + specific instructions for its target
+    const vars = buildVars(collected, state);
+    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 sharedContext = header +
+        `## Project\n\n${vars.PROJECT_CONTEXT}\n\n` +
+        `{{#if HAS_SOURCE}}## Source samples\n\n${vars.SOURCE_CONTEXT}\n{{/if}}`;
+    const sharedContextProcessed = processConditionals(sharedContext, buildFlags(collected, state));
     const steps = [
+        {
+            filename: "stack-0-context.md",
+            content: sharedContextProcessed,
+        },
         {
             filename: "stack-1-claude-md.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n${vars.SOURCE_FILES}\n\n` +
-                `## Target: CLAUDE.md\n\n` +
+            content: header + check +
+                `Read /stack-0-context for project info.\n\n` +
+                `## Target: CLAUDE.md\n` +
                 (state.claudeMd.exists
-                    ? `### Current CLAUDE.md — EXISTS — append only, never rewrite, never remove\n${vars.CLAUDE_MD_CONTENT}\n\n`
-                    : `CLAUDE.md does not exist. Create it.\n\n`) +
-                `Write or update CLAUDE.md for THIS specific project.\nMake it specific: reference actual file paths, actual patterns, actual conventions from the source above.\nNo generic boilerplate. Every line must trace back to something in the project files.\n` +
-                (state.claudeMd.exists ? `\nAppend only — never rewrite or remove existing content.` : ""),
+                    ? `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.`,
         },
         {
             filename: "stack-2-mcp.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
-                `## Target: .mcp.json\n\n` +
+            content: header + check +
+                `Read /stack-0-context for project info.\n\n` +
+                `## Target: .mcp.json\n` +
                 (state.mcpJson.exists
-                    ? `### Current .mcp.json — EXISTS — merge only, never remove existing entries\n${vars.MCP_JSON_CONTENT}\n\n`
-                    : `.mcp.json does not exist. Create only if you find evidence of external services in the config files above.\n\n`) +
-                `Only add MCP servers for services evidenced in the project files. No evidence = no server.\n` +
-                (state.mcpJson.exists ? `Merge only — never remove existing entries. Produce valid JSON.` : ""),
+                    ? `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.`,
         },
         {
             filename: "stack-3-settings.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
-                `## Target: .claude/settings.json\n\n` +
+            content: header + check +
+                `Read /stack-0-context for project info.\n\n` +
+                `## Target: .claude/settings.json\n` +
                 (state.settings.exists
-                    ? `### Current settings.json — EXISTS — merge only, never remove existing hooks\n${vars.SETTINGS_CONTENT}\n\n`
-                    : `.claude/settings.json does not exist. Create only if hooks are genuinely warranted for this project.\n\n`) +
-                `Every hook adds overhead on every Claude Code action. Only add if clearly earned for THIS project.\n` +
-                (state.settings.exists ? `Merge only — never remove existing hooks. Never modify existing values.` : ""),
+                    ? `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.`,
         },
         {
             filename: "stack-4-skills.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n${vars.SOURCE_FILES}\n\n` +
-                `## Target: .claude/skills/\n\n` +
-                `Skills installed: ${vars.SKILLS_LIST}\n\n` +
-                `Only create skills for patterns that recur across this codebase and benefit from automatic loading.\n` +
-                `Use applies-when frontmatter so skills load only when relevant.\n` +
-                `If a similar skill already exists: extend it. Do not create a parallel one.\n` +
-                `Empty is fine — not every project needs skills.`,
+            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.`,
         },
         {
             filename: "stack-5-commands.md",
-            content: preamble + idempotentCheck +
-                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
-                `## Target: .claude/commands/ (not stack-*.md files)\n\n` +
-                `Commands installed: ${vars.COMMANDS_LIST}\n\n` +
-                `Only create commands that will actually be useful for this kind of project.\n` +
-                `Do not duplicate existing commands. Do not create stack-*.md files.`,
+            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.`,
         },
         {
             filename: "stack-6-workflows.md",
-            content: preamble + idempotentCheck +
-                `## Target: .github/workflows/\n\n` +
-                `.github/ exists: ${vars.HAS_GITHUB_DIR}\n` +
-                `Workflows installed: ${vars.WORKFLOWS_LIST}\n\n` +
+            content: header + check +
+                `## Target: .github/workflows/\n.github/ exists: ${vars.HAS_GITHUB_DIR}\nInstalled: ${vars.WORKFLOWS_LIST}\n\n` +
                 (state.hasGithubDir
-                    ? `Only create workflows warranted by the project. If workflows already exist: do not touch them.`
-                    : `.github/ does not exist. Only create workflows if the project clearly warrants them.`),
+                    ? `Only warranted workflows. Don't touch existing ones.`
+                    : `Only create if clearly warranted.`),
         },
     ];
     return steps;
@@ -243,17 +232,17 @@ export function buildAtomicSteps(collected, state) {
 export function buildOrchestratorCommand(steps) {
     const version = getVersion();
     const date = new Date().toISOString().split("T")[0];
-    const stepList = steps
+    // Skip step 0 (context) in the run list — it's referenced by other steps
+    const runSteps = steps.filter(s => s.filename !== "stack-0-context.md");
+    const stepList = runSteps
         .map((s, i) => `${i + 1}. /${s.filename.replace(".md", "")}`)
         .join("\n");
-    return `<!-- Generated by claude-setup ${version} on ${date} — DO NOT hand-edit -->
-<!-- Run /stack-init in Claude Code -->
+    return `<!-- claude-setup ${version} ${date} -->
 
-Run these in order. If one fails, fix it and continue from that step only.
-Do not re-run steps that already completed.
+Run these in order. If one fails, fix and continue from that step.
 
 ${stepList}
 
-After all steps complete: one-line summary of what was created.
+After all complete: one-line summary of what was created.
 `;
 }

package/dist/collect.d.ts

@@ -9,5 +9,14 @@ export interface CollectedFiles {
         reason: string;
     }>;
 }
-export declare function collectProjectFiles(cwd?: string): Promise<CollectedFiles>;
+export interface ProjectDigest {
+    configFilesFound: string[];
+    deps: string[];
+    scripts: string[];
+    tree: string;
+    envVars: string[];
+    configs: Record<string, string>;
+}
+export type CollectMode = "deep" | "normal" | "configOnly";
+export declare function collectProjectFiles(cwd?: string, mode?: CollectMode): Promise<CollectedFiles>;
 export declare function isEmptyProject(collected: CollectedFiles): boolean;