@cruxy/cli 1.0.2 → 1.0.4

package/dist/tools/file/paths.d.ts

@@ -1,160 +0,0 @@
-import { PathEscapeError, type DeclaredRoot, type RootRef, type Workspace } from "../../workspace/index.js";
-import type { ToolContext } from "../types.js";
-/**
- * Path confinement for file tools (C.26). The confinement kernel itself lives in
- * `src/workspace` ({@link confineToRoot}); this module is the tool-facing funnel
- * that every path-taking tool calls instead of touching the filesystem directly.
- * Keeping ONE resolver here is what makes Funnel A ("a path tool cannot reach fs
- * outside the selected root") a structural property rather than a per-tool habit.
- */
-export { PathEscapeError };
-/**
- * The workspace this context acts in. `ctx.workspace` is a required field (C.26
- * Step 6), so this is a plain accessor — there is no single-root fallback to
- * synthesize, because no code path can reach a path-taking tool without a
- * workspace (the type forbids the omission; the `no-split-brain` guard forbids a
- * mid-subsystem synthesis). Kept as the one named seam every funnel calls.
- */
-export declare function contextWorkspace(ctx: ToolContext): Workspace;
-/**
- * Resolve a tool-supplied path against the workspace and prove it stays inside the
- * one root it selects — the single funnel for every path-taking file tool.
- *
- * Single-root sessions short-circuit straight to `confineToRoot(primary, path)`,
- * which is exactly the legacy `resolveInRoot` behaviour (same result, same
- * error type + message for every case: relative, absolute-inside, absolute-outside,
- * outward symlink). Multi-root sessions run the two-step select-then-confine:
- * {@link selectRoot} commits to exactly one declared root FIRST, then
- * {@link confineToRoot} validates against only that root — so a `../otherRoot/x`
- * that lands in a sibling is refused as an ordinary `PATH_ESCAPE` (R2), never
- * rebound to the sibling.
- *
- * `deferNonPrimaryWrite` (set by the mutating file tools) refuses a write whose
- * selected root is NOT the primary in a multi-root session, with
- * `CRUXY_E_MULTIROOT_WRITE_DEFERRED` — UNLESS `ctx.checkpointsActive` is true.
- * That flag is the C.26 step-3 coupling: it is set exactly when a per-root
- * checkpoint gate is wired, which captures the write (snapshots its root) before
- * it reaches disk — so the refusal lifts precisely when the write becomes
- * rollback-able, never before (not step-wide, not lift-then-verify). With
- * checkpoints disabled the flag is false, so a non-primary write is still refused
- * rather than left un-restorable (⚖︎JC-γ: the opt-out covers the user's own cwd,
- * not every declared sibling). It is a no-op in single-root (there is only the
- * primary) and for reads (which never set it). The refusal is raised BEFORE any
- * filesystem access.
- *
- * @throws {PathEscapeError} if the path escapes the selected root.
- * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN / CRUXY_E_ROOT_AMBIGUOUS on bad selection,
- *   or CRUXY_E_MULTIROOT_WRITE_DEFERRED on a non-primary write while deferred.
- */
-export declare function resolveToolPath(ctx: ToolContext, ref: RootRef, opts?: {
-    requireExplicit?: boolean;
-    deferNonPrimaryWrite?: boolean;
-}): Promise<{
-    root: DeclaredRoot;
-    abs: string;
-}>;
-/**
- * Legacy single-root entry point, retained as a thin shim over
- * {@link resolveToolPath} so callers that pass only a bare path (e.g. the LSP
- * tools) keep working and stay byte-identical. New path tools should call
- * {@link resolveToolPath} so they can carry an explicit root selector.
- *
- * @returns the resolved absolute path (lexical, not realpath'd).
- * @throws {PathEscapeError} if the path escapes the root.
- */
-export declare function resolveInRoot(ctx: ToolContext, p: string): Promise<string>;
-/**
- * True when a glob pattern could walk outside its root — an absolute pattern or one
- * containing a `..` segment. The ONE implementation of "does this pattern escape",
- * shared by `glob` and `grep_files` so the two walk-rooted tools cannot diverge
- * (closing G1/G2). Path *arguments* go through {@link resolveToolPath}; glob
- * *patterns* are not resolvable paths, so this predicate guards the walk instead.
- *
- * NB — a known internal inconsistency, documented rather than fixed: this split on
- * `/[/\\]/` (and the sibling `firstSegmentIsRoot` in grep_files) treats `\` as a
- * separator on EVERY platform, but the resolution kernel {@link confineToRoot} →
- * `path.resolve` does NOT on POSIX (there `\` is a legal filename character). The
- * two only diverge for a `..\`-style argument on POSIX, which is unreachable from
- * anything the tools EMIT (grep/apply_patch produce `\` only on Windows, where
- * `path.resolve` does treat it as a separator). It is left as-is deliberately:
- * "fixing" confineToRoot to fold `\`→`/` on POSIX would break access to files
- * whose names legitimately contain a backslash.
- */
-export declare function isEscapingPattern(pattern: string): boolean;
-/**
- * The separator between a root's name and a path within it (`‹root› ▸ rel`) — one
- * constant so every no-path tool that fans across roots renders the same label.
- */
-export declare const ROOT_LABEL_SEP = " \u25B8 ";
-/**
- * Rewrite the OS path separator to forward slashes for MODEL-FACING output — the
- * one display convention every path tool shares. The rest of the toolset already
- * emits POSIX paths on Windows (the indexer normalises the same way in
- * `indexing/walker.ts`, and git's porcelain and tinyglobby both hand back `/`);
- * this seam is what keeps the two `path.relative`-based stragglers, `grep_files`
- * and `apply_patch`, from drifting to native `src\b.ts`.
- *
- * It splits on `path.sep`, NOT a literal `\`, so it only ever rewrites the real OS
- * separator: on POSIX (`path.sep === "/"`) it is a no-op that PRESERVES a literal
- * backslash in a filename — legal on POSIX — rather than mangling it; on Windows
- * (`path.sep === "\\"`) it turns `path.relative`'s `src\b.ts` into `src/b.ts`.
- *
- * Purely cosmetic at the boundary — the model never needs native separators back:
- * a path it echoes into read_file/edit_file resolves through {@link confineToRoot}
- * → `path.resolve`, which accepts `/` on Windows, so the forward-slash form
- * round-trips as-is.
- */
-export declare function toPosix(p: string): string;
-/**
- * Prefix a root-relative path with its root name — but ONLY in a genuine
- * multi-root session. In single-root the label is dropped so output stays
- * byte-identical with the pre-C.26 tools. The `root`/`rel` pair always comes from
- * the same fan iteration that produced the bytes, so a rendered label can never
- * point at a different root than the one that was walked (the honesty pin).
- */
-export declare function labelPath(root: DeclaredRoot, rel: string, isMultiRoot: boolean): string;
-/** As {@link labelPath} but from a bare root name (for hits that carry only a name). */
-export declare function labelName(rootName: string, rel: string): string;
-/**
- * The Funnel-B selector for **no-path** tools (`glob`, `grep_files`, `list_files`,
- * `git_status`, `search_codebase`) — the counterpart to {@link resolveToolPath}.
- * A no-path tool has no path to confine; its boundary is *which root's `absPath`*
- * it threads as the walk-start / index-key / spawn-cwd. This returns that root
- * set, and the tool commits to exactly one root per read by iterating it:
- *
- *   - an explicit `root` name → that one declared root (fail-loud on unknown, R1);
- *   - single-root session → the primary root (so output is byte-identical);
- *   - multi-root, unscoped → **fan** every declared root.
- *
- * The fan is N independent single-root reads (one `root.absPath` each), never one
- * walk over a union — so each read is Funnel-B-confined and the cross-root merge
- * only ever happens on already-attributed *results*, never on the filesystem.
- * Reads leave `requireExplicit` false (that gate is for mutations, ⚖︎#3).
- *
- * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN if a named root is not declared.
- */
-export declare function resolveReadRoots(ctx: ToolContext, ref?: {
-    root?: string;
-}): readonly DeclaredRoot[];
-/**
- * The Funnel-B selector for a **no-path, whole-root MUTATION** — today
- * `create_pull_request` (and the future commit/branch/push tools). Unlike
- * {@link resolveReadRoots} it commits to exactly ONE root and, in a multi-root
- * session, refuses to default (⚖︎#11, JC-1 take B):
- *
- *   - an explicit `root` name → that one declared root (fail-loud on unknown, R1);
- *   - single-root session → the primary root (byte-identical to pre-C.26 — a
- *     single root is unambiguous, so no `root` is required);
- *   - multi-root, unscoped → refuse `ROOT_AMBIGUOUS` (a defaulted PR is the
- *     "opened the wrong repo" accident; ambiguity only exists when N > 1).
- *
- * `what` names the action in the refusal message (e.g. `"a pull request"`). This
- * throws BEFORE the caller runs any git, so a no-root multi-root call performs
- * zero git spawns.
- *
- * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN (unknown name) / CRUXY_E_ROOT_AMBIGUOUS
- *   (multi-root, no root).
- */
-export declare function resolveMutationRoot(ctx: ToolContext, ref: {
-    root?: string;
-}, what: string): DeclaredRoot;

