@cruxy/cli 1.0.3 → 1.0.4

package/dist/errors/types.d.ts

@@ -1,270 +0,0 @@
-/**
- * The one error type for every user-facing failure (U.5). A {@link CruxyError}
- * carries structured fields — title, optional human cause, next steps, a stable
- * greppable {@link ErrorCode}, and a process exit code — while *formatting* lives
- * separately (see `format.ts`). The raw underlying error is preserved but shown
- * only under `--verbose`; no Node stack trace ever reaches the user by default.
- */
-/**
- * Stable, greppable error identifiers. The string value *is* the id that appears
- * in output (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`) — grep for it in logs/issues.
- * Grouped by category; each category maps to a distinct process exit code
- * (see {@link exitCodeFor}).
- */
-export declare const ErrorCode: {
-    readonly Internal: "CRUXY_E_INTERNAL";
-    readonly Usage: "CRUXY_E_USAGE";
-    readonly InteractiveRequired: "CRUXY_E_INTERACTIVE_REQUIRED";
-    readonly ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN";
-    readonly ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED";
-    readonly GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH";
-    readonly PlanInvalid: "CRUXY_E_PLAN_INVALID";
-    readonly PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT";
-    readonly CheckpointNotFound: "CRUXY_E_CHECKPOINT_NOT_FOUND";
-    /** Routing (C.30): a task class is mapped to a tier the gateway does not
-     * offer — fix the config, NEVER a silent substitution to another tier. */
-    readonly RoutingTierUnavailable: "CRUXY_E_ROUTING_TIER_UNAVAILABLE";
-    readonly ConfigParse: "CRUXY_E_CONFIG_PARSE";
-    readonly ConfigInvalid: "CRUXY_E_CONFIG_INVALID";
-    readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
-    readonly AuthInvalid: "CRUXY_E_AUTH_INVALID";
-    readonly ForgeAuth: "CRUXY_E_FORGE_AUTH";
-    /** A credential could not be persisted with owner-only permissions (C.27c) —
-     * e.g. on Windows the store's ACL could not be restricted to the current user
-     * (non-NTFS filesystem, `icacls`/SID unavailable). Refused loudly rather than
-     * written world-inheritable: a secret is never persisted at permissions we
-     * could not verify as owner-only. */
-    readonly CredentialsUnprotected: "CRUXY_E_CREDENTIALS_UNPROTECTED";
-    readonly GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE";
-    readonly GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED";
-    readonly Api: "CRUXY_E_API";
-    readonly ApiRateLimit: "CRUXY_E_API_RATE_LIMIT";
-    readonly ApiOverloaded: "CRUXY_E_API_OVERLOADED";
-    readonly BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED";
-    readonly ForgeApi: "CRUXY_E_FORGE_API";
-    readonly FileNotFound: "CRUXY_E_FILE_NOT_FOUND";
-    readonly PermissionDenied: "CRUXY_E_PERMISSION_DENIED";
-    readonly PathEscape: "CRUXY_E_PATH_ESCAPE";
-    readonly CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED";
-    /** The fastembed native module could not be LOADED (missing/broken install,
-     * un-built onnxruntime-node addon). Fail-loud by design — the embedder never
-     * silently degrades to the lexical hashing backend (that would be a silent
-     * quality loss). See the store-vs-embedder asymmetry note in `schema.ts`. */
-    readonly IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE";
-    /** The fastembed module loaded, but the model could not be brought up at
-     * RUNTIME — the first-run download/decompress, or the ONNX-runtime init,
-     * failed (offline, the model bucket is unreachable, a proxy blocks it). Kept
-     * DISTINCT from `IndexEmbedderUnavailable` (a load failure) and from the
-     * generic `IndexFailed` ("re-run --verbose") so the actual, common first-run
-     * failure carries an actionable cause instead of a shrug. */
-    readonly IndexEmbedderDownloadFailed: "CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED";
-    readonly IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE";
-    readonly IndexFailed: "CRUXY_E_INDEX_FAILED";
-    readonly SkillInvalid: "CRUXY_E_SKILL_INVALID";
-    readonly SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND";
-    readonly ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED";
-    readonly PlanApprovalRequired: "CRUXY_E_PLAN_APPROVAL_REQUIRED";
-    readonly RollbackApprovalRequired: "CRUXY_E_ROLLBACK_APPROVAL_REQUIRED";
-    readonly SubagentDepthExceeded: "CRUXY_E_SUBAGENT_DEPTH_EXCEEDED";
-    /** Carried inside a SubagentResult (informational) — never fatal by itself. */
-    readonly SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET";
-    readonly SubagentFailed: "CRUXY_E_SUBAGENT_FAILED";
-    /** Two children of one parallel fan-out (C.33) declare overlapping write scope
-     * (same root). Refused pre-dispatch so concurrent siblings can never race on a
-     * root — the model corrects it (distinct roots, or read-only). */
-    readonly SubagentScopeOverlap: "CRUXY_E_SUBAGENT_SCOPE_OVERLAP";
-    /** Carried inside a SubagentResult (informational): the run was cancelled — a
-     * fatal sibling failure or Ctrl-C aborted the whole fan-out (C.33). Never a
-     * fabricated success; the parent sees exactly which children did not finish. */
-    readonly SubagentCancelled: "CRUXY_E_SUBAGENT_CANCELLED";
-    readonly TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND";
-    /** Carried inside a run_tests result (informational) — never fatal by itself. */
-    readonly TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT";
-    /** Sandbox was enabled but no container runtime is available — fail loud,
-     * NEVER fall back to un-sandboxed host execution. */
-    readonly SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE";
-    readonly SandboxImage: "CRUXY_E_SANDBOX_IMAGE";
-    readonly SandboxExec: "CRUXY_E_SANDBOX_EXEC";
-    /** A blocking hook failed (non-zero exit / declined / errored) → the action
-     * is aborted fail-closed. Advisory hooks never raise this. */
-    readonly HookFailed: "CRUXY_E_HOOK_FAILED";
-    /** A project defines hooks that have not been trusted for this repo — they are
-     * never run silently (supply-chain safety). */
-    readonly HookUntrusted: "CRUXY_E_HOOK_UNTRUSTED";
-    /** A malformed hook definition — excluded from the catalog and surfaced,
-     * never eval'd. */
-    readonly HookInvalid: "CRUXY_E_HOOK_INVALID";
-    /** A malformed custom slash-command definition — excluded and surfaced. */
-    readonly SlashInvalid: "CRUXY_E_SLASH_INVALID";
-    /** A malformed memory entry — excluded from recall/writes and surfaced,
-     * never eval'd. */
-    readonly MemoryInvalid: "CRUXY_E_MEMORY_INVALID";
-    /** A repo's project memory has not been trusted — it is never recalled into
-     * context silently (supply-chain safety). */
-    readonly MemoryUntrusted: "CRUXY_E_MEMORY_UNTRUSTED";
-    /** A memory write was refused because the content matched a secret shape —
-     * secrets are never persisted (defense in depth over C.17). */
-    readonly MemorySecret: "CRUXY_E_MEMORY_SECRET";
-    /** The local usage store is corrupt/unreadable — the read is SKIPPED and this
-     * is surfaced; never fatal to a run (usage display is best-effort). */
-    readonly UsageRead: "CRUXY_E_USAGE_READ";
-    /** A language server binary is not installed / not on PATH (or no server is
-     * configured for the file's language). Actionable, NEVER a silent empty
-     * result — "no server" must not read as "no references found". */
-    readonly LspServerNotFound: "CRUXY_E_LSP_SERVER_NOT_FOUND";
-    /** A server's `initialize` handshake or a single request exceeded its timeout
-     * — the process was killed / the request errored, never left to hang. */
-    readonly LspTimeout: "CRUXY_E_LSP_TIMEOUT";
-    /** A language server crashed (and, where applicable, a single restart also
-     * failed). Distinct from "server returned no results". */
-    readonly LspCrashed: "CRUXY_E_LSP_CRASHED";
-    /** A project configures MCP servers that have not been trusted for this repo.
-     * Trusting a server runs its code UNSANDBOXED with your privileges, so an
-     * untrusted config is never connected silently — and in non-interactive mode
-     * it fails closed BEFORE any server is spawned (supply-chain safety). */
-    readonly McpUntrusted: "CRUXY_E_MCP_UNTRUSTED";
-    /** A trusted MCP server failed to spawn, complete the `initialize` handshake,
-     * or list its tools. Surfaced (that server contributes no tools) rather than
-     * silently swallowed; never fatal to the run. */
-    readonly McpConnect: "CRUXY_E_MCP_CONNECT";
-    /** A network (`url`) MCP server was REFUSED before/at connect for a SECURITY
-     * reason, distinct from an ordinary connect failure: a non-https(non-loopback)
-     * scheme, a host that resolves into a private/loopback/link-local range (SSRF),
-     * or an endpoint that tried to redirect. A refusal, not a transient error. */
-    readonly McpBlocked: "CRUXY_E_MCP_BLOCKED";
-    /** A network (`url`) MCP server's CREDENTIAL failed (C.27c): the endpoint
-     * rejected it (401/403) or the named `credentialRef` has no token in the
-     * `~/.cruxy` store. Distinct from a transport connect failure — the server was
-     * reached (or the credential was simply absent), not merely unreachable. */
-    readonly McpAuth: "CRUXY_E_MCP_AUTH";
-    /** A project-scope config was REFUSED for a credential-safety reason (C.27c):
-     * it tried to set raw `headers` on an MCP server. A live header value is a
-     * secret; project scope (a possibly-cloned repo) may only NAME a credential via
-     * `credentialRef`, never carry the value. Rejected loudly, never silently. */
-    readonly McpConfig: "CRUXY_E_MCP_CONFIG";
-    /** `web.enabled` is on but no usable search provider is configured — the API
-     * key env var is unset or the provider is unknown. Actionable, NEVER a silent
-     * empty result: "no provider" must not read as "no search results". */
-    readonly WebUnavailable: "CRUXY_E_WEB_UNAVAILABLE";
-    /** A web search failed (provider HTTP error, network failure, or timeout). The
-     * search did NOT run to completion — distinct from a search that ran and found
-     * nothing (that is an ordinary `ok:true` empty result). */
-    readonly WebSearch: "CRUXY_E_WEB_SEARCH";
-    /** A `web_fetch` failed: network error, timeout, oversize/non-text body, or too
-     * many redirects. Distinct from a page fetched successfully that had no readable
-     * text (an ordinary `ok:true` empty result). */
-    readonly WebFetch: "CRUXY_E_WEB_FETCH";
-    /** A `web_fetch` was REFUSED before any request was dispatched: a non-http(s)
-     * scheme, or a host that resolves into a private/loopback/link-local range
-     * (SSRF guard — e.g. 127.0.0.1, 169.254.169.254, 10.x, internal DNS). A
-     * security stop, kept distinct from an ordinary fetch failure for grep-ability. */
-    readonly WebBlockedHost: "CRUXY_E_WEB_BLOCKED_HOST";
-    /** A path/selector names a workspace root that is not in the declared set (or an
-     * absolute path that lands in no declared root). Fail-loud and NEVER fuzzy- or
-     * prefix-matched to a nearby root — a silent near-match is a cross-root misfire.
-     * Refused before any FS access; never falls through to the host filesystem. */
-    readonly RootUnknown: "CRUXY_E_ROOT_UNKNOWN";
-    /** A path is ambiguous across the declared root set: an absolute path that falls
-     * inside ≥2 declared roots, or a mutating tool given no root when there's no
-     * unambiguous choice. Writes fail closed rather than guess a root. */
-    readonly RootAmbiguous: "CRUXY_E_ROOT_AMBIGUOUS";
-    /** Declaration-time: a declared root nests inside / overlaps another. Refused at
-     * session start — overlap makes "which root owns this path" ambiguous and lets
-     * two checkpoints/grants fight over the same bytes. Declare the monorepo root OR
-     * its packages, never both. */
-    readonly RootOverlap: "CRUXY_E_ROOT_OVERLAP";
-    /** An interactive add-root was refused: no TTY to confirm, or the user declined
-     * the confirm/trust prompt. The root set only ever grows by an explicit human
-     * act — never by the model or a repo-local config. */
-    readonly RootAddRefused: "CRUXY_E_ROOT_ADD_REFUSED";
-    /** A write targeted a NON-PRIMARY root while per-root checkpoints are not yet
-     * wired (C.26 Step 2b). Refused so "every write cruxy makes is checkpointed and
-     * rollback-able" stays true — an un-checkpointed write to a sibling root would be
-     * silently un-restorable when rollback reverts the primary. Lifted in Step 3 when
-     * per-root checkpoints ship. Reads to any root are unaffected. */
-    readonly MultirootWriteDeferred: "CRUXY_E_MULTIROOT_WRITE_DEFERRED";
-    /** A multi-root rollback set references a member checkpoint that is missing or
-     * corrupt, or a touched root has no member. Loud — a partial rollback must never
-     * masquerade as success. */
-    readonly CheckpointSetIncomplete: "CRUXY_E_CHECKPOINT_SET_INCOMPLETE";
-    /** A multi-root rollback failed mid-apply (R3): carries which roots were restored
-     * and which were not. The set is left recoverable by an idempotent re-run and is
-     * NEVER reported as success. */
-    readonly CheckpointSetPartial: "CRUXY_E_CHECKPOINT_SET_PARTIAL";
-    /** VCS target-integrity guard (C.26 Step 4): the `origin` remote of the acting
-     * root resolved to a DIFFERENT `owner/repo` between the U.3 preview (what the
-     * human approved) and the moment the pull-request API call is made (a concurrent
-     * `git remote set-url` on a mutable `.git/config`). The PR is NOT opened —
-     * refused, never warn-and-proceed — and both the approved and current targets are
-     * named. Reachable single-root too; introduced with the multi-root VCS hardening. */
-    readonly VcsRemoteChanged: "CRUXY_E_VCS_REMOTE_CHANGED";
-    /** A pull request was requested for one declared root while a SIBLING declared
-     * root shares the same git working tree (two non-overlapping roots inside one
-     * repo, e.g. `packages/a` + `packages/b` under one `.git`). A commit there would
-     * `git add -A` the sibling's changes too, so the PR would span both roots — a PR
-     * is a single-repo artifact, so it is refused (naming both) rather than silently
-     * PR one half. */
-    readonly VcsCrossRoot: "CRUXY_E_VCS_CROSS_ROOT";
-    /** A `run_in_background` dispatch was refused because the live job count
-     * (queued + running + paused) already sits at `jobs.maxJobs`. The MODEL corrects
-     * it — wait for a job to finish (or cancel one) and retry — so it is a usage-tier
-     * coded error, never a silently-dropped dispatch. */
-    readonly JobLimit: "CRUXY_E_JOB_LIMIT";
-    /** `cruxy cancel/logs/rollback <id>` named a job id that does not exist in this
-     * session. Jobs are session-scoped (NOT a daemon), so an id from a prior session
-     * is legitimately unknown — fail loud with the id rather than a silent no-op. */
-    readonly JobNotFound: "CRUXY_E_JOB_NOT_FOUND";
-    /** A background-jobs command (`cruxy jobs/logs/cancel`) was used while
-     * `jobs.enabled` is false. The feature is opt-in; surfaced with how to enable it
-     * rather than pretending there are simply no jobs. */
-    readonly JobsDisabled: "CRUXY_E_JOBS_DISABLED";
-    /** No usable host shell was found to run commands through. On Windows this
-     * means neither Git Bash nor PowerShell could be located and no
-     * `shell.executable` override was set. Fail loud at session start — NEVER
-     * silently fall back to cmd.exe running bash-shaped commands (which
-     * mis-parses `;`/`&&`/quoting and can report a false success). */
-    readonly NoShell: "CRUXY_E_NO_SHELL";
-    /** A one-shot `cruxy run` ended WITHOUT completing the task: the agent loop hit
-     * a hard stop (the iteration cap or a token budget) or was cancelled, rather
-     * than finishing on its own. Fail loud with a non-zero exit so CI never reads a
-     * gave-up run as success — the partial work already streamed to stdout stands. */
-    readonly AgentIncomplete: "CRUXY_E_AGENT_INCOMPLETE";
-};
-export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
-/** The process exit code for an error code (defaults to 1 for safety). */
-export declare function exitCodeFor(code: ErrorCode): number;
-export interface CruxyErrorInit {
-    /** Stable error id (drives the exit code and appears in output). */
-    code: ErrorCode;
-    /** One plain line: what failed. */
-    title: string;
-    /** The specific reason, when known. Always shown (part 2 of the standard). */
-    cause?: string;
-    /** Concrete actions the user can take. */
-    nextSteps?: string[];
-    /** Structured context (not rendered; for future JSON output / telemetry). */
-    meta?: Record<string, unknown>;
-    /** The original thrown error, preserved and shown only under `--verbose`. */
-    underlying?: unknown;
-    /** Override the exit code; defaults to {@link exitCodeFor}(code). */
-    exitCode?: number;
-}
-/**
- * Every user-facing failure is (or becomes) one of these. Extends `Error` so it
- * flows through normal throw/catch; `.message` mirrors `title` so logs and
- * `instanceof Error` consumers stay useful.
- */
-export declare class CruxyError extends Error {
-    readonly code: ErrorCode;
-    readonly title: string;
-    /** Human-readable reason (part 2). Narrows the inherited `Error.cause`. */
-    readonly cause?: string;
-    readonly nextSteps: string[];
-    readonly exitCode: number;
-    readonly meta?: Record<string, unknown>;
-    /** The wrapped lower-level error — rendered only under `--verbose`. */
-    readonly underlying?: unknown;
-    constructor(init: CruxyErrorInit);
-    /** Type guard — true for any CruxyError (across realms, via the brand). */
-    static is(err: unknown): err is CruxyError;
-}

