dsh-hashline-edit 0.2.0 → 0.2.2

package/lib/types/src/apply-patch/types.d.ts

@@ -1,362 +0,0 @@
-/**
- * apply_patch v4 — shared contract types.
- *
- * This module is the frozen vocabulary every apply-patch lane compiles against:
- *
- * - the **patch AST** the grammar layer produces (`PatchDocument`),
- * - the **plan IR** the planner produces and the transaction layer commits
- *   (`PatchPlan`, `PlannedFile`, `PlannedMutation`),
- * - the **result / error** types the renderer and the host adapter consume.
- *
- * The engine underneath is the existing hashline kernel: content-addressed 4-char
- * anchors, served leases, MVCC snapshots, correlated multi-file transactions and
- * the undo store. Nothing here re-declares those primitives; the plan IR only
- * adds the addressing and lifecycle vocabulary apply_patch needs.
- *
- * Vocabulary (see GLOSSARY.md): anchor, served row, lease, fragment hunk,
- * identity hunk, reference hunk, patch line, plan.
- *
- * @module dsh-hashline-edit/apply-patch/types
- */
-import type { DomainErrorCode, ServedRow } from "../domain-errors.js";
-import type { LineEnding } from "../edit-diff.js";
-import type { HashStore } from "../hash-store.js";
-import type { TransactionRecoveryReport } from "../mutation-engine/types.js";
-/** Patch AST (grammar layer output). */
-/** A 4-character anchor: `[A-Za-z0-9]{4}` (the hashline alphabet). */
-export type Anchor = string;
-/** A 1-based line number in the submitted patch text, used by every diagnostic. */
-export type PatchLineNumber = number;
-/** A path exactly as written in the patch: workspace-relative or workspace-absolute. */
-export type PatchPath = string;
-/** A closed anchor span; both anchors must have been served for the same file. */
-export interface AnchorSpan {
-    readonly from: Anchor;
-    readonly to: Anchor;
-}
-/** One parsed `*** Begin Patch` … `*** End Patch` document. */
-export interface PatchDocument {
-    /** File operations in submission order. */
-    readonly files: readonly PatchFileOp[];
-    /** Total number of lines in the input (1-based diagnostics may point at EOF). */
-    readonly lineCount: number;
-}
-export type PatchFileOp = AddFileOp | DeleteFileOp | UpdateFileOp;
-/** `*** Add File: <path>` — every following line is a '+' content line. */
-export interface AddFileOp {
-    readonly kind: "add";
-    readonly path: PatchPath;
-    readonly headerLine: PatchLineNumber;
-    /** Content lines WITHOUT the leading '+', in file order. Empty means an empty file. */
-    readonly contentLines: readonly string[];
-}
-/** `*** Delete File: <path>` */
-export interface DeleteFileOp {
-    readonly kind: "delete";
-    readonly path: PatchPath;
-    readonly headerLine: PatchLineNumber;
-}
-/** `*** Update File: <path>` with its optional `*** Move to:` and zero or more hunks. */
-export interface UpdateFileOp {
-    readonly kind: "update";
-    readonly path: PatchPath;
-    readonly headerLine: PatchLineNumber;
-    /** `*** Move to: <path>`; the parser only accepts it directly after the update header. */
-    readonly moveTo?: MoveDirective;
-    /** Hunks in submission order; each hunk's window starts after the previous hunk's end. */
-    readonly hunks: readonly PatchHunk[];
-}
-/** `*** Move to: <path>` */
-export interface MoveDirective {
-    readonly path: PatchPath;
-    readonly line: PatchLineNumber;
-}
-export type PatchHunk = FragmentHunk | IdentityHunk | ReferenceHunk;
-/**
- * The addressing a hunk opens with.
- *
- * `start` is the bare `@@` (fragment mode, search from the file start);
- * `context` is `@@ <line>` (fragment mode, search window starts after that
- * line's unique hit); `anchors` is `@@<a>` / `@@<a>-<b>` (identity mode).
- */
-export type HunkAddress = {
-    readonly kind: "start";
-} | {
-    readonly kind: "context";
-    readonly text: string;
-} | {
-    readonly kind: "anchors";
-    readonly span: AnchorSpan;
-};
-/** A context/line matcher hunk: `@@` or `@@ <context>` followed by ' '/'+'/'-' lines. */
-export interface FragmentHunk {
-    readonly kind: "fragment";
-    /** Grammar guarantees this is `start` or `context`; `anchors` never appears here. */
-    readonly address: HunkAddress;
-    readonly headerLine: PatchLineNumber;
-    /** Body lines, in submission order; at least one is required. */
-    readonly lines: readonly FragmentLine[];
-    /** `*** End of File` line number when the hunk is tail-pinned, absent otherwise. */
-    readonly endOfFile?: PatchLineNumber;
-}
-/** One body line of a fragment hunk. */
-export interface FragmentLine {
-    readonly op: "context" | "remove" | "add";
-    /** Line content without the leading marker (' ', '-', '+'). */
-    readonly text: string;
-    readonly line: PatchLineNumber;
-}
-/** An identity hunk: `@@<a>` / `@@<a>-<b>` followed by '+' lines only (empty body = delete). */
-export interface IdentityHunk {
-    readonly kind: "identity";
-    readonly span: AnchorSpan;
-    readonly headerLine: PatchLineNumber;
-    /** '+' lines without the marker; empty means the span is deleted. */
-    readonly addedLines: readonly string[];
-}
-/** A copy/cut hunk: the content comes from another file's served span; no body lines allowed. */
-export interface ReferenceHunk {
-    readonly kind: "reference";
-    /**
-     * The hunk's own addressing (`@@`, `@@ <context>`, `@@<a>` or `@@<a>-<b>`),
-     * which determines the destination position (see docs/apply-patch-v4-internals.md §4).
-     */
-    readonly address: HunkAddress;
-    readonly source: ReferenceSource;
-    readonly headerLine: PatchLineNumber;
-}
-/** `*** Copy From:` / `*** Cut From:` source span. */
-export interface ReferenceSource {
-    readonly mode: "copy" | "cut";
-    readonly path: PatchPath;
-    readonly span: AnchorSpan;
-    readonly line: PatchLineNumber;
-}
-/** Plan IR (planner output / transaction input). */
-/**
- * An inclusive 1-based line range in a file's pre-call baseline.
- *
- * A zero-width insertion uses the engine's inverted convention:
- * `startLine = point + 1` and `endLine = point` (insert after line `point`;
- * point 0 inserts at the start of the file).
- */
-export interface LineRange {
-    readonly startLine: number;
-    readonly endLine: number;
-}
-/** The file-lifecycle action planned for one target. */
-export type LifecyclePlan = {
-    readonly kind: "keep";
-} | {
-    readonly kind: "add";
-} | {
-    readonly kind: "delete";
-} | {
-    readonly kind: "move";
-    readonly to: PatchPath;
-    readonly toAbsolutePath: string;
-};
-/** One file's state at call time — the single baseline every mutation resolves against. */
-export interface FileBaseline {
-    /** The path as written in the patch. */
-    readonly path: PatchPath;
-    /** The resolved absolute path the engine reads/writes. */
-    readonly absolutePath: string;
-    /** LF-normalized text; `""` for an Add File target. */
-    readonly text: string;
-    /** 4-char anchors parallel to the file's lines; empty for an Add File target. */
-    readonly hashes: readonly string[];
-    /** Byte-order mark the file carried ("" when none). */
-    readonly bom: string;
-    /** The file's original line ending. */
-    readonly ending: LineEnding;
-    /** False for `*** Add File:` targets, true for every other existing target. */
-    readonly exists: boolean;
-}
-/** One resolved content mutation against `FileBaseline.text`, in baseline coordinates. */
-export interface PlannedMutation {
-    readonly kind: "replace" | "insert" | "delete";
-    readonly range: LineRange;
-    /** Replacement lines (LF-joined at commit); empty for `delete` and for an empty insertion. */
-    readonly lines: readonly string[];
-    /** The patch line that produced this mutation (diagnostics and ordering evidence). */
-    readonly patchLine: PatchLineNumber;
-}
-/** One Copy/Cut source span materialized from a baseline. */
-export interface PlannedReferenceUse {
-    readonly mode: "copy" | "cut";
-    readonly path: PatchPath;
-    readonly absolutePath: string;
-    readonly range: LineRange;
-    /** The source bytes, line-split and LF-normalized. */
-    readonly lines: readonly string[];
-    readonly patchLine: PatchLineNumber;
-}
-/** One file in the plan, with every mutation expressed against its own pre-call baseline. */
-export interface PlannedFile {
-    readonly path: PatchPath;
-    readonly absolutePath: string;
-    readonly lifecycle: LifecyclePlan;
-    readonly baseline: FileBaseline;
-    /** Non-overlapping mutations in baseline coordinates, ordered by `range.startLine`. */
-    readonly mutations: readonly PlannedMutation[];
-    /** Copy/Cut sources this target consumes. */
-    readonly references: readonly PlannedReferenceUse[];
-    /** True when committing this member changes bytes or the namespace. */
-    readonly writes: boolean;
-}
-/** The full plan one apply_patch call commits as one correlated transaction. */
-export interface PatchPlan {
-    /** Written members in commit order: the primary file leads, the rest follow deterministically. */
-    readonly files: readonly PlannedFile[];
-    /** Files read only as Copy/Cut sources (never written). */
-    readonly referenceFiles: readonly FileBaseline[];
-    readonly stats: PatchStats;
-}
-/** Aggregate line/file counts the success summary reports. */
-export interface PatchStats {
-    readonly filesChanged: number;
-    readonly addedLines: number;
-    readonly removedLines: number;
-}
-/** Result and error types. */
-/**
- * The two error codes apply_patch adds to the shared registry.
- *
- * `E_STALE_ANCHOR` is NOT new: `src/domain-errors.ts` already registers it with
- * the served-rows payload this feature reuses. The registry lane must add these
- * two codes (payload + producer) before the surface lane registers the tool.
- */
-export type ApplyPatchNewErrorCode = "E_PATCH_SYNTAX" | "E_UNIQUE_MATCH";
-/** Every code a patch problem may carry. */
-export type ApplyPatchErrorCode = DomainErrorCode | ApplyPatchNewErrorCode;
-/** One candidate row for an ambiguous fragment match, served back to the model. */
-export interface PatchCandidate {
-    /** 1-based line number in the baseline. */
-    readonly line: number;
-    readonly hash: Anchor;
-    readonly text: string;
-}
-/** One collectable problem in a rejection; every problem carries its patch line and code. */
-export interface PatchProblem {
-    readonly code: ApplyPatchErrorCode;
-    readonly patchLine: PatchLineNumber;
-    readonly path?: PatchPath;
-    readonly message: string;
-    /** Candidate rows when the failure is an ambiguous fragment match. */
-    readonly candidates?: readonly PatchCandidate[];
-    /** 1-based target line used to center the rejection serve window when known. */
-    readonly line?: number;
-}
-/** One file's current rows rendered `HASH│content` for reject-and-serve. */
-export interface ServedFileBlock {
-    readonly path: PatchPath;
-    readonly rows: readonly ServedRow[];
-    /** Rendered block, one `HASH│content` row per line. */
-    readonly text: string;
-}
-/** One file's lifecycle status and line counts in the success summary. */
-export interface AppliedFileSummary {
-    /** A = added, M = modified, R = renamed, D = deleted. */
-    readonly status: "A" | "M" | "R" | "D";
-    readonly path: PatchPath;
-    /** Original path for a rename (`R` only). */
-    readonly fromPath?: PatchPath;
-    readonly addedLines: number;
-    readonly removedLines: number;
-}
-/** Metrics one committed call reports (mirrors the existing RMetrics intent). */
-export interface PatchMetrics {
-    readonly files: number;
-    readonly hunks: number;
-    readonly addedLines: number;
-    readonly removedLines: number;
-    readonly durationMs?: number;
-}
-/** Successful apply_patch outcome. */
-export interface ApplyPatchSuccess {
-    readonly ok: true;
-    /** File-level summary, e.g. `Updated 2 files:\nA src/new.ts\nM src/a.ts`. */
-    readonly summary: string;
-    /** Annotated diff for the UI/details (never the model's primary text). */
-    readonly diff: string;
-    readonly files: readonly AppliedFileSummary[];
-    /** New anchors for every changed line, per file — the second call needs no read. */
-    readonly served: readonly ServedFileBlock[];
-    readonly warnings: readonly string[];
-    readonly metrics: PatchMetrics;
-}
-/** Rejected apply_patch outcome: one transaction, zero disk writes. */
-export interface ApplyPatchFailure {
-    readonly ok: false;
-    /** Primary code for the envelope; every problem still carries its own code. */
-    readonly code: ApplyPatchErrorCode;
-    readonly message: string;
-    /** Every independently diagnosable problem, in patch order. */
-    readonly problems: readonly PatchProblem[];
-    /** Current rows for every file named by a problem (reject-and-serve). */
-    readonly served: readonly ServedFileBlock[];
-    /** A rejection is pre-commit: the disk is unchanged by construction. */
-    /**
-     * True when the commit left the disk byte-identical (every written member rolled back). A
-     * mid-commit failure that could not be rolled back sets this false and reports exactly which
-     * members were restored, remain, or are uncertain.
-     */
-    readonly changedNothing: boolean;
-    /** The rollback's three-way outcome, when the failure happened after a member was written. */
-    readonly recovery?: TransactionRecoveryReport;
-}
-export type ApplyPatchResult = ApplyPatchSuccess | ApplyPatchFailure;
-/** The grammar seam's total result: a document or every syntax problem found. */
-export type ParsePatchResult = {
-    readonly ok: true;
-    readonly document: PatchDocument;
-} | {
-    readonly ok: false;
-    readonly problems: readonly PatchProblem[];
-};
-/** The planner seam's total result. */
-export type PlanPatchResult = {
-    readonly ok: true;
-    readonly plan: PatchPlan;
-} | {
-    readonly ok: false;
-    readonly problems: readonly PatchProblem[];
-    /** Current rows for every problem file, so the rejection needs no read to retry. */
-    readonly served: readonly ServedFileBlock[];
-};
-/** The model-facing tool envelope returned by the renderer / tool use case. */
-export interface ApplyPatchToolResult {
-    readonly content: ReadonlyArray<{
-        readonly type: "text";
-        readonly text: string;
-    }>;
-    readonly details: ApplyPatchDetails;
-    /** True when this envelope renders a rejection (nothing was written). */
-    readonly isError?: boolean;
-}
-/** The structured details half of {@link ApplyPatchToolResult}. */
-export interface ApplyPatchDetails {
-    readonly summary: string;
-    readonly diff: string;
-    readonly files: readonly AppliedFileSummary[];
-    readonly servedByPath: readonly ServedFileBlock[];
-    readonly warnings: readonly string[];
-    readonly metrics: PatchMetrics;
-}
-/** Execution facts every apply_patch seam shares. */
-export interface ApplyPatchContext {
-    /** Absolute directory relative request paths resolve against (the live session directory). */
-    readonly cwd: string;
-    /** Session identity that keys served anchors and leases; never empty. */
-    readonly sessionKey: string;
-    /** Caller cancellation forwarded into every async file operation. */
-    readonly signal?: AbortSignal;
-}
-/** Options for the planner/commit seams over the existing hash store. */
-export interface ApplyPatchEngineOptions extends ApplyPatchContext {
-    /** Hash store override for tests; the default opens the configured store. */
-    readonly store?: HashStore;
-    /** POSIX access-mode bitmask; commit defaults to read+write, plan to read-only. */
-    readonly accessMode?: number;
-}

