@swoop111/dsh-tool-fs 0.2.0-rc.2 → 0.2.0-rc.2.1

package/lib/types/completion.d.ts

@@ -1,58 +1,58 @@
-/**
- * Window completion for reads: the neighbouring lines that give a delivered
- * window its structural boundaries. The head is the single line that opened
- * the construct the window starts inside; the tail is the run of following
- * lines that closes the construct the window ends inside. Neither ever
- * modifies, reorders, or drops a delivered line — a window either gains
- * context or stays exactly as the caller asked for it.
- *
- * The head is one line because everything between that opening line and the
- * window is the content the caller chose to skip; the tail is a run because
- * the construct cannot be called closed until its closer arrives.
- * @module @deepseek-ai/dsh-tool-fs/completion
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
 import type { FileTextLine } from './read-render.ts';
 import type { CompletionRule } from './structure.ts';
-/** Fetches up to `count` lines of the file on one side of the window, in file order. */
+ 
 export type LineSupplier = (count: number) => Promise<FileTextLine[] | undefined>;
-/** Where a completion fetches the lines on each side of the window. */
+ 
 export interface CompletionLineSuppliers {
-    /**
-     * The lines immediately before the window, in file order; the last entry is
-     * the window's predecessor line. `undefined` signals that no such line exists.
-     */
+    
+
+
+
     preceding: LineSupplier;
-    /**
-     * The lines immediately after the window, in file order; the first entry is
-     * the window's successor line. `undefined` signals end of file.
-     */
+    
+
+
+
     following: LineSupplier;
 }
-/** Configuration for window completion; the only field is a hard cap. */
+ 
 export interface CompletionTuning {
-    /**
-     * Maximum lines appended to close the tail, and how far back the head search
-     * may reach for the line that opened the construct.
-     */
+    
+
+
+
     maxLines: number;
 }
-/** The neighbouring lines a window gained, and the rules that found them. */
+ 
 export interface CompletionResult {
-    /** The line that opened the construct the window starts inside; empty when the window starts at a boundary. */
+     
     head: FileTextLine[];
-    /** The lines that close the construct the window ends inside; empty when the tail is balanced. */
+     
     tail: FileTextLine[];
-    /** The rule that produced `head`; absent when nothing was prepended. */
+     
     headRule?: CompletionRule;
-    /** The rule that produced `tail`; absent when nothing was appended. */
+     
     tailRule?: CompletionRule;
 }
-/**
- * Complete a window's structural boundaries.
- * @param lines - the delivered window lines, in file order.
- * @param supply - the line sources on each side of the window.
- * @param tuning - the hard caps for the added lines.
- * @returns the head and tail lines with the rules that produced them; `undefined` when neither side completes.
- */
+
+
+
+
+
+
+
 export declare function completeWindow(lines: readonly FileTextLine[], supply: CompletionLineSuppliers, tuning: CompletionTuning): Promise<CompletionResult | undefined>;
-//# sourceMappingURL=completion.d.ts.map
+ 

package/lib/types/diff.d.ts

@@ -1,41 +1,41 @@
-/**
- * Result-time contextual diff presentation for write and edit. Storage returns before/after
- * text; this model-facing layer derives one three-line-context card per applied hunk.
- * @module @deepseek-ai/dsh-tool-fs/src/diff
- */
+
+
+
+
+
 import type { FileDiff } from '@deepseek-ai/dsh-tools';
-/** Context lines shown on each side of an applied hunk. */
+ 
 export declare const DIFF_CONTEXT = 3;
-/**
- * The `write`/`edit` tools' private `tool/result` `meta` payload: the applied
- * contextual-diff hunks, and for `write` whether the call created or updated
- * the file, which tells an empty hunk list of a create from one of an
- * unchanged overwrite. Attached opaquely (as `unknown`) on the tool result and
- * persisted with the session log — it must be JSON-serializable (the session
- * validates this at `append`), so `presentResult` reproduces the diff card on
- * replay. The producing tool owns and narrows this opaque shape.
- */
+
+
+
+
+
+
+
+
+
 export type FsDiffMeta = {
     diffs: FileDiff[];
     operation?: 'create' | 'update';
 };
