token-pilot 0.19.2 → 0.22.2

package/dist/hooks/summary-ast-index.js

@@ -0,0 +1,122 @@
+/**
+ * Primary hook-summary parser: spawns the bundled `ast-index` binary with
+ * `ast-index outline <path>` and maps the returned outline entries to
+ * SignalLine[]. Returns null when the binary is unavailable or the
+ * subprocess fails — the pipeline then falls back to regex / head+tail.
+ *
+ * Short-lived: the hook process spawns the binary once per invocation.
+ * The long-running AstIndexClient used by the MCP server is intentionally
+ * NOT reused here to keep the hook's startup cost minimal.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { findBinary } from "../ast-index/binary-manager.js";
+import { parseOutlineText } from "../ast-index/parser.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 4000;
+const MAX_TEXT_LEN = 140;
+function extractExtension(filePath) {
+    const lastDot = filePath.lastIndexOf(".");
+    if (lastDot === -1 || lastDot === filePath.length - 1)
+        return "";
+    const ext = filePath.slice(lastDot + 1).toLowerCase();
+    if (ext.includes("/") || ext.includes("\\"))
+        return "";
+    return ext;
+}
+function truncate(text) {
+    const trimmed = text.trim();
+    if (trimmed.length <= MAX_TEXT_LEN)
+        return trimmed;
+    return trimmed.slice(0, MAX_TEXT_LEN - 1) + "…";
+}
+function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    const charEstimate = Math.ceil(text.length / 4);
+    const whitespaceRatio = (text.match(/\s/g)?.length ?? 0) / text.length;
+    const adjustment = 1 - whitespaceRatio * 0.3;
+    return Math.ceil(charEstimate * adjustment);
+}
+const defaultExec = async (binary, args, opts) => {
+    const { stdout, stderr } = await execFileAsync(binary, args, {
+        timeout: opts.timeout,
+    });
+    return { stdout: String(stdout), stderr: String(stderr) };
+};
+/**
+ * Resolve the binary path unless the caller already supplied one (including
+ * `null` to force "not available" for tests).
+ */
+async function resolveBinaryPath(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    try {
+        const status = await findBinary(null);
+        return status?.available ? status.path : null;
+    }
+    catch {
+        return null;
+    }
+}
+function flattenEntries(entries) {
+    const signals = [];
+    function walk(entry, depth) {
+        const indent = depth > 0 ? "  ".repeat(depth) : "";
+        const label = entry.signature && entry.signature.length > 0
+            ? entry.signature
+            : entry.name;
+        const text = truncate(`${indent}${entry.kind} ${label}`);
+        signals.push({
+            line: entry.start_line,
+            kind: entry.visibility === "public" ? "export" : "declaration",
+            text,
+        });
+        if (entry.children && entry.children.length > 0) {
+            for (const child of entry.children)
+                walk(child, depth + 1);
+        }
+    }
+    for (const entry of entries)
+        walk(entry, 0);
+    return signals;
+}
+export async function parseAstIndexSummary(content, filePath, options = {}) {
+    const binaryPath = await resolveBinaryPath(options.binaryPath);
+    if (!binaryPath)
+        return null;
+    const exec = options.exec ?? defaultExec;
+    const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let outlineText;
+    try {
+        const { stdout } = await exec(binaryPath, ["outline", filePath], {
+            timeout,
+        });
+        outlineText = stdout;
+    }
+    catch {
+        return null;
+    }
+    let entries;
+    try {
+        entries = parseOutlineText(outlineText);
+    }
+    catch {
+        return null;
+    }
+    if (!entries || entries.length === 0)
+        return null;
+    const signals = flattenEntries(entries);
+    if (signals.length === 0)
+        return null;
+    const language = extractExtension(filePath);
+    const totalLines = content.split("\n").length;
+    const estimatedTokens = estimateTokens(content);
+    return {
+        signals,
+        totalLines,
+        estimatedTokens,
+        language,
+    };
+}
+//# sourceMappingURL=summary-ast-index.js.map

