dsh-hashline-edit 0.2.2 → 0.3.0

package/lib/types/src/edit-tool.d.ts

@@ -1,41 +0,0 @@
-/** SAFETY: EditTool — deep module owning the edit Use Case seam.
- *
- * Graded surface: one narrow interface `EditTool { execute, preview }`
- * hides pipeline delegation, warnings/drift stitching.
- * Frameworks (pi TUI) never cross this seam — that lives in TuiPresenter.
- * Clean Architecture: Use Cases depend inward only (mutation-engine),
- * never outward to Frameworks.
- *
- * Typed boundaries: validate once at admission (payload-contract via normReq/assertReq),
- * trust inside. Immutable state: never mutates caller-owned request.
- */
-type EditToolContext = {
-    cwd: string;
-    sessionManager?: {
-        getSessionId(): string;
-    };
-};
-export type PreviewContext = {
-    sessionManager?: {
-        getSessionId(): string;
-    };
-};
-type PreviewResult = {
-    diff: string;
-} | {
-    error: string;
-};
-export interface EditTool {
-    /** SAFETY: Execute a validated edit; returns pi tool_result or throws on failure. Admission: params validated by normReq/assertReq. */
-    execute(params: unknown, signal: AbortSignal | undefined, ctx: EditToolContext): Promise<{
-        content: Array<{
-            type: "text";
-            text: string;
-        }>;
-        details: unknown;
-    }>;
-    /** SAFETY: Preview without persisting — mirrors pi's compPreview(request, cwd, ctx). The ctx must carry the session whose serves the anchors came from (#165). */
-    preview(request: unknown, cwd: string, ctx: PreviewContext): Promise<PreviewResult>;
-}
-export declare function createEditTool(): EditTool;
-export {};

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