package/dist/hooks/config.d.ts

@@ -1,21 +0,0 @@
-import { type HookCatalog } from "./types.js";
-/**
- * Discovery for hooks + custom slash commands (C.19), mirroring the C.18 skills
- * loader: scan layered sources (project > user), validate every definition
- * fail-loud, exclude the malformed (collected as {@link HookConfigError}, never
- * thrown past the loader, never eval'd), and resolve precedence. Hook
- * definitions carry their {@link HookSource} — the trust model depends on
- * telling a repo's hooks (project) apart from your own (user).
- */
-/** The two source directories (each a `.cruxy` dir holding `hooks.json` and
- * `commands/`). */
-export interface HookSources {
-    /** `<cwd>/.cruxy` */
-    project: string;
-    /** `~/.cruxy` */
-    user: string;
-}
-/** The real sources for a project root. */
-export declare function defaultHookSources(cwd: string): HookSources;
-/** Load and resolve the full hook + command catalog. */
-export declare function loadHookCatalog(sources: HookSources): Promise<HookCatalog>;

package/dist/hooks/index.d.ts

@@ -1,7 +0,0 @@
-export { HOOK_EVENTS, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, HooksFileSchema, SlashFrontmatterSchema, defaultBlocking, type HookCatalog, type HookConfigError, type HookDefinition, type HookEvent, type HookSource, type HookSpec, type HookTrust, type SlashCommandSpec, type SlashKind, } from "./types.js";
-export { defaultHookSources, loadHookCatalog, type HookSources, } from "./config.js";
-export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPath, type TrustStore, } from "./trust.js";
-export { HookRunner, type HookRunnerDeps, type TrustPromptInfo, } from "./runner.js";
-export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, type SlashResolution, } from "./slash.js";
-export { buildHooksService, type BuildHooksServiceOptions, type HooksService, } from "./service.js";
-export { buildHooksRouter, type BuildHooksRouterOptions, type HooksRouterResult, type UntrustedHookRoot, } from "./router.js";

