dsh-hashline-edit 0.1.0 → 0.2.0

package/lib/types/dsh/encoding.d.ts

@@ -1,144 +0,0 @@
-import { type LineEnding } from "../src/edit-diff.js";
-/** The single config knob set the admission gates read. */
-export interface EncodingConfig {
-    /** When true, admit a probabilistic decode (the autoGuess gate). */
-    readonly autoGuessEncoding: boolean;
-    /** Legacy code pages scored for the Top-3 preview. */
-    readonly supportedEncodings: readonly string[];
-}
-/** Defaults mirror the reference config: deterministic until the user opts in. */
-export declare const DEFAULT_ENCODING_CONFIG: EncodingConfig;
-/**
- * One file's encoding state, recorded after a governed read and inverted on save.
- * `version` is the file-version snapshot the read observed; a memo whose version
- * differs from the current one is stale and must not steer a write.
- */
-export interface EncodingState {
-    readonly encoding: string;
-    readonly hasBOM: boolean;
-    readonly lineEnding: LineEnding;
-    readonly version: string | undefined;
-}
-/** One Top-3 preview row: the guessed encoding, a sample of its decode, and its score. */
-export interface CandidatePreview {
-    readonly encoding: string;
-    readonly sample: string;
-    readonly score: number;
-}
-/** A successful admission. */
-export interface DecodeResult {
-    /** The decoded text, without a BOM character. */
-    readonly text: string;
-    /** The canonical encoding that was used. */
-    readonly encoding: string;
-    /** Whether the admitted bytes carried a BOM. */
-    readonly hasBOM: boolean;
-    /** The dominant line ending of the decoded text. */
-    readonly lineEnding: LineEnding;
-    /** Top-3 previews: always empty on a deterministic/BOM/hint admission. */
-    readonly candidates: CandidatePreview[];
-    /** Auto-guess notice appended to the read text (heuristic path only). */
-    readonly footer?: string;
-}
-/** Caller-supplied admission overrides. */
-export interface DecodeOptions {
-    /** Reopen-with-encoding: an explicit choice beats BOM and UTF-8 detection. */
-    encodingHint?: string;
-    /** Path used in model-facing diagnostics. */
-    displayPath?: string;
-}
-/** Inverse of {@link decodeForOpen}: bytes to write plus the state to record for them. */
-export interface SaveResult {
-    readonly bytes: Uint8Array;
-    readonly state: EncodingState;
-    /**
-     * True when a legacy code page could not represent the edited text and the
-     * bytes were written as UTF-8 instead. Callers must surface this on the
-     * model-facing channel; a silent degradation is data loss the model cannot
-     * see.
-     */
-    readonly degraded: boolean;
-}
-/** Caller-supplied save overrides. */
-export interface SaveOptions {
-    /** Re-encode to this encoding instead of the recorded state. */
-    encodingHint?: string;
-}
-/**
- * Canonicalize a case/separator-insensitive encoding name, or `undefined` when
- * the name is outside the closed vocabulary. `utf-8`/`UTF_8`/`utf8` all map to
- * `utf8`, so the model may spell the name however it read it elsewhere.
- */
-export declare function normalizeEncoding(input: string): string | undefined;
-/** Whether a name (after canonicalization) is in the closed vocabulary. */
-export declare function isSupportedEncoding(encoding: string): boolean;
-/** The detected BOM: the canonical encoding it announces and its byte width. */
-export interface BomInfo {
-    readonly encoding: string;
-    readonly bomLen: number;
-}
-/**
- * Sniff a leading BOM. The 4-byte UTF-32 BOMs are checked before the 2-byte
- * UTF-16 ones because a UTF-32 BOM starts with a parent UTF-16 BOM.
- */
-export declare function detectBom(bytes: Uint8Array): BomInfo | undefined;
-/** Whether the bytes are valid strict (fatal) UTF-8. */
-export declare function isValidUtf8(bytes: Uint8Array): boolean;
-/** Score one decode; negative scores mark decodes that are almost certainly wrong. */
-export declare function scoreText(text: string, encoding: string): number;
-/**
- * Two-axis Top-3 preview: decode under every allowlist entry, score the result,
- * sort descending, keep three. BOM handling belongs to the caller.
- */
-export declare function top3Candidates(bytes: Uint8Array, allowlist?: readonly string[]): CandidatePreview[];
-/**
- * Admit a raw byte buffer for a read. Pure: no IO and no memo writes; the caller
- * records the returned state with {@link recordEncodingState}.
- *
- * Order is fixed: an explicit hint wins for decoding (a BOM still wins for
- * `hasBOM`), BOM sniff always precedes strict UTF-8, and probabilistic decoding
- * runs only when the autoGuess gate is open. A failed admission throws
- * `E_UNSUPPORTED_FILE` carrying the Top-3 preview as its description.
- */
-export declare function decodeForOpen(bytes: Uint8Array, config?: EncodingConfig, options?: DecodeOptions): DecodeResult;
-/**
- * Inverse of {@link decodeForOpen}: restore the recorded line ending and BOM,
- * then encode to the recorded code page. A code page that cannot reproduce the
- * edited text degrades to UTF-8 (never lossy bytes); an explicit hint that
- * cannot be honored is a model-facing `E_BAD_PAYLOAD` refusal instead, because
- * silently overriding a choice the model made would drop data the model expects
- * to keep.
- */
-export declare function encodeForSave(content: string, existing: EncodingState | undefined, options?: SaveOptions): SaveResult;
-/**
- * Whether the core's UTF-8 read/write path handles this recorded state without
- * a host bridge. UTF-8 (with or without a BOM) is the only class the core can
- * read back verbatim: its loader strips/reattaches the BOM and restores line
- * endings itself. Every other recorded code page has to be staged as UTF-8 for
- * the core and re-encoded afterwards.
- */
-export declare function isUtf8Native(state: EncodingState): boolean;
-/**
- * The model-facing note for a save that had to degrade a legacy code page to
- * UTF-8 because the edited text is not representable in it. Phrased as a fact
- * plus the next action: the bytes on disk are now UTF-8 and future reads see
- * that, so a re-read re-syncs the encoding state.
- */
-export declare function lossyDegradeWarning(state: EncodingState): string;
-/**
- * The recorded state for a target, or `undefined` when absent or stale.
- * A stale entry is dropped here so a write can never invert a state the read
- * that recorded it no longer applies to.
- */
-export declare function encodingStateFor(targetKey: string, version: string | undefined): EncodingState | undefined;
-/** Record the state a read observed. */
-export declare function recordEncodingState(targetKey: string, state: EncodingState): void;
-/** Forget one target's state, or every target's when called without a key. */
-export declare function clearEncodingState(targetKey?: string): void;
-/** A stable version token for a `stat(2)` identity, or `undefined` when absent. */
-export declare function versionOfStat(stat: {
-    readonly size: number;
-    readonly mtimeMs: number;
-} | undefined): string | undefined;
-/** Build the state to record from an admission, bound to the version it observed. */
-export declare function stateFromDecode(result: DecodeResult, version: string | undefined): EncodingState;

