@ctxo/cli 0.13.0 → 0.14.0

package/dist/internal.d.ts

@@ -0,0 +1,747 @@
+import { z, ZodRawShape } from 'zod';
+
+declare const SymbolKindSchema: z.ZodEnum<{
+    function: "function";
+    class: "class";
+    interface: "interface";
+    method: "method";
+    variable: "variable";
+    type: "type";
+    table: "table";
+    view: "view";
+    procedure: "procedure";
+}>;
+type SymbolKind = z.infer<typeof SymbolKindSchema>;
+
+declare const EdgeKindSchema: z.ZodEnum<{
+    imports: "imports";
+    calls: "calls";
+    extends: "extends";
+    implements: "implements";
+    uses: "uses";
+    reads: "reads";
+    writes: "writes";
+    executes: "executes";
+}>;
+type EdgeKind = z.infer<typeof EdgeKindSchema>;
+declare const SymbolNodeSchema: z.ZodObject<{
+    symbolId: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        function: "function";
+        class: "class";
+        interface: "interface";
+        method: "method";
+        variable: "variable";
+        type: "type";
+        table: "table";
+        view: "view";
+        procedure: "procedure";
+    }>;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+    startOffset: z.ZodOptional<z.ZodNumber>;
+    endOffset: z.ZodOptional<z.ZodNumber>;
+    annotations: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        args: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        named: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type SymbolNode = z.infer<typeof SymbolNodeSchema>;
+declare const GraphEdgeSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    kind: z.ZodEnum<{
+        imports: "imports";
+        calls: "calls";
+        extends: "extends";
+        implements: "implements";
+        uses: "uses";
+        reads: "reads";
+        writes: "writes";
+        executes: "executes";
+    }>;
+    typeOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type GraphEdge = z.infer<typeof GraphEdgeSchema>;
+declare const FileIndexSchema: z.ZodObject<{
+    file: z.ZodString;
+    lastModified: z.ZodNumber;
+    contentHash: z.ZodOptional<z.ZodString>;
+    symbols: z.ZodArray<z.ZodObject<{
+        symbolId: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            function: "function";
+            class: "class";
+            interface: "interface";
+            method: "method";
+            variable: "variable";
+            type: "type";
+            table: "table";
+            view: "view";
+            procedure: "procedure";
+        }>;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        startOffset: z.ZodOptional<z.ZodNumber>;
+        endOffset: z.ZodOptional<z.ZodNumber>;
+        annotations: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            args: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            named: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        kind: z.ZodEnum<{
+            imports: "imports";
+            calls: "calls";
+            extends: "extends";
+            implements: "implements";
+            uses: "uses";
+            reads: "reads";
+            writes: "writes";
+            executes: "executes";
+        }>;
+        typeOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    complexity: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        symbolId: z.ZodString;
+        cyclomatic: z.ZodNumber;
+    }, z.core.$strip>>>;
+    intent: z.ZodArray<z.ZodObject<{
+        hash: z.ZodString;
+        message: z.ZodString;
+        date: z.ZodString;
+        kind: z.ZodLiteral<"commit">;
+    }, z.core.$strip>>;
+    antiPatterns: z.ZodArray<z.ZodObject<{
+        hash: z.ZodString;
+        message: z.ZodString;
+        date: z.ZodString;
+    }, z.core.$strip>>;
+    facts: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            "literal-comparison": "literal-comparison";
+            normalization: "normalization";
+            "retry-timeout": "retry-timeout";
+            endpoint: "endpoint";
+        }>;
+        symbolId: z.ZodString;
+        line: z.ZodNumber;
+        text: z.ZodString;
+        detail: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type FileIndex = z.infer<typeof FileIndexSchema>;
+interface ChurnData {
+    readonly filePath: string;
+    readonly commitCount: number;
+}
+interface CoChangeEntry {
+    readonly file1: string;
+    readonly file2: string;
+    readonly sharedCommits: number;
+    readonly frequency: number;
+}
+interface CommitRecord {
+    readonly hash: string;
+    readonly message: string;
+    readonly date: string;
+    readonly author: string;
+}
+/** git name-status letters Ctxo keeps; A added, M modified, D deleted, R renamed, C copied, T type changed. */
+type FileChangeStatus = 'A' | 'M' | 'D' | 'R' | 'C' | 'T';
+interface FileChange {
+    readonly status: FileChangeStatus;
+    /** Path after the change: repo-relative, forward slashes. */
+    readonly path: string;
+    /** Path before the change; set only for renames (R) and copies (C). */
+    readonly oldPath?: string;
+}
+/** One non-merge commit and the files it changed. */
+interface CommitChangeSet {
+    /** Full commit SHA (git %H). */
+    readonly hash: string;
+    /** Subject line (git %s). */
+    readonly message: string;
+    /** Author date, strict ISO 8601 (git %aI). */
+    readonly date: string;
+    /** Author name (git %an). */
+    readonly author: string;
+    /** Committer date in unix seconds (git %ct). */
+    readonly committedAt: number;
+    readonly changes: readonly FileChange[];
+}
+interface ChangeLog {
+    /** Short SHA of HEAD (git %h), which may itself be a merge commit. */
+    readonly head: string;
+    /** Committer date of HEAD in unix seconds (git %ct). */
+    readonly headCommittedAt: number;
+    /** Non-merge commits reachable from HEAD, newest first. */
+    readonly commits: readonly CommitChangeSet[];
+}
+/** A revision range: commits reachable from `head` and from none of `exclude`. */
+interface GitRange {
+    readonly head: string;
+    readonly exclude: readonly string[];
+}
+/** One commit of a range log. */
+interface RangeCommit {
+    /** Full commit SHA (git %H). */
+    readonly hash: string;
+    readonly subject: string;
+    /** More than one parent. */
+    readonly isMerge: boolean;
+    /** Values of the requested trailer key, in message order, trimmed, no empties. */
+    readonly trailers: readonly string[];
+    /** Files the commit changed; empty for merge commits. */
+    readonly changes: readonly FileChange[];
+}
+/** Branch facts of a repository; every field but `branches` is absent when git cannot say. */
+interface GitRefs {
+    /** Undefined on a detached HEAD. */
+    readonly currentBranch?: string;
+    /** For example 'origin/feat'. */
+    readonly upstream?: string;
+    /** For example 'origin/main'. */
+    readonly originHead?: string;
+    /** Local and remote-tracking short names without the remote HEAD aliases, in codepoint order. */
+    readonly branches: readonly string[];
+    /** Local branches only (refs/heads), in codepoint order. */
+    readonly localBranches?: readonly string[];
+    /** Remote-tracking branches as `<remote>/<name>` (refs/remotes, no HEAD aliases), in codepoint order. */
+    readonly remoteBranches?: readonly string[];
+}
+interface CommunityEntry {
+    readonly symbolId: string;
+    readonly communityId: number;
+    readonly communityLabel: string;
+}
+interface GodNode {
+    readonly symbolId: string;
+    readonly bridgedCommunities: readonly number[];
+    readonly centralityScore: number;
+}
+declare const EDGE_QUALITY: readonly ["full", "syntax-only", "mixed"];
+type EdgeQuality = (typeof EDGE_QUALITY)[number];
+interface CommunitySnapshot {
+    readonly version: 1;
+    readonly computedAt: string;
+    readonly commitSha: string;
+    readonly modularity: number;
+    readonly communities: readonly CommunityEntry[];
+    readonly godNodes: readonly GodNode[];
+    readonly edgeQuality: EdgeQuality;
+    readonly crossClusterEdges: number;
+}
+
+/** A table, view or procedure as one resource across every definition of its canonical name. */
+interface DataResourceIdentity {
+    /** `<name>::<kind>` with the winner's kind, for example `dbo.loans::table`. */
+    readonly canonicalId: string;
+    /** The definition every data reference to the name resolves to (the `definitionRank` tie-break). */
+    readonly winner: SymbolNode;
+    /** Every definition of the name, once each, in tie-break order: the winner comes first. */
+    readonly definitions: readonly SymbolNode[];
+    /**
+     * The definitions in neither a test file nor a documentation folder (the best `definitionRank`), in
+     * tie-break order. Empty when every definition is a docs or test copy.
+     */
+    readonly production: readonly SymbolNode[];
+}
+/**
+ * The symbol graph of an index.
+ *
+ * Add all nodes before any edge: `addEdge` resolves each endpoint against the nodes present at that moment,
+ * and an endpoint it cannot resolve keeps its raw id for good.
+ *
+ * A table, view or procedure is one resource per canonical name, whatever the number of files that define
+ * it (`dataResourceIdentity`). Every data reference resolves to the same definition, the winner, so only the
+ * winner has incoming edges. The impact tools read dependents through `getDependentEdges`, which gives every
+ * definition those edges, and forward edges stay on each definition: a procedure body in a later migration
+ * keeps its own accesses.
+ */
+declare class SymbolGraph$1 {
+    private readonly nodes;
+    private readonly nodesByFileAndName;
+    private readonly nodesByNameAndKind;
+    private readonly forwardEdges;
+    private readonly reverseEdges;
+    private readonly definitionRanks;
+    private edgeSet;
+    addNode(node: SymbolNode): void;
+    addEdge(edge: GraphEdge): void;
+    getNode(symbolId: string): SymbolNode | undefined;
+    private resolveNodeId;
+    private resolveNodeFuzzy;
+    /**
+     * Resolves a 2-part data reference (`dbo.loans::table`). A table or view reference is kind-agnostic
+     * across data resource kinds, a procedure reference matches procedures only. Several definitions
+     * resolve by `definitionRank` (a production copy before a documentation copy before a test copy), then
+     * to the codepoint-smallest symbolId, which is the first file in sorted path order. The result does
+     * not depend on insertion order.
+     */
+    private resolveDataReference;
+    /** The tie-break order of same-name definitions: `definitionRank`, then the codepoint-smaller symbolId. */
+    private readonly compareDefinitions;
+    /**
+     * The identity of the table, view or procedure that `id` names: a full id of any of its definitions, or a
+     * 2-part reference such as `dbo.loans::table`. Undefined when `id` names no node, or a node of another
+     * kind. A table or view identity spans both kinds, as a 2-part `::table` reference does.
+     */
+    dataResourceIdentity(id: string): DataResourceIdentity | undefined;
+    private identityOf;
+    /** `definitionRank`, cached per symbolId (the glob match runs once per definition). */
+    private definitionRankOf;
+    /**
+     * Extracts a `name::kind` key from the segments of a reference ID, supporting:
+     *   - 2-part: `Bar::class`                  → `Bar::class`
+     *   - 3-part: `pkg.Bar::helper::method`      → `helper::method`
+     * Returns undefined for 1-part IDs (no kind information available).
+     */
+    private extractNameKind;
+    getForwardEdges(symbolId: string): GraphEdge[];
+    getReverseEdges(symbolId: string): GraphEdge[];
+    /**
+     * The dependents of a resolved symbolId, as the impact tools read them. For a definition of a table, view
+     * or procedure these are the incoming edges of every same-name definition, which in practice are the
+     * winner's: any copy then reports the dependents of the resource. For every other id they are its own
+     * incoming edges, as `getReverseEdges` gives them.
+     */
+    getDependentEdges(symbolId: string): GraphEdge[];
+    hasNode(symbolId: string): boolean;
+    get nodeCount(): number;
+    get edgeCount(): number;
+    allNodes(): SymbolNode[];
+    allEdges(): GraphEdge[];
+}
+
+type ImpactConfidence = 'confirmed' | 'likely' | 'potential';
+interface BlastRadiusEntry {
+    readonly symbolId: string;
+    readonly depth: number;
+    readonly dependentCount: number;
+    readonly riskScore: number;
+    readonly confidence: ImpactConfidence;
+    readonly edgeKinds: string[];
+    readonly coChangeFrequency?: number;
+}
+interface BlastRadiusResult {
+    readonly impactedSymbols: BlastRadiusEntry[];
+    readonly directDependentsCount: number;
+    readonly confirmedCount: number;
+    readonly likelyCount: number;
+    readonly potentialCount: number;
+    readonly overallRiskScore: number;
+}
+declare class BlastRadiusCalculator$1 {
+    /**
+     * `symbolId` may be any id `SymbolGraph.getNode` resolves, a 2-part data id included. The root is the
+     * node it names, and the root's own file is the one co-change is matched against. Dependents come from
+     * `getDependentEdges`, so every copy of a table, view or procedure, and its 2-part id, has the dependents
+     * of the resource, and no definition of the resource counts as a dependent of another.
+     */
+    calculate(graph: SymbolGraph$1, symbolId: string, coChangeMap?: Map<string, CoChangeEntry[]>): BlastRadiusResult;
+}
+
+declare const CtxoConfigSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    stats: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    index: z.ZodOptional<z.ZodObject<{
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ignoreProjects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        facts: z.ZodOptional<z.ZodBoolean>;
+        tests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    masking: z.ZodOptional<z.ZodObject<{
+        clusterLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    watch: z.ZodOptional<z.ZodObject<{
+        snapshotMinFileChanges: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    gate: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        sensitivity: z.ZodOptional<z.ZodEnum<{
+            strict: "strict";
+            balanced: "balanced";
+            lenient: "lenient";
+        }>>;
+        minDependents: z.ZodOptional<z.ZodNumber>;
+        percentile: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    cochange: z.ZodOptional<z.ZodObject<{
+        maxCommits: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"all">]>>;
+        since: z.ZodOptional<z.ZodString>;
+        maxFilesPerCommit: z.ZodOptional<z.ZodNumber>;
+        minShared: z.ZodOptional<z.ZodNumber>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    communities: z.ZodOptional<z.ZodObject<{
+        resolution: z.ZodOptional<z.ZodNumber>;
+        godNodeMinBridged: z.ZodOptional<z.ZodNumber>;
+        godNodeMaxResults: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    contextsView: z.ZodOptional<z.ZodObject<{
+        weights: z.ZodOptional<z.ZodObject<{
+            dependency: z.ZodOptional<z.ZodNumber>;
+            coChange: z.ZodOptional<z.ZodNumber>;
+            data: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        hubs: z.ZodOptional<z.ZodObject<{
+            auto: z.ZodOptional<z.ZodBoolean>;
+            topPercent: z.ZodOptional<z.ZodNumber>;
+            minDependents: z.ZodOptional<z.ZodNumber>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        resolution: z.ZodOptional<z.ZodNumber>;
+        minCandidateFiles: z.ZodOptional<z.ZodNumber>;
+        technicalTerms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$loose>;
+type CtxoConfig = z.infer<typeof CtxoConfigSchema>;
+
+interface LoadedConfig {
+    readonly config: CtxoConfig;
+    readonly errors: readonly string[];
+    readonly invalidGlobs: readonly string[];
+    readonly path: string;
+    readonly exists: boolean;
+}
+
+/**
+ * Structured logger for Ctxo — all output goes to stderr (stdout reserved for MCP JSON-RPC).
+ *
+ * Supports debug mode via DEBUG environment variable:
+ *   DEBUG=ctxo:*          — all debug output
+ *   DEBUG=ctxo:git        — only git adapter debug
+ *   DEBUG=ctxo:index      — only indexing debug
+ *   DEBUG=ctxo:mcp        — only MCP handler debug
+ *   DEBUG=ctxo:storage    — only storage adapter debug
+ *   DEBUG=ctxo:masking    — only masking pipeline debug
+ *
+ * Always outputs: info, warn, error (regardless of DEBUG).
+ * Only outputs debug when matching namespace is enabled.
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+type CheckStatus = 'pass' | 'warn' | 'fail';
+interface CheckResult {
+    readonly id: string;
+    readonly title: string;
+    readonly status: CheckStatus;
+    readonly message: string;
+    readonly fix?: string;
+    readonly value?: string;
+}
+interface CheckContext {
+    readonly projectRoot: string;
+    readonly ctxoRoot: string;
+    readonly indices?: readonly FileIndex[];
+}
+interface IHealthCheck {
+    readonly id: string;
+    readonly title: string;
+    run(ctx: CheckContext): Promise<CheckResult>;
+}
+
+interface IGitPort {
+    getCommitHistory(filePath: string, maxCount?: number): Promise<CommitRecord[]>;
+    getFileChurn(filePath: string): Promise<ChurnData>;
+    getChangedFiles(since: string): Promise<string[]>;
+    isAvailable(): Promise<boolean>;
+    /** Short (8-char) SHA of current HEAD, or undefined if git is unavailable. */
+    getHeadSha?(): Promise<string | undefined>;
+    /**
+     * Number of commits in `base..HEAD` (reachable from HEAD but not from base).
+     * Returns undefined when either ref cannot be resolved. Zero means HEAD has
+     * not advanced past `base`.
+     */
+    countCommitsBetween?(base: string): Promise<number | undefined>;
+    /**
+     * Non-merge commits reachable from HEAD, newest first, each with the files it
+     * changed (renames carry `oldPath`). `maxCommits` caps the number of non-merge
+     * commits; 'all' reads the whole history. `head` and `headCommittedAt` describe
+     * HEAD itself, even when HEAD is a merge commit. Returns undefined when git
+     * fails or the repository has no commits.
+     */
+    getChangeLog?(maxCommits: number | 'all'): Promise<ChangeLog | undefined>;
+    /**
+     * Files changed by a single commit, root commits included. A merge commit
+     * yields an empty list. Returns undefined when `rev` cannot be resolved or git
+     * fails.
+     */
+    getCommitFileChanges?(rev: string): Promise<FileChange[] | undefined>;
+    /**
+     * Tracked paths that git marks skip-worktree (a sparse checkout, or
+     * `git update-index --skip-worktree`): git still tracks them, but they are
+     * deliberately absent from the working tree. Repo-relative, forward slashes.
+     * Returns undefined when git fails, so a caller can fail safe.
+     */
+    getSkipWorktreePaths?(): Promise<ReadonlySet<string> | undefined>;
+    /**
+     * Of the given repo-relative paths, those that git ignores (.gitignore, .git/info/exclude, the global
+     * excludes). A tracked file is never ignored in this sense, however a pattern matches it. Returns
+     * undefined when git fails.
+     */
+    getIgnoredPaths?(paths: readonly string[]): Promise<ReadonlySet<string> | undefined>;
+    /**
+     * The methods below return undefined when git fails, and refuse any ref that starts with `-`.
+     */
+    /** Full SHA of `<ref>^{commit}`. */
+    resolveCommit?(ref: string): Promise<string | undefined>;
+    /** Full SHA of the merge base of two refs. */
+    mergeBase?(a: string, b: string): Promise<string | undefined>;
+    /** Whether `ancestor` is reachable from `descendant`. */
+    isAncestor?(ancestor: string, descendant: string): Promise<boolean | undefined>;
+    /**
+     * Commits reachable from `range.head` and from none of `range.exclude`, newest first. Merge commits
+     * carry no changes. `trailerKey` collects that trailer's values per commit.
+     */
+    getRangeLog?(range: GitRange, options?: {
+        readonly trailerKey?: string;
+    }): Promise<RangeCommit[] | undefined>;
+    /**
+     * 'all': staged, unstaged and untracked (not ignored) changes against HEAD; 'staged': only the index.
+     */
+    getWorkingTreeChanges?(scope: 'all' | 'staged'): Promise<FileChange[] | undefined>;
+    /** Current branch, upstream, origin/HEAD and the branch list. */
+    getRefs?(): Promise<GitRefs | undefined>;
+    /** Tracked paths (git ls-files -z), repo-relative, forward slashes. */
+    listTrackedFiles?(): Promise<string[] | undefined>;
+}
+
+/**
+ * The module API: what an opt-in module such as `@ctxo/domain` registers with the CLI, and the host
+ * services it receives in return (ADR-018). Types only. A module imports these from `@ctxo/cli/internal`
+ * with `import type`; every runtime service arrives through `CtxoHost.services`. The API changes only in
+ * minor releases, and a module runs only when its `major.minor` equals the running CLI's.
+ */
+/** The 14 core MCP tools a module may enrich. */
+type CoreToolName = 'get_logic_slice' | 'get_why_context' | 'get_change_intelligence' | 'get_blast_radius' | 'get_architectural_overlay' | 'find_dead_code' | 'get_context_for_task' | 'get_ranked_context' | 'search_symbols' | 'get_changed_symbols' | 'find_importers' | 'get_class_hierarchy' | 'get_symbol_importance' | 'get_pr_impact';
+/**
+ * Adds fields to a core tool's payload before the envelope, truncation and masking see it. Additive only:
+ * it returns the payload with its fields added and never removes or rewrites the core's fields.
+ */
+type ResponseEnricher = (payload: Record<string, unknown>, args: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+/** An MCP tool a module contributes. The CLI wraps the handler with the envelope, masking and recording. */
+interface ModuleToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    /** A factory that receives the host's `zod`, so the module needs no zod dependency of its own. */
+    readonly inputSchema: (zod: typeof z) => ZodRawShape;
+    handler(args: Record<string, unknown>): Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+interface ToolRegistrar {
+    registerTool(tool: ModuleToolDefinition): void;
+}
+interface ModuleCommandContext {
+    readonly projectRoot: string;
+    readonly ctxoRoot: string;
+    readStdin(): Promise<string>;
+}
+/** A `ctxo <name>` command a module contributes. */
+interface ModuleCommand {
+    readonly name: string;
+    /** Usage lines for `ctxo <name> --help` and `ctxo --help`. */
+    readonly help: readonly string[];
+    /** The full usage for `ctxo <name> --help` (flags, exit codes); `help` is printed when absent. */
+    readonly usage?: readonly string[];
+    /** Left out of `ctxo --help` (hook commands). */
+    readonly hidden?: boolean;
+    /** Resolves to the exit code. */
+    run(args: readonly string[], ctx: ModuleCommandContext): Promise<number>;
+}
+interface CommandRegistrar {
+    registerCommand(command: ModuleCommand): void;
+}
+/** Whether a repo-relative path (either separator) is a test file. It already holds the annotated files. */
+type TestFileCheck = (path: string) => boolean;
+/** The raw commits of the configured co-change window, newest first, renames intact. */
+interface CoChangeWindowCommits {
+    /** Short SHA of HEAD. */
+    readonly head: string;
+    /** HEAD's committer date in unix seconds. */
+    readonly headCommittedAt: number;
+    readonly commits: readonly CommitChangeSet[];
+}
+/** What a module's index pass receives at the end of `ctxo index`. */
+interface IndexPassContext {
+    readonly projectRoot: string;
+    readonly ctxoRoot: string;
+    readonly config: CtxoConfig;
+    /** The merged full index. */
+    readonly indices: readonly FileIndex[];
+    /** Built on first call, then reused. */
+    graph(): SymbolGraph$1;
+    readonly isTestFile: TestFileCheck;
+    /** Raw window commits, renames intact; absent with --skip-history or without git. */
+    readonly history?: CoChangeWindowCommits;
+}
+interface InitFileResult {
+    readonly file: string;
+    readonly action: 'created' | 'updated' | 'skipped';
+    readonly warning?: string;
+}
+interface ClaudeHookEntry {
+    readonly event: string;
+    readonly matcher?: string;
+    readonly command: string;
+}
+interface InitPrompter {
+    confirm(message: string, initial: boolean): Promise<boolean>;
+    select<T extends string>(message: string, options: readonly {
+        readonly value: T;
+        readonly label: string;
+    }[], initial: T): Promise<T>;
+}
+interface InitPartContext {
+    readonly projectRoot: string;
+    readonly toolIds: readonly string[];
+    readonly dryRun: boolean;
+    readonly yes: boolean;
+    readonly boundaries?: 'by-rung' | 'report';
+    /** Returns `initial` when not interactive or with --yes. */
+    readonly prompt: InitPrompter;
+    ensureConfigFile(): InitFileResult;
+    ensureClaudeHookEntry(entry: ClaudeHookEntry): InitFileResult;
+    installSkill(platformId: string, name: string, content: string): InitFileResult | undefined;
+}
+/** The part a module adds to `ctxo init`. */
+interface InitContribution {
+    readonly part: 'domain';
+    apply(ctx: InitPartContext): Promise<readonly InitFileResult[]>;
+}
+/** What a module contributes. Every member is optional; the CLI uses the ones present. */
+interface CtxoModuleRegistration {
+    readonly id: 'domain';
+    /** Capabilities `ctxo index` requests from the plugins on the module's behalf. */
+    readonly indexCapabilities?: {
+        readonly facts?: boolean;
+    };
+    indexPass?(ctx: IndexPassContext): Promise<void>;
+    registerTools?(registrar: ToolRegistrar): void;
+    readonly enrich?: Partial<Record<CoreToolName, ResponseEnricher>>;
+    registerCommands?(registrar: CommandRegistrar): void;
+    readonly init?: InitContribution;
+    readonly doctorChecks?: readonly IHealthCheck[];
+}
+/** The runtime services a module gets from the CLI instead of importing them. */
+interface CtxoHostServices {
+    createLogger(namespace: string): Logger;
+    loadConfig(ctxoRoot: string): LoadedConfig;
+    /** The CLI's glob matcher: forward-slash normalised, dotfiles included. */
+    makeGlobMatcher(patterns: readonly string[]): (path: string) => boolean;
+    /** The classifier the contexts view uses: test globs, `index.tests`, test-framework annotations. */
+    createTestFileCheck(config: CtxoConfig, indices: readonly FileIndex[]): TestFileCheck;
+    createGit(projectRoot: string): IGitPort;
+    readIndex(ctxoRoot: string): FileIndex[];
+    buildGraph(indices: readonly FileIndex[]): SymbolGraph$1;
+    /** The configured co-change window (`cochange.maxCommits`, `cochange.since`); undefined without git history. */
+    readCoChangeWindow(projectRoot: string, config: CtxoConfig): Promise<CoChangeWindowCommits | undefined>;
+    /** The nearest directory at or above `dir` that holds `.git`. */
+    findGitRoot(dir: string): string | undefined;
+    /** Short names of the attributes that mark a test (`Fact`, `Test`, `TestMethod`, ...): the classifier's own list. */
+    readonly testFrameworkAnnotations: readonly string[];
+}
+interface CtxoHost {
+    readonly cliVersion: string;
+    readonly mode: 'mcp' | 'cli' | 'hook';
+    readonly projectRoot: string;
+    readonly ctxoRoot: string;
+    readonly services: CtxoHostServices;
+}
+/** The `register` export of a module package. Resolves to undefined when the module declines to run. */
+type CtxoModuleRegister = (host: CtxoHost) => Promise<CtxoModuleRegistration | undefined>;
+
+interface IStoragePort {
+    writeSymbolFile(fileIndex: FileIndex): void;
+    readSymbolFile(relativePath: string): FileIndex | undefined;
+    listIndexedFiles(): string[];
+    deleteSymbolFile(relativePath: string): void;
+    getSymbolById(symbolId: string): SymbolNode | undefined;
+    getEdgesFrom(symbolId: string): GraphEdge[];
+    getEdgesTo(symbolId: string): GraphEdge[];
+    getAllSymbols(): SymbolNode[];
+    getAllEdges(): GraphEdge[];
+    bulkWrite(indices: FileIndex[]): void;
+    readCommunities(): CommunitySnapshot | undefined;
+    writeCommunities(snapshot: CommunitySnapshot): void;
+    listCommunityHistory(limit?: number): CommunitySnapshot[];
+    close(): void;
+}
+
+interface IMaskingPort {
+    mask(text: string): string;
+}
+
+/**
+ * Response envelope — adds _meta field and truncates large payloads.
+ *
+ * Applied between payload construction and masking in every MCP handler.
+ * Threshold default: 8192 bytes (~8KB). Configurable via CTXO_RESPONSE_LIMIT env.
+ */
+interface ResponseMeta {
+    totalItems: number;
+    returnedItems: number;
+    truncated: boolean;
+    totalBytes: number;
+    hint?: string;
+    /**
+     * Workspace descriptor (forward-compat for Monorepo Workspace PRD).
+     * v0.7: `root` is set at startup; `package` is always undefined.
+     */
+    workspace?: {
+        root: string;
+        package?: string;
+    };
+    /**
+     * How far the community snapshot has drifted from current git HEAD.
+     * Only populated on cluster-aware MCP tools (overlay, blast-radius,
+     * why-context, pr-impact). Tells AI agents whether the cluster / drift /
+     * boundary data they are about to act on is fresh or N commits stale.
+     */
+    snapshotStaleness?: {
+        snapshotCommit: string;
+        currentHeadCommit?: string;
+        commitsBehind?: number;
+        hint?: string;
+    };
+}
+
+interface CreateModuleHostOptions {
+    readonly projectRoot: string;
+    readonly mode: CtxoHost['mode'];
+    /** Defaults to the running CLI's version. */
+    readonly cliVersion?: string;
+}
+/**
+ * The host a module's `register(host)` receives: the CLI version, the run mode, the project paths and the
+ * shared services. Imports neither the CLI router nor the MCP server, so the hook route can build one.
+ */
+declare function createModuleHost(options: CreateModuleHostOptions): CtxoHost;
+
+/**
+ * `@ctxo/cli/internal`: the API an opt-in module such as `@ctxo/domain` builds against (ADR-018).
+ *
+ * Types only, plus one runtime function, `createModuleHost`. Modules import the types with `import type`;
+ * every runtime service reaches them through `host.services`. No adapter is exported. The API changes only
+ * in minor releases. This file is a package entry and the one exception to the no-barrel rule.
+ */
+
+type SymbolGraph = SymbolGraph$1;
+type BlastRadiusCalculator = BlastRadiusCalculator$1;
+
+export { type BlastRadiusCalculator, type ChangeLog, type CheckContext, type CheckResult, type CheckStatus, type ClaudeHookEntry, type CoChangeEntry, type CoChangeWindowCommits, type CommandRegistrar, type CommitChangeSet, type CoreToolName, type CtxoConfig, type CtxoHost, type CtxoHostServices, type CtxoModuleRegister, type CtxoModuleRegistration, type EdgeKind, type FileChange, type FileChangeStatus, type FileIndex, type GitRange, type GitRefs, type GraphEdge, type IGitPort, type IHealthCheck, type IMaskingPort, type IStoragePort, type IndexPassContext, type InitContribution, type InitFileResult, type InitPartContext, type InitPrompter, type LoadedConfig, type Logger, type ModuleCommand, type ModuleCommandContext, type ModuleToolDefinition, type RangeCommit, type ResponseEnricher, type ResponseMeta, type SymbolGraph, type SymbolKind, type SymbolNode, type TestFileCheck, type ToolRegistrar, createModuleHost };