@cruxy/cli 0.1.1 → 0.3.0

package/README.md

@@ -25,7 +25,18 @@ cruxy run                           # interactive session
 ## Features
 
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
-  `grep_files`, `run_command`, `git_status`, `apply_patch`.
+  `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`,
+  `list_skills`, `load_skill`.
+- **Codebase index** — a local, incremental semantic index (`cruxy index`)
+  behind the `search_codebase` tool. Embeddings run on-device via fastembed
+  (ONNX, bge-small-en-v1.5) with no network calls; the store is SQLite at
+  `.cruxy/index.db`. Only changed files are re-embedded; `.gitignore` /
+  `.cruxyignore` are respected and secrets (`.env*`, keys) are never indexed.
+- **Skills** — reusable, task-specific instructions in a `SKILL.md`
+  (frontmatter + markdown), discovered via `list_skills` and pulled on demand
+  with `load_skill` (progressive disclosure: only name + description are in
+  context until a skill is loaded). Layered project > user > builtin, strictly
+  validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
 - **Safety** — a single approval gate with diff previews that fails closed;
@@ -36,6 +47,29 @@ Interactive slash commands: `/help`, `/clear`, `/compact`, `/reload`, `/exit`.
 
 For unattended runs, pass `--yes` to approve every action.
 
+### Codebase search
+
+```bash
+cruxy index            # build / refresh the local index (.cruxy/index.db)
+cruxy index --status   # show what's indexed
+cruxy index --force    # re-embed every file
+```
+
+The index refreshes itself lazily the first time the agent calls
+`search_codebase`, so it works even without running `cruxy index` first. The
+bge-small embedding model (~130 MB) downloads and caches on first use.
+
+### Skills
+
+```bash
+cruxy skills            # list the resolved skill catalog
+cruxy skills --status   # show source directories and validation errors
+```
+
+Add a skill by creating `<name>/SKILL.md` under `.cruxy/skills/` (project) or
+`~/.cruxy/skills/` (user); shipped builtins are the lowest layer. See the
+built-in `using-skills` skill for the authoring rules.
+
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.
 

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `cruxy index` — build or refresh the local codebase search index that backs
+ * the `search_codebase` tool. `--status` reports the current state without
+ * modifying it; `--force` re-embeds every file regardless of content hashes.
+ */
+export declare function indexCommand(): Command;

package/dist/cli/commands/index.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { getIndexService, indexDbPath, resetIndexServices, } from "../../indexing/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy index` — build or refresh the local codebase search index that backs
+ * the `search_codebase` tool. `--status` reports the current state without
+ * modifying it; `--force` re-embeds every file regardless of content hashes.
+ */
+export function indexCommand() {
+    return new Command("index")
+        .description("build or refresh the local codebase search index")
+        .option("--status", "show index status without building")
+        .option("--force", "re-embed every file, ignoring content hashes")
+        .action(async (opts) => {
+        const { config } = loadConfig();
+        if (!config.index.enabled) {
+            logger.warn("codebase indexing is disabled (index.enabled = false)");
+            return;
+        }
+        const cwd = process.cwd();
+        if (opts.status) {
+            // Don't create an empty DB just to report "no index built yet".
+            if (config.index.store !== "memory" && !existsSync(indexDbPath(cwd))) {
+                logger.print(`${pc.bold("index:")} ${pc.dim("not built yet")} — run ${pc.bold("cruxy index")}`);
+                return;
+            }
+            const service = await getIndexService(cwd, config, logger);
+            printStatus(service.status());
+            await resetIndexServices();
+            return;
+        }
+        logger.info(pc.dim(`indexing ${cwd} …`));
+        logger.info(pc.dim("(first run may download the local embedding model)"));
+        const service = await getIndexService(cwd, config, logger);
+        try {
+            const stats = await service.index({ force: opts.force });
+            logger.print(`${pc.green("indexed")} ${stats.filesIndexed} file(s), ${stats.chunksIndexed} chunk(s) ` +
+                pc.dim(`(${stats.filesSkipped} unchanged, ${stats.filesPurged} purged, ${stats.durationMs}ms)`));
+        }
+        catch (err) {
+            logger.error(`indexing failed: ${err.message}`);
+            process.exitCode = 1;
+        }
+        finally {
+            await resetIndexServices();
+        }
+    });
+}
+function printStatus(status) {
+    logger.print(`${pc.bold("index:")}    ${status.exists ? pc.green("built") : pc.yellow("empty")}`);
+    logger.print(`${pc.bold("store:")}    ${status.storePath ?? "(in-memory)"}`);
+    logger.print(`${pc.bold("embedder:")} ${status.embedderId ?? pc.dim("(none)")}` +
+        (status.dim ? pc.dim(` · ${status.dim}d`) : ""));
+    logger.print(`${pc.bold("files:")}    ${status.files}`);
+    logger.print(`${pc.bold("chunks:")}   ${status.chunks}`);
+}

