@oh-my-pi/hashline 15.5.4

package/dist/types/recovery.d.ts

@@ -0,0 +1,38 @@
+import type { SnapshotStore } from "./snapshots";
+import type { ApplyOptions, Edit } from "./types";
+export interface RecoveryArgs {
+    path: string;
+    currentText: string;
+    fileHash: string;
+    edits: readonly Edit[];
+    options?: ApplyOptions;
+}
+export interface RecoveryResult {
+    /** Post-recovery text. */
+    text: string;
+    /** First changed line (1-indexed) relative to the live `currentText`, or `undefined`. */
+    firstChangedLine: number | undefined;
+    /** Warnings collected during recovery, including the user-facing recovery banner. */
+    warnings: string[];
+}
+/**
+ * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
+ * call {@link Recovery.tryRecover} per stale-hash incident. The default
+ * implementation tries three strategies in order:
+ *
+ * 1. Apply on the cached `fullText` snapshot, then 3-way-merge onto current.
+ * 2. (Session chain) If the snapshot wasn't the head, retry on current text
+ *    when line counts match — the user's previous edit advanced the hash but
+ *    didn't shift line numbers.
+ * 3. Reconstruct from a sparse snapshot (lines map only), verify the rebuilt
+ *    text hashes to the expected value, then 3-way-merge.
+ */
+export declare class Recovery {
+    readonly store: SnapshotStore;
+    constructor(store: SnapshotStore);
+    /**
+     * Attempt recovery. Returns `null` when no path forward is found — the
+     * caller should then surface a {@link MismatchError}.
+     */
+    tryRecover(args: RecoveryArgs): RecoveryResult | null;
+}

package/dist/types/snapshots.d.ts

@@ -0,0 +1,67 @@
+/**
+ * One snapshot of a file as it was observed at a point in time. Either the
+ * full text is recorded (`fullText` set) for full-file reads, or a sparse
+ * map of `(lineNumber, content)` pairs for partial views (search matches,
+ * range reads).
+ */
+export interface Snapshot {
+    /** 1-indexed line number → exact content as observed. */
+    readonly lines: Map<number, string>;
+    /** Full normalized text when the read observed the whole file. */
+    fullText?: string;
+    /** 4-hex hash carried alongside the read, when known. */
+    fileHash?: string;
+    /** Timestamp (ms since epoch) the snapshot was recorded. */
+    recordedAt: number;
+}
+/** Optional metadata supplied at snapshot record time. */
+export interface SnapshotMetadata {
+    /** Full normalized text, when the producer observed the whole file. */
+    fullText?: string;
+    /** 4-hex hash carried by the read, when known. */
+    fileHash?: string;
+}
+/**
+ * Storage seam for file-content snapshots. The patcher calls {@link head}
+ * for the latest snapshot of a path and {@link byHash} when it needs the
+ * specific historical snapshot that matches a section's stale hash.
+ */
+export declare abstract class SnapshotStore {
+    /** Most-recent snapshot for `path`, or `null` if none. */
+    abstract head(path: string): Snapshot | null;
+    /** Most-recent snapshot for `path` whose `fileHash` equals `fileHash`. */
+    abstract byHash(path: string, fileHash: string): Snapshot | null;
+    /** Record a contiguous run of lines (e.g. from a `read` tool). `startLine` is 1-indexed. */
+    abstract recordContiguous(path: string, startLine: number, lines: readonly string[], metadata?: SnapshotMetadata): void;
+    /** Record sparse `(lineNumber, content)` pairs (e.g. a `search` match plus context). */
+    abstract recordSparse(path: string, entries: Iterable<readonly [number, string]>, metadata?: SnapshotMetadata): void;
+    /** Drop the snapshot history for a single path. */
+    abstract invalidate(path: string): void;
+    /** Drop every snapshot history. */
+    abstract clear(): void;
+}
+export interface InMemorySnapshotStoreOptions {
+    /** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
+    maxPaths?: number;
+    /** Maximum snapshots retained per path (default 4). Oldest dropped first. */
+    maxSnapshotsPerPath?: number;
+}
+/**
+ * In-memory {@link SnapshotStore} backed by `lru-cache`. Per-path snapshot
+ * history is a short ring (oldest dropped first); per-session path tracking
+ * is LRU-bounded so cold paths age out automatically.
+ *
+ * Newer snapshots merge into the head when their entries don't conflict and
+ * the recorded `fileHash` (if any) still agrees; otherwise a fresh snapshot
+ * is pushed onto the front of the history list.
+ */
+export declare class InMemorySnapshotStore extends SnapshotStore {
+    #private;
+    constructor(options?: InMemorySnapshotStoreOptions);
+    head(path: string): Snapshot | null;
+    byHash(path: string, fileHash: string): Snapshot | null;
+    recordContiguous(path: string, startLine: number, lines: readonly string[], metadata?: SnapshotMetadata): void;
+    recordSparse(path: string, entries: Iterable<readonly [number, string]>, metadata?: SnapshotMetadata): void;
+    invalidate(path: string): void;
+    clear(): void;
+}