package/dist/tools/file/read-file.d.ts

@@ -1,8 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "../types.js";
-/**
- * Read a UTF-8 text file from within the project root. Read-only — no approval.
- */
-export declare const readFileTool: Tool<z.ZodObject<{
-    path: z.ZodString;
-}>>;

package/dist/tools/file/write-file.d.ts

@@ -1,10 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "../types.js";
-/**
- * Create or overwrite a file within the project root. Gated on `ctx.approve`
- * before anything is written.
- */
-export declare const writeFileTool: Tool<z.ZodObject<{
-    path: z.ZodString;
-    content: z.ZodString;
-}>>;

package/dist/tools/git-status.d.ts

@@ -1,15 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "./types.js";
-/**
- * Report the current git branch and working-tree status (`git status
- * --porcelain`) for the project root. Read-only — no approval, like read_file
- * and glob.
- *
- * Multi-repo (C.26, Funnel B): with more than one declared root, it fans every
- * root — each `getGitStatus(root.absPath)` spawns git with that root as its cwd,
- * so a section reports exactly the working tree its label names. A non-git root
- * is NAMED (not fatal), and a `root` argument scopes to one root.
- */
-export declare const gitStatusTool: Tool<z.ZodObject<{
-    root: z.ZodOptional<z.ZodString>;
-}>>;

