dsh-tool-docx 0.5.0

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `dsh-tool-docx`.
+* @module dsh-tool-docx/invariant
+*/
+const PACKAGE_NAME = "dsh-tool-docx";
+/** Cordis companion plugin name. */
+const name = "tool-docx-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the tools are model-facing consumers of the filesystem
+* seam; execution relations are owned by the seam they call.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/caps.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolved docx tool caps — plugin config after defaulting (see `Config` in
+ * index.ts), shared by all three tools.
+ * @module dsh-tool-docx/caps
+ */
+export interface DocxToolCaps {
+    /** Inclusive byte cap on a whole `.docx` file (read + ZIP expansion). */
+    maxDocxBytes: number;
+    /** Inclusive character cap on the markdown input to create/edit. */
+    maxMarkdownChars: number;
+    /** Inclusive character cap on the markdown returned by `docx_read`. */
+    maxReadChars: number;
+}
+//# sourceMappingURL=caps.d.ts.map

package/lib/types/docx/extract.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Extract a `.docx` package into Markdown and structured blocks: walks
+ * `word/document.xml` (paragraphs, runs, lists, tables, hyperlinks, images),
+ * resolves list numbering through `word/numbering.xml`, and reads document
+ * properties from `docProps/core.xml`. Pure — no I/O; callers supply the
+ * bounded package bytes.
+ * @module dsh-tool-docx/docx/extract
+ */
+import type { ExtractedDocx } from '../types.ts';
+/**
+ * Extract one `.docx` package into markdown + structured blocks.
+ * @param data - the whole package bytes (already bounded by the caller).
+ * @param maxUncompressedBytes - cap for the ZIP expansion.
+ * @returns the extraction result.
+ * @throws {@link DocxError} with a stable code for invalid/encrypted packages.
+ */
+export declare function extractDocx(data: Uint8Array, maxUncompressedBytes: number): Promise<ExtractedDocx>;
+//# sourceMappingURL=extract.d.ts.map

package/lib/types/docx/generate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generate a `.docx` package buffer from structured blocks using the `docx`
+ * library: headings, paragraphs with inline styling, nested bullet/numbered
+ * lists, pipe tables, and external hyperlinks. Document properties come from
+ * the caller (extracted from the previous version on an edit).
+ * @module dsh-tool-docx/docx/generate
+ */
+import type { Buffer } from 'node:buffer';
+import type { DocxBlock, DocxProps } from '../types.ts';
+/**
+ * Generate a `.docx` package buffer from blocks.
+ * @param blocks - the structured content to render.
+ * @param props - document properties to stamp (title/creator/created).
+ * @returns the packed `.docx` bytes.
+ */
+export declare function generateDocx(blocks: DocxBlock[], props: DocxProps): Promise<Buffer>;
+//# sourceMappingURL=generate.d.ts.map

package/lib/types/docx/zip.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal bounded ZIP reader over `yauzl`: extracts every entry of a docx
+ * package into a name в†’ bytes map. The uncompressed total is capped so a
+ * compressed bomb inside an already-bounded file cannot expand without limit.
+ * @module dsh-tool-docx/zip
+ */
+import { Buffer } from 'node:buffer';
+/** All entries of one ZIP archive, keyed by their archive names. */
+export type ZipEntries = Map<string, Buffer>;
+/**
+ * Read every file entry of a ZIP buffer into memory.
+ * @param data - the whole archive bytes (already bounded by the caller's read cap).
+ * @param maxUncompressedBytes - inclusive cap on the total uncompressed content.
+ * @returns archive-name в†’ content, directory entries omitted.
+ */
+export declare function readZip(data: Uint8Array, maxUncompressedBytes: number): Promise<ZipEntries>;
+//# sourceMappingURL=zip.d.ts.map