package/lib/types/src/fs-lifecycle.d.ts

@@ -1,44 +0,0 @@
-/**
- * Filesystem primitives for apply_patch's file lifecycle: classify, create directories, delete a
- * regular file and rename one. Every entry point resolves through {@link resolveTarget}, the same
- * symlink-resolving boundary every read/write uses, so a lifecycle action can never escape it.
- *
- * These are primitives, not a second write engine: file CONTENTS still go through writeAtomic;
- * this module only owns namespace operations that writeAtomic deliberately does not express.
- *
- * @module dsh-hashline-edit/fs-lifecycle
- */
-/** The physical kind of a path as the file layer sees it (symlinks resolved first). */
-export type PathKind = "file" | "directory" | "other" | "absent";
-/** Classify one path through the file layer's symlink-resolving boundary. */
-export declare function pathKind(path: string): Promise<PathKind>;
-/**
- * True when `path` resolves inside `root` once every existing symlink/junction component is
- * followed. A missing tail is checked against its nearest existing ancestor: an Add File under a
- * junction ancestor therefore fails before mkdir can create anything outside the workspace.
- */
-export declare function isPathWithinWorkspace(root: string, path: string): Promise<boolean>;
-/** Throw the E_PATCH_SYNTAX boundary refusal for one escaping lifecycle path. */
-export declare function assertPathWithinWorkspace(root: string, path: string): Promise<void>;
-/** Create one directory (and missing parents), through the symlink-resolving boundary. */
-export declare function mkdirp(path: string, workspaceRoot?: string): Promise<void>;
-/**
- * Delete one regular file. Deliberately NOT recursive: a lifecycle delete targets a file, and a
- * directory at the same path is a caller bug that must surface, never be removed wholesale.
- */
-export declare function removeFile(path: string, signal?: AbortSignal): Promise<void>;
-/**
- * Rename one regular file, creating the destination parent first. The destination must not exist:
- * a move never clobbers another file (spec §6: target-exists is a rejection, not an overwrite).
- */
-export declare function renameFile(from: string, to: string, signal?: AbortSignal, workspaceRoot?: string): Promise<void>;
-/**
- * The directories on the way to `path` that do not exist yet, OUTERMOST FIRST. Captured before a
- * lifecycle add writes, so an undo removes exactly the directories the add created and no others.
- */
-export declare function missingAncestorDirs(path: string): Promise<string[]>;
-/**
- * Best-effort removal of directories a lifecycle add created, deepest first. Returns the removed
- * paths. A directory that is no longer empty (an outside writer put something there) is kept.
- */
-export declare function pruneEmptyDirs(dirs: readonly string[]): Promise<string[]>;