package/dist/tools/index.d.ts

@@ -1,9 +0,0 @@
-export * from "./types.js";
-export * from "./registry.js";
-export * from "./list-files.js";
-export * from "./git-status.js";
-export * from "./search-codebase.js";
-export * from "./list-skills.js";
-export * from "./load-skill.js";
-export * from "./create-pull-request.js";
-export * from "./file/index.js";

package/dist/tools/list-files.d.ts

@@ -1,13 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "./types.js";
-/**
- * List the entries of a workspace root, marking each as a directory or a file.
- *
- * Multi-repo (C.26, Funnel B): with more than one declared root, it fans every
- * root — each `fs.readdir(root.absPath)` reads exactly the root its section
- * header names. A per-root read error is NAMED (not fatal), and a `root` argument
- * scopes to one root.
- */
-export declare const listFilesTool: Tool<z.ZodObject<{
-    root: z.ZodOptional<z.ZodString>;
-}>>;

package/dist/tools/list-skills.d.ts

@@ -1,9 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "./types.js";
-/**
- * List the available skills (name + one-line description + source). Read-only —
- * no approval — like the other discovery tools. This is the cheap half of
- * progressive disclosure: only the catalog enters context here; the agent calls
- * `load_skill` to pull a skill's full instructions when a task matches.
- */
-export declare const listSkillsTool: Tool<z.ZodObject<Record<string, never>>>;

package/dist/tools/load-skill.d.ts

@@ -1,21 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "./types.js";
-declare const parameters: z.ZodObject<{
-    name: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-}, {
-    name: string;
-}>;
-/**
- * Load a skill's full instructions on demand — the expensive half of
- * progressive disclosure. Returns the markdown body plus the absolute asset root
- * and the relative paths of any `scripts/` and `reference/` files, so the agent
- * can read or run them through the existing read_file / run_command tools.
- *
- * Read-only — no approval. Loading a skill never executes anything: scripts are
- * surfaced as paths only and run, if at all, through run_command (which applies
- * the normal approval gate).
- */
-export declare const loadSkillTool: Tool<typeof parameters>;
-export {};

package/dist/tools/registry.d.ts

@@ -1,23 +0,0 @@
-import type { ToolSpec } from "@cruxy/sdk";
-import type { Tool } from "./types.js";
-/**
- * In-memory catalogue of the tools available to the agent. Names are unique;
- * `toToolSpecs()` projects the catalogue into the `@cruxy/sdk` wire format.
- */
-export declare class ToolRegistry {
-    private readonly tools;
-    /** Register a tool. Throws if a tool with the same name already exists. */
-    register(tool: Tool): void;
-    /** Look up a tool by name, or `undefined` if not registered. */
-    get(name: string): Tool | undefined;
-    /** All registered tools, in registration order. */
-    list(): Tool[];
-    /**
-     * Project every tool into a `ToolSpec` for the provider: name, description,
-     * and the zod schema rendered as JSON Schema (with the `$schema` / `definitions`
-     * cruft the wire format rejects stripped out).
-     */
-    toToolSpecs(): ToolSpec[];
-}
-/** Build the default registry with every built-in tool registered. */
-export declare function buildDefaultRegistry(): ToolRegistry;

