@xiaoso/dsh-tool-plus 0.1.6 → 0.1.7-beta.1

package/lib/types/tools/omp/edit/modes/patch.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Patch application logic for the edit tool.
+ *
+ * Applies parsed diff hunks to file content using fuzzy matching
+ * for robust handling of whitespace and formatting differences.
+ */
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { type WritethroughCallback } from "../../../omp/tools/writethrough.ts";
+import type { ToolSession } from "../../../omp/tools/index.ts";
+import type { EditToolDetails, Operation } from "../details";
+export interface PatchInput {
+    path: string;
+    op: Operation;
+    rename?: string;
+    diff?: string;
+}
+export interface FileSystem {
+    exists(path: string): Promise<boolean>;
+    read(path: string): Promise<string>;
+    readBinary?: (path: string) => Promise<Uint8Array>;
+    write(path: string, content: string): Promise<void>;
+    delete(path: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+}
+interface FileChange {
+    type: Operation;
+    path: string;
+    newPath?: string;
+    oldContent?: string;
+    newContent?: string;
+}
+export interface ApplyPatchResult {
+    change: FileChange;
+    warnings?: string[];
+}
+export interface ApplyPatchOptions {
+    cwd: string;
+    dryRun?: boolean;
+    fuzzyThreshold?: number;
+    allowFuzzy?: boolean;
+    fs?: FileSystem;
+    /**
+     * Permit `op: "create"` to replace an existing file (full-file overwrite).
+     * The JSON `patch` edit mode sanctions create-as-overwrite for major
+     * restructures (see prompts/tools/patch.md); the Codex `apply_patch`
+     * envelope documents `*** Add File` as strictly non-overwriting and must
+     * leave this unset.
+     */
+    allowCreateOverwrite?: boolean;
+}
+/** Default filesystem implementation using Bun APIs */
+export declare const defaultFileSystem: FileSystem;
+/**
+ * Apply a patch operation to the filesystem.
+ */
+export declare function applyPatch(input: PatchInput, options: ApplyPatchOptions): Promise<ApplyPatchResult>;
+/**
+ * Preview what changes a patch would make without applying it.
+ */
+export declare function previewPatch(input: PatchInput, options: ApplyPatchOptions): Promise<ApplyPatchResult>;
+export declare function computePatchDiff(input: PatchInput, cwd: string, options?: {
+    fuzzyThreshold?: number;
+    allowFuzzy?: boolean;
+    allowCreateOverwrite?: boolean;
+}): Promise<{
+    diff: string;
+    firstChangedLine: number | undefined;
+} | {
+    error: string;
+}>;
+export declare const patchEditEntrySchema: import("@oh-my-pi/omptype").FluentType<{
+    op?: "delete" | "create" | "update" | undefined;
+    rename?: string | undefined;
+    diff?: string | undefined;
+}, {
+    op?: "delete" | "create" | "update" | undefined;
+    rename?: string | undefined;
+    diff?: string | undefined;
+}>;
+export type PatchEditEntry = typeof patchEditEntrySchema.infer;
+export declare const patchEditSchema: import("@oh-my-pi/omptype").FluentType<{
+    path: string;
+    edits: {
+        op?: "delete" | "create" | "update" | undefined;
+        rename?: string | undefined;
+        diff?: string | undefined;
+    }[];
+}, {
+    path: string;
+    edits: {
+        op?: "delete" | "create" | "update" | undefined;
+        rename?: string | undefined;
+        diff?: string | undefined;
+    }[];
+}>;
+export type PatchParams = typeof patchEditSchema.infer;
+export interface ExecutePatchSingleOptions {
+    session: ToolSession;
+    path: string;
+    params: PatchEditEntry;
+    signal?: AbortSignal;
+    allowFuzzy: boolean;
+    fuzzyThreshold: number;
+    /** See {@link ApplyPatchOptions.allowCreateOverwrite}; set by the JSON `patch` mode only. */
+    allowCreateOverwrite?: boolean;
+    writethrough: WritethroughCallback;
+}
+export declare function executePatchSingle(options: ExecutePatchSingleOptions): Promise<AgentToolResult<EditToolDetails, typeof patchEditEntrySchema>>;
+export {};

package/lib/types/tools/omp/edit/modes/replace.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Fuzzy matching utilities for the edit tool.
+ *
+ * Provides both character-level and line-level fuzzy matching with progressive
+ * fallback strategies for finding text in files.
+ */
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { WritethroughCallback } from "../../../omp/tools/writethrough.ts";
+import type { ToolSession } from "../../../omp/tools/index.ts";
+import type { EditToolDetails } from "../details";
+export interface FuzzyMatch {
+    actualText: string;
+    startIndex: number;
+    startLine: number;
+    confidence: number;
+}
+export interface MatchOutcome {
+    match?: FuzzyMatch;
+    closest?: FuzzyMatch;
+    occurrences?: number;
+    occurrenceLines?: number[];
+    occurrencePreviews?: string[];
+    fuzzyMatches?: number;
+    dominantFuzzy?: boolean;
+}
+export type SequenceMatchStrategy = "exact" | "trim-trailing" | "trim" | "comment-prefix" | "unicode" | "prefix" | "substring" | "fuzzy" | "fuzzy-dominant" | "character";
+export interface SequenceSearchResult {
+    index: number | undefined;
+    confidence: number;
+    matchCount?: number;
+    matchIndices?: number[];
+    strategy?: SequenceMatchStrategy;
+}
+export type ContextMatchStrategy = "exact" | "trim" | "unicode" | "prefix" | "substring" | "fuzzy";
+export interface ContextLineResult {
+    index: number | undefined;
+    confidence: number;
+    matchCount?: number;
+    matchIndices?: number[];
+    strategy?: ContextMatchStrategy;
+}
+export declare class EditMatchError extends Error {
+    readonly path: string;
+    readonly searchText: string;
+    readonly closest: FuzzyMatch | undefined;
+    readonly options: {
+        allowFuzzy: boolean;
+        threshold: number;
+        fuzzyMatches?: number;
+    };
+    constructor(path: string, searchText: string, closest: FuzzyMatch | undefined, options: {
+        allowFuzzy: boolean;
+        threshold: number;
+        fuzzyMatches?: number;
+    });
+    static formatMessage(path: string, searchText: string, closest: FuzzyMatch | undefined, options: {
+        allowFuzzy: boolean;
+        threshold: number;
+        fuzzyMatches?: number;
+    }): string;
+}
+/** Default similarity threshold for fuzzy matching */
+export declare const DEFAULT_FUZZY_THRESHOLD = 0.95;
+/** Compute Levenshtein distance between two strings */
+export declare function levenshteinDistance(a: string, b: string): number;
+/** Compute similarity score between two strings (0 to 1) */
+export declare function similarity(a: string, b: string): number;
+/**
+ * Find a match for target text within content.
+ * Used primarily for replace-mode edits; excluded ranges remain invisible to exact and fuzzy matching.
+ */
+export declare function findMatch(content: string, target: string, options: {
+    allowFuzzy: boolean;
+    threshold?: number;
+    excludedRanges?: readonly {
+        startIndex: number;
+        endIndex: number;
+    }[];
+}): MatchOutcome;
+/**
+ * Find a sequence of pattern lines within content lines.
+ *
+ * Attempts matches with decreasing strictness:
+ * 1. Exact match
+ * 2. Trailing whitespace ignored
+ * 3. All whitespace trimmed
+ * 4. Unicode punctuation normalized
+ * 5. Prefix match (pattern is prefix of line)
+ * 6. Substring match (pattern is substring of line)
+ * 7. Fuzzy similarity match
+ *
+ * @param lines - The lines of the file content
+ * @param pattern - The lines to search for
+ * @param start - Starting index for the search
+ * @param eof - If true, prefer matching at end of file first
+ */
+export declare function seekSequence(lines: string[], pattern: string[], start: number, eof: boolean, options?: {
+    allowFuzzy?: boolean;
+}): SequenceSearchResult;
+export declare function findClosestSequenceMatch(lines: string[], pattern: string[], options?: {
+    start?: number;
+    eof?: boolean;
+}): {
+    index: number | undefined;
+    confidence: number;
+    strategy: SequenceMatchStrategy;
+};
+/**
+ * Find a context line in the file using progressive matching strategies.
+ *
+ * @param lines - The lines of the file content
+ * @param context - The context line to search for
+ * @param startFrom - Starting index for the search
+ */
+export declare function findContextLine(lines: string[], context: string, startFrom: number, options?: {
+    allowFuzzy?: boolean;
+    skipFunctionFallback?: boolean;
+}): ContextLineResult;
+export declare const replaceEditSchema: import("@oh-my-pi/omptype").FluentType<{
+    path: string;
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean | undefined;
+}, {
+    path: string;
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean | undefined;
+}>;
+export type ReplaceParams = typeof replaceEditSchema.infer;
+/**
+ * Internal batch form of {@link ReplaceParams}, produced only by the Cursor
+ * exec bridge: a `pi_edit` frame carries several replacements against one
+ * path but must run as a single tool lifecycle with one aggregate result.
+ * Never advertised to the model — the agent loop validates model calls
+ * against {@link replaceEditSchema}, which has no `edits` field.
+ */
+export interface ReplaceBatchParams {
+    path: string;
+    edits: Omit<ReplaceParams, "path">[];
+}
+export interface ExecuteReplaceOptions {
+    session: ToolSession;
+    path: string;
+    params: Omit<ReplaceParams, "path">;
+    signal?: AbortSignal;
+    allowFuzzy: boolean;
+    fuzzyThreshold: number;
+    writethrough: WritethroughCallback;
+}
+export declare function executeReplace(options: ExecuteReplaceOptions): Promise<AgentToolResult<EditToolDetails, ReplaceParams>>;

package/lib/types/tools/omp/edit/normalize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Text normalization utilities for the edit tool.
+ *
+ * Whitespace, Unicode, and indentation helpers. Line-ending and BOM
+ * primitives live in `@oh-my-pi/hashline` and are re-exported here so
+ * existing consumers see one stable surface.
+ */
+export { type BomResult, detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom, } from "@oh-my-pi/hashline";
+/** Count leading whitespace characters in a line */
+export declare function countLeadingWhitespace(line: string): number;
+/** Get the leading whitespace string from a line */
+export declare function getLeadingWhitespace(line: string): string;
+/** Compute minimum indentation of non-empty lines */
+export declare function minIndent(text: string): number;
+/** Detect the indentation character used in text (space or tab) */
+export declare function detectIndentChar(text: string): string;
+export declare function convertLeadingTabsToSpaces(text: string, spacesPerTab: number): string;
+export declare function normalizeUnicode(s: string): string;
+/**
+ * Normalize a line for fuzzy comparison.
+ * Trims, collapses whitespace, and normalizes punctuation.
+ */
+export declare function normalizeForFuzzy(line: string): string;
+/**
+ * Adjust newText indentation to match the indentation delta between
+ * what was provided (oldText) and what was actually matched (actualText).
+ *
+ * If oldText has 0 indent but actualText has 12 spaces, we add 12 spaces
+ * to each line in newText.
+ */
+export declare function adjustIndentation(oldText: string, actualText: string, newText: string): string;

package/lib/types/tools/omp/edit/notebook.d.ts

@@ -0,0 +1,50 @@
+export type NotebookCellType = "code" | "markdown" | "raw";
+export interface NotebookCell {
+    cell_type: NotebookCellType;
+    source?: string | string[];
+    metadata?: Record<string, unknown>;
+    execution_count?: number | null;
+    outputs?: unknown[];
+    [key: string]: unknown;
+}
+export interface NotebookDocument {
+    cells: NotebookCell[];
+    metadata: Record<string, unknown>;
+    nbformat: number;
+    nbformat_minor: number;
+    [key: string]: unknown;
+}
+export declare function isNotebookPath(filePath: string): boolean;
+export declare function splitNotebookSource(content: string): string[];
+export declare function readNotebookDocument(absolutePath: string, displayPath: string): Promise<NotebookDocument>;
+export declare function applyNotebookEditableText(notebook: NotebookDocument, text: string, displayPath: string): NotebookDocument;
+/**
+ * Decode a notebook for display and for hashline anchoring.
+ *
+ * The decode is the **engine's own codec** — `pi-natives`
+ * `notebookToEditableText`, the same call upstream's read tool makes
+ * (`refs/oh-my-pi/packages/coding-agent/src/tools/read.ts:1599`) — not a
+ * second TS implementation. That matters beyond tidiness: `read` mints the
+ * hashline tag over this projection and the edit engine validates the live
+ * file by projecting it the same way (`crates/pi-edit/src/files.rs:138-142`),
+ * so once both sides run the same code their agreement is structural. A
+ * hand-maintained copy can only *resemble* the engine, and the first
+ * divergence (BOM handling, cell escaping, cell join) silently turns every
+ * edit into "file changed between read and edit".
+ *
+ * Error text is identical to the previous TS decoder, verified over the whole
+ * corpus including BOM and every failure shape: the Rust `NotebookError`
+ * `Display` strings are verbatim ports. Only ENOENT is ours, because the read
+ * has to happen here to keep the `File not found: <display>` message the
+ * `read` tool and the patch/replace modes rely on.
+ *
+ * What stays in this file is the **encode** half (`readNotebookDocument` +
+ * `applyNotebookEditableText` + `serializeEditedNotebookText`), which
+ * `native/writer.ts` no longer uses — the engine serializes notebooks itself
+ * for the hashline path. It survives only because the native surface exposes
+ * no encoder and DSH's own patch/replace/write paths still need one; deleting
+ * it means migrating those modes onto the Rust engine (the same move this
+ * migration made for hashline), which is the remaining half of the work.
+ */
+export declare function readEditableNotebookText(absolutePath: string, displayPath: string): Promise<string>;
+export declare function serializeEditedNotebookText(absolutePath: string, displayPath: string, text: string): Promise<string>;

package/lib/types/tools/omp/edit/read-file.d.ts

@@ -0,0 +1,2 @@
+export declare function readEditFileText(absolutePath: string, path: string): Promise<string>;
+export declare function serializeEditFileText(absolutePath: string, path: string, content: string): Promise<string>;

package/lib/types/tools/omp/edit/snapshot-details.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Bound the size of the `oldText` / `newText` snapshots that edit-tool results
+ * carry in `details`. These fields hold the full pre/post file content; for
+ * large files they balloon the per-turn JSONL line and the session file
+ * (300 KB+ each on the cases reported in #3786) without paying for any LLM
+ * context (provider serializers send only `content`, never `details`).
+ *
+ * Only consumer of the raw snapshots is the ACP event mapper, which builds a
+ * `diff` ToolCallContent for ACP clients (Zed). When the snapshots are pruned
+ * the mapper returns `undefined` for that file and the text content still
+ * flows — diff visualization degrades gracefully for over-threshold edits.
+ */
+import type { EditToolDetails, EditToolPerFileResult } from "./details";
+/**
+ * Combined `oldText` + `newText` character budget for a single edit-tool
+ * result. Applies both per-entry (one file at a time) and as an aggregate
+ * across `perFileResults` (so a many-small-files batch can't accumulate
+ * unbounded snapshot bytes — see #3787 review).
+ *
+ * Picked so typical code-file edits keep ACP diff visualization while
+ * pathological cases (large generated files, full-file rewrites, or
+ * many-file batches) drop the raw snapshots before they hit the
+ * session JSONL.
+ */
+export declare const MAX_EDIT_SNAPSHOT_TEXT_CHARS = 32768;
+/**
+ * Prune oversized `oldText` / `newText` from an edit-tool details payload,
+ * recursing into `perFileResults` when present. Per-file overload comes first
+ * so the more specific shape (required `path`) wins overload resolution at
+ * the per-file call sites.
+ */
+export declare function pruneOversizedEditSnapshots(details: EditToolPerFileResult): EditToolPerFileResult;
+export declare function pruneOversizedEditSnapshots(details: EditToolDetails): EditToolDetails;

package/lib/types/tools/omp/extensibility/skills.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DSH adapter for OMP `extensibility/skills.ts` — the `Skill` type
+ * referenced by `tools/path-utils.ts` (skill:// resolution). DSH has no
+ * skill:// protocol; the type is provided verbatim so path-utils compiles.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    source: string;
+    /** When true, loaded but excluded from rendered <skills> listing. */
+    hide?: boolean;
+    /** Filesystem-resolved plugin root for Agent Plugin skills. */
+    containRoot?: string;
+    /** Source metadata for display */
+    _source?: {
+        provider: string;
+        kind?: string;
+        category?: string;
+    };
+}

package/lib/types/tools/omp/internal-urls/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * DSH adapter for OMP `internal-urls/` — the internal URL protocol system
+ * (agent://, memory://, skill://, local://, …).
+ *
+ * plan.md 判定：DSH 无 OMP 内部 URL 协议（read/write 不解析这些 scheme），
+ * 因此适配层仅提供 `path-utils` 引用的表面：
+ * - `LocalProtocolOptions`（verbatim 类型）
+ * - `InternalUrlRouter`（空路由：canHandle 恒 false —— DSH 没有可解析的
+ *   内部协议；engine 的调用方在 canHandle=false 时走普通路径解析）
+ */
+export interface LocalProtocolOptions {
+    getArtifactsDir?: () => string | null;
+    getSessionId?: () => string | null;
+}
+/** Raw resource payload shape (verbatim OMP, unused in DSH). */
+export interface InternalResource {
+    url: string;
+    content: string;
+    contentType: 'text/markdown' | 'application/json' | 'text/plain';
+    size?: number;
+    sourcePath?: string;
+    immutable?: boolean;
+    /** 目录形态标记（verbatim 引擎在 resolve 后读取；空路由永不产生）。 */
+    isDirectory?: boolean;
+}
+/** Resolve context passed to router handlers (verbatim OMP surface). */
+export interface ResolveContext {
+    cwd?: string;
+    signal?: AbortSignal;
+    localProtocolOptions?: LocalProtocolOptions;
+    pathOnly?: boolean;
+    settings?: unknown;
+    skills?: readonly unknown[];
+    /** Session-bound `xd://` documentation resolver. */
+    xd?: {
+        read: (name: string | null) => Promise<string>;
+    };
+}
+/** Write context passed to router write handlers (verbatim OMP surface). */
+export interface WriteContext {
+    cwd?: string;
+    signal?: AbortSignal;
+    localProtocolOptions?: LocalProtocolOptions;
+    /** Session-bound `xd://` device dispatcher. */
+    xd?: {
+        write(name: string | null, content: string): Promise<void>;
+    };
+}
+/** Internal URL shape (verbatim OMP minimal surface). */
+export interface InternalUrl {
+    scheme: string;
+    host: string;
+    pathname: string;
+    search?: string;
+    hash?: string;
+}
+/** Loose URL shape accepted by resolvers (parse.ts's InternalUrl extends URL). */
+type InternalUrlLike = {
+    protocol?: string;
+    host?: string;
+    pathname: string;
+    search?: string;
+    hash?: string;
+};
+/** Parse an internal URL into its parts (verbatim OMP semantics). */
+export declare function parseInternalUrl(input: string): InternalUrl;
+/** Minimal router: no internal protocol handlers are registered in DSH. */
+export declare class InternalUrlRouter {
+    #private;
+    static instance(): InternalUrlRouter;
+    canHandle(_url: string): boolean;
+    canResolve(_input: string): boolean;
+    /** Completion is part of the verbatim engine surface（grep.ts）；空路由恒无候选。 */
+    complete(_scheme: string, _query: string, _context?: ResolveContext): Promise<import('./types.ts').UrlCompletion[] | null>;
+    getHandler(_scheme: string): {
+        write?: (url: unknown, content: string, context?: unknown) => Promise<void>;
+    } | undefined;
+    resolve(_url: string, _context?: ResolveContext): Promise<InternalResource>;
+    write(_input: string, _content: string, _context?: WriteContext): Promise<void>;
+}
+/** DSH: no local:// sandbox — resolve to the raw path. */
+export declare function resolveLocalUrlToPath(input: string | InternalUrlLike, _options?: LocalProtocolOptions, _platform?: NodeJS.Platform): string;
+/** DSH: no memory root registry — empty. */
+export declare function memoryRootsFromRegistry(): string[];
+/** DSH: no memory:// backing — resolve to the raw path. */
+export declare function resolveMemoryUrlToPath(url: InternalUrl, _memoryRoot: string): string;
+/** DSH: no local:// sandbox — static handler with no options. */
+export declare class LocalProtocolHandler {
+    static resolveOptions(_context?: ResolveContext): LocalProtocolOptions | undefined;
+}
+/** DSH: no local:// sandbox — the local root is the cwd. */
+export declare function resolveLocalRoot(_options: LocalProtocolOptions, _platform?: NodeJS.Platform): string;
+/** DSH: no vault:// — resolve to the raw path. */
+export declare function resolveVaultUrlToPath(input: string | InternalUrlLike): string;
+/** DSH: no local:// file backing — resolve to nothing (caller falls back to text path). */
+export declare function resolveLocalUrlToFile(_input: string | InternalUrlLike, _context?: ResolveContext): Promise<{
+    path: string;
+    size: number;
+} | null>;
+export {};

package/lib/types/tools/omp/internal-urls/local-protocol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DSH adapter for OMP `internal-urls/local-protocol.ts`.
+ *
+ * plan.md 判定：DSH 无 local:// 内部协议（internal-urls 空路由
+ * canHandle 恒 false），local:// 解析实现整体删除；仅保留 verbatim 的
+ * `LocalProtocolOptions` 类型面，供 `internal-urls/types.ts` 与 grep 的
+ * verbatim grep.ts 类型引用。
+ */
+export interface LocalProtocolOptions {
+    getArtifactsDir?: () => string | null;
+    getSessionId?: () => string | null;
+}

package/lib/types/tools/omp/internal-urls/parse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Internal URL parser that handles colons in the host segment.
+ *
+ * Standard `new URL()` interprets colons as port separators, which breaks
+ * namespaced internal URLs like `skill://plugin:name`. This parser extracts
+ * components via regex first, then falls back to a minimal URL-like object
+ * when `new URL()` fails.
+ *
+ * All code that parses internal URLs (router, protocol handlers, tools)
+ * MUST use this function instead of calling `new URL()` directly.
+ */
+import type { InternalUrl } from "./types";
+/**
+ * Extract the lowercased scheme from a URI-shaped input, or `undefined` when
+ * the input does not look like a URI.
+ *
+ * Accepts both hierarchical (`scheme://…`) and opaque (`scheme:rest`) forms —
+ * MCP resource URIs may be opaque (`urn:example:document`, `custom:item`).
+ * The opaque form is guarded against path-like false positives:
+ * - Windows drive paths (`C:\…`, `C:/…`, `C:foo`) — single-letter scheme.
+ * - Filenames with extensions (`foo.ts:50`) — dot in the scheme segment.
+ * - Read-tool selector tails (`Makefile:12`, `README:raw:1-20`).
+ */
+export declare function extractUriScheme(input: string): string | undefined;
+/**
+ * Parse an internal URL into an InternalUrl.
+ *
+ * Handles URLs where `new URL()` would fail (e.g., `skill://plugin:name`
+ * where the colon is not a port separator).
+ */
+export declare function parseInternalUrl(input: string): InternalUrl;