@oh-my-pi/hashline 15.5.4

package/README.md

@@ -0,0 +1,78 @@
+# @oh-my-pi/hashline
+
+A compact, line-anchored patch language and applier.
+
+Hashline is a diff format designed for LLM-driven file edits. It binds every
+hunk to a file-content hash so stale anchors are rejected before they corrupt
+code, and it abstracts over the filesystem so the same patcher works on disk,
+in memory, over the network, or against any custom backend.
+
+## Quick start
+
+```ts
+import {
+	Filesystem,
+	InMemoryFilesystem,
+	InMemorySnapshotStore,
+	Patcher,
+	Patch,
+} from "@oh-my-pi/hashline";
+
+const fs = new InMemoryFilesystem();
+await fs.writeText(
+	"hello.ts",
+	`const greeting = "hi";\nexport { greeting };\n`,
+);
+
+const patcher = new Patcher({ fs });
+const patch = Patch.parse(`¶hello.ts\n1:\n+const greeting = "hello";`);
+const result = await patcher.apply(patch);
+
+console.log(result.sections[0].op); // "update"
+console.log(await fs.readText("hello.ts"));
+```
+
+## Format
+
+See [`src/prompt.md`](./src/prompt.md) for the user-facing description and
+[`src/grammar.lark`](./src/grammar.lark) for the formal grammar.
+
+Each hunk starts with a `¶PATH#HASH` header. The hash is a 4-hex-character
+xxHash32 truncation of the file's LF-normalized content. The hash protects
+against stale anchors: if the file changed between the read that produced the
+hash and the edit, the patcher refuses (or, with a `SnapshotStore`, tries
+session-aware recovery).
+
+Inside a hunk:
+
+|Op|Meaning|
+|---|---|
+|`LINE↑`|Insert before LINE (or `BOF↑` for the beginning of file)|
+|`LINE↓`|Insert after LINE (or `EOF↓` for the end of file)|
+|`A-B:`|Replace lines A..B (single-anchor `A:` is sugar for `A-A:`)|
+|`A-B!`|Delete lines A..B (single-anchor `A!` is sugar for `A-A!`)|
+|`+TEXT`|Payload continuation. The `+` prefix is stripped|
+
+## Abstractions
+
+### `Filesystem`
+
+Read and write text by path. The default implementations:
+
+- `InMemoryFilesystem` — backed by a `Map`. Tests, sandboxes.
+- `NodeFilesystem` — disk-backed via `Bun.file`/`Bun.write`. Default for CLIs.
+
+Subclass `Filesystem` to wire hashline into any storage: VFS, S3, an LSP
+text-document protocol, a Git tree, anything.
+
+### `SnapshotStore`
+
+Optional. When provided to `Patcher`, hashline tries to recover from a stale
+section hash by replaying the edit against a cached pre-edit snapshot of the
+file and 3-way-merging onto the current content. See `recovery.ts`.
+
+### `Patcher`
+
+The orchestration class. Reads, normalizes line endings + BOM, applies edits,
+restores line endings, and writes via the configured `Filesystem`. Multi-section
+patches are preflighted up front so a partial batch never lands.

package/dist/types/apply.d.ts

@@ -0,0 +1,10 @@
+import type { ApplyOptions, ApplyResult, Edit } from "./types";
+/**
+ * Apply a parsed list of edits to a text body. Pure function — no I/O.
+ *
+ * Returns the post-edit text, the first changed line number (1-indexed), and
+ * any diagnostic warnings produced by the auto-absorb heuristics or by the
+ * structural-boundary delete check. Throws if an anchor is out of bounds or a
+ * blank-target replace is detected.
+ */
+export declare function applyEdits(text: string, edits: Edit[], options?: ApplyOptions): ApplyResult;

