@cstart/coldstart 2.0.0

package/dist/indexer/walker.js

@@ -0,0 +1,91 @@
+import { readdir, stat, realpath } from 'node:fs/promises';
+import { join, relative, extname } from 'node:path';
+import { DEFAULT_EXCLUDES, EXTENSION_TO_LANGUAGE } from '../constants.js';
+export async function walkDirectory(options) {
+    const { rootDir, excludes = [], includes = [], maxFileSizeBytes = 1_000_000, } = options;
+    const userExcludes = new Set(excludes);
+    const includeSet = includes.length > 0
+        ? new Set(includes.map(i => join(rootDir, i)))
+        : null;
+    const results = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            // Permission error or other read failure — skip silently
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                // Skip symlinks to avoid cycles
+                continue;
+            }
+            if (entry.isDirectory()) {
+                // Skip excluded directories
+                if (DEFAULT_EXCLUDES.has(entry.name) || userExcludes.has(entry.name)) {
+                    continue;
+                }
+                // Skip hidden directories (e.g. .git, .next)
+                if (entry.name.startsWith('.')) {
+                    continue;
+                }
+                // If includes filter is set, only descend into matching roots
+                if (includeSet) {
+                    const isIncluded = [...includeSet].some(inc => fullPath.startsWith(inc) || inc.startsWith(fullPath));
+                    if (!isIncluded)
+                        continue;
+                }
+                await walk(fullPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            let language;
+            const ext = extname(entry.name).toLowerCase();
+            language = EXTENSION_TO_LANGUAGE[ext];
+            // Handle .env files: .env, .env.local, .env.production, .env.development, etc.
+            if (!language && /^\.env(\.|$)/.test(entry.name)) {
+                language = 'env';
+            }
+            // Handle Jenkinsfile: Jenkinsfile, Jenkinsfile.*, etc.
+            if (!language && /^Jenkinsfile(\.|$)/.test(entry.name)) {
+                language = 'groovy';
+            }
+            if (!language)
+                continue;
+            // Skip generated files (e.g. foo.generated.ts, schema_pb.ts, api.pb.go)
+            const nameLower = entry.name.toLowerCase();
+            if (/\.(generated|pb)\.[a-z]+$/.test(nameLower) || /_(generated|pb)\.[a-z]+$/.test(nameLower))
+                continue;
+            // Check file size
+            try {
+                const info = await stat(fullPath);
+                if (info.size > maxFileSizeBytes)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            // Resolve symlink chains in the path (for relative path computation only)
+            let resolvedPath = fullPath;
+            try {
+                resolvedPath = await realpath(fullPath);
+            }
+            catch {
+                resolvedPath = fullPath;
+            }
+            const relativePath = relative(rootDir, resolvedPath);
+            results.push({
+                absolutePath: resolvedPath,
+                relativePath,
+                language,
+            });
+        }
+    }
+    await walk(rootDir);
+    return results;
+}
+//# sourceMappingURL=walker.js.map

package/dist/indexer/walker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walker.js","sourceRoot":"","sources":["../../src/indexer/walker.ts"],"names":[],"mappings":"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"}

package/dist/init.d.ts