package/dist/cli/commands/skills.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy skills` — list the skills available to the agent (the same catalog the
+ * `list_skills` tool sees). `--status` additionally shows the three source
+ * directories in precedence order and any validation errors (skills that were
+ * excluded for being malformed).
+ */
+export declare function skillsCommand(): Command;

package/dist/cli/commands/skills.js

@@ -0,0 +1,51 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { getSkillService, resetSkillServices } from "../../skills/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy skills` — list the skills available to the agent (the same catalog the
+ * `list_skills` tool sees). `--status` additionally shows the three source
+ * directories in precedence order and any validation errors (skills that were
+ * excluded for being malformed).
+ */
+export function skillsCommand() {
+    return new Command("skills")
+        .description("list the skills available to the agent")
+        .option("--status", "show source directories and validation errors")
+        .action(async (opts) => {
+        const service = getSkillService(process.cwd(), logger);
+        const status = await service.status();
+        if (status.entries.length === 0) {
+            logger.print(pc.dim("no skills found"));
+        }
+        else {
+            for (const entry of status.entries) {
+                logger.print(`${pc.bold(entry.name)}  ${pc.dim(`[${entry.source}]`)}`);
+                logger.print(`  ${entry.description}`);
+            }
+        }
+        if (!opts.status) {
+            if (status.errors.length > 0) {
+                logger.print(pc.yellow(`\n${status.errors.length} skill(s) failed validation — run ${pc.bold("cruxy skills --status")} for details`));
+            }
+            resetSkillServices();
+            return;
+        }
+        logger.print(`\n${pc.bold("sources")} ${pc.dim("(precedence high → low):")}`);
+        for (const { source, dir } of status.sources) {
+            logger.print(`  ${source.padEnd(8)} ${pc.dim(dir)}`);
+        }
+        logger.print("");
+        if (status.errors.length === 0) {
+            logger.print(pc.green("no validation errors"));
+        }
+        else {
+            logger.print(pc.yellow(`validation errors (${status.errors.length}):`));
+            for (const err of status.errors) {
+                logger.print(`  ${pc.red("✗")} ${pc.bold(err.name)} ${pc.dim(`[${err.source}]`)}: ${err.message}`);
+                logger.print(`    ${pc.dim(err.dir)}`);
+            }
+        }
+        resetSkillServices();
+    });
+}

package/dist/cli/program.js

@@ -4,6 +4,8 @@ import { APP_NAME, APP_VERSION, APP_DESCRIPTION } from "../constants.js";
 import { logger } from "../utils/logger.js";
 import { runCommand } from "./commands/run.js";
 import { configCommand } from "./commands/config.js";
+import { indexCommand } from "./commands/index.js";
+import { skillsCommand } from "./commands/skills.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -24,6 +26,8 @@ export function buildProgram() {
     });
     program.addCommand(runCommand());
     program.addCommand(configCommand());
+    program.addCommand(indexCommand());
+    program.addCommand(skillsCommand());
     // Default action: no subcommand -> interactive entrypoint (stub for now).
     program.action(() => {
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));

package/dist/config/schema.d.ts

@@ -97,6 +97,93 @@ export declare const ApprovalConfigSchema: z.ZodObject<{
 }, {
     mode?: "auto" | "prompt" | undefined;
 }>;
