@prometheus-ai/hashline 0.5.0

package/dist/types/patcher.d.ts

@@ -0,0 +1,109 @@
+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 { ApplyResult, BlockResolver } from "./types";
+export interface PatcherOptions {
+    /** Storage backend used for all reads and writes. */
+    fs: Filesystem;
+    /** Snapshot store that minted and resolves hashline section tags. Required. */
+    snapshots: SnapshotStore;
+    /**
+     * Resolves `replace block N:` anchors to concrete line spans via tree-sitter.
+     * Optional: when omitted, any `replace block N:` edit throws on apply (the
+     * host did not wire a resolver). Plain line-range ops never need it.
+     */
+    blockResolver?: BlockResolver;
+}
+/** 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 content-hash tag for `after`. Use to anchor follow-up edits. */
+    fileHash: string;
+    /** Hashline section header (`[path#tag]`) 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 a required
+ * {@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;
+    readonly recovery: Recovery;
+    readonly blockResolver: BlockResolver | undefined;
+    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): 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): Promise<void>;
+    /**
+     * Read a section's target file, parse the section, validate the snapshot
+     * tag (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
+     * tag mismatch ({@link MismatchError}).
+     */
+    prepare(section: PatchSection): 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} 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[];

package/dist/types/recovery.d.ts