@@ -0,0 +1,111 @@
+/**
+ * coldstart init — wire coldstart into a project.
+ *
+ * Model: a single `coldstart.md` lives at the repo root and carries ALL the
+ * agent-facing guidance. Clients pull it in by reference, so future wording
+ * changes touch only coldstart.md, never the client's own rules file.
+ *
+ * init asks two things (or takes `--experience` / `--client` flags):
+ *   1. EXPERIENCE — how the agent invokes coldstart:
+ *        - `cli` (recommended) → runs `coldstart find` / `coldstart gs` (shell).
+ *        - `mcp`               → calls the `find` / `gs` MCP tools (no shell).
+ *      This selects the coldstart.md flavor and the hook matcher surface.
+ *   2. CLIENT — which tool to wire (never auto-detected; the user always picks):
+ *        - Claude Code → CLAUDE.md imports `@coldstart.md`; find/gs hooks in
+ *          `.claude/settings.json`. (MCP experience also writes `.mcp.json`.)
+ *        - Cursor      → `.cursor/rules/coldstart.mdc` references coldstart.md;
+ *          Cursor-specific navigation + notebook hooks in `.cursor/hooks.json`.
+ *          (MCP) also writes `.cursor/mcp.json`.
+ *        - Codex       → AGENTS.md points at coldstart.md; Codex-specific
+ *          navigation + notebook hooks in `.codex/hooks.json`. (MCP) writes
+ *          `[mcp_servers.coldstart]` into `.codex/config.toml`.
+ *        - Other       → write coldstart.md only; print wiring directions.
+ *
+ * Claude, Codex, and Cursor receive separate hook entrypoints. They share the
+ * protocol-neutral detector core; only input adaptation, the transcript walk,
+ * and the output envelope differ per host (Cursor capture parses its own JSONL).
+ */
+/** The coldstart.md body for a flavor, read from its checked-in template. */
+export declare function coldstartMd(mode: 'cli' | 'mcp'): string;
+/**
+ * Merge the notebook recall/capture hooks into `.claude/settings.json`.
+ * Idempotent (strips prior kb entries, re-adds), preserves the find/gs hooks
+ * and any foreign entries, fail-safe on invalid JSON. Points at the same
+ * version-pinned stable hooks dir the find/gs hooks use (survives npm update).
+ */
+export declare function wireClaudeKbHooks(cwd: string): 'created' | 'updated' | {
+    error: string;
+};
+/**
+ * Notebook file setup — client-agnostic. Creates the skeleton, sets the
+ * merge=union attribute, and applies the storage choice: private by default
+ * (gitignore `.coldstart/`), or committable when `commit` is set. Does NOT wire
+ * hooks — those are Claude-specific (see wireClaudeKbHooks).
+ */
+export declare function setupNotebook(cwd: string, commit: boolean): void;
+export declare function writeColdstartMd(cwd: string, mode: 'cli' | 'mcp'): 'created' | 'updated';
+/** Ensure CLAUDE.md exists and imports coldstart.md via `@coldstart.md`. */
+export declare function wireClaudeImport(cwd: string): 'created' | 'added' | 'present';
+/**
+ * Register the find/gs search hooks in the project's `.claude/settings.json`.
+ *
+ * Merges (never clobbers): preserves every other setting and any non-coldstart
+ * hooks. Idempotent — strips our prior entries (matched by entry filename) and
+ * re-adds them, so a re-run refreshes a stale hook path without duplicating.
+ * Fail-safe — if settings.json exists but is not valid JSON, we leave it alone
+ * and report, rather than overwrite a file the user owns.
+ */
+export declare function wireClaudeHooks(cwd: string): 'created' | 'updated' | {
+    error: string;
+};
+/**
+ * Register Codex-specific navigation and notebook hooks. Event envelopes are
+ * intentionally handled by separate files so Codex rollout/subagent behavior
+ * can evolve without risking the Claude integration.
+ */
+export declare function wireCodexHooks(cwd: string): 'created' | 'updated' | {
+    error: string;
+};
+/**
+ * Register Cursor navigation + notebook hooks in `.cursor/hooks.json`.
+ *
+ * Cursor's config differs from Codex/Claude: a top-level `version` + a `hooks`
+ * map whose events hold FLAT `{command}` entries (no matcher / no nested hooks).
+ * `preToolUse`/`postToolUse` are generic (fire for Shell + Read + MCP), so no
+ * matcher is needed — the handler filters. The SAME hooks serve both experiences;
+ * the handlers normalize a Shell `coldstart find` (cli) and an MCP find (mcp) to
+ * one shape, mirroring Codex. Recall rides `beforeSubmitPrompt` (Cursor honors
+ * its `additional_context` despite the docs); capture rides `stop`+`subagentStop`.
+ *
+ * Merges idempotently (strips our prior entries by filename, preserves foreign
+ * ones) and is fail-safe on invalid JSON.
+ */
+export declare function wireCursorHooks(cwd: string): 'created' | 'updated' | {
+    error: string;
+};
+/** Write `.cursor/rules/coldstart.mdc` — an always-applied rule that pulls in
+ *  coldstart.md via Cursor's `@file` reference. Overwritten on re-run (it owns
+ *  this file), so guidance edits flow through coldstart.md. */
+export declare function wireCursorRule(cwd: string): 'created' | 'updated';
+/** Ensure AGENTS.md carries a coldstart section pointing at coldstart.md.
+ *  AGENTS.md has no import directive, so we inject a marked block and refresh it
+ *  in place on re-run (idempotent), preserving everything else in the file. */
+export declare function wireCodexAgents(cwd: string): 'created' | 'updated';
+/** Merge `{ mcpServers: { coldstart: entry } }` into a JSON MCP config (used for
+ *  Claude's `.mcp.json` and Cursor's `.cursor/mcp.json` — identical shape).
+ *  Fail-safe on invalid JSON; preserves other servers and keys. */
+export declare function wireJsonMcp(cwd: string, relFile: string, entry: {
+    command: string;
+    args: string[];
+}): 'created' | 'updated' | {
+    error: string;
+};
+/** Write `[mcp_servers.coldstart]` into `.codex/config.toml` (Codex's MCP config).
+ *  Hand-rolled minimal TOML merge — no dependency: strip a prior coldstart table,
+ *  then append a fresh one. Other config is preserved verbatim. */
+export declare function wireCodexMcp(cwd: string, entry: {
+    command: string;
+    args: string[];
+}): 'created' | 'updated';
+export declare function runInit(): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAmCH,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAEvD;AAgED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA+BxF;AA8DD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAehE;AAMD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAKxF;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAW7E;AA+ED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAgCtF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAsDrF;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAyCtF;AAMD;;+DAE+D;AAC/D,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAiBjE;AAKD;;+EAE+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CA0BlE;AAMD;;mEAEmE;AACnE,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACzC,SAAS,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAsB3C;AA2BD;;mEAEmE;AACnE,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACzC,SAAS,GAAG,SAAS,CAcvB;AA2HD,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAwE7C"}