package/dist/hooks/summary-head-tail.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Last-resort head+tail summary.
+ *
+ * When both ast-index and the regex parser fail (crashed, unsupported language,
+ * malformed content), we still owe the caller *something* that respects the
+ * summary shape. This module produces a degraded HookSummary showing the first
+ * HEAD_LINES and last TAIL_LINES of the file as raw text, tagged with a note
+ * so the formatter can explain to the reader why the output is coarse.
+ *
+ * The function is intentionally total: empty input, unicode-heavy input, and
+ * absurdly large input all return a well-formed summary without throwing.
+ */
+import type { HookSummary } from "./summary-types.js";
+export declare function parseHeadTailSummary(content: string, filePath: string): HookSummary;
+//# sourceMappingURL=summary-head-tail.d.ts.map

package/dist/hooks/summary-head-tail.js

@@ -0,0 +1,78 @@
+/**
+ * Last-resort head+tail summary.
+ *
+ * When both ast-index and the regex parser fail (crashed, unsupported language,
+ * malformed content), we still owe the caller *something* that respects the
+ * summary shape. This module produces a degraded HookSummary showing the first
+ * HEAD_LINES and last TAIL_LINES of the file as raw text, tagged with a note
+ * so the formatter can explain to the reader why the output is coarse.
+ *
+ * The function is intentionally total: empty input, unicode-heavy input, and
+ * absurdly large input all return a well-formed summary without throwing.
+ */
+const HEAD_LINES = 40;
+const TAIL_LINES = 20;
+const MAX_TEXT_LEN = 140;
+function extractExtension(filePath) {
+    const lastDot = filePath.lastIndexOf(".");
+    if (lastDot === -1 || lastDot === filePath.length - 1)
+        return "";
+    const ext = filePath.slice(lastDot + 1).toLowerCase();
+    if (ext.includes("/") || ext.includes("\\"))
+        return "";
+    return ext;
+}
+function truncate(text) {
+    const trimmed = text.trimEnd();
+    if (trimmed.length <= MAX_TEXT_LEN)
+        return trimmed;
+    return trimmed.slice(0, MAX_TEXT_LEN - 1) + "…";
+}
+function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    const charEstimate = Math.ceil(text.length / 4);
+    const whitespaceRatio = (text.match(/\s/g)?.length ?? 0) / text.length;
+    const adjustment = 1 - whitespaceRatio * 0.3;
+    return Math.ceil(charEstimate * adjustment);
+}
+export function parseHeadTailSummary(content, filePath) {
+    const lines = content.split("\n");
+    const totalLines = lines.length;
+    const language = extractExtension(filePath);
+    const estimatedTokens = estimateTokens(content);
+    // When the file fits within HEAD_LINES + TAIL_LINES we include everything
+    // and omit the degradation note — no truncation actually happened.
+    if (totalLines <= HEAD_LINES + TAIL_LINES) {
+        const signals = lines.map((line, i) => ({
+            line: i + 1,
+            kind: "raw",
+            text: truncate(line),
+        }));
+        return {
+            signals,
+            totalLines,
+            estimatedTokens,
+            language,
+        };
+    }
+    const head = lines.slice(0, HEAD_LINES).map((line, i) => ({
+        line: i + 1,
+        kind: "raw",
+        text: truncate(line),
+    }));
+    const tailStart = totalLines - TAIL_LINES;
+    const tail = lines.slice(tailStart).map((line, i) => ({
+        line: tailStart + i + 1,
+        kind: "raw",
+        text: truncate(line),
+    }));
+    return {
+        signals: [...head, ...tail],
+        totalLines,
+        estimatedTokens,
+        language,
+        note: `parser unavailable — showing head+tail (first ${HEAD_LINES} and last ${TAIL_LINES} lines of ${totalLines})`,
+    };
+}
+//# sourceMappingURL=summary-head-tail.js.map