package/lib/types/error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed error vocabulary for the docx tools: a stable machine-routable code
+ * distinct from the human-readable message, plus the mapping from the
+ * filesystem seam's `FsError` codes.
+ * @module dsh-tool-docx/error
+ */
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+/** Stable, machine-routable failure classes raised by the docx tool suite. */
+export type DocxErrorCode = 'DOCX_NOT_FOUND' | 'DOCX_NOT_REGULAR_FILE' | 'DOCX_TOO_LARGE' | 'DOCX_INPUT_TOO_LARGE' | 'DOCX_LEGACY_DOC' | 'DOCX_NOT_DOCX' | 'DOCX_ENCRYPTED' | 'DOCX_PARSE_ERROR' | 'DOCX_EXISTS' | 'DOCX_STALE' | 'DOCX_SANDBOX_DENIED' | 'DOCX_WRITE_ERROR' | 'DOCX_HOST_FS_UNSUPPORTED';
+/** Typed docx failure. Extends {@link HarnessError} for a stable code and `cause` chaining. */
+export declare class DocxError extends HarnessError {
+    readonly code: DocxErrorCode;
+    constructor(message: string, code: DocxErrorCode, options?: ErrorOptions);
+}
+/** Map a filesystem-seam failure to the docx vocabulary; other errors pass through.
+ * @param error - the thrown filesystem error (or any other value).
+ * @returns the mapped `DocxError`, or the original value when it is not an `FsError`.
+ */
+export declare function mapFsError(error: unknown): unknown;
+//# sourceMappingURL=error.d.ts.map