package/dist/hooks/router.d.ts

@@ -1,58 +0,0 @@
-import type { CruxyConfig } from "../config/index.js";
-import type { LifecycleHookRunner } from "../agent/loop.js";
-import type { logger as Logger } from "../utils/logger.js";
-import type { DeclaredRoot, Workspace } from "../workspace/index.js";
-import { type TrustStore } from "./trust.js";
-import type { HookCatalog, SlashCommandSpec } from "./types.js";
-/**
- * Per-root hook dispatch for a multi-root session (C.26 step 5).
- *
- * The isolation here is a PROPERTY OF CONSTRUCTION, not a guard: each root gets
- * its OWN {@link HookRunner} (own project-hook catalog, own trust key), so there
- * is no code path from root A's runner to a root-B action. The router only
- * decides WHICH runner to invoke:
- *
- *   - Tool-scoped events (`before-tool` / `after-tool` / `on-file-change`) fire
- *     exactly the ONE acting root's runner — the same root the tool resolved via
- *     {@link selectRoot}. A's project hooks structurally cannot fire for a
- *     B-scoped call (⚖︎10, pinned by test).
- *   - Session lifecycle events (`before-run` / `after-run`) have NO acting root,
- *     so they fan EVERY trusted root sequentially, in declaration order,
- *     root-labeled; a blocking failure in any root aborts the run naming that
- *     root (JC-1). Untrusted roots are skipped and named in the startup banner —
- *     never silent (a user's pre-run guard in an untrusted root must not vanish
- *     without a word).
- *
- * User-scope hooks (`~/.cruxy`) are session-global — authored by you, shared by
- * every root — so they fire EXACTLY ONCE per event through a single shared
- * runner, never once per root.
- */
-/** A root whose project hooks exist but are not trusted → named in the banner. */
-export interface UntrustedHookRoot {
-    name: string;
-    absPath: string;
-    count: number;
-}
-export interface HooksRouterResult {
-    /** The lifecycle firing seam (a {@link LifecycleHookRunner}). */
-    runner: LifecycleHookRunner;
-    /** Custom slash commands (primary root only this release). */
-    commands: SlashCommandSpec[];
-    /** Roots with untrusted project hooks — named in the banner, never silent. */
-    untrustedHookRoots: UntrustedHookRoot[];
-}
-export interface BuildHooksRouterOptions {
-    workspace: Workspace;
-    config: CruxyConfig;
-    logger: typeof Logger;
-    trust?: TrustStore;
-    /** Per-root catalog loader; defaults to the layered on-disk loader. */
-    loadCatalog?: (root: DeclaredRoot) => Promise<HookCatalog>;
-    now?: () => string;
-}
-/**
- * Build the multi-root hook router. One project-hook runner per declared root
- * (trust-gated against that root's key) plus one shared user-hook runner. Load
- * errors are surfaced through the logger exactly as the single-root path does.
- */
-export declare function buildHooksRouter(opts: BuildHooksRouterOptions): Promise<HooksRouterResult>;