package/dist/hooks/summary-pipeline.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Summary-generation pipeline for the deny-enhanced hook.
+ *
+ * Tries three parsers in order — ast-index subprocess → regex → head+tail —
+ * and returns the first result with non-empty signals. If every parser
+ * fails to produce useful output (or throws), the pipeline reports
+ * `pass-through`, at which point the handler lets the original Read
+ * proceed unmodified rather than emitting an empty / misleading denial.
+ *
+ * Each parser is injectable for tests. The default wiring uses the
+ * real implementations from sibling modules.
+ */
+import type { HookSummary } from "./summary-types.js";
+export type PipelineTier = "ast-index" | "regex" | "head-tail";
+export type PipelineResult = {
+    kind: "summary";
+    summary: HookSummary;
+    tier: PipelineTier;
+} | {
+    kind: "pass-through";
+    reason: string;
+};
+type AstIndexFn = (content: string, filePath: string) => Promise<HookSummary | null>;
+type SyncSummaryFn = (content: string, filePath: string) => HookSummary;
+export interface PipelineOptions {
+    /** Primary parser — ast-index subprocess. Returns null on soft fail. */
+    astIndex?: AstIndexFn;
+    /** Fallback parser — regex. Expected to always return a HookSummary. */
+    regex?: SyncSummaryFn;
+    /** Last-resort parser — head+tail. Expected to always return a HookSummary. */
+    headTail?: SyncSummaryFn;
+}
+export declare function runSummaryPipeline(content: string, filePath: string, options?: PipelineOptions): Promise<PipelineResult>;
+export {};
+//# sourceMappingURL=summary-pipeline.d.ts.map

package/dist/hooks/summary-pipeline.js

@@ -0,0 +1,63 @@
+/**
+ * Summary-generation pipeline for the deny-enhanced hook.
+ *
+ * Tries three parsers in order — ast-index subprocess → regex → head+tail —
+ * and returns the first result with non-empty signals. If every parser
+ * fails to produce useful output (or throws), the pipeline reports
+ * `pass-through`, at which point the handler lets the original Read
+ * proceed unmodified rather than emitting an empty / misleading denial.
+ *
+ * Each parser is injectable for tests. The default wiring uses the
+ * real implementations from sibling modules.
+ */
+import { parseAstIndexSummary } from "./summary-ast-index.js";
+import { parseRegexSummary } from "./summary-regex.js";
+import { parseHeadTailSummary } from "./summary-head-tail.js";
+const defaultAstIndex = async (content, filePath) => parseAstIndexSummary(content, filePath);
+const defaultRegex = parseRegexSummary;
+const defaultHeadTail = parseHeadTailSummary;
+function hasSignals(summary) {
+    return !!summary && summary.signals.length > 0;
+}
+async function tryAsync(fn) {
+    try {
+        return await fn();
+    }
+    catch {
+        return null;
+    }
+}
+function trySync(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return null;
+    }
+}
+export async function runSummaryPipeline(content, filePath, options = {}) {
+    const astIndex = options.astIndex ?? defaultAstIndex;
+    const regex = options.regex ?? defaultRegex;
+    const headTail = options.headTail ?? defaultHeadTail;
+    // Tier 1 — ast-index. Soft-fails on null or throw.
+    const astResult = await tryAsync(() => astIndex(content, filePath));
+    if (hasSignals(astResult)) {
+        return { kind: "summary", summary: astResult, tier: "ast-index" };
+    }
+    // Tier 2 — regex. Empty signals means "nothing useful here, try next".
+    const regexResult = trySync(() => regex(content, filePath));
+    if (hasSignals(regexResult)) {
+        return { kind: "summary", summary: regexResult, tier: "regex" };
+    }
+    // Tier 3 — head+tail. Always produces *something*, unless the parser
+    // itself crashes (in which case we pass-through).
+    const headTailResult = trySync(() => headTail(content, filePath));
+    if (hasSignals(headTailResult)) {
+        return { kind: "summary", summary: headTailResult, tier: "head-tail" };
+    }
+    return {
+        kind: "pass-through",
+        reason: "all parsers returned empty or threw",
+    };
+}
+//# sourceMappingURL=summary-pipeline.js.map

package/dist/hooks/summary-regex.d.ts

@@ -0,0 +1,14 @@
+/**
+ * In-process regex-based structural summary parser.
+ *
+ * Fallback when the bundled ast-index binary is unavailable. Intentionally
+ * coarse: extracts imports, exports, and major top-level declarations per
+ * language using line-oriented regex. Never throws — worst case returns
+ * empty signals.
+ *
+ * Used by the hook summary pipeline (Phase 1 subtask 1.6).
+ */
+import type { HookSummary, SignalKind, SignalLine } from "./summary-types.js";
+export type { HookSummary, SignalKind, SignalLine };
+export declare function parseRegexSummary(content: string, filePath: string): HookSummary;
+//# sourceMappingURL=summary-regex.d.ts.map