package/lib/types/dsh/tools/edit.d.ts

@@ -1,10 +0,0 @@
-import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
-import type { ToolDependencies } from "../contracts.js";
-/** dsh tool name; the agent-layer registration shadows the preset's built-in `edit`. */
-export declare const EDIT_TOOL_NAME = "edit";
-/**
- * Build the dsh `edit` tool for one agent install.
- * @param deps - the host seams this tool may touch; `sandbox` advertises and resolves escalation.
- * @returns a registry-ready dsh tool definition named `edit`.
- */
-export declare function buildEditTool(deps: ToolDependencies): ToolDefinition;

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,124 +0,0 @@
-import { Type } from "typebox";
-import type { EditPlacement } from "./hashline/resolve.js";
-declare const normalizedEdit: unique symbol;
-/**
- * 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;
-};
-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;
-};
-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]>>;
-    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]>>;
-        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 = "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). Use rows this session served for the file: `read`, a diff, or a bash view. `anchor_from`/`anchor_to` are bare 4-char HASH anchors. Copy the 4 chars before `\u2502` 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.";
-export declare const EDIT_SNIPPET = "Edit a file range via `edit`: `{\"file\":file,\"edits\":[{\"anchor_from\":a,\"anchor_to\":b,\"text\":text}]}` \u2014 anchors are bare 4-char hashes copied from served `HASH\u2502content` 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.";
-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 4-char hash (for example "wUpX"). A `HASH│content` line (for example `wUpX│    pass`) is a served row, and `│` separates the two. Copy only the 4 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 4-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). Use rows this session served for the file: `read`, a diff, or a bash view. `anchor_from`/`anchor_to` are bare 4-char HASH anchors. Copy the 4 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.