@flyingrobots/graft 0.5.0 → 0.6.1

package/dist/operations/read-range.js

@@ -0,0 +1,41 @@
+const MAX_RANGE_LINES = 250;
+export async function readRange(filePath, start, end, opts) {
+    let raw;
+    try {
+        raw = await opts.fs.readFile(filePath, "utf-8");
+    }
+    catch {
+        return { path: filePath, reason: "NOT_FOUND" };
+    }
+    if (start > end) {
+        return { path: filePath, reason: "INVALID_RANGE" };
+    }
+    const allLines = raw.split("\n");
+    const totalLines = allLines.length;
+    let effectiveEnd = end;
+    let truncated = false;
+    let clipped = false;
+    // Check if range exceeds 250 lines
+    if (effectiveEnd - start + 1 > MAX_RANGE_LINES) {
+        effectiveEnd = start + MAX_RANGE_LINES - 1;
+        truncated = true;
+    }
+    // Clip to EOF
+    if (effectiveEnd > totalLines) {
+        effectiveEnd = totalLines;
+        clipped = true;
+    }
+    // Extract lines (1-based to 0-based)
+    const selected = allLines.slice(start - 1, effectiveEnd);
+    const content = selected.join("\n");
+    return {
+        path: filePath,
+        content,
+        startLine: start,
+        endLine: effectiveEnd,
+        ...(truncated ? { truncated: true, reason: "RANGE_EXCEEDED" } : {}),
+        ...(clipped && !truncated ? { clipped: true } : {}),
+        ...(clipped && truncated ? { clipped: true } : {}),
+    };
+}
+//# sourceMappingURL=read-range.js.map

package/dist/operations/read-range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-range.js","sourceRoot":"","sources":["../../src/operations/read-range.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG,GAAG,CAAC;AAY5B,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,KAAa,EACb,GAAW,EACX,IAAwB;IAExB,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACjD,CAAC;IAED,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QAChB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;IAEnC,IAAI,YAAY,GAAG,GAAG,CAAC;IACvB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,mCAAmC;IACnC,IAAI,YAAY,GAAG,KAAK,GAAG,CAAC,GAAG,eAAe,EAAE,CAAC;QAC/C,YAAY,GAAG,KAAK,GAAG,eAAe,GAAG,CAAC,CAAC;QAC3C,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,cAAc;IACd,IAAI,YAAY,GAAG,UAAU,EAAE,CAAC;QAC9B,YAAY,GAAG,UAAU,CAAC;QAC1B,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,qCAAqC;IACrC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEpC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO;QACP,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,YAAY;QACrB,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC"}

package/dist/operations/repo-workspace.d.ts