package/lib/types/src/host-utils.d.ts

@@ -1,63 +0,0 @@
-/** Retained line budget, matching pi's `DEFAULT_MAX_LINES`. */
-export declare const DEFAULT_MAX_LINES = 2000;
-/** Retained byte budget, matching pi's `DEFAULT_MAX_BYTES` (50KB). */
-export declare const DEFAULT_MAX_BYTES: number;
-/** The truncation report the core's read page renders. */
-export interface TruncationResult {
-    /** The truncated content. */
-    content: string;
-    /** Whether truncation occurred. */
-    truncated: boolean;
-    /** Which limit was hit: `"lines"`, `"bytes"`, or `null` when nothing was cut. */
-    truncatedBy: "lines" | "bytes" | null;
-    /** Total number of lines in the original content. */
-    totalLines: number;
-    /** Total number of bytes in the original content. */
-    totalBytes: number;
-    /** Number of complete lines in the truncated output. */
-    outputLines: number;
-    /** Number of bytes in the truncated output. */
-    outputBytes: number;
-    /** Whether the last line was partially truncated (tail truncation only). */
-    lastLinePartial: boolean;
-    /** Whether the first line exceeded the byte limit (head truncation only). */
-    firstLineExceedsLimit: boolean;
-    /** The line limit that was applied. */
-    maxLines: number;
-    /** The byte limit that was applied. */
-    maxBytes: number;
-}
-/** The two independent limits a truncation call applies. */
-export interface TruncationOptions {
-    /** Maximum number of lines; defaults to {@link DEFAULT_MAX_LINES}. */
-    maxLines?: number;
-    /** Maximum number of bytes; defaults to {@link DEFAULT_MAX_BYTES}. */
-    maxBytes?: number;
-}
-/**
- * Format bytes as a human-readable size (`512B`, `1.5KB`, `2.0MB`).
- * @param bytes - the byte count to render.
- * @returns the pi-compatible size label.
- */
-export declare function formatSize(bytes: number): string;
-/**
- * Truncate content from the head (keep the first N lines / bytes).
- *
- * WHY: the read page's oversize and truncation warnings must agree with the pi
- * implementation the rest of the contract was written against, so this is a
- * faithful port including its two edge rules: complete lines only, and an
- * over-long first line yields empty content with `firstLineExceedsLimit`.
- * @param content - the text to truncate.
- * @param options - the line and byte limits.
- * @returns the truncation report.
- */
-export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
-/**
- * Serialize file mutation operations that target the same file; different files still run
- * in parallel. A faithful port of pi's queue so the core's cut transaction keeps its
- * lock ordering guarantees under the dsh host.
- * @param filePath - the file the mutation targets.
- * @param run - the critical section to run once the path is free.
- * @returns the critical section's result.
- */
-export declare function withFileMutationQueue<T>(filePath: string, run: () => Promise<T>): Promise<T>;