package/dist/tools/search-codebase.d.ts

@@ -1,35 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "./types.js";
-declare const parameters: z.ZodObject<{
-    query: z.ZodString;
-    k: z.ZodOptional<z.ZodNumber>;
-    pathGlob: z.ZodOptional<z.ZodString>;
-    root: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    root?: string | undefined;
-    k?: number | undefined;
-    pathGlob?: string | undefined;
-}, {
-    query: string;
-    root?: string | undefined;
-    k?: number | undefined;
-    pathGlob?: string | undefined;
-}>;
-/**
- * Semantic search over the project's local code index (C.17). Read-only — no
- * approval — like read_file and grep_files. The index is built/refreshed lazily
- * on first use; results are ranked by cosine similarity and token-budgeted.
- *
- * Multi-repo (C.26, Funnel B): with more than one declared root, the search fans
- * every root, gets each root's own index (`getIndexService(root.absPath)` — the
- * per-cwd cache is the per-root map), and merges into one globally-ranked list.
- * Each hit is labelled with its source root, `k` and the token budget are applied
- * AFTER the merge (global rank, ⚖︎JC-I), and any root whose index failed — or whose
- * matches the cap dropped — is NAMED, never silently implied to have no matches.
- *
- * Complements `grep_files`: prefer this for conceptual "where / how does X work"
- * questions, and grep for exact strings or symbols.
- */
-export declare const searchCodebaseTool: Tool<typeof parameters>;
-export {};

package/dist/tools/shell/exec.d.ts

@@ -1,53 +0,0 @@
-import type { ToolContext } from "../types.js";
-/**
- * The ONE gated + sandboxed shell path (C.16 + C.19). Both `run_command` and the
- * C.19 hook runner funnel through {@link runGatedShell}: a command reaches
- * execution only after passing the SAME `ctx.requestApproval` gate and only
- * through the SAME `ctx.sandbox` (or host) substrate. There is deliberately no
- * second exec route, so a hook can never get a privileged path — proven by the
- * fact that both callers invoke this exact function.
- *
- * The structured {@link ShellExecResult} carries the raw exit code (which
- * `run_command`'s text `ToolResult` hides) so the hook runner can decide
- * blocking pass/fail on exit 0 vs non-zero, while `run_command` maps the same
- * result back to its byte-identical `ToolResult`.
- */
-/** The raw outcome of executing a shell command (gate already passed). */
-export interface ShellExecResult {
-    /** The wall-clock timeout tripped and the process tree was killed. */
-    timedOut: boolean;
-    /** Numeric exit code, or null when killed / signalled / unknown. */
-    exitCode: number | null;
-    /** Terminating signal (host path only); null under the sandbox. */
-    signal: string | null;
-    /** Combined stdout+stderr, capped to `shell.maxOutputBytes`. */
-    output: string;
-    /** Output was truncated at the cap. */
-    truncated: boolean;
-    /** The host process failed to *start* (spawn error). Sandbox start failures
-     * throw a coded error instead (propagated, never returned here). */
-    spawnError?: string;
-}
-/** The result of the gate + (if allowed) execution. */
-export interface GatedShellOutcome {
-    /** The U.3 gate allowed the command. When false, nothing executed. */
-    approved: boolean;
-    /** The rejection feedback when `approved` is false. */
-    rejection?: string;
-    /** The execution result — present iff `approved`. */
-    exec?: ShellExecResult;
-}
-/**
- * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
- * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
- * rejection returns `{ approved: false }` and runs nothing. A non-interactive
- * gate throws `CRUXY_E_APPROVAL_REQUIRED` (propagated, never swallowed); a
- * sandbox that can't run throws its coded error (fail loud, no host fallback).
- */
-export declare function runGatedShell(command: string, ctx: ToolContext): Promise<GatedShellOutcome>;
-/**
- * Execute an already-approved command. Substrate is chosen SOLELY by
- * `ctx.sandbox`: present → the container (C.16), never the host; absent → the
- * bounded host spawn. No fallback path — a sandbox that can't run throws.
- */
-export declare function execShell(command: string, ctx: ToolContext): Promise<ShellExecResult>;

package/dist/tools/shell/index.d.ts

@@ -1 +0,0 @@
-export * from "./run-command.js";

package/dist/tools/shell/resolve-shell.d.ts