@@ -0,0 +1,114 @@
+import { type SafeReadResult } from "./safe-read.js";
+import { type FileOutlineResult } from "./file-outline.js";
+import { type ReadRangeResult } from "./read-range.js";
+import { ObservationCache } from "./observation-cache.js";
+import { GovernorTracker } from "../session/tracker.js";
+import { type OutlineDiff } from "../parser/diff.js";
+import type { JumpEntry, OutlineEntry } from "../parser/types.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { JsonCodec } from "../ports/codec.js";
+export interface RepoWorkspaceRefusedResult {
+    readonly path: string;
+    readonly projection: "refused";
+    readonly reason: string;
+    readonly reasonDetail: string;
+    readonly next: string[];
+    readonly actual: {
+        readonly lines: number;
+        readonly bytes: number;
+    };
+}
+export interface RepoWorkspaceSafeReadCacheHitResult {
+    readonly path: string;
+    readonly projection: "cache_hit";
+    readonly reason: "REREAD_UNCHANGED";
+    readonly outline: readonly OutlineEntry[];
+    readonly jumpTable: readonly JumpEntry[];
+    readonly actual: Readonly<{
+        lines: number;
+        bytes: number;
+    }>;
+    readonly readCount: number;
+    readonly estimatedBytesAvoided: number;
+    readonly lastReadAt: string;
+}
+export interface RepoWorkspaceSafeReadDiffResult {
+    readonly path: string;
+    readonly projection: "diff";
+    readonly reason: "CHANGED_SINCE_LAST_READ";
+    readonly diff: OutlineDiff;
+    readonly outline: readonly OutlineEntry[];
+    readonly jumpTable: readonly JumpEntry[];
+    readonly actual: Readonly<{
+        lines: number;
+        bytes: number;
+    }>;
+    readonly readCount: number;
+    readonly lastReadAt: string;
+}
+export type RepoWorkspaceSafeReadResult = SafeReadResult | RepoWorkspaceSafeReadCacheHitResult | RepoWorkspaceSafeReadDiffResult;
+export type RepoWorkspaceFileOutlineResult = FileOutlineResult | RepoWorkspaceRefusedResult;
+export type RepoWorkspaceReadRangeResult = ReadRangeResult | RepoWorkspaceRefusedResult;
+export type RepoWorkspaceChangedSinceResult = {
+    readonly status: "file_not_found";
+} | {
+    readonly status: "refused";
+    readonly reason: string;
+} | {
+    readonly status: "unsupported";
+    readonly reason: "UNSUPPORTED_LANGUAGE";
+} | {
+    readonly status: "unchanged";
+} | {
+    readonly status: "no_previous_observation";
+} | {
+    readonly diff: OutlineDiff;
+    readonly consumed: boolean;
+};
+export interface RepoWorkspaceOptions {
+    readonly projectRoot: string;
+    readonly fs: FileSystem;
+    readonly codec: JsonCodec;
+    readonly graftignorePatterns?: readonly string[] | undefined;
+    readonly resolvePath?: ((input: string) => string) | undefined;
+    readonly toPolicyPath?: ((resolvedPath: string) => string) | undefined;
+    readonly governor?: GovernorTracker | undefined;
+    readonly cache?: ObservationCache | undefined;
+}
+export declare class RepoWorkspace {
+    private readonly resolveWorkspacePath;
+    private readonly policyPathForWorkspaceFile;
+    readonly projectRoot: string;
+    readonly fs: FileSystem;
+    readonly codec: JsonCodec;
+    readonly graftignorePatterns: readonly string[];
+    readonly governor: GovernorTracker;
+    readonly cache: ObservationCache;
+    constructor(options: RepoWorkspaceOptions);
+    static loadGraftignorePatterns(fs: Pick<FileSystem, "readFile">, projectRoot: string): Promise<string[]>;
+    setBudget(bytes: number): void;
+    getBudget(): {
+        total: number;
+        consumed: number;
+        remaining: number;
+        fraction: number;
+    } | null;
+    private evaluateRefusal;
+    safeRead(args: {
+        readonly path: string;
+        readonly intent?: string | undefined;
+    }): Promise<RepoWorkspaceSafeReadResult>;
+    fileOutline(args: {
+        readonly path: string;
+    }): Promise<RepoWorkspaceFileOutlineResult>;
+    readRange(args: {
+        readonly path: string;
+        readonly start: number;
+        readonly end: number;
+    }): Promise<RepoWorkspaceReadRangeResult>;
+    changedSince(args: {
+        readonly path: string;
+        readonly consume?: boolean | undefined;
+    }): Promise<RepoWorkspaceChangedSinceResult>;
+}
+//# sourceMappingURL=repo-workspace.d.ts.map

package/dist/operations/repo-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-workspace.d.ts","sourceRoot":"","sources":["../../src/operations/repo-workspace.ts"],"names":[],"mappings":"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"}

package/dist/operations/repo-workspace.js