package/dist/hooks/runner.d.ts

@@ -1,88 +0,0 @@
-import type { ToolContext } from "../tools/types.js";
-import { type TrustStore } from "./trust.js";
-import type { HookDefinition, HookEvent } from "./types.js";
-/**
- * The hook runner (C.19) — the security core. When a lifecycle event fires, it
- * runs the matching user-authored hooks, but a hook is **never** an approval
- * bypass:
- *
- * 1. **Project trust gate** (supply-chain safety). Before ANY project hook runs,
- *    the repo must be trusted for its current hook fingerprint. Untrusted →
- *    prompt (interactive) or `CRUXY_E_HOOK_UNTRUSTED` (non-interactive / declined
- *    / `trustPrompt` off). A cloned repo's hooks never execute silently. User
- *    hooks skip this prompt (you authored them) but NOT the gate below.
- * 2. **Per-command gate + sandbox** — every hook command goes through the SAME
- *    {@link runGatedShell} as `run_command`: the U.3 approval gate then the C.16
- *    sandbox (or host). There is no privileged route.
- * 3. **Blocking vs advisory** — a blocking hook that fails aborts the action
- *    fail-closed (`CRUXY_E_HOOK_FAILED`); an advisory hook reports and continues.
- */
-/** What the interactive trust prompt is shown. */
-export interface TrustPromptInfo {
-    root: string;
-    hooks: HookDefinition[];
-}
-export interface HookRunnerDeps {
-    /** Resolved hooks (with sources) for this project. */
-    hooks: HookDefinition[];
-    /** Persisted per-repo trust (see `trust.ts`). */
-    trust: TrustStore;
-    /** `config.hooks.enabled` — when false, nothing ever fires. */
-    enabled: boolean;
-    /** `config.hooks.trustPrompt` — when false, untrusted project hooks fail loud
-     * rather than prompting (never auto-trust). */
-    trustPrompt: boolean;
-    /** Whether cruxy can actually prompt (stdin is a TTY). */
-    interactive: boolean;
-    /** Project root — the trust key and fingerprint scope. */
-    cwd: string;
-    /** Root label for multi-root fan-out (C.26 step 5). When set, a blocking
-     * failure names its root (`<label> ▸ <hook>`) so an aborted run says which
-     * root refused. Undefined in the single-root path → messages unchanged. */
-    label?: string;
-    /** Interactive trust prompt (returns true to trust). Required only when a
-     * project defines hooks and `trustPrompt` + `interactive` are both on. */
-    promptTrust?: (info: TrustPromptInfo) => Promise<boolean>;
-    /** "running hook: <name>" surface (visible on every fire). */
-    announce?: (message: string) => void;
-    /** Advisory-failure surface (blocking failures throw instead). */
-    reportFailure?: (message: string) => void;
-    /** Injectable clock for the recorded trust timestamp (tests). */
-    now?: () => string;
-}
-export declare class HookRunner {
-    private readonly deps;
-    constructor(deps: HookRunnerDeps);
-    /** The project hooks — the trust-gated subset. */
-    private get projectHooks();
-    /** Prefix a hook name with the root label (multi-root), else leave it. */
-    private qualify;
-    /** Whether this root's project hooks are trusted for their current
-     * fingerprint. Read-only (never prompts/records) — the router uses it to skip
-     * untrusted roots and to name them in the banner. */
-    get projectTrusted(): boolean;
-    /** Count of project (trust-gated) hooks — for the untrusted-root banner. */
-    get projectHookCount(): number;
-    /**
-     * Fire every hook registered for `event`, in catalog order. Resolves normally
-     * when all hooks pass (or advisory ones fail); THROWS `CRUXY_E_HOOK_FAILED`
-     * when a blocking hook fails, or `CRUXY_E_HOOK_UNTRUSTED` when a project's
-     * hooks are not trusted. A no-op when hooks are disabled or none match.
-     */
-    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
-    /**
-     * Ensure this repo's project hooks are trusted for their current fingerprint.
-     * Records trust on an interactive accept; throws `CRUXY_E_HOOK_UNTRUSTED` on
-     * decline, when `trustPrompt` is off, or when non-interactive — NEVER
-     * auto-trusts. The fingerprint covers ALL project hooks, so a change to any of
-     * them invalidates a prior decision (stale → re-prompt).
-     */
-    private ensureProjectTrust;
-    /**
-     * Run one hook command through the shared gate + sandbox path and reduce it to
-     * a pass/fail verdict. A throw from {@link runGatedShell} (non-interactive
-     * approval, sandbox start failure) is a failure whose policy the caller
-     * applies — so an advisory hook can never abort the run on an infra error.
-     */
-    private runOne;
-}