package/lib/types/fs-binary-local-plugin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `fs-binary-local-plugin` — the mount for minimal hosts without a sandbox
+ * policy: a namespace plugin that registers the binary write primitive as the
+ * SEPARATE `fsBinary` service, unfenced, over the host's own `ctx.fs`. The
+ * host filesystem is left untouched. Sandboxed hosts should mount
+ * `fs-binary-sandbox-plugin` instead, which applies the policy fence.
+ * @module dsh-tool-docx/fs-binary-local-plugin
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "fs-binary-local";
+/** Services required: the host filesystem (reads/stat/resolve and the write body). */
+export declare const inject: string[];
+/**
+ * Register the `fsBinary` service: unfenced binary writes over `ctx.fs`.
+ * @param ctx - the plugin context; execution uses its `fs` service.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=fs-binary-local-plugin.d.ts.map

package/lib/types/fs-binary-local.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The plugin's own distribution of the harness's binary filesystem seam: a
+ * local `ctx.fs` provider that adds the `writeBytes` primitive to the
+ * published `@deepseek-ai/dsh-fs-local` backend. Mount this plugin as `ctx.fs`
+ * (in place of `dsh-fs-local`) on a host whose filesystem seam lacks
+ * `writeBytes`; the docx tools then run unchanged, with the same
+ * probe → intent-guard → atomic-publish flow the harness seam provides.
+ *
+ * For a sandboxed host (a `SandboxedFileSystem` mounted as `ctx.fs`), mount
+ * `dsh-tool-docx/fs-binary-sandbox` instead — it preserves the policy fence.
+ * @module dsh-tool-docx/fs-binary-local
+ */
+import type { FsInfo, FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs';
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local';
+import type { FsBytesWriteOutcome } from './fs-binary.ts';
+/**
+ * The probe → intent-guard → atomic-publish body shared by the plugin's binary
+ * fs providers: stat the target, enforce the version/absence intent
+ * (`FS_STALE_VERSION` / `FS_NOT_OBSERVED`), publish atomically, and report the
+ * fresh version.
+ * @param provider - the filesystem whose `stat` observes the target (the
+ * provider itself, after any sandbox fence has run).
+ * @param target - the (possibly fence-checked) target to write.
+ * @param data - the raw bytes to write.
+ * @param expected - the write intent guarding the write; omit for unconditional.
+ * @param signal - cancellation.
+ * @returns the create/update outcome with the fresh version.
+ */
+export declare function performByteWrite(provider: {
+    stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+}, target: FsTarget, data: Uint8Array, expected: FsWriteIntent | undefined, signal: AbortSignal | undefined): Promise<FsBytesWriteOutcome>;
+/**
+ * The local filesystem backend with the binary write primitive. Inherits the
+ * full published `LocalFileSystem` contract (text reads/writes, `readBytes`,
+ * intent handling) and adds `writeBytes`. Per-targetKey operations are
+ * serialized with a tail promise, mirroring the backend's own lock discipline.
+ */
+export declare class DocxBinaryFileSystem extends LocalFileSystem {
+    private readonly byteLocks;
+    private withByteLock;
+    /** Write raw bytes with an optional version/absence guard. */
+    writeBytes(target: FsTarget, data: Uint8Array, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsBytesWriteOutcome>;
+}
+export default DocxBinaryFileSystem;
+//# sourceMappingURL=fs-binary-local.d.ts.map

package/lib/types/fs-binary-sandbox-plugin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `fs-binary-sandbox-plugin` — the recommended mount for sandboxed hosts: a
+ * namespace plugin that registers the binary write primitive as the SEPARATE
+ * `fsBinary` service, fenced by the same per-call policy as the harness's
+ * `fs-sandbox` mutations. The host's own `ctx.fs` (and its `fs-sandbox` row)
+ * is left untouched, so this plugin can never break the host filesystem — at
+ * worst the docx write tools report `DOCX_HOST_FS_UNSUPPORTED` when it is not
+ * mounted.
+ * @module dsh-tool-docx/fs-binary-sandbox-plugin
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "fs-binary-sandbox";
+/** Services required: the host filesystem (reads/stat/resolve) and the policy. */
+export declare const inject: string[];
+/**
+ * Register the `fsBinary` service: fenced binary writes through the same
+ * containment the sandbox applies to every mutation.
+ * @param ctx - the plugin context; execution uses its `fs` and `sandboxPolicy`.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=fs-binary-sandbox-plugin.d.ts.map

package/lib/types/fs-binary-sandbox.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The sandbox-preserving binary fs provider: `DocxSandboxedFileSystem` extends
+ * the published `@deepseek-ai/dsh-fs-sandbox` `SandboxedFileSystem` and adds the
+ * binary `writeBytes` primitive through the SAME policy fence as the base's
+ * `writeText`/`editText`. The fence itself (`checkWriteTarget`) is shared with
+ * the `fs-binary-sandbox-plugin` namespace plugin, which registers it as the
+ * separate `fsBinary` service — the recommended mount for sandboxed hosts,
+ * because it never replaces the host's own `ctx.fs`.
+ * @module dsh-tool-docx/fs-binary-sandbox
+ */
+import { type FsTarget, type FsWriteIntent } from '@deepseek-ai/dsh-fs';
+import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox';
+import { type SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+import type { FsBytesWriteOutcome } from './fs-binary.ts';
+/**
+ * Enforce the per-call policy against `target` and return the exact target the
+ * mutation must use — the same containment the base `SandboxedFileSystem`
+ * applies to its mutations (`danger-full-access` passes unfenced, `read-only`
+ * denies, `workspace-write` re-canonicalizes now and requires containment under
+ * a writable root). Throws `FS_SANDBOX_DENIED` on refusal.
+ * @param resolveTarget - resolves a display path to a fresh canonical target
+ * (the provider's own `resolve`, so the checked identity is the mutated one).
+ * @param policy - the per-call mode and workspace root.
+ * @param target - the caller's resolved target.
+ * @returns the fresh target the mutation must use.
+ */
+export declare function checkWriteTarget(resolveTarget: (displayPath: string) => Promise<FsTarget>, policy: SandboxExecutionPolicy, target: FsTarget): Promise<FsTarget>;
+/**
+ * The sandboxed filesystem backend with the binary write primitive. Inherits
+ * the full `SandboxedFileSystem` contract (local text/binary reads, fenced
+ * `writeText`/`editText`) and adds fenced `writeBytes`: the per-call policy
+ * fence runs first (the same containment check the base applies to mutations),
+ * then the probe → intent-guard → atomic-publish body. Per-targetKey
+ * operations are serialized with a tail promise. Intended for hosts that want
+ * the full backend mounted AS `ctx.fs` (replacing `fs-sandbox` deliberately);
+ * the default mount for sandboxed hosts is the `fs-binary-sandbox-plugin`,
+ * which registers this same fenced write under the separate `fsBinary` service.
+ */
+export declare class DocxSandboxedFileSystem extends SandboxedFileSystem {
+    private readonly byteLocks;
+    private withByteLock;
+    /**
+     * Enforce the per-call policy against `target` and return the exact target
+     * the mutation must use, via the shared {@link checkWriteTarget}.
+     */
+    private checkedWriteTarget;
+    /** Write raw bytes with an optional version/absence guard, through the policy fence. */
+    writeBytes(target: FsTarget, data: Uint8Array, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsBytesWriteOutcome>;
+}
+export default DocxSandboxedFileSystem;
+//# sourceMappingURL=fs-binary-sandbox.d.ts.map

package/lib/types/fs-binary.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The binary filesystem contract the docx tools require.
+ *
+ * The plugin reads whole `.docx` packages through `readBytes` and writes them
+ * through `writeBytes`. `readBytes` is part of the published `@deepseek-ai/dsh-fs`
+ * contract since `0.1.0-rc.7`, so every conforming host provides it on `ctx.fs`.
+ * `writeBytes` is NOT part of any published `dsh-fs` release yet, so the plugin
+ * ships its own binary providers (`dsh-tool-docx/fs-binary-sandbox-plugin` for
+ * sandboxed hosts, `dsh-tool-docx/fs-binary-local-plugin` for minimal hosts)
+ * that register a SEPARATE `fsBinary` service — the host's `ctx.fs` is never
+ * replaced or modified. A host that natively gained `writeBytes` is used
+ * directly. This module declares the extended contract and resolves the writer
+ * at call time, so a host without any binary writer fails with a clear typed
+ * error instead of a cryptic `fs.writeBytes is not a function`.
+ * @module dsh-tool-docx/fs-binary
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { FileSystem, type FsTarget, type FsVersion, type FsWriteIntent } from '@deepseek-ai/dsh-fs';
+/** The outcome of a binary write, mirroring the host seam's `FsBytesWriteOutcome`. */
+export interface FsBytesWriteOutcome {
+    /** Whether the write created a new file or updated an existing one. */
+    operation: 'create' | 'update';
+    /** The new file version after the write. */
+    version: FsVersion;
+}
+/** The binary write surface the docx tools need, wherever it comes from. */
+export type FsBytesWriter = (target: FsTarget, data: Uint8Array, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: unknown) => Promise<FsBytesWriteOutcome>;
+/** A host filesystem that additionally provides the binary read/write primitives. */
+export declare abstract class BinaryFileSystem extends FileSystem {
+    /** Read the whole file as bytes, bounded by `maxBytes`. */
+    abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
+    /** Write raw bytes with an optional version/intent guard. */
+    abstract writeBytes(target: FsTarget, data: Uint8Array, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: unknown): Promise<FsBytesWriteOutcome>;
+}
+/** The service name the plugin's binary providers register under. */
+export declare const FS_BINARY_SERVICE = "fsBinary";
+/**
+ * Resolve the binary writer for this context: the plugin's `fsBinary` service
+ * when mounted, else a host `ctx.fs` that natively provides `writeBytes`.
+ * @param ctx - the plugin context; `fsBinary` is resolved optionally.
+ * @returns the bound writer, or `undefined` when no binary writer is mounted.
+ */
+export declare function resolveWriteBytes(ctx: Context): FsBytesWriter | undefined;
+/**
+ * Resolve the binary writer or fail with the typed host-requirement error.
+ * @param ctx - the plugin context.
+ * @returns the bound writer.
+ * @throws `DOCX_HOST_FS_UNSUPPORTED` when neither the `fsBinary` service nor a
+ *   native `ctx.fs.writeBytes` is available.
+ */
+export declare function requireWriteBytes(ctx: Context): FsBytesWriter;
+//# sourceMappingURL=fs-binary.d.ts.map

package/lib/types/fsio-bytes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal atomic binary write for the plugin's local filesystem provider.
+ * Mirrors the deepseek-harness `fs-local` `writeFileAtomic` semantics — a
+ * private owner-only staging directory, an exclusive temp file, fsync, then an
+ * atomic publish; a `createIfAbsent` publish uses a hard-link no-replace
+ * primitive so a concurrent creator wins (`FS_NOT_OBSERVED`) — for a
+ * `Uint8Array` payload. The Win32 DACL-preservation ceremony of the harness
+ * original is intentionally omitted in this first version (a replacement
+ * inherits the temp file's owner-only ACL).
+ * @module dsh-tool-docx/fsio-bytes
+ */
+/**
+ * Atomically write raw bytes to `absolutePath`: stage an owner-only temp file
+ * in a private sibling directory, fsync, then publish. With `createIfAbsent`,
+ * publish uses a hard link that fails if the target appeared concurrently
+ * (`FS_NOT_OBSERVED`); otherwise the temp is renamed over the target.
+ * @param absolutePath - destination path (typically a target key); missing
+ * parent directories are created.
+ * @param data - the raw bytes to write.
+ * @param signal - cancellation checked before and during the write.
+ * @param createIfAbsent - when provided, publish with the no-replace primitive
+ * and reject a concurrent creator with `FS_NOT_OBSERVED`.
+ */
+export declare function writeFileAtomicBytes(absolutePath: string, data: Uint8Array, signal: AbortSignal | undefined, createIfAbsent?: {
+    displayPath: string;
+}): Promise<void>;
+//# sourceMappingURL=fsio-bytes.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Model-facing Microsoft Word (.docx) tools: `docx_read` (docx → Markdown or
+ * structured JSON blocks), `docx_create` (Markdown → new docx), and
+ * `docx_edit` (round-trip Markdown replacement preserving document
+ * properties). Reading uses the bounded `ctx.fs.readBytes` primitive (part of
+ * the published filesystem contract since rc.7); creating and editing use a
+ * binary writer resolved at call time — the plugin's `fsBinary` service
+ * (`dsh-tool-docx/fs-binary-sandbox-plugin` / `fs-binary-local-plugin`) or a
+ * host `ctx.fs` that natively provides `writeBytes` — so the sandbox fence and
+ * observation policy apply to docx mutations exactly as they do to text
+ * writes, without ever replacing the host's own `ctx.fs`.
+ * @module dsh-tool-docx
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "tool-docx";
+/** Services required by the docx tool suite. */
+export declare const inject: string[];
+/** Plugin config (all optional — `Config` supplies the defaults). */
+export interface Config {
+    /** Inclusive byte cap on a whole `.docx` file (read + ZIP expansion). */
+    maxDocxBytes?: number;
+    /** Inclusive character cap on the markdown input to create/edit. */
+    maxMarkdownChars?: number;
+    /** Inclusive character cap on the markdown returned by `docx_read`. */
+    maxReadChars?: number;
+}
+export declare const Config: z<Config>;
+/** Register the full `docx_read`/`docx_create`/`docx_edit` tool suite. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `dsh-tool-docx`.
+ * @module dsh-tool-docx/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-docx-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/markdown.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Markdown в†’ block parsing for the docx generator: headings, paragraphs,
+ * nested lists, pipe tables, and inline formatting (`**bold**`, `*italic*`,
+ * `` `code` ``, `~~strike~~`, `[text](url)`). The supported subset is
+ * deliberately small and matches what {@link extractDocx} emits, so a
+ * read в†’ edit в†’ write round trip is stable. Unsupported constructs degrade to
+ * paragraphs with a warning instead of failing.
+ * @module dsh-tool-docx/markdown
+ */
+import type { DocxBlock } from './types.ts';
+/** One inline segment of a paragraph/heading/cell. */
+export interface InlineSegment {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+    strike?: boolean;
+    /** External link target when the segment came from `[text](url)`. */
+    link?: string;
+}
+/**
+ * Split inline text into styled segments. Bare asterisks, unterminated
+ * markers, and stray brackets stay literal text.
+ * @param text - inline markdown text (escapes from extraction are unescaped).
+ * @returns ordered segments; adjacent plain text is not merged.
+ */
+export declare function parseInline(text: string): InlineSegment[];
+/**
+ * Parse a markdown document into structured blocks.
+ * @param markdown - the markdown source (must fit the caller's input cap).
+ * @param warnings - receives human-readable notes about unsupported constructs.
+ * @returns the blocks the generator renders; an empty document yields `[]`.
+ */
+export declare function parseMarkdown(markdown: string, warnings: string[]): DocxBlock[];
+//# sourceMappingURL=markdown.d.ts.map

package/lib/types/path-contains.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Path-containment mechanics for the plugin's sandboxed filesystem provider —
+ * ported from the deepseek-harness `fs-sandbox` package (MIT, see LICENSE):
+ * the lexical fast path handles canonical spellings, and filesystem identity
+ * supplies the conservative fallback for alias-equivalent roots (Windows 8.3
+ * names, casing).
+ * @module dsh-tool-docx/path-contains
+ */
+/**
+ * Determine whether a canonical target is a writable root or lies beneath it.
+ * The lexical fast path handles normal canonical spellings; when spellings
+ * differ, walk the target's existing ancestors and compare filesystem identity
+ * with the root.
+ * @param path - canonical target key, which may end in a missing suffix.
+ * @param root - canonical writable root.
+ * @param caseSensitive - whether lexical comparison preserves case; defaults
+ * to the host filesystem convention used by supported platforms.
+ * @returns whether the target is the root or a descendant of it.
+ */
+export declare function isPathUnder(path: string, root: string, caseSensitive?: boolean): Promise<boolean>;
+//# sourceMappingURL=path-contains.d.ts.map

package/lib/types/sandbox.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The sandbox-escalation API for the mutating docx tools: per-call policy
+ * resolution, advertised escalation fields, and denial-marker mapping — the
+ * same pieces `dsh-tool-fs` uses, so docx mutations escalate identically to
+ * bash and fs. Built ONCE per plugin from `ctx.fs.sandboxMode`.
+ *
+ * This mirrors `packages/fs/tool-fs/src/sandbox.ts`; extracting a shared
+ * controller is deferred work (see the package README).
+ *
+ * @module dsh-tool-docx/sandbox
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+/** The two escalation arguments a mutating tool may carry. */
+export interface DocxEscalationArgs {
+    sandbox_permissions?: string;
+    justification?: string;
+}
+/** The schema fields spread into a mutating tool's `parameters` under a confining backend. */
+export interface EscalationSchemaFields {
+    sandbox_permissions: {
+        type: 'string';
+        enum: string[];
+        description: string;
+    };
+    justification: {
+        type: 'string';
+        description: string;
+    };
+}
+/** The docx escalation API: advertisement gating, policy resolution, and denial mapping. */
+export declare class DocxSandboxController {
+    private readonly ctx;
+    /** Escalation targets this composition advertises (`[]` when no confining backend is mounted). */
+    readonly escalationModes: readonly SandboxMode[];
+    private readonly policy;
+    constructor(ctx: Context);
+    /**
+     * The escalation schema fields for a mutating tool's `parameters` (confining backend only).
+     * @returns the two escalation parameter specs.
+     */
+    schemaFields(): EscalationSchemaFields;
+    /**
+     * The policy to stamp onto this mutation: an approved escalation grant, else
+     * the session's standing mode (with the session cwd as the workspace root).
+     * @param toolName - the mutating tool's name, for the approval audit trail.
+     * @param args - the call's escalation arguments.
+     * @param exec - the tool-execution context.
+     * @returns the policy for the mutation, or undefined for an unsandboxed backend.
+     */
+    resolvePolicy(toolName: string, args: DocxEscalationArgs, exec: ToolExecution): Promise<SandboxExecutionPolicy | undefined>;
+    /**
+     * Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes a
+     * `DocxError` carrying the shared `[sandbox: …]` marker plus the same-turn
+     * escalation hint (keeping the structured `DOCX_SANDBOX_DENIED` code).
+     * @param error - the error thrown by the mutation.
+     * @param policy - the policy stamped onto the call.
+     * @returns the error to throw.
+     */
+    mapError(error: unknown, policy: SandboxExecutionPolicy | undefined): unknown;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/lib/types/tool-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared helpers for the docx tools: path/extension validation, session-cwd
+ * resolution, observed-state emission, and common argument validation.
+ * @module dsh-tool-docx/tool-utils
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { FsTarget, FsVersion } from '@deepseek-ai/dsh-fs';
+/**
+ * Reject `.doc` with the legacy hint; everything else is parsed by content.
+ * @param path - the file path to check.
+ */
+export declare function assertSupportedExtension(path: string): void;
+/**
+ * Validate a non-empty file path; whitespace-only paths are rejected like the fs tool suite.
+ * @param path - the raw tool argument.
+ * @returns the same path, confirmed non-blank.
+ */
+export declare function requirePath(path: string): string;
+/**
+ * The calling agent's session cwd, or undefined for a non-agent caller.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the agent's session workspace cwd, or undefined.
+ */
+export declare function sessionCwd(exec: ToolExecution): string | undefined;
+/**
+ * Resolution options for the current call: session cwd + cancellation.
+ * @param exec - the tool-execution context supplying session cwd and cancellation.
+ * @returns provider resolution options for the current tool call.
+ */
+export declare function resolveOptions(exec: ToolExecution): {
+    cwd?: string;
+    signal?: AbortSignal;
+};
+/**
+ * Record an authoritative positive observation (no-op when no policy listens).
+ * @param ctx - the Cordis context the event is emitted on.
+ * @param target - the observed target.
+ * @param version - the observed file version.
+ * @param exec - the tool-execution context, carried as the event actor.
+ */
+export declare function emitObserved(ctx: Context, target: FsTarget, version: FsVersion, exec: ToolExecution): void;
+/**
+ * Record a confirmed-absent observation (no-op when no policy listens).
+ * @param ctx - the Cordis context the event is emitted on.
+ * @param target - the observed (absent) target.
+ * @param exec - the tool-execution context, carried as the event actor.
+ */
+export declare function emitAbsent(ctx: Context, target: FsTarget, exec: ToolExecution): void;
+/**
+ * Validate a positive-integer cap from config.
+ * @param name - the config field name, for the error message.
+ * @param value - the configured value to validate.
+ */
+export declare function assertPositiveInteger(name: string, value: number): void;
+//# sourceMappingURL=tool-utils.d.ts.map

package/lib/types/tools/create.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Model-facing `docx_create`: generate a new `.docx` file from Markdown.
+ * Guarded with `createIfAbsent` by default so an existing file is never
+ * blindly overwritten (the observation-policy waterfall may supply its own
+ * intent).
+ * @module dsh-tool-docx/tools/create
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { DocxToolCaps } from '../caps.ts';
+import { DocxSandboxController } from '../sandbox.ts';
+/**
+ * Register the `docx_create` tool.
+ * @param ctx - the plugin context; execution uses its `fs` service for
+ * resolution/reads and the `fsBinary` binary writer for the mutation.
+ * @param caps - the deployment's resolved caps.
+ * @param sandbox - the shared sandbox-escalation API.
+ */
+export declare function applyCreateTool(ctx: Context, caps: DocxToolCaps, sandbox: DocxSandboxController): void;
+//# sourceMappingURL=create.d.ts.map

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

@@ -0,0 +1,19 @@
+/**
+ * Model-facing `docx_edit`: replace a `.docx` document's content from
+ * Markdown, preserving its title/author/created properties. Reads the current
+ * file (validating it is a docx), regenerates the body, and writes back with a
+ * version guard so a concurrent change reports `DOCX_STALE`.
+ * @module dsh-tool-docx/tools/edit
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { DocxToolCaps } from '../caps.ts';
+import { DocxSandboxController } from '../sandbox.ts';
+/**
+ * Register the `docx_edit` tool.
+ * @param ctx - the plugin context; execution uses its `fs` service for
+ * resolution/reads and the `fsBinary` binary writer for the mutation.
+ * @param caps - the deployment's resolved caps.
+ * @param sandbox - the shared sandbox-escalation API.
+ */
+export declare function applyEditTool(ctx: Context, caps: DocxToolCaps, sandbox: DocxSandboxController): void;
+//# sourceMappingURL=edit.d.ts.map

package/lib/types/tools/read.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Model-facing `docx_read`: extract a `.docx` file as Markdown or structured
+ * JSON blocks. Bounded by the configured byte cap (whole file), the ZIP
+ * expansion cap, and the returned-markdown character cap.
+ * @module dsh-tool-docx/tools/read
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { DocxToolCaps } from '../caps.ts';
+/**
+ * Register the `docx_read` tool and its system-prompt guidance.
+ * @param ctx - the plugin context; execution uses its `fs` service (`readBytes`
+ * is part of the published filesystem contract since rc.7).
+ * @param caps - the deployment's resolved caps.
+ */
+export declare function applyReadTool(ctx: Context, caps: DocxToolCaps): void;
+//# sourceMappingURL=read.d.ts.map