package/dist/types/diff-preview.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Re-number a unified diff that uses the `+<lineNum>|content` /
+ * `-<lineNum>|content` / ` <lineNum>|content` line format into a compact
+ * preview that anchors every line to its post-edit position. Added lines,
+ * removed lines, and context lines all end up with a hashline-style anchor
+ * so a follow-up edit can reuse them directly.
+ *
+ * This is intentionally decoupled from the diff producer: anything that
+ * emits the `<sign><lineNum>|<content>` shape works.
+ */
+import type { CompactDiffOptions, CompactDiffPreview } from "./types";
+export declare function buildCompactDiffPreview(diff: string, _options?: CompactDiffOptions): CompactDiffPreview;

package/dist/types/format.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Hashline format primitives: sigils, separators, regex fragments, and the
+ * file-hash computation. These are the single source of truth for the
+ * parser, the tokenizer, the prompt, and the formal grammar.
+ */
+/** Op sigil used immediately after a line-number anchor to insert before it. */
+export declare const HL_OP_INSERT_BEFORE = "\u2191";
+/** Op sigil used immediately after a line-number anchor to insert after it. */
+export declare const HL_OP_INSERT_AFTER = "\u2193";
+/** Op sigil used after a range (or single anchor) to replace its lines. */
+export declare const HL_OP_REPLACE = ":";
+/** Op sigil used after a range (or single anchor) to delete its lines. */
+export declare const HL_OP_DELETE = "!";
+/** All hashline edit op sigils, concatenated for fast membership tests. */
+export declare const HL_OP_CHARS = "\u2191\u2193:!";
+/** Prefix for payload continuation lines. The prefix itself is not written. */
+export declare const HL_PAYLOAD_PREFIX = "+";
+/** Hashline edit file-section header marker. */
+export declare const HL_FILE_PREFIX = "\u00B6";
+/** Separator between a hashline file path and its file hash. */
+export declare const HL_FILE_HASH_SEP = "#";
+/** Separator between a line number and displayed line content in hashline mode. */
+export declare const HL_LINE_BODY_SEP = ":";
+/**
+ * Decoration prefix that may precede a line number in tool output:
+ * `>` (context line in grep), `-` (removed line), `*` (match line).
+ * Any combination, in any order, surrounded by optional whitespace. Output
+ * formatters emit at most one decoration per line; the parser stays liberal
+ * because it accepts whatever the model echoes back.
+ */
+export declare const HL_ANCHOR_DECORATION_RE_RAW = "\\s*[>\\-*]*\\s*";
+/** Capture-group regex source for a decorated bare line-number anchor. */
+export declare const HL_ANCHOR_RE_RAW = "\\s*[>\\-*]*\\s*(\\d+)";
+/** Bare positive line-number Lid (no decorations, no captures, no anchors). */
+export declare const HL_LINE_RE_RAW = "[1-9]\\d*";
+/** Capture-group form of {@link HL_LINE_RE_RAW}. */
+export declare const HL_LINE_CAPTURE_RE_RAW = "([1-9]\\d*)";
+/** Four-hex-character file hash carried by a hashline section header. */
+export declare const HL_FILE_HASH_RE_RAW = "[0-9a-f]{4}";
+/** Capture-group form of {@link HL_FILE_HASH_RE_RAW}. */
+export declare const HL_FILE_HASH_CAPTURE_RE_RAW = "([0-9a-f]{4})";
+/** Regex-escaped form of {@link HL_LINE_BODY_SEP}, safe for embedding inside a regex. */
+export declare const HL_LINE_BODY_SEP_RE_RAW: string;
+/**
+ * Representative file hashes for use in user-facing error messages and prompt
+ * examples.
+ */
+export declare const HL_FILE_HASH_EXAMPLES: readonly ["1a2b", "3c4d", "9f3e"];
+/**
+ * Format a comma-separated list of example anchors with an optional line-number
+ * prefix, quoted for inclusion in error messages: `"160", "42", "7"`.
+ */
+export declare function describeAnchorExamples(linePrefix?: string): string;
+/**
+ * Compute the 4-hex-character hash carried by a hashline section header. The
+ * hash normalizes CR characters and trailing whitespace before hashing so
+ * platform line endings and display-trimmed lines do not invalidate anchors.
+ */
+export declare function computeFileHash(text: string): string;
+/** Format a hashline section header for a file path and file hash. */
+export declare function formatHashlineHeader(filePath: string, fileHash: string): string;
+/** Formats a single numbered line as `LINE:TEXT`. */
+export declare function formatNumberedLine(lineNumber: number, line: string): string;
+/** Format file text with hashline-mode line-number prefixes for display. */
+export declare function formatNumberedLines(text: string, startLine?: number): string;

