@cruxy/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,104 +1,60 @@
 # @cruxy/cli
 
-An agentic coding CLI. **Phase C.0 — CLI scaffolding + config.**
+**An agentic coding CLI that plans, edits, tests, and ships from your terminal — powered by the Cruxy API.**
 
-This is the foundation pass: a working command-line skeleton with a layered
-configuration system. The agent loop, tools, indexing, and everything else in
-the C-series slot into the directory structure laid out here.
+[![npm version](https://img.shields.io/npm/v/@cruxy/cli.svg)](https://www.npmjs.com/package/@cruxy/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@cruxy/cli.svg)](https://www.npmjs.com/package/@cruxy/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-43853d.svg)](https://nodejs.org)
 
-## Requirements
+Cruxy is a terminal-first coding agent that works directly in your repository —
+reading code, editing files, running commands, and verifying its own work, with
+an approval gate before anything touches disk.
 
-- Node.js >= 20
-
-## Setup
-
-```bash
-npm install
-npm run build      # compile TypeScript -> dist/
-npm link           # optional: expose the `cruxy` command globally
-```
-
-During development you can skip the build step:
+## Install
 
 ```bash
-npm run dev -- --help
-npm run dev -- config path
-```
+npm install -g @cruxy/cli
 
-## Usage
+export CRUXY_API_KEY=cxy_live_...   # from app.cruxy.in
 
-```bash
-cruxy                       # entrypoint (interactive REPL stub — lands in C.3)
-cruxy run "fix the bug"     # one-shot prompt (agent loop stub — lands in C.4)
-cruxy config init           # write a default global config
-cruxy config list           # print the fully-resolved config
-cruxy config get model.temperature
-cruxy config set model.model claude-opus-4-8
-cruxy config path           # show where config files live
-cruxy --help
+cruxy run "explain this codebase"   # one-shot
+cruxy run                           # interactive session
 ```
 
-Global flags: `--config <path>`, `--log-level <level>`, `--verbose`, `--version`.
-
-## Configuration
-
-Config is resolved in layers, where later sources override earlier ones:
+## Features
 
-1. Built-in schema defaults
-2. Global config — `~/.cruxy/config.json`
-3. Project config — `cruxy.config.json` or `.cruxy/config.json` (discovered by
-   walking up from the current directory), or an explicit `--config <path>`
-4. Environment variables — `CRUXY_MODEL`, `CRUXY_PROVIDER`, `CRUXY_LOG_LEVEL`
+- **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
+  `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`.
+- **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.
+- **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;
+  read-only tools never prompt; file access is confined to the project root;
+  shell commands run bounded.
 
-The merged result is validated against a [zod](https://zod.dev) schema
-(`src/config/schema.ts`); invalid configs are rejected with a readable error.
+Interactive slash commands: `/help`, `/clear`, `/compact`, `/reload`, `/exit`.
 
-**API keys are never stored in config files.** They are read from the
-environment only (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `CRUXY_API_KEY`).
-Copy `.env.example` to `.env` to set them locally.
+For unattended runs, pass `--yes` to approve every action.
 
-## Project structure
+### 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
 ```
-src/
-  index.ts            # bin entry (shebang) + top-level error handling
-  constants.ts        # app name/version, config file names
-  cli/
-    program.ts        # commander program + global options
-    commands/
-      run.ts          # `cruxy run` (agent loop stub)
-      config.ts       # `cruxy config` subcommands
-  config/
-    schema.ts         # zod config schema + types
-    paths.ts          # global/project config path resolution
-    manager.ts        # layered load/merge/validate, get/set/init
-    index.ts          # barrel
-  utils/
-    logger.ts         # leveled logger
-```
 
-Folders for `agent/`, `tools/`, and `providers/` are introduced as their phases
-land, so this layout grows without restructuring.
-
-## Roadmap (C-series)
-
-| Phase    | Description                                                                                                                |
-| -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| C.0      | CLI scaffolding + config                                                                                                   |
-| C.1–C.10 | Provider client, tool system, agent loop, file tools, **permissions** ← you are here, terminal UI, shell, git, IDE plugins |
-| C.11     | Codebase indexing (vector store)                                                                                           |
-| C.12     | Per-language LSP integration                                                                                               |
-| C.13     | Test execution + iteration loop                                                                                            |
-| C.14     | Subagent orchestration                                                                                                     |
-| C.15     | PR generation                                                                                                              |
-| C.16     | Sandbox / Docker execution                                                                                                 |
-| C.17     | Web-search subtool                                                                                                         |
-| C.18     | Custom skills (SKILL.md system)                                                                                            |
-| C.19     | Hooks + slash commands                                                                                                     |
-| C.20     | Headless / CI mode                                                                                                         |
-| C.21     | Multi-repo agents                                                                                                          |
-| C.22     | Telemetry + cost tracking                                                                                                  |
-| C.23     | Streaming UI improvements                                                                                                  |
+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.
+
+The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
+provider-agnostic, built over `fetch`, with no vendor SDKs.
 
 ## License
 

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/program.js

@@ -4,6 +4,7 @@ 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";
 export function buildProgram() {
     const program = new Command();
     program
@@ -24,6 +25,7 @@ export function buildProgram() {
     });
     program.addCommand(runCommand());
     program.addCommand(configCommand());
+    program.addCommand(indexCommand());
     // 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/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;
+}