package/dist/types/stream.d.ts

@@ -0,0 +1,2 @@
+import type { StreamOptions } from "./types";
+export declare function streamHashLines(source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, options?: StreamOptions): AsyncGenerator<string>;

package/dist/types/tokenizer.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Stateful, line-oriented classifier for hashline diff text.
+ *
+ * The {@link Tokenizer} can be fed in chunks ({@link Tokenizer.feed}/{@link
+ * Tokenizer.end}) for streaming use, or in one shot ({@link
+ * Tokenizer.tokenizeAll}). Each emitted token carries its 1-indexed source
+ * line number so downstream consumers (parser, validators, error messages)
+ * can refer back to the input precisely.
+ *
+ * The tokenizer is intentionally permissive about decorations and prefixes
+ * the model may echo back from `read`/`search` output — leading `*`/`>`/`-`
+ * markers, CR-terminated lines, leading whitespace before line numbers, and
+ * so on are all stripped before classification.
+ */
+import type { Anchor, Cursor, ParsedRange } from "./types";
+/**
+ * Split a hashline diff into individual lines without losing the trailing
+ * empty line that callers may rely on for explicit blank payloads. CRLF pairs
+ * are normalized to a single line break.
+ *
+ * This mirrors the line-splitting performed by {@link Tokenizer}'s streaming
+ * drain loop and is kept for non-streaming callers that prefer a single-shot
+ * split.
+ */
+export declare function splitHashlineLines(text: string): string[];
+export declare function cloneCursor(cursor: Cursor): Cursor;
+/** Parse a bare line-number anchor (used by insert ops). Throws on malformed input. */
+export declare function parseLid(raw: string, lineNum: number): Anchor;
+/**
+ * Returns true when the line scans as `LINE!payload` (delete sigil followed
+ * by additional content). The parser uses this for the dedicated "deletes
+ * only" diagnostic, separate from the standard "unrecognized op" path.
+ */
+export declare function isDeleteOpWithPayload(line: string): boolean;
+interface TokenBase {
+    /** 1-indexed line number in the original input stream. */
+    lineNum: number;
+}
+export type Token = (TokenBase & {
+    kind: "blank";
+}) | (TokenBase & {
+    kind: "envelope-begin";
+}) | (TokenBase & {
+    kind: "envelope-end";
+}) | (TokenBase & {
+    kind: "abort";
+}) | (TokenBase & {
+    kind: "header";
+    path: string;
+    fileHash?: string;
+}) | (TokenBase & {
+    kind: "op-insert";
+    cursor: Cursor;
+    inlineBody: string | undefined;
+}) | (TokenBase & {
+    kind: "op-replace";
+    range: ParsedRange;
+    inlineBody: string | undefined;
+}) | (TokenBase & {
+    kind: "op-delete";
+    range: ParsedRange;
+    trailingPayload: boolean;
+}) | (TokenBase & {
+    kind: "payload";
+    text: string;
+}) | (TokenBase & {
+    kind: "raw";
+    text: string;
+});
+/**
+ * Stateful, line-oriented classifier for hashline diff text. Use the
+ * streaming {@link feed}/{@link end} pair to ingest text in chunks (each
+ * completed line emits exactly one token; a trailing partial line stays
+ * buffered until the next chunk or {@link end}). Use the stateless
+ * {@link tokenize}/predicate methods for callers that already hold whole
+ * lines and only need classification without buffering.
+ */
+export declare class Tokenizer {
+    #private;
+    /**
+     * Ingest a chunk of input text. Each newline-terminated line in the
+     * combined buffer produces one token. A trailing partial line (no `\n`
+     * yet, possibly ending in a lone `\r`) stays buffered until the next
+     * `feed`/`end` call so CRLF pairs that straddle chunk boundaries are
+     * still normalized correctly.
+     */
+    feed(chunk: string): Token[];
+    /**
+     * Flush any buffered residual line (the last line of input when it lacks
+     * a trailing newline) and mark the tokenizer closed. Calling `end` a
+     * second time returns `[]`; reuse requires `reset`.
+     */
+    end(): Token[];
+    /** Discard any buffered text and reset the line counter to 1. */
+    reset(): void;
+    /** Convenience: feed an entire text and immediately flush. */
+    tokenizeAll(text: string): Token[];
+    /** Stateless one-shot classification. Does not touch the streaming buffer. */
+    tokenize(line: string, lineNum?: number): Token;
+    isOp(line: string): boolean;
+    isHeader(line: string): boolean;
+    isEnvelopeMarker(line: string): boolean;
+}
+export type { ParsedRange } from "./types";