package/dist/hooks/service.d.ts

@@ -1,38 +0,0 @@
-import type { CruxyConfig } from "../config/index.js";
-import type { logger as Logger } from "../utils/logger.js";
-import { type HookSources } from "./config.js";
-import { HookRunner, type TrustPromptInfo } from "./runner.js";
-import { type TrustStore } from "./trust.js";
-import type { HookCatalog, SlashCommandSpec } from "./types.js";
-/**
- * Construction/wiring for the hooks subsystem (C.19). Loads the layered catalog,
- * builds the {@link HookRunner} with the real trust store + an interactive trust
- * prompt, and exposes the resolved custom slash commands. Everything the runner
- * needs is injectable so the security behavior is unit-testable without touching
- * disk or a TTY.
- */
-export interface HooksService {
-    /** The lifecycle firing seam (threaded into the loop / session). */
-    runner: HookRunner;
-    /** Resolved custom slash commands (project > user). */
-    commands: SlashCommandSpec[];
-    /** The full catalog (for `cruxy hooks list` + surfacing load errors). */
-    catalog: HookCatalog;
-}
-export interface BuildHooksServiceOptions {
-    cwd: string;
-    config: CruxyConfig;
-    /** Whether cruxy can prompt (stdin is a TTY). */
-    interactive: boolean;
-    logger: typeof Logger;
-    sources?: HookSources;
-    trust?: TrustStore;
-    promptTrust?: (info: TrustPromptInfo) => Promise<boolean>;
-    now?: () => string;
-}
-/**
- * Load the catalog and assemble the {@link HooksService}. Malformed definitions
- * are surfaced (never eval'd, never silently dropped) through the logger; the
- * valid ones proceed.
- */
-export declare function buildHooksService(opts: BuildHooksServiceOptions): Promise<HooksService>;