-/**
- * Compute one {@link FileDiff} per hunk between `before` and `after`, each carrying the
- * applied change plus {@link DIFF_CONTEXT} context lines. Pure insertions use `oldText: null`,
- * patch-only no-newline markers are omitted, and scattered replacements remain separate hunks.
- *
- * @param path - the path stamped on every produced diff (the model-facing `file_path`; the
- *   bridge relativizes it).
- * @param before - the file text before the change (the backend's LF-normalized diff basis).
- * @param after - the file text after the change, on the same basis.
- * @returns one diff per applied hunk, in file order; empty when the texts are identical.
- */
+
+
+
+
+
+
+
+
+
+
+
 export declare function computeHunkDiffs(path: string, before: string, after: string): FileDiff[];
-/**
- * Narrow opaque live or replayed result metadata to non-empty file diffs. Malformed metadata
- * returns `undefined` so presentation can fall back instead of throwing during replay.
- * @param meta - result metadata.
- * @returns validated hunks, or `undefined` for absent or malformed data.
- */
+
+
+
+
+
+
 export declare function diffsFromMeta(meta: unknown): FileDiff[] | undefined;
-//# sourceMappingURL=diff.d.ts.map
+ 

package/lib/types/edit.d.ts

@@ -1,73 +1,73 @@
-/**
- * Model-facing literal edit, unique-match by default. It obtains an optional guard from the
- * single intent slot, calls `ctx.fs.editText` without a separate stat, then records the observed
- * version; no policy means an unconditional atomic edit. When the literal match fails or is
- * ambiguous, the `@deepseek-ai/dsh-fs-edit-repair` engine re-anchors the pair before the error
- * reaches the model.
- * @module @deepseek-ai/dsh-tool-fs/src/edit
- */
+
+
+
+
+
+
+
+
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
 import type { FsSandboxController } from './sandbox.ts';
-/** Repair tuning for failed `edit` matches; rules live in `@deepseek-ai/dsh-fs-edit-repair`. */
+ 
 export interface EditRepairConfig {
-    /** Disable the repair engine so failed matches always error (default enabled). */
+     
     enabled?: boolean;
-    /** Content length above which the line-window repair rules are skipped. */
+     
     maxFileChars?: number;
-    /** `old_string` line count above which the line-window repair rules are skipped. */
+     
     maxWindowLines?: number;
 }
-/**
- * The edit repair tuning after defaulting, plus the session path-history
- * source for missing-target re-anchoring.
- */
+
+
+
+
 export interface EditRepairTuning {
-    /** Master switch: failed-match repair and missing-path re-anchoring. */
+     
     enabled: boolean;
-    /** Content length above which the line-window repair rules are skipped. */
+     
     maxFileChars: number;
-    /** `old_string` line count above which the line-window repair rules are skipped. */
+     
     maxWindowLines: number;
-    /**
-     * Absolute path arguments of the session's prior successful tool calls, most
-     * recent first — the missing-path re-anchor's history source.
-     */
+    
+
+
+
     priorPaths(session: Session | undefined, limit?: number): string[];
 }
-/** Validated `edit` arguments after defaulting. */
+ 
 interface EditInput {
     filePath: string;
     oldString: string;
     newString: string;
     replaceAll: boolean;
 }
-/**
- * Validate value constraints the schema DSL can't express: a non-blank
- * `file_path`, a non-empty `old_string`, and `old_string !== new_string`
- * (an equal pair would be a guaranteed no-op edit).
- * @param args - the schema-validated raw tool arguments.
- * @returns the camelCased input with `replace_all` defaulted to false.
- */
+
+
+
+
+
+
+
 export declare function parseEditArgs(args: {
     file_path: string;
     old_string: string;
     new_string: string;
     replace_all?: boolean;
 }): EditInput;