package/dist/hooks/summary-regex.js

@@ -0,0 +1,130 @@
+/**
+ * In-process regex-based structural summary parser.
+ *
+ * Fallback when the bundled ast-index binary is unavailable. Intentionally
+ * coarse: extracts imports, exports, and major top-level declarations per
+ * language using line-oriented regex. Never throws — worst case returns
+ * empty signals.
+ *
+ * Used by the hook summary pipeline (Phase 1 subtask 1.6).
+ */
+const MAX_TEXT_LEN = 140;
+const EXTENSIONS = {
+    ts: tsJsPattern(),
+    tsx: tsJsPattern(),
+    js: tsJsPattern(),
+    jsx: tsJsPattern(),
+    mjs: tsJsPattern(),
+    cjs: tsJsPattern(),
+    py: pythonPattern(),
+    go: goPattern(),
+    rs: rustPattern(),
+};
+function tsJsPattern() {
+    return {
+        // Covers ES modules and CommonJS: `import ...`, `const x = require(...)`
+        import: /^\s*(import\s|const\s+\w+\s*=\s*require\s*\()/,
+        // export keyword, module.exports, exports.foo =
+        export: /^\s*(export\s|module\.exports\s*=|exports\.\w+\s*=)/,
+        // top-level declarations not prefixed with export — function/class/interface/type/enum
+        declaration: /^\s*(async\s+)?(function|class|interface|type|enum)\s+\w+/,
+    };
+}
+function pythonPattern() {
+    return {
+        import: /^\s*(import\s|from\s+\S+\s+import\s)/,
+        declaration: /^\s*(async\s+)?(def\s+\w+|class\s+\w+)/,
+    };
+}
+function goPattern() {
+    return {
+        import: /^\s*import\s/,
+        declaration: /^\s*(func\s|type\s+\w+\s+(struct|interface|func))/,
+    };
+}
+function rustPattern() {
+    return {
+        import: /^\s*use\s/,
+        export: /^\s*pub\s+(fn|struct|trait|enum|type|mod|const|static)\s/,
+        declaration: /^\s*(async\s+)?(fn|struct|trait|enum|type|mod)\s+\w+/,
+    };
+}
+/**
+ * Derive the lower-case extension for a file path.
+ * Returns an empty string if the path has no dot.
+ */
+function extractExtension(filePath) {
+    const lastDot = filePath.lastIndexOf(".");
+    if (lastDot === -1 || lastDot === filePath.length - 1)
+        return "";
+    const ext = filePath.slice(lastDot + 1).toLowerCase();
+    // Guard against extensions containing path separators (e.g., "/foo.d/bar").
+    if (ext.includes("/") || ext.includes("\\"))
+        return "";
+    return ext;
+}
+function truncate(text) {
+    const trimmed = text.trim();
+    if (trimmed.length <= MAX_TEXT_LEN)
+        return trimmed;
+    return trimmed.slice(0, MAX_TEXT_LEN - 1) + "…";
+}
+/**
+ * Very rough token estimate mirroring the project-wide heuristic
+ * (see src/core/token-estimator.ts). Duplicated here to avoid a hard
+ * dependency in the hook hot-path.
+ */
+function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    const charEstimate = Math.ceil(text.length / 4);
+    const whitespaceRatio = (text.match(/\s/g)?.length ?? 0) / text.length;
+    const adjustment = 1 - whitespaceRatio * 0.3;
+    return Math.ceil(charEstimate * adjustment);
+}
+export function parseRegexSummary(content, filePath) {
+    const language = extractExtension(filePath);
+    const totalLines = content.split("\n").length;
+    const estimatedTokens = estimateTokens(content);
+    const patterns = EXTENSIONS[language];
+    if (!patterns) {
+        return {
+            signals: [],
+            totalLines,
+            estimatedTokens,
+            language,
+        };
+    }
+    const lines = content.split("\n");
+    const signals = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line || line.trim().length === 0)
+            continue;
+        // Classification order: import → export → declaration. First match wins.
+        let kind = null;
+        if (patterns.import?.test(line)) {
+            kind = "import";
+        }
+        else if (patterns.export?.test(line)) {
+            kind = "export";
+        }
+        else if (patterns.declaration?.test(line)) {
+            kind = "declaration";
+        }
+        if (kind !== null) {
+            signals.push({
+                line: i + 1,
+                kind,
+                text: truncate(line),
+            });
+        }
+    }
+    return {
+        signals,
+        totalLines,
+        estimatedTokens,
+        language,
+    };
+}
+//# sourceMappingURL=summary-regex.js.map