+/**
+ * Codebase semantic index (C.17): the local embedding index that backs the
+ * `search_codebase` tool and `cruxy index`. Every field is defaulted so the
+ * feature works with zero configuration.
+ */
+export declare const IndexConfigSchema: z.ZodObject<{
+    /** Master switch for `search_codebase` and `cruxy index`. */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
+     * model downloads and caches on first use) is selectable — if it cannot be
+     * loaded, indexing fails loudly rather than degrading. (The deterministic
+     * hashing embedder exists for tests and is injected directly, never chosen
+     * here.)
+     */
+    embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
+    /**
+     * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
+     * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
+     * falls back to memory when the native dependency cannot be loaded.
+     */
+    store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
+    /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
+    maxFileBytes: z.ZodDefault<z.ZodNumber>;
+    chunk: z.ZodEffects<z.ZodDefault<z.ZodObject<{
+        /** Target chunk window, in lines. */
+        windowLines: z.ZodDefault<z.ZodNumber>;
+        /** Lines shared between consecutive chunks; must be < windowLines. */
+        overlapLines: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        windowLines: number;
+        overlapLines: number;
+    }, {
+        windowLines?: number | undefined;
+        overlapLines?: number | undefined;
+    }>>, {
+        windowLines: number;
+        overlapLines: number;
+    }, {
+        windowLines?: number | undefined;
+        overlapLines?: number | undefined;
+    } | undefined>;
+    search: z.ZodDefault<z.ZodObject<{
+        /** Number of hits returned when the tool omits `k`. */
+        defaultK: z.ZodDefault<z.ZodNumber>;
+        /** Approximate token budget for combined snippets (chars/4 heuristic). */
+        tokenBudget: z.ZodDefault<z.ZodNumber>;
+        /** Maximum lines kept in any single returned snippet. */
+        maxSnippetLines: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        defaultK: number;
+        tokenBudget: number;
+        maxSnippetLines: number;
+    }, {
+        defaultK?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxSnippetLines?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    search: {
+        defaultK: number;
+        tokenBudget: number;
+        maxSnippetLines: number;
+    };
+    enabled: boolean;
+    embedder: "fastembed";
+    store: "auto" | "sqlite" | "memory";
+    maxFileBytes: number;
+    chunk: {
+        windowLines: number;
+        overlapLines: number;
+    };
+}, {
+    search?: {
+        defaultK?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxSnippetLines?: number | undefined;
+    } | undefined;
+    enabled?: boolean | undefined;
+    embedder?: "fastembed" | undefined;
+    store?: "auto" | "sqlite" | "memory" | undefined;
+    maxFileBytes?: number | undefined;
+    chunk?: {
+        windowLines?: number | undefined;
+        overlapLines?: number | undefined;
+    } | undefined;
+}>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -203,6 +290,88 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     }, {
         mode?: "auto" | "prompt" | undefined;
     }>>;