@@ -0,0 +1,40 @@
+import type { SnapshotStore } from "./snapshots";
+import type { Edit } from "./types";
+export interface RecoveryArgs {
+    path: string;
+    currentText: string;
+    fileHash: string;
+    edits: readonly Edit[];
+}
+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-tag incident. The default
+ * implementation tries two strategies in order:
+ *
+ * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
+ *    the resulting patch onto the live content (handles external writes).
+ * 2. (Session chain) If that version wasn't the head, replay the edits onto
+ *    the live content directly when line counts match AND every edit's anchor
+ *    line content is unchanged between version and current — a prior in-session
+ *    edit advanced the tag and the model's anchors still name the same logical
+ *    rows. Emits a dedicated {@link RECOVERY_SESSION_REPLAY_WARNING} because
+ *    even with both guards a coincidental insert+delete pair on duplicate rows
+ *    can still land the edit on the wrong row; see {@link replaySessionChainOnCurrent}.
+ */
+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,55 @@
+/**
+ * One full-file version observed at a point in time. The tag the model sees is
+ * {@link Snapshot.hash}; recovery replays edits against {@link Snapshot.text}.
+ */
+export interface Snapshot {
+    /** Canonical path this version belongs to. */
+    readonly path: string;
+    /** Full normalized (LF, no BOM) file text as observed. */
+    readonly text: string;
+    /** Content-derived tag for {@link Snapshot.text} (see {@link computeFileHash}). */
+    readonly hash: string;
+    /** Timestamp (ms since epoch) the version was recorded. */
+    recordedAt: number;
+}
+/**
+ * Storage seam for full-file version snapshots. The patcher calls {@link head}
+ * for the latest version of a path and {@link byHash} when it needs the
+ * specific historical version a section's stale tag names.
+ */
+export declare abstract class SnapshotStore {
+    /** Most-recently recorded version for `path`, or `null` if none. */
+    abstract head(path: string): Snapshot | null;
+    /** Recorded version for `path` whose tag equals `hash`, or `null`. */
+    abstract byHash(path: string, hash: string): Snapshot | null;
+    /** Record the full normalized text of `path` and return its content tag. */
+    abstract record(path: string, fullText: string): string;
+    /** Drop the version history for a single path. */
+    abstract invalidate(path: string): void;
+    /** Drop every version history. */
+    abstract clear(): void;
+}
+export interface InMemorySnapshotStoreOptions {
+    /** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
+    maxPaths?: number;
+    /** Maximum full-file versions retained per path (default 4). Oldest dropped first. */
+    maxVersionsPerPath?: number;
+}
+/**
+ * In-memory {@link SnapshotStore} backed by `lru-cache`. Per-path history is a
+ * short ring of full-file versions (oldest dropped first); per-session path
+ * tracking is LRU-bounded so cold paths age out automatically.
+ *
+ * Recording byte-identical content again refreshes recency and reuses the
+ * existing tag (read fusion); recording new content unshifts a fresh version
+ * onto the front of the path history.
+ */
+export declare class InMemorySnapshotStore extends SnapshotStore {
+    #private;
+    constructor(options?: InMemorySnapshotStoreOptions);
+    head(path: string): Snapshot | null;
+    byHash(path: string, hash: string): Snapshot | null;
+    record(path: string, fullText: string): string;
+    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,65 @@
+import type { Anchor, Cursor, ParsedRange } from "./types";
+export declare function splitHashlineLines(text: string): string[];
+export declare function cloneCursor(cursor: Cursor): Cursor;
+/** Parse a bare line-number anchor. Throws on malformed input. */
+export declare function parseLid(raw: string, lineNum: number): Anchor;
+export type BlockTarget = {
+    kind: "replace";
+    range: ParsedRange;
+} | {
+    kind: "block";
+    anchor: Anchor;
+} | {
+    kind: "delete";
+    range: ParsedRange;
+} | {
+    kind: "delete_block";
+    anchor: Anchor;
+} | {
+    kind: "insert_before";
+    anchor: Anchor;
+} | {
+    kind: "insert_after";
+    anchor: Anchor;
+} | {
+    kind: "bof";
+} | {
+    kind: "eof";
+};
+interface TokenBase {
+    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-block";
+    target: BlockTarget;
+}) | (TokenBase & {
+    kind: "payload-literal";
+    text: string;
+}) | (TokenBase & {
+    kind: "raw";
+    text: string;
+});
+export declare class Tokenizer {
+    #private;
+    feed(chunk: string): Token[];
+    end(): Token[];
+    reset(): void;
+    tokenizeAll(text: string): Token[];
+    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,129 @@
+/**
+ * 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. Replacement payloads are tagged so the
+ * applier can distinguish literal insertion from new content for a deleted
+ * line.
+ */
+export type Edit = {
+    kind: "insert";
+    cursor: Cursor;
+    text: string;
+    lineNum: number;
+    index: number;
+    mode?: "replacement";
+} | {
+    kind: "delete";
+    anchor: Anchor;
+    lineNum: number;
+    index: number;
+    oldAssertion?: string;
+} | {
+    /**
+     * Deferred block edit (`replace block N:` / `delete block N`). The exact
+     * line span is unknown at parse time — it is computed by
+     * {@link resolveBlockEdits} once file text + path (→ language) are
+     * available, then expanded into concrete edits: a non-empty `payloads`
+     * (from `replace block`) becomes the same `replacement` inserts + deletes
+     * that `replace start..end:` produces; an empty `payloads` (from `delete
+     * block`) becomes a pure range deletion. `applyEdits` never sees this
+     * variant.
+     */
+    kind: "block";
+    anchor: Anchor;
+    payloads: string[];
+    lineNum: number;
+    index: number;
+};
+/** 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 parser, patcher, or recovery. */
+    warnings?: string[];
+}
+/** 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;
+}
+/**
+ * Resolved 1-indexed inclusive line span of a `replace block N:` target.
+ */
+export interface BlockSpan {
+    /** First line of the block (1-indexed, inclusive). */
+    start: number;
+    /** Last line of the block (1-indexed, inclusive). */
+    end: number;
+}
+/** Request handed to a {@link BlockResolver} to resolve one `replace block N:` anchor. */
+export interface BlockResolverRequest {
+    /** Target file path (used to infer language by extension). */
+    path: string;
+    /** Full text the block must be resolved against (the snapshot the tag names). */
+    text: string;
+    /** 1-indexed line the block must begin on. */
+    line: number;
+}
+/**
+ * Resolves a `replace block N:` anchor to the line span of the syntactic block
+ * that begins on line N. Returns `null` when no block can be resolved
+ * (unrecognized language, blank/out-of-range line, no node begins there, or the
+ * resolved subtree has a syntax error). Pure seam: the hashline core declares
+ * the contract; the host injects a tree-sitter-backed implementation.
+ */
+export type BlockResolver = (request: BlockResolverRequest) => BlockSpan | null;

package/package.json

@@ -0,0 +1,62 @@
+{
+	"type": "module",
+	"name": "@prometheus-ai/hashline",
+	"version": "0.5.0",
+	"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://prometheus.trivlab.com",
+	"author": "Uttam Trivedi",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/uttamtrivedi/Prometheus.git",
+		"directory": "packages/hashline"
+	},
+	"bugs": {
+		"url": "https://github.com/uttamtrivedi/Prometheus/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 .",
+		"test": "bun test --parallel",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"diff": "^9.0.0",
+		"lru-cache": "11.5.1"
+	},
+	"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"
+	}
+}