@@ -1,81 +0,0 @@
-import { type ChildProcess, type SpawnOptions } from "node:child_process";
-/**
- * WHICH shell a host command runs through, and — just as important — WHICH
- * dialect the model must emit for it. `run_command` and `run_tests` both spawn
- * with the platform default shell (`{ shell: true }` → `/bin/sh` on POSIX,
- * `%ComSpec%`/cmd.exe on win32). The model emits bash, so on Windows a command
- * like `echo x; exit 1` runs as a single `echo`, exits 0, and reads as a false
- * success. This module makes Windows host execution first-class instead:
- *
- *  Tier 0  `shell.executable` override → use it verbatim (the user owns it).
- *  Tier 1  Git Bash (Git for Windows) → full POSIX parity, no model changes.
- *  Tier 2  PowerShell (pwsh, else powershell.exe) → the model is told, via a
- *          system-prompt directive keyed on {@link ShellPlan.dialect}, to emit
- *          native PowerShell.
- *  Tier 3  nothing usable → throw CRUXY_E_NO_SHELL. We NEVER hand bash-shaped
- *          strings to cmd.exe silently — that is the exact false-green above.
- *
- * A non-default shell is ALWAYS invoked with explicit argv (`bash -c <cmd>`,
- * `powershell -NoProfile -Command <cmd>`), never Node's `shell: <path>` string
- * form: Node builds that command line with cmd.exe quoting rules, which mangle a
- * command bound for bash/PowerShell. POSIX with no override keeps `shell: true`
- * verbatim — a zero-change path off Windows.
- */
-export type ShellDialect = "posix" | "powershell" | "cmd";
-export type ShellSource = "default" | "config" | "git-bash" | "powershell";
-/**
- * The shell-selection fields the resolver reads — a structural subset of the
- * config's `ShellConfig` (which also carries `timeoutMs`/`maxOutputBytes`). Kept
- * narrow so callers and tests pass only what selection needs.
- */
-export interface ShellSelection {
-    executable?: string;
-    dialect?: ShellDialect;
-}
-/** How to spawn a host command, and which dialect the model should emit for it. */
-export type ShellPlan = 
-/** POSIX default: `spawn(command, { shell: true })`, byte-identical to before. */
-{
-    kind: "system";
-    dialect: "posix";
-    source: "default";
-}
-/** Explicit shell binary + fixed flags; the command is the final argv element. */
- | {
-    kind: "explicit";
-    file: string;
-    flags: readonly string[];
-    dialect: ShellDialect;
-    source: ShellSource;
-};
-/** Injected so the resolver's win32 logic is unit-testable on a POSIX CI host. */
-export interface ShellEnv {
-    platform: NodeJS.Platform;
-    env: NodeJS.ProcessEnv;
-    exists: (candidate: string) => boolean;
-}
-/**
- * Infer a dialect from a shell path's basename, but ONLY for the unambiguous
- * names — anything exotic (`nu`, `fish`, `xonsh`, …) returns undefined so the
- * caller demands an explicit `shell.dialect` rather than guessing wrong.
- */
-export declare function sniffDialect(executable: string): ShellDialect | undefined;
-/**
- * Resolve the shell PLAN from config + environment. Pure over its injected
- * {@link ShellEnv}, so the win32 tiers are exercised on any CI host. Throws
- * CRUXY_E_NO_SHELL (no usable shell) or CRUXY_E_CONFIG_INVALID (an override
- * whose dialect can't be determined) — both fail loud, never a silent fallback.
- */
-export declare function computeShellPlan(shell: ShellSelection, env?: ShellEnv): ShellPlan;
-/** The memoized production resolver. Throws (fail loud) exactly as compute does. */
-export declare function resolveShell(shell: ShellSelection): ShellPlan;
-/** Test hook: drop the memoized plan so the next resolve re-detects. */
-export declare function __resetShellResolution(): void;
-/**
- * Spawn `command` through the resolved shell as a killable process tree — the
- * single seam both `run_command` and `run_tests` route through. `system` keeps
- * the exact `{ shell: true }` spawn; every other plan invokes the shell binary
- * with explicit argv so the command reaches bash/PowerShell unmangled (see the
- * module header).
- */
-export declare function spawnShell(command: string, shell: ShellSelection, options?: SpawnOptions): ChildProcess;

package/dist/tools/shell/run-command.d.ts

@@ -1,14 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "../types.js";
-/**
- * Run an arbitrary shell command in the project root. The highest-risk tool we
- * ship: it is gated on `ctx.approve` (a denial runs nothing) and bounded by a
- * timeout that kills the whole process tree plus a cap on captured output.
- *
- * Gate + execution live in the shared {@link runGatedShell} (also used by the
- * C.19 hook runner — the single, un-bypassable shell path); this tool only maps
- * the structured result back onto its `ToolResult` framing.
- */
-export declare const runCommandTool: Tool<z.ZodObject<{
-    command: z.ZodString;
-}>>;