package/lib/types/src/mutation-engine/edit-request.d.ts

@@ -1,34 +0,0 @@
-/** The internal payload vocabulary the mutation engine consumes; no wire schema lives here. */
-type SpanRef = {
-    anchor_from: string;
-    anchor_to: string;
-    file?: string;
-    mode: "copy" | "cut";
-};
-type EditMode = "general" | "literal";
-type Placement = "in-place" | "before" | "after";
-export type DesiredContent = {
-    kind: "literal";
-    text: string;
-} | {
-    kind: "reference";
-    span: SpanRef;
-    mode: "copy" | "cut";
-} | {
-    kind: "empty";
-};
-export type NormalizedEditItem = {
-    target: {
-        anchor_from: string;
-        anchor_to: string;
-    };
-    at: Placement;
-    payload: DesiredContent;
-    file?: string;
-};
-export type NormalizedEditRequest = {
-    file: string;
-    edits: NormalizedEditItem[];
-    mode?: EditMode;
-};
-export {};

package/prompts/apply-patch-guidelines.md

@@ -1,10 +0,0 @@
-- apply_patch: one call = one transaction. Collect every related file change (code, tests, docs, config) into one patch; split only when an earlier RESULT must decide a later edit.
-- apply_patch: two addressing modes. Fragment mode (`@@` or `@@ <context>`) locates by exact content and needs no served state. Identity mode (`@@<a>` / `@@<a>-<b>`) targets rows this session served and never writes the old text back.
-- apply_patch: the character after `@@` selects the mode. `@@` followed immediately by exactly four anchor characters is identity mode; `@@` followed by a space is Codex context mode (`@@ <line>`); a bare `@@` starts the search at the file start. Any other token is a syntax rejection.
-- apply_patch: fragment mode must match exactly once. Zero or several hits reject and serve the candidate rows; add surrounding context to disambiguate, never guess.
-- apply_patch: identity mode accepts only `+` lines; an empty body deletes the span. A `-` or context line in an identity hunk, or body lines in a Copy/Cut hunk, rejects at admission with its patch line number.
-- apply_patch: every hunk resolves against the file as it was before the call; later windows begin after the previous hunk's end. Overlapping target ranges in one file reject the whole batch.
-- apply_patch: lifecycle joins the same transaction and undo. `*** Add File:` content lines all start with `+`; `*** Delete File:` removes the file; `*** Move to:` must immediately follow `*** Update File:` and renames before its hunks apply; an existing move target rejects.
-- apply_patch: a rejection writes nothing. Read the `- patch line N ([E_*], path): ...` lines, then use the immediately following `HASH│content` block — those are the current rows and anchors; retry directly without issuing a separate `read`.
-- apply_patch: a success starts with `Updated N files:` and ends with the changed lines' fresh anchors per file; use those anchors directly in the next identity hunk. `[W_*]` lines are informational.
-- apply_patch: paths are workspace-relative or workspace-absolute; `..`, `.git`, and symlink targets reject. Whole-file replacement stays with `write`.

package/prompts/apply-patch.md

@@ -1 +0,0 @@
-Apply one Codex-format patch to one or more files in a single transaction: `{ input: string }`. `input` is the complete patch text: `*** Begin Patch` ... `*** End Patch`, with `*** Add File:`, `*** Delete File:`, `*** Update File:` (plus optional `*** Move to:`) and hunks addressed either by content (`@@` or `@@ <context>` with ` `/`-`/`+` lines) or by served anchors (`@@<a>` / `@@<a>-<b>` with `+` lines only). `*** Copy From:` / `*** Cut From:` copy or move a served span from another file. Every target validates before anything is written; a rejection changes nothing and returns the current rows with anchors. On success the result lists the changed files and the new anchors for the changed lines, so a follow-up call needs no `read`. `write` stays for whole-file replacement.