package/dist/types/fs.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Result returned by {@link Filesystem.writeText}. The patcher echoes back
+ * `text` so adapters that transform on serialization (e.g. notebooks) can
+ * report what actually landed on disk.
+ */
+export interface WriteResult {
+    /** Final text that was persisted. May differ from the input if the FS transformed it. */
+    text: string;
+}
+/**
+ * ENOENT-like error thrown by {@link Filesystem.readText} when a path is
+ * missing. Carrying a `code` property keeps the contract compatible with
+ * `node:fs` callers that already check `err.code === "ENOENT"`.
+ */
+export declare class NotFoundError extends Error {
+    readonly code = "ENOENT";
+    constructor(path: string, cause?: unknown);
+}
+/** Type guard for {@link NotFoundError} and structurally-compatible errors. */
+export declare function isNotFound(error: unknown): boolean;
+/**
+ * Abstract storage backend the {@link Patcher} reads from and writes to.
+ * Subclass for new backends; the package ships {@link InMemoryFilesystem} and
+ * {@link NodeFilesystem} for the most common cases.
+ *
+ * Implementations work with raw text — the patcher handles BOM stripping and
+ * line-ending normalization itself. `readText` MUST throw {@link
+ * NotFoundError} (or any error for which {@link isNotFound} returns true)
+ * when the path doesn't exist; that's how the patcher detects a create-vs-
+ * update.
+ */
+export declare abstract class Filesystem {
+    /** Read the file's full text content. Throw on missing file. */
+    abstract readText(path: string): Promise<string>;
+    /** Validate that `path` is writable before a prepared batch starts committing. */
+    preflightWrite(_path: string): Promise<void>;
+    /** Persist `content` at `path`. Returns the actual final text that was written. */
+    abstract writeText(path: string, content: string): Promise<WriteResult>;
+    /** Return true when the path exists and can be read. Default: probe via {@link readText}. */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Canonical path used as a key by external caches (e.g. snapshot
+     * stores). The default is identity; override to return an absolute or
+     * otherwise canonicalised path so producers and consumers of cached
+     * snapshots agree on the key without each having to redo the resolution.
+     */
+    canonicalPath(path: string): string;
+}
+/**
+ * In-memory {@link Filesystem}. Useful for tests, sandboxes, dry-runs, and as
+ * a building block for stacked adapters (e.g. an LRU layer on top).
+ */
+export declare class InMemoryFilesystem extends Filesystem {
+    #private;
+    constructor(initial?: Iterable<readonly [string, string]>);
+    readText(path: string): Promise<string>;
+    writeText(path: string, content: string): Promise<WriteResult>;
+    exists(path: string): Promise<boolean>;
+    /** Synchronous helper for setting up fixtures without awaiting. */
+    set(path: string, content: string): void;
+    /** Synchronous helper for inspecting state without awaiting. */
+    get(path: string): string | undefined;
+    /** Remove a single entry. Returns true when something was removed. */
+    delete(path: string): boolean;
+    /** Wipe all entries. */
+    clear(): void;
+    /** Iterate `[path, content]` pairs. */
+    entries(): IterableIterator<[string, string]>;
+}
+/**
+ * Disk-backed {@link Filesystem} using Bun's file APIs. The default for CLI
+ * use. Paths are accepted as-is; callers responsible for any cwd or
+ * jail/sandbox resolution should wrap this with their own subclass.
+ */
+export declare class NodeFilesystem extends Filesystem {
+    readText(path: string): Promise<string>;
+    writeText(path: string, content: string): Promise<WriteResult>;
+    canonicalPath(path: string): string;
+    exists(path: string): Promise<boolean>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./apply";
+export * from "./diff-preview";
+export * from "./format";
+export * from "./fs";
+export * from "./input";
+export * from "./messages";
+export * from "./mismatch";
+export * from "./normalize";
+export * from "./parser";
+export * from "./patcher";
+export * from "./prefixes";
+export * from "./recovery";
+export * from "./snapshots";
+export * from "./stream";
+export * from "./tokenizer";
+export * from "./types";

package/dist/types/input.d.ts

@@ -0,0 +1,85 @@
+import type { ApplyOptions, ApplyResult, Edit, SplitOptions } from "./types";
+interface RawSection {
+    path: string;
+    fileHash?: string;
+    diff: string;
+}
+/**
+ * Returns true when the input contains at least one line that the tokenizer
+ * recognizes as a hashline op. Used by streaming previews to decide whether
+ * the partial input is worth treating as a hashline patch yet.
+ */
+export declare function containsRecognizableHashlineOperations(input: string): boolean;
+/**
+ * Snapshot of one section in a parsed {@link Patch}: a target file plus the
+ * lazily-parsed list of edits that should land on it. Constructed by
+ * {@link Patch.parse}; consumers usually iterate `patch.sections` rather
+ * than build these directly.
+ */
+export declare class PatchSection {
+    #private;
+    readonly path: string;
+    readonly fileHash: string | undefined;
+    readonly diff: string;
+    constructor(raw: RawSection);
+    /**
+     * Parse this section's diff body. Cached: subsequent calls return the
+     * same `{ edits, warnings }` object so callers can safely call this from
+     * multiple paths (preflight, apply, diff-preview).
+     */
+    parse(): {
+        edits: Edit[];
+        warnings: readonly string[];
+    };
+    /** Parsed edits for this section. */
+    get edits(): readonly Edit[];
+    /** Warnings emitted during parsing of this section. */
+    get warnings(): readonly string[];
+    /**
+     * True when at least one edit anchors to a concrete file line (range or
+     * before/after_anchor insert). Pure BOF/EOF inserts do not count: those
+     * are safe to apply to files that don't yet exist.
+     */
+    get hasAnchorScopedEdit(): boolean;
+    /** Anchor lines touched by this section, sorted ascending and deduplicated. */
+    collectAnchorLines(): readonly number[];
+    /**
+     * Apply this section's edits to `text` and return the post-edit result.
+     * Pure: does no I/O, does not validate the section file hash. The
+     * {@link Patcher} owns hash validation and recovery; reach for this
+     * method directly when you've already validated the file content and
+     * just want the result.
+     */
+    applyTo(text: string, options?: ApplyOptions): ApplyResult;
+}
+/**
+ * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted
+ * at a `¶PATH#HASH` header. Construct via {@link Patch.parse}.
+ *
+ * `Patch` is pure data: parsing is line-anchored and does not look at the
+ * filesystem. To apply a patch, hand it to {@link Patcher.apply}.
+ */
+export declare class Patch {
+    readonly sections: readonly PatchSection[];
+    private constructor();
+    /**
+     * Parse `input` into a {@link Patch}. `options.cwd` resolves absolute
+     * paths inside headers to cwd-relative form; `options.path` provides a
+     * fallback when the input lacks a header but contains hashline ops
+     * (useful for streaming previews).
+     *
+     * Consecutive sections targeting the same path are merged into a single
+     * section with concatenated diff bodies. Anchors authored against the
+     * same file snapshot must be applied as one batch; otherwise the first
+     * sub-edit shifts line numbers out from under the second's anchors and
+     * validation fails.
+     */
+    static parse(input: string, options?: SplitOptions): Patch;
+    /**
+     * Parse `input` and return only the first section. Throws if the input
+     * has zero sections. Convenience for the single-section case where the
+     * caller already knows the patch is one hunk.
+     */
+    static parseSingle(input: string, options?: SplitOptions): PatchSection;
+}
+export {};

package/dist/types/messages.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Centralized error and warning text emitted by the hashline parser, applier,
+ * and patcher. Consolidating these as named constants makes them easy to
+ * audit and keeps wording stable across the rendering paths that surface
+ * them.
+ */
+/** Lines of context shown either side of a hash mismatch. */
+export declare const MISMATCH_CONTEXT = 2;
+/** Optional patch envelope start marker; silently consumed when present. */
+export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
+/** Optional patch envelope end marker; terminates parsing when encountered. */
+export declare const END_PATCH_MARKER = "*** End Patch";
+/**
+ * Recovery sentinel emitted by an agent loop when a contaminated tool-call
+ * stream is truncated mid-call. Behaves like {@link END_PATCH_MARKER} for
+ * parsing — terminates the line loop — and additionally surfaces a warning
+ * so the caller knows to re-issue any remaining edits.
+ */
+export declare const ABORT_MARKER = "*** Abort";
+/** Warning text appended to the tool result when {@link ABORT_MARKER} terminates parsing. */
+export declare const ABORT_WARNING = "Tool stream truncated mid-call due to detected output corruption. Applied ops above are valid. Re-issue any remaining edits.";
+/**
+ * Warning text appended when two consecutive `A-B:` ops on the exact same
+ * range get coalesced (model painted a before/after pair). The second op wins;
+ * the first op's payload is silently discarded.
+ */
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Detected an identical-range before/after replace pair; kept only the second block's payload. Issue ONE op per range \u2014 the payload is the final desired content, never both old and new.";
+/**
+ * Warning text appended when un-prefixed continuation lines are accepted as
+ * implicit payload (lenient legacy behavior). The author wrote a multi-line
+ * replace without `+` prefixes; the parser accepted it because the lines did
+ * not classify as ops/headers/payloads, but the canonical syntax requires `+`
+ * on every continuation line after the op.
+ */
+export declare const IMPLICIT_CONTINUATION_WARNING = "Accepted continuation line(s) without the `+` prefix as implicit payload. Canonical syntax is `A-B:` followed by `+` on every continuation row; without `+`, lines that look like ops will be parsed as new ops instead of payload. Prefer the explicit form.";
+/**
+ * Warning text appended when an inner `LINE:TEXT` (or sub-range `A-B:TEXT`)
+ * op arrives while an outer `A-B:` replace is still pending and the inner
+ * anchor falls inside the outer range. The author used the read-output
+ * `LINE:TEXT` format as if it were a payload-continuation line; we strip the
+ * `LINE:` prefix and append the body to the pending payload, but warn so the
+ * canonical `+`-continuation form remains preferred.
+ */
+export declare const PAYLOAD_LINE_PREFIX_DEMOTED_WARNING = "Detected one or more `LINE:TEXT` lines whose anchors fell inside a pending replace range; treated them as payload-continuation lines and stripped the `LINE:` prefix. Inside an `A-B:` block, every payload line must be on its own row prefixed with `+` \u2014 never reuse the read-output gutter format.";
+/**
+ * Warning text appended when an op carries an inline payload (`LINE:TEXT`,
+ * `LINE↑CONTENT`, `LINE↓CONTENT`). Canonical syntax is the bare op followed
+ * by `+`-prefixed payload rows on the next line(s).
+ */
+export declare const INLINE_PAYLOAD_ACCEPTED_WARNING = "Accepted inline payload on the op line (e.g. `LINE:CONTENT`, `LINE\u2191CONTENT`). Canonical syntax is the bare op followed by `+`-prefixed payload rows on the next line(s). Prefer the explicit form.";
+/** Warning text emitted by `Recovery` when an external write fits a cached snapshot. */
+export declare const RECOVERY_EXTERNAL_WARNING = "Recovered from a stale file hash using a previous read snapshot (file changed externally between read and edit).";
+/** Warning text emitted by `Recovery` when a prior in-session edit advanced the hash. */
+export declare const RECOVERY_SESSION_CHAIN_WARNING = "Recovered from a stale file hash using an earlier in-session snapshot (the file hash advanced after a prior edit in this session).";
+/** Warning text emitted by `Recovery` when the session-chain fast-path was taken. */
+export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content \u2014 your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";

package/dist/types/mismatch.d.ts

@@ -0,0 +1,35 @@
+/** Format the required-shape diagnostic shown when a line reference is malformed. */
+export declare function formatFullAnchorRequirement(raw?: string): string;
+/** Parse a decorated bare line-number anchor like `42`, `*42:foo`, ` > 7`. */
+export declare function parseTag(ref: string): {
+    line: number;
+};
+export interface MismatchDetails {
+    path?: string;
+    expectedFileHash: string;
+    actualFileHash: string;
+    fileLines: string[];
+    anchorLines?: readonly number[];
+}
+/**
+ * Raised when a hashline section's file hash doesn't match the live file's
+ * content (and recovery, if configured, declined the merge). Carries the
+ * file lines plus anchored lines so renderers can produce a richer
+ * diagnostic via {@link MismatchError.displayMessage}.
+ */
+export declare class MismatchError extends Error {
+    readonly path: string | undefined;
+    readonly expectedFileHash: string;
+    readonly actualFileHash: string;
+    readonly fileLines: string[];
+    readonly anchorLines: readonly number[];
+    constructor(details: MismatchDetails);
+    get displayMessage(): string;
+    static rejectionHeader(details: MismatchDetails): string[];
+    static formatDisplayMessage(details: MismatchDetails): string;
+    static formatMessage(details: MismatchDetails): string;
+}
+/** Throws when the line reference is out of bounds for the given file. */
+export declare function validateLineRef(ref: {
+    line: number;
+}, fileLines: string[]): void;

package/dist/types/normalize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal text-shape normalization: line-ending detection / round-trip and
+ * BOM stripping. The patcher uses these to canonicalize text to LF before
+ * applying edits and to restore the original shape on write-back.
+ */
+export type LineEnding = "\r\n" | "\n";
+/** Detect the first line ending style in `content`. Defaults to LF when neither is present. */
+export declare function detectLineEnding(content: string): LineEnding;
+/** Normalize every line ending to LF. */
+export declare function normalizeToLF(text: string): string;
+/** Re-encode LF text with the requested line ending. */
+export declare function restoreLineEndings(text: string, ending: LineEnding): string;
+export interface BomResult {
+    /** Either the empty string or the BOM sequence (currently UTF-8 BOM). */
+    bom: string;
+    /** Text with any leading BOM removed. */
+    text: string;
+}
+/** Strip a UTF-8 BOM if present and return both the BOM and the trailing text. */
+export declare function stripBom(content: string): BomResult;

package/dist/types/parser.d.ts

@@ -0,0 +1,50 @@
+import { type Token } from "./tokenizer";
+import type { Edit } from "./types";
+/**
+ * Token-driven state machine that turns a stream of {@link Token}s into a
+ * flat list of {@link Edit}s.
+ *
+ * `feed()` accepts tokens one at a time; multi-line payloads accumulate
+ * until the next op or {@link end} flushes them. After `terminated` flips
+ * true (on `envelope-end` or `abort`) subsequent feeds are silently ignored
+ * so callers can keep draining their tokenizer.
+ */
+export declare class Executor {
+    #private;
+    /** True once an `envelope-end` or `abort` token has been observed. */
+    get terminated(): boolean;
+    /**
+     * Consume one token. After `terminated` flips true subsequent feeds are
+     * silently ignored so callers can keep draining their tokenizer without
+     * explicit early-exit guards.
+     */
+    feed(token: Token): void;
+    /**
+     * Flush any open pending op (with its full accumulated payload, including
+     * explicit `+` blank lines) and return the accumulated edits and
+     * warnings. The executor is single-use; {@link reset} is required for
+     * reuse.
+     *
+     * Throws if two replace/delete ops target the same line with non-identical
+     * shapes (different ranges, replace+delete, delete+delete). Identical-range
+     * `A-B:` pairs in the same hunk are coalesced last-wins by `feed()` with a
+     * warning, so they never reach the validator.
+     */
+    end(): {
+        edits: Edit[];
+        warnings: string[];
+    };
+    /** Reset to a fresh state so the same instance can drive another parse. */
+    reset(): void;
+}
+/**
+ * Drive a full hashline diff through the tokenizer + executor pipeline and
+ * return the resulting edits plus any parse-time warnings. This is the
+ * convenience entry point most callers want; reach for {@link Tokenizer} /
+ * {@link Executor} directly only when you need streaming feeds, cross-section
+ * state, or custom token handling.
+ */
+export declare function parsePatch(diff: string): {
+    edits: Edit[];
+    warnings: string[];
+};

package/dist/types/patcher.d.ts

@@ -0,0 +1,112 @@
+import type { Filesystem } from "./fs";
+import type { Patch, PatchSection } from "./input";
+import { type LineEnding } from "./normalize";
+import { Recovery } from "./recovery";
+import type { SnapshotStore } from "./snapshots";
+import type { ApplyOptions, ApplyResult } from "./types";
+export interface PatcherOptions {
+    /** Storage backend used for all reads and writes. */
+    fs: Filesystem;
+    /**
+     * Optional snapshot store that enables stale-hash recovery. When set, a
+     * section with a stale hash tries a 3-way merge against a cached
+     * snapshot before the apply fails with {@link MismatchError}.
+     */
+    snapshots?: SnapshotStore;
+    /**
+     * Optional default {@link ApplyOptions} forwarded to every section.
+     * Per-call overrides win on a key-by-key basis.
+     */
+    applyOptions?: ApplyOptions;
+}
+/** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
+export interface PatchSectionResult {
+    /** Section path (as authored, after cwd-resolution at parse time). */
+    path: string;
+    /** Filesystem-canonical key for this section (e.g. absolute path). */
+    canonicalPath: string;
+    /** `"noop"` when the apply produced no change; otherwise `"create"` / `"update"`. */
+    op: "create" | "update" | "noop";
+    /** Pre-edit text (LF-normalized, BOM-stripped). */
+    before: string;
+    /** Post-edit text (LF-normalized, BOM-stripped). For `"noop"` equals `before`. */
+    after: string;
+    /** Same text as `after` but with the original BOM and line ending restored. */
+    persisted: string;
+    /** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
+    written: string;
+    /** 4-hex hash of `after`. Use to anchor follow-up edits. */
+    fileHash: string;
+    /** Hashline section header (`¶path#hash`) of the post-edit content. */
+    header: string;
+    /** 1-indexed first changed line in `after`, or `undefined` for noops. */
+    firstChangedLine?: number;
+    /** Warnings collected by the parser, applier, and (optionally) recovery. */
+    warnings: string[];
+}
+export interface PatcherApplyResult {
+    sections: PatchSectionResult[];
+}
+/**
+ * Opaque token returned by {@link Patcher.prepare}. Carries the section, the
+ * raw file content read off disk, and the in-memory apply result.
+ * {@link Patcher.commit} just writes the {@link PreparedSection.applyResult}.
+ */
+export declare class PreparedSection {
+    readonly section: PatchSection;
+    readonly canonicalPath: string;
+    readonly exists: boolean;
+    readonly rawContent: string;
+    readonly bom: string;
+    readonly lineEnding: LineEnding;
+    readonly normalized: string;
+    readonly applyResult: ApplyResult;
+    readonly parseWarnings: readonly string[];
+    /** @internal */
+    constructor(section: PatchSection, canonicalPath: string, exists: boolean, rawContent: string, bom: string, lineEnding: LineEnding, normalized: string, applyResult: ApplyResult, parseWarnings: readonly string[]);
+    /** Convenience: returns true when the apply produced no change. */
+    get isNoop(): boolean;
+}
+/**
+ * High-level patcher. Wires a {@link Filesystem} and an optional
+ * {@link SnapshotStore} together with the parsing + applying core.
+ *
+ * Construct once per FS configuration; reuse across patches.
+ */
+export declare class Patcher {
+    #private;
+    readonly fs: Filesystem;
+    readonly snapshots: SnapshotStore | undefined;
+    readonly recovery: Recovery | undefined;
+    readonly applyOptions: ApplyOptions;
+    constructor(options: PatcherOptions);
+    /**
+     * Apply every section in `patch`. `prepare` runs the full apply for each
+     * section in memory before any write hits the filesystem, so a
+     * multi-section batch is naturally all-or-nothing. Returns one
+     * {@link PatchSectionResult} per section in the original patch order.
+     */
+    apply(patch: Patch, options?: ApplyOptions): Promise<PatcherApplyResult>;
+    /**
+     * Run the preflight pass only: read, parse, validate, apply-in-memory.
+     * No writes hit the filesystem. Use for CI checks and dry runs.
+     */
+    preflight(patch: Patch, options?: ApplyOptions): Promise<void>;
+    /**
+     * Read a section's target file, parse the section, validate the file
+     * hash (with recovery), and apply the edits in memory. Returns a
+     * {@link PreparedSection} which can be fed to {@link commit} to land
+     * the result on the filesystem.
+     *
+     * Throws on parse error, missing-file-for-anchored-edit, or unrecovered
+     * hash mismatch ({@link MismatchError}).
+     */
+    prepare(section: PatchSection, options?: ApplyOptions): Promise<PreparedSection>;
+    /**
+     * Commit a previously {@link prepare}d section to the filesystem.
+     * Restores line endings and BOM, writes via the {@link Filesystem}, and
+     * records a fresh snapshot in the {@link SnapshotStore} (when
+     * configured) keyed by the filesystem-canonical path.
+     */
+    commit(prepared: PreparedSection): Promise<PatchSectionResult>;
+}