-/**
- * Format an edit success (single-match or replace-all) as a Claude-style model-facing message.
- * @param displayPath - the backend-resolved path shown to the model.
- * @param replaceAll - selects the all-occurrences wording over the single-replacement one.
- * @returns the confirmation sentence the model sees as the tool result.
- */
+
+
+
+
+
+
 export declare function formatEditOutput(displayPath: string, replaceAll: boolean): string;
-/**
- * Register the `edit` tool and its scope-aware system-prompt guidance.
- * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
- * @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
- * @param repair - the resolved tuning for the failed-match repair engine and missing-path re-anchoring.
- */
+
+
+
+
+
+
 export declare function applyEditTool(ctx: Context, sandbox: FsSandboxController, repair: EditRepairTuning): void;
 export {};
-//# sourceMappingURL=edit.d.ts.map
+ 

package/lib/types/error.d.ts

@@ -1,19 +1,19 @@
-/**
- * Model-facing diagnostics for guarded-mutation failures. Providers and
- * policies retain operation-specific causes, while this package owns the
- * stable message shown to the model.
- * @module @deepseek-ai/dsh-tool-fs/src/error
- */
-/**
- * Render the stable model-facing diagnostic for a guarded-mutation failure.
- * `FS_STALE_VERSION` keeps the provider's reason and appends its re-read
- * remedy. `FS_NOT_OBSERVED` replaces operation-specific policy/provider text
- * with one path-aware reason and read remedy. The original error remains the
- * cause, and both diagnostics preserve its code for machine routing. Anything
- * else passes through untouched.
- * @param error - the caught value from a write/edit execution.
- * @param displayPath - the resolved target path shown to the model.
- * @returns a remediated `FsError` for the two guarded-mutation codes, else the original value.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export declare function remediateFsError(error: unknown, displayPath: string): unknown;
-//# sourceMappingURL=error.d.ts.map
+ 

package/lib/types/index.d.ts

@@ -1,36 +1,36 @@
-/**
- * Model-facing read, read_image, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
- * read windows, formatting, and observation events, never a concrete provider. An optional
- * event policy supplies mutation guards; without one the tools use unconditional provider calls.
- * @module @deepseek-ai/dsh-tool-fs
- */
+
+
+
+
+
+
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { ReadRepairConfig } from './read.ts';
 import type { WriteRepairConfig } from './write.ts';
 import type { EditRepairConfig } from './edit.ts';
-/** Cordis plugin name used by loader diagnostics. */
+ 
 export declare const name = "tool-fs";
-/** Services required by the filesystem tool suite. */
+ 
 export declare const inject: string[];
-/** Plugin config (all optional — `Config` supplies the defaults). */
+ 
 export interface Config {
-    /** Default and maximum number of lines returned by one `read` call. */
+     
     readLimit?: number;
-    /** Maximum characters returned for a single line before truncation. */
+     
     readMaxLineLength?: number;
-    /** Maximum bytes returned for the selected lines of one `read` call. */
+     
     readMaxBytes?: number;
-    /** Files at or above this size stream instead of loading whole into memory. */
+     
     readStreamMinSize?: number;
-    /** Repair tuning applied when `edit`'s `old_string` fails to match verbatim (enabled by default). */
+     
     editRepair?: EditRepairConfig;
-    /** Repair tuning for the `read` tool's addressing and path failures (enabled by default). */
+     
     readRepair?: ReadRepairConfig;
-    /** Tuning for the `write` tool's drifted-path hint on creates (enabled by default). */
+     
     writeRepair?: WriteRepairConfig;
 }
 export declare const Config: z<Config>;
-/** Register the full `read`/`write`/`edit` filesystem tool suite, plus `read_image` while `attachments` is mounted. */
+ 
 export declare function apply(ctx: Context, config: Config): void;
-//# sourceMappingURL=index.d.ts.map
+ 