package/dist/hooks/slash.d.ts

@@ -1,48 +0,0 @@
-import type { SlashCommandSpec } from "./types.js";
-/**
- * Custom slash-command resolution (C.19). Builtins are reserved and always win —
- * a custom command can never shadow `/help`, `/exit`, etc. A resolved custom
- * command is either a `prompt` (expanded to safe text fed to the agent) or a
- * `shell` binding (executed through the SAME gate + sandbox as everything else,
- * by the caller). Nothing here executes anything; it only resolves + expands.
- */
-/** The builtin slash commands (C.13) — reserved, not overridable. */
-export declare const BUILTIN_SLASH_COMMANDS: readonly ["help", "clear", "compact", "reload", "plan", "exit", "quit"];
-/** Is `name` (no leading slash) a reserved builtin? */
-export declare function isBuiltinSlash(name: string): boolean;
-/** The outcome of resolving a `/…` line against the custom catalog. */
-export type SlashResolution = 
-/** A builtin — the REPL's own dispatch handles it (custom never shadows it). */
-{
-    kind: "builtin";
-    name: string;
-}
-/** A prompt-template command, already expanded to the text to send the agent. */
- | {
-    kind: "prompt";
-    spec: SlashCommandSpec;
-    prompt: string;
-}
-/** A shell-bound command — the caller runs `spec.command` through the gate. */
- | {
-    kind: "shell";
-    spec: SlashCommandSpec;
-    args: string;
-}
-/** Not a slash line, or an unknown command. */
- | {
-    kind: "none";
-};
-/**
- * Resolve one input line. Non-slash input and unknown names → `none`. Builtins
- * short-circuit to `builtin` BEFORE the custom catalog is consulted, so a custom
- * command named after a builtin is inert (surfaced separately at load time).
- */
-export declare function resolveSlash(line: string, commands: readonly SlashCommandSpec[]): SlashResolution;
-/**
- * Expand a prompt template — substitute every `{{args}}` with the caller's args.
- * Pure text in, pure text out: the result is fed to the agent as a user prompt,
- * so a prompt command can never execute anything (that is the whole safety of
- * the default `prompt` kind).
- */
-export declare function expandTemplate(template: string, args: string): string;