package/dist/types/prefixes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * When a hashline payload is authored against `read`/`search` output, each
+ * line is prefixed with either a hashline-mode line number (`123:`) or, for
+ * diff-style echoes, a leading `+`. These helpers detect that and recover
+ * the raw text. Two strip modes are exposed:
+ *
+ * - {@link stripNewLinePrefixes} — opportunistic: strips when the input
+ *   clearly carries hashline or diff prefixes, leaves it alone otherwise.
+ * - {@link stripHashlinePrefixes} — strict: only strips when every non-empty
+ *   content line is hashline-prefixed.
+ *
+ * These run *before* the tokenizer; they exist because hashline mode is the
+ * common case for echoed file content, and erroneously echoed prefixes will
+ * otherwise turn every content line into a (malformed) op.
+ */
+/**
+ * Strip whichever prefix scheme the lines appear to be carrying:
+ * - hashline line-number prefixes (`123:`) when every content line has one
+ * - leading `+` (diff style) when at least half the lines have one
+ * - mixed `+<n>:` form when present
+ *
+ * Returns the lines untouched if no scheme is recognized.
+ */
+export declare function stripNewLinePrefixes(lines: string[]): string[];
+/**
+ * Strict variant: strip hashline prefixes only when every content line is
+ * hashline-prefixed. Returns the lines unchanged otherwise.
+ */
+export declare function stripHashlinePrefixes(lines: string[]): string[];
+/**
+ * Normalize line payloads by stripping read/search line prefixes. `null` /
+ * `undefined` yield `[]`; a single multiline string is split on `\n`.
+ */
+export declare function hashlineParseText(edit: string[] | string | null | undefined): string[];