claude-setup 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AbdoKnbGit
+
+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

@@ -0,0 +1,51 @@
+# 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.)

package/dist/builder.d.ts

@@ -0,0 +1,24 @@
+import { CollectedFiles } from "./collect.js";
+import { ExistingState } from "./state.js";
+export declare function buildInitCommand(collected: CollectedFiles, state: ExistingState): string;
+export declare function buildEmptyProjectCommand(): string;
+export declare function buildAddCommand(input: string, collected: CollectedFiles, state: ExistingState): string;
+export interface FileDiff {
+    added: Array<{
+        path: string;
+        content: string;
+    }>;
+    changed: Array<{
+        path: string;
+        current: string;
+    }>;
+    deleted: string[];
+}
+export declare function buildSyncCommand(diff: FileDiff, collected: CollectedFiles, state: ExistingState): string;
+export declare function buildRemoveCommand(input: string, state: ExistingState): string;
+export interface AtomicStep {
+    filename: string;
+    content: string;
+}
+export declare function buildAtomicSteps(collected: CollectedFiles, state: ExistingState): AtomicStep[];
+export declare function buildOrchestratorCommand(steps: AtomicStep[]): string;

package/dist/builder.js

@@ -0,0 +1,259 @@
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+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)) {
+        result = result.replaceAll(`{{${key}}}`, value);
+    }
+    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 : "";
+    });
+    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 formatSourceFiles(source) {
+    if (source.length === 0)
+        return "(no source files sampled)";
+    return source
+        .map(({ path, content }) => {
+        return `#### ${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(", ");
+}
+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),
+        CLAUDE_MD_CONTENT: state.claudeMd.content
+            ? `\`\`\`\n${state.claudeMd.content}\n\`\`\``
+            : "",
+        MCP_JSON_CONTENT: state.mcpJson.content
+            ? `\`\`\`json\n${state.mcpJson.content}\n\`\`\``
+            : "",
+        SETTINGS_CONTENT: state.settings.content
+            ? `\`\`\`json\n${state.settings.content}\n\`\`\``
+            : "",
+        SKILLS_LIST: formatList(state.skills),
+        COMMANDS_LIST: formatList(state.commands),
+        WORKFLOWS_LIST: formatList(state.workflows),
+        HAS_GITHUB_DIR: state.hasGithubDir ? "yes" : "no",
+    };
+}
+function buildFlags(collected, state) {
+    return {
+        HAS_SKIPPED: collected.skipped.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)
+        return content;
+    // Progressively remove source files, largest first
+    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)
+            break;
+    }
+    return content;
+}
+function applyTemplate(templateName, collected, state, extraVars = {}) {
+    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})`);
+    }
+    content = fitToTokenBudget(content, collected.source);
+    return content;
+}
+export function buildInitCommand(collected, state) {
+    return applyTemplate("init.md", collected, state);
+}
+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 });
+}
+export function buildAddCommand(input, collected, state) {
+    return applyTemplate("add.md", collected, state, { USER_INPUT: input });
+}
+export function buildSyncCommand(diff, collected, state) {
+    const lastRun = state.manifest?.runs.at(-1);
+    const addedStr = diff.added.length > 0
+        ? diff.added.map(f => `#### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``).join("\n\n")
+        : "(none)";
+    const modifiedStr = diff.changed.length > 0
+        ? diff.changed.map(f => `#### ${f.path}\n\`\`\`\n${f.current}\n\`\`\``).join("\n\n")
+        : "(none)";
+    const deletedStr = diff.deleted.length > 0
+        ? diff.deleted.map(f => `- ${f}`).join("\n")
+        : "(none)";
+    return applyTemplate("sync.md", collected, state, {
+        LAST_RUN_DATE: lastRun?.at ?? "unknown",
+        ADDED_FILES: addedStr,
+        MODIFIED_FILES: modifiedStr,
+        DELETED_FILES: deletedStr,
+    });
+}
+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 });
+}
+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 steps = [
+        {
+            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` +
+                (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.` : ""),
+        },
+        {
+            filename: "stack-2-mcp.md",
+            content: preamble + idempotentCheck +
+                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
+                `## Target: .mcp.json\n\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.` : ""),
+        },
+        {
+            filename: "stack-3-settings.md",
+            content: preamble + idempotentCheck +
+                `## Project context\n\n${vars.CONFIG_FILES}\n\n` +
+                `## Target: .claude/settings.json\n\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.` : ""),
+        },
+        {
+            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.`,
+        },
+        {
+            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.`,
+        },
+        {
+            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` +
+                (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.`),
+        },
+    ];
+    return steps;
+}
+export function buildOrchestratorCommand(steps) {
+    const version = getVersion();
+    const date = new Date().toISOString().split("T")[0];
+    const stepList = steps
+        .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 -->
+
+Run these in order. If one fails, fix it and continue from that step only.
+Do not re-run steps that already completed.
+
+${stepList}
+
+After all steps complete: one-line summary of what was created.
+`;
+}

package/dist/collect.d.ts

@@ -0,0 +1,13 @@
+export interface CollectedFiles {
+    configs: Record<string, string>;
+    source: Array<{
+        path: string;
+        content: string;
+    }>;
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+export declare function collectProjectFiles(cwd?: string): Promise<CollectedFiles>;
+export declare function isEmptyProject(collected: CollectedFiles): boolean;

package/dist/collect.js

@@ -0,0 +1,266 @@
+import { readFileSync, existsSync, statSync } from "fs";
+import { glob } from "glob";
+import { join, extname, basename, dirname } from "path";
+// Universal blocklist — always exclude these patterns
+const BLOCKED_DIRS = new Set([
+    "node_modules", "vendor", ".venv", "venv", "env", "__pypackages__",
+    "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", "__pycache__",
+    "target", ".git", ".cache", "coverage", ".nyc_output", ".pytest_cache",
+    ".tox", "htmlcov", ".ruff_cache", "logs",
+]);
+const BLOCKED_EXTENSIONS = new Set([
+    ".lock", ".pyc", ".pyo", ".class", ".o", ".a", ".so", ".dylib", ".dll",
+    ".exe", ".wasm", ".min.js", ".min.css", ".bundle.js", ".chunk.js", ".map",
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico",
+    ".woff", ".woff2", ".ttf", ".eot", ".otf",
+    ".mp4", ".mp3", ".wav", ".ogg", ".webm", ".pdf",
+    ".zip", ".tar", ".gz", ".bz2", ".rar", ".7z", ".dmg", ".pkg", ".deb", ".rpm",
+    ".sqlite3", ".sqlite", ".db", ".csv", ".parquet", ".arrow",
+    ".pkl", ".pickle", ".npy", ".npz",
+    ".log", ".swp", ".swo",
+]);
+const BLOCKED_FILES = new Set([
+    "go.sum", "poetry.lock", "Pipfile.lock", "composer.lock",
+    ".DS_Store", "Thumbs.db",
+]);
+// Config files to read at root (or one level deep)
+const CONFIG_FILES = [
+    { pattern: "package.json" },
+    { pattern: "package-lock.json", truncate: truncatePackageLock },
+    { pattern: "pyproject.toml" },
+    { pattern: "setup.py", truncate: (c) => firstLines(c, 60) },
+    { pattern: "requirements.txt" },
+    { pattern: "Pipfile" },
+    { pattern: "go.mod" },
+    { pattern: "Cargo.toml" },
+    { pattern: "pom.xml", truncate: (c) => firstLines(c, 80) },
+    { pattern: "build.gradle", truncate: (c) => firstLines(c, 80) },
+    { pattern: "build.gradle.kts", truncate: (c) => firstLines(c, 80) },
+    { pattern: "composer.json" },
+    { pattern: "Gemfile" },
+    { pattern: "turbo.json" },
+    { pattern: "nx.json" },
+    { pattern: "pnpm-workspace.yaml" },
+    { pattern: "lerna.json" },
+    { pattern: ".env.example" },
+    { pattern: ".env.sample" },
+    { pattern: ".env.template" },
+    { pattern: "docker-compose.yml", truncate: (c) => c.length > 8000 ? firstLines(c, 100) + "\n[... truncated]" : c },
+    { pattern: "docker-compose.yaml", truncate: (c) => c.length > 8000 ? firstLines(c, 100) + "\n[... truncated]" : c },
+    { pattern: "Dockerfile", truncate: (c) => firstLines(c, 50) },
+];
+const SOURCE_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".go", ".rs", ".java", ".kt", ".scala",
+    ".rb", ".php", ".cs", ".swift", ".c", ".cpp", ".h",
+    ".vue", ".svelte", ".astro",
+]);
+const ENTRY_BASENAMES = new Set([
+    "index", "main", "app", "server", "cmd", "cli", "mod", "run",
+]);
+const ENTRY_DIRS = [".", "src", "app", "cmd", "bin"];
+const PRIMARY_SOURCE_DIRS = [
+    "src", "app", "lib", "core", "pkg", "internal", "api", "cmd",
+];
+const MAX_SOURCE_FILES = 10;
+const MAX_FILE_BYTES = 80_000;
+export async function collectProjectFiles(cwd = process.cwd()) {
+    const configs = {};
+    const source = [];
+    const skipped = [];
+    // Collect config files
+    for (const cfg of CONFIG_FILES) {
+        const filePath = join(cwd, cfg.pattern);
+        if (existsSync(filePath)) {
+            try {
+                let content = readFileSync(filePath, "utf8");
+                if (cfg.truncate)
+                    content = cfg.truncate(content);
+                configs[cfg.pattern] = content;
+            }
+            catch {
+                skipped.push({ path: cfg.pattern, reason: "could not read" });
+            }
+        }
+    }
+    // Check for .env (note existence but never read)
+    if (existsSync(join(cwd, ".env")) && !configs[".env"]) {
+        configs[".env"] = "[.env exists — not read for security]";
+    }
+    // Root-level *.config.{js,ts,mjs} files
+    for (const ext of ["js", "ts", "mjs"]) {
+        try {
+            const matches = await glob(`*.config.${ext}`, { cwd, nodir: true });
+            for (const m of matches) {
+                const filePath = join(cwd, m);
+                try {
+                    const content = readFileSync(filePath, "utf8");
+                    configs[m] = firstLines(content, 100);
+                }
+                catch {
+                    skipped.push({ path: m, reason: "could not read" });
+                }
+            }
+        }
+        catch { /* glob error — skip */ }
+    }
+    // Root-level *.csproj files
+    try {
+        const csprojMatches = await glob("*.csproj", { cwd, nodir: true });
+        for (const m of csprojMatches) {
+            try {
+                configs[m] = readFileSync(join(cwd, m), "utf8");
+            }
+            catch {
+                skipped.push({ path: m, reason: "could not read" });
+            }
+        }
+    }
+    catch { /* skip */ }
+    // Collect source files — max 10, cost-aware
+    const allSourceFiles = await findSourceFiles(cwd);
+    // Step 1: entry points
+    const entries = [];
+    for (const dir of ENTRY_DIRS) {
+        for (const file of allSourceFiles) {
+            const base = basename(file, extname(file));
+            const fileDir = dirname(file);
+            if (ENTRY_BASENAMES.has(base) && (fileDir === dir || fileDir === ".")) {
+                if (!entries.includes(file))
+                    entries.push(file);
+                if (entries.length >= 3)
+                    break;
+            }
+        }
+        if (entries.length >= 3)
+            break;
+    }
+    // Step 2: breadth sample from primary source directory
+    let primaryDir = "";
+    let maxCount = 0;
+    for (const dir of PRIMARY_SOURCE_DIRS) {
+        const count = allSourceFiles.filter(f => f.startsWith(dir + "/")).length;
+        if (count > maxCount) {
+            maxCount = count;
+            primaryDir = dir;
+        }
+    }
+    const breadthFiles = [];
+    if (primaryDir) {
+        const dirFiles = allSourceFiles
+            .filter(f => f.startsWith(primaryDir + "/"))
+            .filter(f => !entries.includes(f));
+        // Sort smallest first — highest signal-to-size ratio
+        const withSize = dirFiles.map(f => {
+            try {
+                return { path: f, size: statSync(join(cwd, f)).size };
+            }
+            catch {
+                return { path: f, size: Infinity };
+            }
+        }).sort((a, b) => a.size - b.size);
+        for (const { path: p } of withSize) {
+            if (breadthFiles.length >= 5)
+                break;
+            breadthFiles.push(p);
+        }
+    }
+    // Step 3: fill remaining from other top-level dirs
+    const selected = [...entries, ...breadthFiles];
+    const remaining = allSourceFiles.filter(f => !selected.includes(f));
+    for (const f of remaining) {
+        if (selected.length >= MAX_SOURCE_FILES)
+            break;
+        selected.push(f);
+    }
+    // Step 4: read and truncate
+    for (const filePath of selected) {
+        const fullPath = join(cwd, filePath);
+        try {
+            const stat = statSync(fullPath);
+            if (stat.size > MAX_FILE_BYTES) {
+                skipped.push({ path: filePath, reason: `too large (${(stat.size / 1024).toFixed(0)}KB)` });
+                continue;
+            }
+            const raw = readFileSync(fullPath, "utf8");
+            source.push({ path: filePath, content: truncateSource(raw, filePath) });
+        }
+        catch {
+            skipped.push({ path: filePath, reason: "could not read" });
+        }
+    }
+    return { configs, source, skipped };
+}
+async function findSourceFiles(cwd) {
+    try {
+        const files = await glob("**/*", {
+            cwd,
+            nodir: true,
+            ignore: [...BLOCKED_DIRS].map(d => `${d}/**`),
+            maxDepth: 5,
+        });
+        return files
+            .filter(f => {
+            const ext = extname(f);
+            const base = basename(f);
+            if (BLOCKED_FILES.has(base))
+                return false;
+            if (BLOCKED_EXTENSIONS.has(ext))
+                return false;
+            if (SOURCE_EXTENSIONS.has(ext))
+                return true;
+            return false;
+        })
+            .map(f => f.replace(/\\/g, "/"));
+    }
+    catch {
+        return [];
+    }
+}
+function truncateSource(content, path) {
+    const lines = content.split("\n");
+    const total = lines.length;
+    if (total <= 150)
+        return content;
+    if (total <= 400) {
+        return lines.slice(0, 100).join("\n") + `\n[... ${total - 100} more lines truncated]`;
+    }
+    return lines.slice(0, 60).join("\n") + `\n[... truncated — ${total} lines total]`;
+}
+function firstLines(content, n) {
+    const lines = content.split("\n");
+    if (lines.length <= n)
+        return content;
+    return lines.slice(0, n).join("\n") + `\n[... ${lines.length - n} more lines]`;
+}
+function truncatePackageLock(content) {
+    try {
+        const pkg = JSON.parse(content);
+        return JSON.stringify({
+            name: pkg.name,
+            version: pkg.version,
+            lockfileVersion: pkg.lockfileVersion,
+        }, null, 2);
+    }
+    catch {
+        return "[package-lock.json: could not parse]";
+    }
+}
+export function isEmptyProject(collected) {
+    const hasSource = collected.source.length > 0;
+    const hasOnlyBarePackageJson = Object.keys(collected.configs).length === 1 &&
+        "package.json" in collected.configs &&
+        isBarePkgJson(collected.configs["package.json"]);
+    const hasAnyConfig = Object.keys(collected.configs).length > 0;
+    return !hasSource && (!hasAnyConfig || hasOnlyBarePackageJson);
+}
+function isBarePkgJson(content) {
+    try {
+        const pkg = JSON.parse(content);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+        return Object.keys(deps).length === 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/add.d.ts

@@ -0,0 +1 @@
+export declare function runAdd(): Promise<void>;