package/lib/types/read-image.d.ts

@@ -1,25 +1,25 @@
-/**
- * The model-facing `read_image` tool commits a PNG/JPEG/WebP/GIF file. A path
- * without a file extension is identified from its file signature, while the
- * attachment service's full decode stays authoritative. The mounted `ctx.fs`
- * backend owns path resolution and read access; names only declare media type.
- *
- * The route gate is deliberately stricter than the host upload preflight. An
- * image-reading tool is useful only when the exact calling route can inspect
- * its result, so unknown capability refuses instead of relying on an adapter
- * failure after filesystem and attachment work.
- * @module @deepseek-ai/dsh-tool-fs/src/read-image
- */
+
+
+
+
+
+
+
+
+
+
+
+
 import type { Context } from '@deepseek-ai/cordis';
 import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
 import type { ToolExecution } from '@deepseek-ai/dsh-tools';
-/**
- * Identify the media type declared by a supported image file signature.
- * @param data - file bytes read through the current filesystem backend.
- * @returns the detected supported media type, or undefined for other bytes.
- */
+
+
+
+
+
 export declare function sniffImageMediaType(data: Uint8Array): ImageMediaType | undefined;
-/** The structured outcome declared by the `read_image` output schema. */
+ 
 export interface ImageReadValue {
     path: string;
     image: {
@@ -29,52 +29,52 @@ export interface ImageReadValue {
         width: number;
         height: number;
         name?: string;
-        /** Orientation-applied file dimensions before normalization; present only when storage reduced it. */
+         
         originalDimensions?: {
             width: number;
             height: number;
         };
     };
 }
-/**
- * Map a model-supplied path to its declared image media type by extension.
- * @param filePath - the raw `file_path` argument (not yet resolved).
- * @returns the declared media type, or undefined when the path does not claim an image.
- */
+
+
+
+
+
 export declare function imageMediaTypeForPath(filePath: string): ImageMediaType | undefined;
-/**
- * Enforce the strict image-capability gate for the calling route. Resolves the
- * session's latest routed provider/model (request header config, then agent
- * options) and requires the exact resolved route to declare `image` input explicitly.
- * @param ctx - the plugin context used to resolve the optional `llm` service.
- * @param exec - the tool-execution context supplying the calling agent.
- * @param requestedPath - the raw, not-yet-resolved path rendered in refusal messages.
- */
+
+
+
+
+
+
+
+
 export declare function assertImageCapableRoute(ctx: Context, exec: ToolExecution, requestedPath: string): Promise<void>;
-/**
- * Re-brand a structured image outcome into the durable attachment reference an
- * `ImageBlock` carries.
- * @param image - the image metadata from the output schema.
- * @returns the branded attachment reference.
- */
+
+
+
+
+
+
 export declare function imageRefFromValue(image: ImageReadValue['image']): ImageAttachmentRef;
-/**
- * Format an image read as the model-facing envelope beside its image block.
- * A downscaled read names the on-disk dimensions and the multiplier that maps
- * coordinates measured on the attached image back onto the original file.
- * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
- * @param image - the image metadata to summarize.
- * @returns the model-facing envelope; the image itself rides the adjacent image block.
- */
+
+
+
+
+
+
+
+
 export declare function formatImageReadOutput(displayPath: string, image: ImageReadValue['image']): string;
-/**
- * Register the `read_image` tool into the given context. The composing plugin
- * owns the attachments gate: `src/index.ts` calls this inside
- * `ctx.inject(['attachments'], …)` so the tool exists only while a durable
- * store is mounted. Execution still re-checks `ctx.get('attachments')` for
- * direct callers and gates on the calling route's declared image input.
- * @param ctx - the registration scope; execution uses its `fs` service plus
- *   the optional `attachments`/`llm` services.
- */
+
+
+
+
+
+
+
+
+
 export declare function applyReadImageTool(ctx: Context): void;
-//# sourceMappingURL=read-image.d.ts.map
+