@@ -0,0 +1,228 @@
+import { safeRead } from "./safe-read.js";
+import { fileOutline } from "./file-outline.js";
+import { readRange } from "./read-range.js";
+import { CachedFile } from "./cached-file.js";
+import { ObservationCache, hashContent } from "./observation-cache.js";
+import { GovernorTracker } from "../session/tracker.js";
+import { diffOutlines } from "../parser/diff.js";
+import { extractOutlineForFile } from "../parser/outline.js";
+import { evaluatePolicy } from "../policy/evaluate.js";
+import { RefusedResult } from "../policy/types.js";
+import { loadGraftignore } from "../policy/graftignore.js";
+async function loadWorkspaceGraftignore(fs, projectRoot) {
+    try {
+        return loadGraftignore(await fs.readFile(`${projectRoot}/.graftignore`, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+export class RepoWorkspace {
+    resolveWorkspacePath;
+    policyPathForWorkspaceFile;
+    projectRoot;
+    fs;
+    codec;
+    graftignorePatterns;
+    governor;
+    cache;
+    constructor(options) {
+        this.projectRoot = options.projectRoot;
+        this.fs = options.fs;
+        this.codec = options.codec;
+        this.graftignorePatterns = options.graftignorePatterns ?? [];
+        this.governor = options.governor ?? new GovernorTracker();
+        this.cache = options.cache ?? new ObservationCache();
+        this.resolveWorkspacePath = options.resolvePath ?? ((input) => input);
+        this.policyPathForWorkspaceFile = options.toPolicyPath ?? ((resolvedPath) => resolvedPath);
+    }
+    static async loadGraftignorePatterns(fs, projectRoot) {
+        return loadWorkspaceGraftignore(fs, projectRoot);
+    }
+    setBudget(bytes) {
+        this.governor.setBudget(bytes);
+    }
+    getBudget() {
+        return this.governor.getBudget();
+    }
+    evaluateRefusal(filePath, actual) {
+        const policy = evaluatePolicy({
+            path: this.policyPathForWorkspaceFile(filePath),
+            lines: actual.lines,
+            bytes: actual.bytes,
+        }, {
+            graftignorePatterns: this.graftignorePatterns.length > 0 ? [...this.graftignorePatterns] : undefined,
+            sessionDepth: this.governor.getGovernorDepth(),
+            budgetRemaining: this.governor.getBudget()?.remaining,
+        });
+        if (!(policy instanceof RefusedResult)) {
+            return null;
+        }
+        return {
+            path: filePath,
+            projection: "refused",
+            reason: policy.reason,
+            reasonDetail: policy.reasonDetail,
+            next: [...policy.next],
+            actual,
+        };
+    }
+    async safeRead(args) {
+        const filePath = this.resolveWorkspacePath(args.path);
+        let snapshot = null;
+        try {
+            snapshot = new CachedFile(filePath, await this.fs.readFile(filePath, "utf-8"));
+        }
+        catch {
+            // Let safeRead produce the not-found error shape.
+        }
+        if (snapshot?.supportsOutline === true) {
+            const cacheResult = this.cache.check(filePath, snapshot.rawContent);
+            if (cacheResult.hit) {
+                cacheResult.obs.touch();
+                return {
+                    path: filePath,
+                    projection: "cache_hit",
+                    reason: "REREAD_UNCHANGED",
+                    outline: cacheResult.obs.outline,
+                    jumpTable: cacheResult.obs.jumpTable,
+                    actual: cacheResult.obs.actual,
+                    readCount: cacheResult.obs.readCount,
+                    estimatedBytesAvoided: snapshot.actual.bytes,
+                    lastReadAt: cacheResult.obs.lastReadAt,
+                };
+            }
+            if (cacheResult.stale !== null) {
+                const refusal = this.evaluateRefusal(filePath, snapshot.actual);
+                if (refusal !== null) {
+                    return refusal;
+                }
+                this.cache.record(filePath, snapshot.hash, snapshot.outline, snapshot.jumpTable, snapshot.actual);
+                const updated = this.cache.get(filePath);
+                return {
+                    path: filePath,
+                    projection: "diff",
+                    reason: "CHANGED_SINCE_LAST_READ",
+                    diff: diffOutlines(cacheResult.stale.outline, snapshot.outline),
+                    outline: snapshot.outline,
+                    jumpTable: snapshot.jumpTable,
+                    actual: snapshot.actual,
+                    readCount: cacheResult.stale.readCount + 1,
+                    lastReadAt: updated?.lastReadAt ?? new Date().toISOString(),
+                };
+            }
+        }
+        const result = await safeRead(filePath, {
+            fs: this.fs,
+            codec: this.codec,
+            content: snapshot?.rawContent,
+            intent: args.intent,
+            policyPath: this.policyPathForWorkspaceFile(filePath),
+            graftignorePatterns: [...this.graftignorePatterns],
+            sessionDepth: this.governor.getGovernorDepth(),
+            budgetRemaining: this.governor.getBudget()?.remaining,
+        });
+        if (snapshot !== null &&
+            snapshot.supportsOutline &&
+            result.actual !== undefined &&
+            (result.projection === "content" || result.projection === "outline") &&
+            result.reason !== "UNSUPPORTED_LANGUAGE") {
+            this.cache.record(filePath, snapshot.hash, snapshot.outline, snapshot.jumpTable, result.actual);
+        }
+        return result;
+    }
+    async fileOutline(args) {
+        const filePath = this.resolveWorkspacePath(args.path);
+        let rawContent = null;
+        try {
+            rawContent = await this.fs.readFile(filePath, "utf-8");
+        }
+        catch {
+            // Let fileOutline shape the not-found result.
+        }
+        if (rawContent !== null) {
+            const actual = {
+                lines: rawContent.split("\n").length,
+                bytes: Buffer.byteLength(rawContent),
+            };
+            const refusal = this.evaluateRefusal(filePath, actual);
+            if (refusal !== null) {
+                return refusal;
+            }
+            const cacheResult = this.cache.check(filePath, rawContent);
+            if (cacheResult.hit) {
+                cacheResult.obs.touch();
+                return {
+                    path: filePath,
+                    outline: [...cacheResult.obs.outline],
+                    jumpTable: [...cacheResult.obs.jumpTable],
+                    cacheHit: true,
+                };
+            }
+        }
+        const result = await fileOutline(filePath, { fs: this.fs });
+        if (rawContent !== null && result.reason !== "UNSUPPORTED_LANGUAGE") {
+            this.cache.record(filePath, hashContent(rawContent), result.outline, result.jumpTable, { lines: rawContent.split("\n").length, bytes: Buffer.byteLength(rawContent) });
+        }
+        return result;
+    }
+    async readRange(args) {
+        const filePath = this.resolveWorkspacePath(args.path);
+        let rawContent = null;
+        try {
+            rawContent = await this.fs.readFile(filePath, "utf-8");
+        }
+        catch {
+            // Let readRange shape the not-found result.
+        }
+        if (rawContent !== null) {
+            const refusal = this.evaluateRefusal(filePath, {
+                lines: rawContent.split("\n").length,
+                bytes: Buffer.byteLength(rawContent),
+            });
+            if (refusal !== null) {
+                return refusal;
+            }
+        }
+        return readRange(filePath, args.start, args.end, { fs: this.fs });
+    }
+    async changedSince(args) {
+        const filePath = this.resolveWorkspacePath(args.path);
+        const consume = args.consume === true;
+        let rawContent;
+        try {
+            rawContent = await this.fs.readFile(filePath, "utf-8");
+        }
+        catch {
+            return { status: "file_not_found" };
+        }
+        const actual = {
+            lines: rawContent.split("\n").length,
+            bytes: Buffer.byteLength(rawContent),
+        };
+        const refusal = this.evaluateRefusal(filePath, actual);
+        if (refusal !== null) {
+            return { status: "refused", reason: refusal.reason };
+        }
+        const newOutlineResult = extractOutlineForFile(filePath, rawContent);
+        if (newOutlineResult === null) {
+            return {
+                status: "unsupported",
+                reason: "UNSUPPORTED_LANGUAGE",
+            };
+        }
+        const cacheResult = this.cache.check(filePath, rawContent);
+        if (cacheResult.hit) {
+            return { status: "unchanged" };
+        }
+        if (cacheResult.stale === null) {
+            return { status: "no_previous_observation" };
+        }
+        const diff = diffOutlines(cacheResult.stale.outline, newOutlineResult.entries);
+        if (consume) {
+            this.cache.record(filePath, hashContent(rawContent), newOutlineResult.entries, newOutlineResult.jumpTable ?? [], actual);
+        }
+        return { diff, consumed: consume };
+    }
+}
+//# sourceMappingURL=repo-workspace.js.map

package/dist/operations/repo-workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-workspace.js","sourceRoot":"","sources":["../../src/operations/repo-workspace.ts"],"names":[],"mappings":"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"}

package/dist/operations/result-dto.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject } from "../contracts/json-object.js";
+/**
+ * Convert any result object with known fields into a plain JsonObject
+ * suitable for ctx.respond(). Strips class identity, prototype chain,
+ * and index signatures — the result is a clean { ...fields } record.
+ *
+ * Skips undefined values to keep the serialized output compact.
+ */
+export declare function toJsonObject(result: object): JsonObject;
+//# sourceMappingURL=result-dto.d.ts.map

package/dist/operations/result-dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-dto.d.ts","sourceRoot":"","sources":["../../src/operations/result-dto.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CASvD"}

package/dist/operations/result-dto.js

@@ -0,0 +1,21 @@
+// ---------------------------------------------------------------------------
+// Result DTO — converts runtime result objects to JSON-serializable records
+// ---------------------------------------------------------------------------
+/**
+ * Convert any result object with known fields into a plain JsonObject
+ * suitable for ctx.respond(). Strips class identity, prototype chain,
+ * and index signatures — the result is a clean { ...fields } record.
+ *
+ * Skips undefined values to keep the serialized output compact.
+ */
+export function toJsonObject(result) {
+    const obj = {};
+    const source = result;
+    for (const key of Object.keys(source)) {
+        if (source[key] !== undefined) {
+            obj[key] = source[key];
+        }
+    }
+    return obj;
+}
+//# sourceMappingURL=result-dto.js.map

package/dist/operations/result-dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-dto.js","sourceRoot":"","sources":["../../src/operations/result-dto.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAI9E;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;YAC9B,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/operations/safe-read.d.ts

@@ -0,0 +1,35 @@
+import type { GovernorDepth } from "../policy/types.js";
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { JsonCodec } from "../ports/codec.js";
+export interface SafeReadResult {
+    path: string;
+    projection: "content" | "outline" | "refused" | "error";
+    reason: string;
+    content?: string | undefined;
+    outline?: OutlineEntry[] | undefined;
+    jumpTable?: JumpEntry[] | undefined;
+    estimatedBytesAvoided?: number | undefined;
+    next?: string[] | undefined;
+    actual?: {
+        lines: number;
+        bytes: number;
+    } | undefined;
+    thresholds?: {
+        lines: number;
+        bytes: number;
+    } | undefined;
+    sessionDepth?: GovernorDepth | undefined;
+}
+export interface SafeReadOptions {
+    fs: FileSystem;
+    codec: JsonCodec;
+    content?: string | undefined;
+    intent?: string | undefined;
+    policyPath?: string | undefined;
+    graftignorePatterns?: string[] | undefined;
+    sessionDepth?: GovernorDepth | undefined;
+    budgetRemaining?: number | undefined;
+}
+export declare function safeRead(filePath: string, options: SafeReadOptions): Promise<SafeReadResult>;
+//# sourceMappingURL=safe-read.d.ts.map

package/dist/operations/safe-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-read.d.ts","sourceRoot":"","sources":["../../src/operations/safe-read.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAC;IACrC,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IACpC,qBAAqB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACtD,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC1D,YAAY,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,UAAU,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3C,YAAY,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACzC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAiFzB"}

package/dist/operations/safe-read.js

@@ -0,0 +1,75 @@
+import { evaluatePolicy } from "../policy/evaluate.js";
+import { ContentResult, RefusedResult } from "../policy/types.js";
+import { extractOutlineForFile } from "../parser/outline.js";
+export async function safeRead(filePath, options) {
+    let content;
+    let bytes;
+    if (options.content !== undefined) {
+        content = options.content;
+        bytes = Buffer.byteLength(content, "utf-8");
+    }
+    else {
+        let raw;
+        try {
+            raw = await options.fs.readFile(filePath);
+        }
+        catch {
+            return {
+                path: filePath,
+                projection: "error",
+                reason: "NOT_FOUND",
+            };
+        }
+        content = raw.toString("utf-8");
+        bytes = raw.byteLength;
+    }
+    const lines = content.split("\n").length;
+    const policy = evaluatePolicy({ path: options.policyPath ?? filePath, lines, bytes }, {
+        graftignorePatterns: options.graftignorePatterns,
+        sessionDepth: options.sessionDepth,
+        budgetRemaining: options.budgetRemaining,
+    });
+    const base = {
+        path: filePath,
+        projection: policy.projection,
+        reason: policy.reason,
+        actual: policy.actual,
+        thresholds: policy.thresholds,
+        ...(policy.sessionDepth !== undefined ? { sessionDepth: policy.sessionDepth } : {}),
+    };
+    if (policy instanceof ContentResult) {
+        return { ...base, content };
+    }
+    if (policy instanceof RefusedResult) {
+        return {
+            ...base,
+            next: [...policy.next],
+        };
+    }
+    // projection === "outline"
+    const outlineResult = extractOutlineForFile(filePath, content);
+    if (outlineResult === null) {
+        const emptyOutlineJson = options.codec.encode({ entries: [], jumpTable: [] });
+        const estimatedBytesAvoided = bytes - Buffer.byteLength(emptyOutlineJson, "utf-8");
+        return {
+            ...base,
+            reason: "UNSUPPORTED_LANGUAGE",
+            outline: [],
+            jumpTable: [],
+            estimatedBytesAvoided: estimatedBytesAvoided > 0 ? estimatedBytesAvoided : 0,
+            next: [
+                "No parser-backed outline is available for this file type.",
+                "Use read_range for targeted reads if you know the section you need.",
+            ],
+        };
+    }
+    const outlineJson = options.codec.encode(outlineResult);
+    const estimatedBytesAvoided = bytes - Buffer.byteLength(outlineJson, "utf-8");
+    return {
+        ...base,
+        outline: outlineResult.entries,
+        jumpTable: outlineResult.jumpTable,
+        estimatedBytesAvoided: estimatedBytesAvoided > 0 ? estimatedBytesAvoided : 0,
+    };
+}
+//# sourceMappingURL=safe-read.js.map

package/dist/operations/safe-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-read.js","sourceRoot":"","sources":["../../src/operations/safe-read.ts"],"names":[],"mappings":"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"}

package/dist/operations/state.d.ts

@@ -0,0 +1,25 @@
+import type { FileSystem } from "../ports/filesystem.js";
+export declare const STATE_FILENAME = "state.md";
+export declare class StateSaveResult {
+    readonly ok: boolean;
+    readonly reason?: string | undefined;
+    private constructor();
+    static success(): StateSaveResult;
+    static rejected(reason: string): StateSaveResult;
+}
+export declare class StateLoadResult {
+    readonly content: string | null;
+    private constructor();
+    static found(content: string): StateLoadResult;
+    static empty(): StateLoadResult;
+}
+export declare function stateSave(content: string, opts: {
+    stateDir: string;
+    statePath: string;
+    fs: FileSystem;
+}): Promise<StateSaveResult>;
+export declare function stateLoad(opts: {
+    statePath: string;
+    fs: FileSystem;
+}): Promise<StateLoadResult>;
+//# sourceMappingURL=state.d.ts.map

package/dist/operations/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/operations/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC,qBAAa,eAAe;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,OAAO;IAKP,MAAM,CAAC,OAAO,IAAI,eAAe;IAIjC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;CAGjD;AAED,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC,OAAO;IAIP,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe;IAI9C,MAAM,CAAC,KAAK,IAAI,eAAe;CAGhC;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,GAC5D,OAAO,CAAC,eAAe,CAAC,CAY1B;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,GAC1C,OAAO,CAAC,eAAe,CAAC,CAO1B"}

package/dist/operations/state.js

@@ -0,0 +1,47 @@
+const MAX_STATE_BYTES = 8192;
+export const STATE_FILENAME = "state.md";
+export class StateSaveResult {
+    ok;
+    reason;
+    constructor(ok, reason) {
+        this.ok = ok;
+        this.reason = reason;
+    }
+    static success() {
+        return new StateSaveResult(true);
+    }
+    static rejected(reason) {
+        return new StateSaveResult(false, reason);
+    }
+}
+export class StateLoadResult {
+    content;
+    constructor(content) {
+        this.content = content;
+    }
+    static found(content) {
+        return new StateLoadResult(content);
+    }
+    static empty() {
+        return new StateLoadResult(null);
+    }
+}
+export async function stateSave(content, opts) {
+    const bytes = Buffer.byteLength(content, "utf-8");
+    if (bytes > MAX_STATE_BYTES) {
+        return StateSaveResult.rejected(`State exceeds 8 KB limit (${String(bytes)} bytes)`);
+    }
+    await opts.fs.mkdir(opts.stateDir, { recursive: true });
+    await opts.fs.writeFile(opts.statePath, content, "utf-8");
+    return StateSaveResult.success();
+}
+export async function stateLoad(opts) {
+    try {
+        const content = await opts.fs.readFile(opts.statePath, "utf-8");
+        return StateLoadResult.found(content);
+    }
+    catch {
+        return StateLoadResult.empty();
+    }
+}
+//# sourceMappingURL=state.js.map