package/dist/hooks/trust.d.ts

@@ -1,46 +0,0 @@
-import type { HookDefinition, HookTrust } from "./types.js";
-/**
- * The project-hook trust model (C.19). Trust is recorded in the GLOBAL dir
- * (`~/.cruxy/trust.json`) — in the user's home, NEVER inside a repo — so cloning
- * a repo carries zero trust and an attacker cannot ship a pre-trusted marker.
- *
- * Trust is bound to a {@link fingerprintHooks fingerprint} of the exact project
- * hook commands seen at trust time. It is re-checked on every run: if the
- * project's hooks change (a command / event / blocking edit), the fingerprint no
- * longer matches and trust is stale → the user is re-prompted. This is what
- * defeats trust-then-swap.
- */
-/** ~/.cruxy/trust.json */
-export declare function trustPath(): string;
-/**
- * A stable content fingerprint of a repo's PROJECT hook definitions. Canonical
- * by construction so a benign reformat of `hooks.json` (reindent, reordered
- * keys, extra whitespace inside a command) does NOT change it, while any real
- * change to a command, event, or blocking flag DOES:
- * - only the meaning-bearing fields are hashed (name, event, command, blocking);
- * - the command string is whitespace-normalized (trim + collapse runs);
- * - specs are sorted by name and serialized with a fixed key order.
- */
-export declare function fingerprintHooks(hooks: readonly HookDefinition[]): string;
-/** The persisted trust seam — a file-backed store in production, injectable for
- * tests. `get`/`record` are synchronous (the record is tiny). */
-export interface TrustStore {
-    /** The recorded decision for a repo root, or undefined if never trusted. */
-    get(root: string): HookTrust | undefined;
-    /** Persist a trust decision (overwrites any prior one for the same root). */
-    record(trust: HookTrust): void;
-}
-/**
- * Is this repo's current project-hook set trusted? True only when a decision
- * exists AND its fingerprint matches the current one — a changed hook set is
- * treated as untrusted (stale), forcing a fresh decision.
- */
-export declare function isTrusted(store: TrustStore, root: string, currentFingerprint: string): boolean;
-/**
- * The real store, persisting to `~/.cruxy/trust.json` as `{ [root]: HookTrust }`.
- * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
- * (fail-closed — a broken trust file must never grant trust).
- */
-export declare function fileTrustStore(file?: string): TrustStore;
-/** An in-memory store for tests (and any ephemeral run). */
-export declare function memoryTrustStore(seed?: HookTrust[]): TrustStore;