package/dist/types/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Pure data types shared across the hashline parser, applier, and patcher.
+ * Nothing in this file references a filesystem, agent runtime, or schema
+ * library — keep it that way.
+ */
+/** A line-number anchor (1-indexed). */
+export interface Anchor {
+    line: number;
+}
+/** Where an `insert` edit should land relative to existing content. */
+export type Cursor = {
+    kind: "bof";
+} | {
+    kind: "eof";
+} | {
+    kind: "before_anchor";
+    anchor: Anchor;
+} | {
+    kind: "after_anchor";
+    anchor: Anchor;
+};
+/**
+ * A single low-level edit produced by the parser and consumed by the applier.
+ * Multi-line replacements decompose to one `insert` per replacement line plus
+ * one `delete` per consumed line.
+ */
+export type Edit = {
+    kind: "insert";
+    cursor: Cursor;
+    text: string;
+    lineNum: number;
+    index: number;
+} | {
+    kind: "delete";
+    anchor: Anchor;
+    lineNum: number;
+    index: number;
+    oldAssertion?: string;
+};
+/** Result of applying a parsed set of edits to a text body. */
+export interface ApplyResult {
+    /** Post-edit text body. */
+    text: string;
+    /** First line number (1-indexed) that changed, or `undefined` for a no-op apply. */
+    firstChangedLine?: number;
+    /** Diagnostic warnings collected by the applier (auto-absorb, boundary checks, …). */
+    warnings?: string[];
+}
+/** Optional knobs forwarded to {@link Edit} application. */
+export interface ApplyOptions {
+    /**
+     * When `true`, pure-insert and single-line replacement-boundary duplicates
+     * are dropped opportunistically. Default `false`: only multi-line block
+     * duplicates and structural-boundary single lines are absorbed.
+     */
+    autoDropPureInsertDuplicates?: boolean;
+}
+/** A parsed `[A..B]` line range. */
+export interface ParsedRange {
+    start: Anchor;
+    end: Anchor;
+}
+/** Optional hints for {@link splitPatchInput}. */
+export interface SplitOptions {
+    /** Resolves absolute paths inside hashline headers to cwd-relative form. */
+    cwd?: string;
+    /**
+     * Fallback path used when the input lacks a `¶PATH` header but contains
+     * recognizable hashline operations. Lets streaming previews work before
+     * the model has written the header.
+     */
+    path?: string;
+}
+/** Streaming-formatter knobs for {@link streamHashLines}. */
+export interface StreamOptions {
+    /** First line number to use when formatting (1-indexed, default 1). */
+    startLine?: number;
+    /** Maximum formatted lines per yielded chunk (default 200). */
+    maxChunkLines?: number;
+    /** Maximum UTF-8 bytes per yielded chunk (default 64 KiB). */
+    maxChunkBytes?: number;
+}
+/** Result of {@link buildCompactDiffPreview}. */
+export interface CompactDiffPreview {
+    preview: string;
+    addedLines: number;
+    removedLines: number;
+}
+/** Optional knobs for {@link buildCompactDiffPreview}. Reserved for future use. */
+export interface CompactDiffOptions {
+    /** Maximum entries kept on each side of an unchanged-context truncation (default 2). */
+    maxUnchangedRun?: number;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+	"type": "module",
+	"name": "@oh-my-pi/hashline",
+	"version": "15.5.4",
+	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
+	"homepage": "https://omp.sh",
+	"author": "Can Boluk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/can1357/oh-my-pi.git",
+		"directory": "packages/hashline"
+	},
+	"bugs": {
+		"url": "https://github.com/can1357/oh-my-pi/issues"
+	},
+	"keywords": [
+		"patch",
+		"diff",
+		"edit",
+		"hashline",
+		"agent",
+		"llm"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"diff": "^9.0.0",
+		"lru-cache": "11.3.6"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./grammar.lark": "./src/grammar.lark",
+		"./prompt.md": "./src/prompt.md",
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}