package/dist/hooks/summary-types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared types for the hook summary pipeline (Phase 1).
+ *
+ * Every parser in the fallback chain (ast-index subprocess, regex, head+tail)
+ * returns a HookSummary. The downstream formatter in handleHookRead renders
+ * this structure into the `permissionDecisionReason` body.
+ */
+export type SignalKind = "import" | "export" | "declaration" | "raw";
+export interface SignalLine {
+    /** 1-based line number in the original source. */
+    line: number;
+    kind: SignalKind;
+    /** Trimmed source line, truncated to a parser-defined character cap. */
+    text: string;
+}
+export interface HookSummary {
+    signals: SignalLine[];
+    totalLines: number;
+    estimatedTokens: number;
+    /** Lower-case extension without the dot; empty string if none. */
+    language: string;
+    /**
+     * Optional human-readable note explaining a non-standard summary
+     * (e.g. "parser unavailable — showing head+tail only"). Rendered by the
+     * formatter above the signals section.
+     */
+    note?: string;
+}
+//# sourceMappingURL=summary-types.d.ts.map

package/dist/hooks/summary-types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for the hook summary pipeline (Phase 1).
+ *
+ * Every parser in the fallback chain (ast-index subprocess, regex, head+tail)
+ * returns a HookSummary. The downstream formatter in handleHookRead renders
+ * this structure into the `permissionDecisionReason` body.
+ */
+export {};
+//# sourceMappingURL=summary-types.js.map

package/dist/index.d.ts

@@ -1,9 +1,21 @@
 #!/usr/bin/env node
+import type { HookMode } from "./types.js";
 export declare const CODE_EXTENSIONS: Set<string>;
 export declare function getVersion(): string;
 export declare function main(cliArgs?: string[]): Promise<void>;
 export declare function startServer(cliArgs?: string[]): Promise<void>;
-export declare function handleHookRead(filePathArg?: string, denyThreshold?: number): void;
+export interface HookReadAdaptiveOptions {
+    adaptiveThreshold?: boolean;
+    adaptiveBudgetTokens?: number;
+}
+export declare function handleHookRead(filePathArg?: string, mode?: HookMode, denyThreshold?: number, projectRoot?: string, adaptive?: HookReadAdaptiveOptions): Promise<void>;
+/**
+ * Pure implementation of the hook-read dispatch — returns the JSON payload
+ * to write to stdout, or null when we should pass-through (no output).
+ * Extracted for testability; the outer handleHookRead adds the process.exit
+ * wrapping.
+ */
+export declare function runHookReadDispatch(filePathArg: string | undefined, mode: HookMode, denyThresholdArg?: number, projectRootArg?: string, adaptive?: HookReadAdaptiveOptions): Promise<string | null>;
 export declare function handleHookEdit(): void;
 export declare function handleInstallHook(projectRoot: string): Promise<void>;
 export declare function handleUninstallHook(projectRoot: string): Promise<void>;
@@ -11,8 +23,8 @@ export declare function handleInstallAstIndex(): Promise<void>;
 export declare function handleDoctor(): Promise<void>;
 export declare function handleInit(targetDir: string): Promise<void>;
 export declare function checkNpmLatest(packageName: string): Promise<string | null>;
-import type { TokenPilotConfig } from './types.js';
-import type { BinaryStatus } from './ast-index/binary-manager.js';
+import type { TokenPilotConfig } from "./types.js";
+import type { BinaryStatus } from "./ast-index/binary-manager.js";
 export declare function checkAllUpdates(config: TokenPilotConfig, binaryStatus: BinaryStatus): Promise<void>;
 export declare function printHelp(): void;
 //# sourceMappingURL=index.d.ts.map