@@ -1,31 +0,0 @@
-/**
- * SAFETY: MutationEngine — deep module behind the mutation seam.
- *
- * Small interface: `execute` + `preview`. Deep implementation: load → parse
- * → mutate → finalize → drift → persist → serve hidden inside the pipeline.
- * Internal seams (validate, verify, mutate, guard, persist, record) stay
- * private — not exported. The interface is the test surface.
- *
- * Typed boundaries: validate once at admission (edit.ts via payload-contract),
- * trust inside. Errors fail loud with typed `MutationFailure`.
- */
-import type { PipelineOptions } from "./types.js";
-import type { MutationResult } from "./types.js";
-import type { NormalizedEditRequest } from "../payload-contract.js";
-declare function toFailure(error: unknown): MutationResult;
-/**
- * SAFETY: Execute a mutation against the file system (persist + undo + serve).
- * Returns discriminated `MutationResult` — callers must switch on `ok`.
- *
- * No `any` threading: input is `NormalizedEditRequest` (validated at
- * admission), output is typed. Failures are `ok:false` with `code`, not
- * loose `isError` flags.
- */
-export declare function execute(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<MutationResult>;
-/**
- * SAFETY: Preview a mutation without persisting (noPersist). Same seam as `execute`,
- * same `MutationResult` — one interface, N call sites (preview + apply share
- * the internal path via `runMutations` with `noPersist:true`).
- */
-export declare function preview(request: NormalizedEditRequest, cwd: string, options?: Omit<PipelineOptions, "noPersist">): Promise<MutationResult>;
-export { toFailure };

package/lib/types/src/payload-contract.d.ts

@@ -1,135 +0,0 @@
-import { Type } from "typebox";
-import type { EditPlacement } from "./hashline/resolve.js";
-declare const normalizedEdit: unique symbol;
-/** Width-appropriate illustrative anchor for prompt examples (width is a build-time setting, ADR-0020). */
-export declare const ANCHOR_EXAMPLE: string;
-/**
- * The `text_ref` payload: two inclusive bare anchors bounding a served span, an optional serving
- * `file`, and a REQUIRED `mode` — `"copy"` re-inserts the span bytes, `"cut"` additionally retires
- * them. Both modes apply to this file AND to another served file (ticket-04b): a foreign-source
- * `"cut"` commits the insert and the source retirement as one correlated transaction (ADR-0028).
- */
-type SpanRef = {
-    anchor_from: string;
-    anchor_to: string;
-    file?: string;
-    mode: "copy" | "cut";
-};
-/**
- * Wire item (ticket-04): exactly one payload per item — `text` or `text_ref` — over the inclusive
- * anchor pair, with optional `at` placement. There is no `op` field and no verbs: the key set IS
- * the vocabulary (ADR-0007 line 26; content comes from the copy of another served file, which the
- * wire expresses as `text_ref.file`).
- */
-export type EditItem = {
-    anchor_from: string;
-    anchor_to: string;
-    at?: "in-place" | "before" | "after";
-    text?: string;
-    text_ref?: SpanRef;
-    /**
-     * The file this item edits; absent means the call's top-level `file`. One call may therefore
-     * cross files: each item resolves its anchors and its lease against the file it names.
-     */
-    file?: string;
-};
-type EditMode = "general" | "literal";
-/**
- * Internal normalized vocabulary owned by the admission boundary (ticket-01, renamed ticket-04).
- * The wire never names these shapes: `normReq` builds them once from the validated payload and
- * everything downstream consumes the union — the engine switches on `payload.kind` exhaustively.
- */
-export type Placement = "in-place" | "before" | "after";
-/**
- * @public Intentional surface (knip): the tuple type is the wire/engine
- * vocabulary check, so the binding is never imported — its reason to exist
- * is the typecheck failure it produces when the unions drift.
- */
-export declare const _placementVocabularyAgreement: [
-    Placement extends EditPlacement ? true : never,
-    EditPlacement extends Placement ? true : never
-];
-/** The anchor pair an item targets — placement and payload are relative to its resolved span. */
-type AnchorSpan = {
-    anchor_from: string;
-    anchor_to: string;
-};
-export type DesiredContent = {
-    kind: "literal";
-    text: string;
-} | {
-    kind: "reference";
-    span: SpanRef;
-    mode: "copy" | "cut";
-} | {
-    kind: "empty";
-};
-export type NormalizedEditItem = {
-    target: AnchorSpan;
-    at: Placement;
-    payload: DesiredContent;
-    /** The file this item edits, when the wire named one; absent means the request's `file`. */
-    file?: string;
-};
-export type NormalizedEditRequest = {
-    file: string;
-    edits: NormalizedEditItem[];
-    mode?: EditMode;
-};
-/** The wire-folded request (the admission analyzer's view): canonical keys, pre-union. */
-type PreAdmissionRequest = {
-    file: string;
-    edits: EditItem[];
-    mode?: EditMode;
-};
-type NormalizedPayload = NormalizedEditRequest & {
-    readonly [normalizedEdit]: true;
-};
-type RawPayload = string | number | boolean | null | undefined | Record<string, unknown>;
-export type NormReqResult = NormalizedPayload | RawPayload;
-export declare const anchorFromSchema: Type.TString;
-export declare const anchorToSchema: Type.TString;
-export declare const editFileSchema: Type.TString;
-export declare const editModeSchema: Type.TUnion<[Type.TLiteral<"general">, Type.TLiteral<"literal">]>;
-export declare const editItemSchema: Type.TObject<{
-    anchor_from: Type.TString;
-    anchor_to: Type.TString;
-    at: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"in-place">, Type.TLiteral<"before">, Type.TLiteral<"after">]>, Type.TNull]>>;
-    file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
-    text: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
-    text_ref: Type.TOptional<Type.TUnion<[Type.TObject<{
-        anchor_from: Type.TString;
-        anchor_to: Type.TString;
-        file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
-        mode: Type.TUnion<[Type.TLiteral<"copy">, Type.TLiteral<"cut">]>;
-    }>, Type.TNull]>>;
-}>;
-export declare const editToolSchema: Type.TObject<{
-    file: Type.TString;
-    edits: Type.TArray<Type.TObject<{
-        anchor_from: Type.TString;
-        anchor_to: Type.TString;
-        at: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"in-place">, Type.TLiteral<"before">, Type.TLiteral<"after">]>, Type.TNull]>>;
-        file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
-        text: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
-        text_ref: Type.TOptional<Type.TUnion<[Type.TObject<{
-            anchor_from: Type.TString;
-            anchor_to: Type.TString;
-            file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
-            mode: Type.TUnion<[Type.TLiteral<"copy">, Type.TLiteral<"cut">]>;
-        }>, Type.TNull]>>;
-    }>>;
-    mode: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"general">, Type.TLiteral<"literal">]>, Type.TNull]>>;
-}>;
-export declare const EDIT_DESCRIPTION: string;
-export declare const EDIT_SNIPPET: string;
-export declare const EDIT_GUIDELINES: string[];
-export declare function editRequestFrom(input: unknown): PreAdmissionRequest | undefined;
-export declare function normReq(input: unknown): NormReqResult;
-export declare function prepareEditArguments(args: unknown): Record<string, unknown>;
-export declare function getPreviewInput(args: unknown): {
-    file: string;
-    edits: EditItem[];
-} | null;
-export declare function assertReq(request: unknown): asserts request is NormalizedEditRequest;
-export {};