+    index: z.ZodDefault<z.ZodObject<{
+        /** Master switch for `search_codebase` and `cruxy index`. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
+         * model downloads and caches on first use) is selectable — if it cannot be
+         * loaded, indexing fails loudly rather than degrading. (The deterministic
+         * hashing embedder exists for tests and is injected directly, never chosen
+         * here.)
+         */
+        embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
+        /**
+         * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
+         * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
+         * falls back to memory when the native dependency cannot be loaded.
+         */
+        store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
+        /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
+        maxFileBytes: z.ZodDefault<z.ZodNumber>;
+        chunk: z.ZodEffects<z.ZodDefault<z.ZodObject<{
+            /** Target chunk window, in lines. */
+            windowLines: z.ZodDefault<z.ZodNumber>;
+            /** Lines shared between consecutive chunks; must be < windowLines. */
+            overlapLines: z.ZodDefault<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            windowLines: number;
+            overlapLines: number;
+        }, {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        }>>, {
+            windowLines: number;
+            overlapLines: number;
+        }, {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        } | undefined>;
+        search: z.ZodDefault<z.ZodObject<{
+            /** Number of hits returned when the tool omits `k`. */
+            defaultK: z.ZodDefault<z.ZodNumber>;
+            /** Approximate token budget for combined snippets (chars/4 heuristic). */
+            tokenBudget: z.ZodDefault<z.ZodNumber>;
+            /** Maximum lines kept in any single returned snippet. */
+            maxSnippetLines: z.ZodDefault<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            defaultK: number;
+            tokenBudget: number;
+            maxSnippetLines: number;
+        }, {
+            defaultK?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxSnippetLines?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        search: {
+            defaultK: number;
+            tokenBudget: number;
+            maxSnippetLines: number;
+        };
+        enabled: boolean;
+        embedder: "fastembed";
+        store: "auto" | "sqlite" | "memory";
+        maxFileBytes: number;
+        chunk: {
+            windowLines: number;
+            overlapLines: number;
+        };
+    }, {
+        search?: {
+            defaultK?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxSnippetLines?: number | undefined;
+        } | undefined;
+        enabled?: boolean | undefined;
+        embedder?: "fastembed" | undefined;
+        store?: "auto" | "sqlite" | "memory" | undefined;
+        maxFileBytes?: number | undefined;
+        chunk?: {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        } | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -251,6 +420,21 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval: {
         mode: "auto" | "prompt";
     };
+    index: {
+        search: {
+            defaultK: number;
+            tokenBudget: number;
+            maxSnippetLines: number;
+        };
+        enabled: boolean;
+        embedder: "fastembed";
+        store: "auto" | "sqlite" | "memory";
+        maxFileBytes: number;
+        chunk: {
+            windowLines: number;
+            overlapLines: number;
+        };
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -291,6 +475,21 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval?: {
         mode?: "auto" | "prompt" | undefined;
     } | undefined;
+    index?: {
+        search?: {
+            defaultK?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxSnippetLines?: number | undefined;
+        } | undefined;
+        enabled?: boolean | undefined;
+        embedder?: "fastembed" | undefined;
+        store?: "auto" | "sqlite" | "memory" | undefined;
+        maxFileBytes?: number | undefined;
+        chunk?: {
+            windowLines?: number | undefined;
+            overlapLines?: number | undefined;
+        } | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -72,6 +72,60 @@ export const ApprovalConfigSchema = z
     mode: z.enum(["prompt", "auto"]).default("prompt"),
 })
     .strict();
+/**
+ * Codebase semantic index (C.17): the local embedding index that backs the
+ * `search_codebase` tool and `cruxy index`. Every field is defaulted so the
+ * feature works with zero configuration.
+ */
+export const IndexConfigSchema = z
+    .object({
+    /** Master switch for `search_codebase` and `cruxy index`. */
+    enabled: z.boolean().default(true),
+    /**
+     * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
+     * model downloads and caches on first use) is selectable — if it cannot be
+     * loaded, indexing fails loudly rather than degrading. (The deterministic
+     * hashing embedder exists for tests and is injected directly, never chosen
+     * here.)
+     */
+    embedder: z.enum(["fastembed"]).default("fastembed"),
+    /**
+     * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
+     * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
+     * falls back to memory when the native dependency cannot be loaded.
+     */
+    store: z.enum(["auto", "sqlite", "memory"]).default("auto"),
+    /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
+    maxFileBytes: z
+        .number()
+        .int()
+        .positive()
+        .default(1024 * 1024),
+    chunk: z
+        .object({
+        /** Target chunk window, in lines. */
+        windowLines: z.number().int().positive().default(60),
+        /** Lines shared between consecutive chunks; must be < windowLines. */
+        overlapLines: z.number().int().nonnegative().default(15),
+    })
+        .strict()
+        .default({})
+        .refine((c) => c.overlapLines < c.windowLines, {
+        message: "index.chunk.overlapLines must be less than windowLines",
+    }),
+    search: z
+        .object({
+        /** Number of hits returned when the tool omits `k`. */
+        defaultK: z.number().int().positive().default(8),
+        /** Approximate token budget for combined snippets (chars/4 heuristic). */
+        tokenBudget: z.number().int().positive().default(1500),
+        /** Maximum lines kept in any single returned snippet. */
+        maxSnippetLines: z.number().int().positive().default(40),
+    })
+        .strict()
+        .default({}),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -90,6 +144,7 @@ export const CruxyConfigSchema = z
     shell: ShellConfigSchema.default({}),
     context: ContextConfigSchema.default({}),
     approval: ApprovalConfigSchema.default({}),
+    index: IndexConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/constants.d.ts

@@ -9,3 +9,16 @@ export declare const CONFIG_FILE_NAME = "config.json";
 export declare const PROJECT_CONFIG_FILENAMES: string[];
 /** Project-instruction filenames, checked in order (first match wins). */
 export declare const PROJECT_INSTRUCTION_FILENAMES: string[];
+/**
+ * Name of the skills subdirectory, used under the project dir
+ * (`<cwd>/.cruxy/skills`), the global dir (`~/.cruxy/skills`), and the package
+ * root for shipped builtins.
+ */
+export declare const SKILLS_DIR_NAME = "skills";
+/**
+ * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
+ * Anchored the same way as the package.json lookup above: both `dist/` and
+ * `src/` sit one level below the package root, so `../skills` resolves to the
+ * shipped `skills/` directory in dev, in `dist`, and when published.
+ */
+export declare const BUILTIN_SKILLS_DIR: string;

package/dist/constants.js

@@ -29,3 +29,16 @@ export const PROJECT_CONFIG_FILENAMES = [
 ];
 /** Project-instruction filenames, checked in order (first match wins). */
 export const PROJECT_INSTRUCTION_FILENAMES = ["CRUXY.md", "AGENTS.md"];
+/**
+ * Name of the skills subdirectory, used under the project dir
+ * (`<cwd>/.cruxy/skills`), the global dir (`~/.cruxy/skills`), and the package
+ * root for shipped builtins.
+ */
+export const SKILLS_DIR_NAME = "skills";
+/**
+ * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
+ * Anchored the same way as the package.json lookup above: both `dist/` and
+ * `src/` sit one level below the package root, so `../skills` resolves to the
+ * shipped `skills/` directory in dev, in `dist`, and when published.
+ */
+export const BUILTIN_SKILLS_DIR = join(__dirname, "..", SKILLS_DIR_NAME);

package/dist/indexing/chunker.d.ts

@@ -0,0 +1,28 @@
+import type { Chunk } from "./types.js";
+/** Knobs for {@link chunkFile}. */
+export interface ChunkOptions {
+    /** Target window size, in lines. */
+    windowLines: number;
+    /** Lines shared between consecutive windows (clamped to < windowLines). */
+    overlapLines: number;
+    /**
+     * How far (in lines) the window end may slide to land on a blank-line
+     * boundary. Keeps chunks aligned to natural gaps without drifting too far
+     * from the target size.
+     */
+    snapSlack?: number;
+}
+/**
+ * Split a file's text into overlapping line windows.
+ *
+ * Windows are `windowLines` long and advance by `windowLines - overlapLines`, so
+ * consecutive chunks share `overlapLines` lines (context that would otherwise be
+ * severed at a hard cut). Where possible the window end is nudged — within
+ * `snapSlack` lines — to fall right after a blank line, so chunks break at
+ * natural boundaries (between functions, paragraphs, etc.).
+ *
+ * Line numbers are 1-based and inclusive. A whitespace-only (or empty) file
+ * yields no chunks. A file shorter than one window yields exactly one chunk.
+ * Coverage is gap-free: every source line belongs to at least one chunk.
+ */
+export declare function chunkFile(path: string, text: string, opts: ChunkOptions): Chunk[];

package/dist/indexing/chunker.js

@@ -0,0 +1,65 @@
+const DEFAULT_SNAP_SLACK = 8;
+/**
+ * Split a file's text into overlapping line windows.
+ *
+ * Windows are `windowLines` long and advance by `windowLines - overlapLines`, so
+ * consecutive chunks share `overlapLines` lines (context that would otherwise be
+ * severed at a hard cut). Where possible the window end is nudged — within
+ * `snapSlack` lines — to fall right after a blank line, so chunks break at
+ * natural boundaries (between functions, paragraphs, etc.).
+ *
+ * Line numbers are 1-based and inclusive. A whitespace-only (or empty) file
+ * yields no chunks. A file shorter than one window yields exactly one chunk.
+ * Coverage is gap-free: every source line belongs to at least one chunk.
+ */
+export function chunkFile(path, text, opts) {
+    if (text.trim() === "")
+        return [];
+    const lines = text.split("\n");
+    // A trailing newline produces a phantom empty final element; drop it so line
+    // counts match what an editor shows.
+    if (lines.length > 1 && lines[lines.length - 1] === "")
+        lines.pop();
+    const n = lines.length;
+    const window = Math.max(1, Math.floor(opts.windowLines));
+    const overlap = Math.min(Math.max(0, Math.floor(opts.overlapLines)), window - 1);
+    const slack = Math.max(0, opts.snapSlack ?? DEFAULT_SNAP_SLACK);
+    const chunks = [];
+    let start = 0; // 0-based, inclusive
+    while (start < n) {
+        let end = Math.min(start + window, n); // 0-based, exclusive
+        // Snap the end to a nearby blank-line boundary (the last included line is
+        // blank), unless we've already reached EOF.
+        if (end < n && slack > 0) {
+            const lo = Math.max(start + 1, end - slack);
+            const hi = Math.min(n, end + slack);
+            let best = -1;
+            let bestDist = Infinity;
+            for (let e = lo; e <= hi; e++) {
+                const endsOnBlank = e === n || lines[e - 1].trim() === "";
+                if (!endsOnBlank)
+                    continue;
+                const dist = Math.abs(e - end);
+                if (dist < bestDist) {
+                    bestDist = dist;
+                    best = e;
+                }
+            }
+            if (best !== -1)
+                end = best;
+        }
+        chunks.push({
+            path,
+            startLine: start + 1,
+            endLine: end,
+            text: lines.slice(start, end).join("\n"),
+        });
+        if (end >= n)
+            break;
+        // Advance by the window stride, but never regress (a short snapped window
+        // could otherwise leave nextStart <= start).
+        const nextStart = end - overlap;
+        start = nextStart > start ? nextStart : end;
+    }
+    return chunks;
+}