package/prompts/edit-guidelines.md

@@ -1,10 +0,0 @@
-- edit: an `anchor` is the bare {{HASH_LEN}}-char hash (for example "{{ANCHOR_EXAMPLE}}"). A `HASH│content` line (for example `{{ANCHOR_EXAMPLE}}│    pass`) is a served row, and `│` separates the two. Copy only the {{HASH_LEN}} chars before `│` into `anchor_from`/`anchor_to`.
-- edit: give each item two anchors and exactly one payload. `file` is the text file. One item is one edit. Several items batch to that one file. Choose one payload field: `text` or `text_ref`. `at` is optional. A null in an optional field (`text`, `text_ref`, `at`, the top-level `mode`, `text_ref.file`) reads as absent. A null in a required field (`file`, `edits`, any anchor, `text_ref.mode`) is refused.
-- edit: `anchor_from`/`anchor_to` bound an inclusive range. In-place replaces both boundary lines. `before`/`after` insert at the boundary instead. Out-of-band writes (bash, scripts, formatters) bypass serve recording. When a served line changes, the refusal serves the current rows. Copy fresh anchors from it.
-- edit: `text` is plain file content. Join lines with `\n`. Use `""` to delete the range. The tool refuses a line that copies a served hash echo. `text` is verbatim, so include the indentation you want.
-- edit: place the payload with `at`. `"in-place"` (default) rewrites the range. `"before"`/`"after"` insert at its boundary and need a single-line resolved target. `text: ""` with before/after writes nothing (noop).
-- edit: `text_ref` `{anchor_from, anchor_to, mode}` writes the bytes of a served span into the target. `mode: "copy"` keeps the source. `mode: "cut"` removes those lines from the source. When `file` names another served file, both modes apply to that file's rows. A `cut` then removes the span there in the same call. `mode` is required. Prefer `text_ref` to reproduce served bytes exactly or to move them. Use `text` for content you author.
-- edit: an anchor is bound to the file that served it. The lease is (session, file, anchor). Copy `anchor_from`/`anchor_to` only from the served rows of the file the payload names. That is this file by default, or `text_ref.file` when it names another file.
-- edit: after success the diff serves fresh `HASH│content` rows: context rows and `+` rows. Copy new anchors from the diff for your next call. Verify that the diff matches your intended mutation.
-- edit: a `[MODEL] [W_*]` line in `content` is informational. The mutation was applied. A `[MODEL] [E_*]` line is your retry instruction or a rejection: follow it from the message alone. A `[MODEL]` line that presents `Current range (fresh read):` shows the current rows. Decide from them. A dimmed `[USER]` line in `details` is human info.
-- edit: batch independent ranges in one `edits` array. Inside it, every edit validates BEFORE the first rename, and any failure there writes nothing. A foreign `cut` writes its files in a fixed order, and a defeated rollback restores captured bytes or is repaired on the next run.

package/prompts/edit-snippet.md

@@ -1 +0,0 @@
-Edit a file range via `edit`: `{"file":file,"edits":[{"anchor_from":a,"anchor_to":b,"text":text}]}` — anchors are bare {{HASH_LEN}}-char hashes copied from served `HASH│content` from rows this file served this session. One payload per item: `text` is bare content (`""` deletes) or `text_ref` writes a served span (`"copy"` keeps source, `"cut"` removes it from this file or `file`). `at`: "in-place" (default), "before", "after". Chain from diff anchors.

package/prompts/edit.md

@@ -1 +0,0 @@
-Edit a range of lines in a text file via `edit`: `{ "file": file, "edits": [{ "anchor_from": a, "anchor_to": b, "text": text }, ...] }` (one file per call, or one per item `file`). Use rows this session served for the file: `read`, a diff, or a bash view. `anchor_from`/`anchor_to` are bare {{HASH_LEN}}-char HASH anchors. Copy the {{HASH_LEN}} chars before `│` in this file's served rows (lease (session, file, anchor)). One payload per item: `text` (`\n` joins lines, `""` deletes) or `text_ref` `{anchor_from, anchor_to, mode (required), file?}`, the bytes of a served span (`mode` `"copy"` keeps it, `"cut"` removes it). `file` names another served file. `at`: "in-place" (default), "before", "after". A null optional field reads as absent. `[MODEL] [E_*]` is your retry instruction. `[W_*]` is informational.

package/prompts/read-snippet.md

@@ -1 +0,0 @@
-Read a file via `file`, `windows?`, `mode?`; default returns HASH│content rows for editing, `mode: "verbatim"` returns plain text when you will not edit; batch several ranges in one call via `windows`