dsh-office-tools 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * dsh-office-tools host plugin.
+ *
+ * Registers seven model-facing tools on `ctx.tools`:
+ *
+ *   word_create / word_read
+ *   excel_create / excel_read / excel_update
+ *   ppt_create / ppt_read
+ *
+ * All file access is confined to the calling agent's session workspace and
+ * every registration is wrapped in `ctx.effect` so Cordis disposes the tools
+ * with the plugin fiber.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Plugin identity for cordis.yml rows. */
+export declare const name = "dsh-office-tools";
+/** The tool registry is the only runtime service this plugin requires. */
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/types/paths.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Workspace-confined path resolution and durable-write helpers shared by all
+ * seven Office tools.
+ *
+ * Every tool binds to the CALLING agent's session cwd (the authoritative
+ * `session.header.cwd`) — the model never gets to pick a root. Relative paths
+ * resolve against that cwd, absolute paths are accepted only when they stay
+ * inside it, and a realpath check on the nearest existing ancestor closes the
+ * symlink escape hatch.
+ */
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+/** Hard cap for reading an existing Office file into memory. */
+export declare const MAX_OFFICE_FILE_BYTES: number;
+/** Cap for text materialized into a single tool result. */
+export declare const MAX_TEXT_CHARS = 200000;
+/** Cap for worksheet cells materialized into a single tool result. */
+export declare const MAX_READ_CELLS = 200000;
+/** Cap for worksheet cells accepted by one create/update call. */
+export declare const MAX_WRITE_CELLS = 200000;
+export interface ResolvedOfficePath {
+    /** The path exactly as the model passed it. */
+    input: string;
+    /** Absolute path used for every fs operation. */
+    absolute: string;
+    /** Path rendered back to the model (workspace-relative when possible). */
+    display: string;
+    /** Lowercased extension including the leading dot. */
+    ext: string;
+}
+/**
+ * Resolve one model-supplied path to a workspace-confined absolute file path.
+ *
+ * @param exec - the running tool call (carries the session cwd + abort signal).
+ * @param rawPath - the model-supplied path string.
+ * @param allowedExts - acceptable lowercased extensions WITH dots (e.g. `.docx`).
+ * @param mustExist - when true, stat the file and reject directories.
+ */
+export declare function resolveOfficePath(exec: ToolRunContext, rawPath: string, allowedExts: readonly string[], mustExist: boolean): Promise<ResolvedOfficePath>;
+/**
+ * Read a bounded Office file into memory, observing tool-call cancellation.
+ */
+export declare function readOfficeBuffer(path: string, signal: AbortSignal): Promise<{
+    buffer: Buffer;
+    sizeBytes: number;
+}>;
+/**
+ * Write a buffer through a same-directory temp file + rename so a failed
+ * generation never leaves a half-written Office document behind.
+ */
+export declare function atomicWriteFile(path: string, buffer: Buffer): Promise<number>;
+/**
+ * Reject an overwrite when `overwrite` is false and the target already exists.
+ * Callers use this BEFORE doing expensive generation so the model gets a fast
+ * refusal instead of wasted work.
+ */
+export declare function assertMayCreate(path: string, overwrite: boolean): Promise<void>;

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

@@ -0,0 +1,8 @@
+/**
+ * Excel (.xlsx) tools over SheetJS: `excel_create` writes a new workbook,
+ * `excel_read` materializes sheets as rows of scalar cells, and
+ * `excel_update` replaces/creates whole sheets and/or writes individual cell
+ * values into an existing workbook.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare function registerExcelTools(ctx: Context): () => void;

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

@@ -0,0 +1,8 @@
+/**
+ * PowerPoint (.pptx) tools: `ppt_create` builds slide decks with pptxgenjs
+ * (text, bullets, speaker notes, and PNG/JPG/GIF images); `ppt_read` unzips a
+ * deck with JSZip and extracts paragraph text, speaker notes, and per-slide
+ * image counts without any native dependency.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare function registerPptTools(ctx: Context): () => void;

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

@@ -0,0 +1,48 @@
+/**
+ * Shared schema fragments and cell types for the Office tool suite. Keeping
+ * the schemas in one place keeps the seven tool contracts consistent.
+ */
+/** One cell value accepted by the Excel tools. */
+export declare const CELL_VALUE_SCHEMA: {
+    readonly oneOf: readonly [{
+        readonly type: "string";
+    }, {
+        readonly type: "number";
+    }, {
+        readonly type: "boolean";
+    }, {
+        readonly type: "null";
+    }];
+};
+/** One spreadsheet row. */
+export declare const ROW_SCHEMA: {
+    readonly type: "array";
+    readonly items: {
+        readonly oneOf: readonly [{
+            readonly type: "string";
+        }, {
+            readonly type: "number";
+        }, {
+            readonly type: "boolean";
+        }, {
+            readonly type: "null";
+        }];
+    };
+};
+/** Common success echo for a created/replaced file. */
+export declare const FILE_RESULT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly sizeBytes: {
+            readonly type: "integer";
+            readonly required: true;
+        };
+    };
+};
+export type CellValue = string | number | boolean | null;
+export type CellRow = CellValue[];

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

@@ -0,0 +1,6 @@
+/**
+ * Word (.docx) tools: `word_create` builds a styled document with the `docx`
+ * package; `word_read` extracts plain text with `mammoth`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare function registerWordTools(ctx: Context): () => void;

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "dsh-office-tools",
+  "version": "0.1.0",
+  "description": "DSH model-facing Office tools: create, read, and update Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files inside the session workspace.",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "dsh.plugin.json",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run build"
+  },
+  "dependencies": {
+    "docx": "^9.5.1",
+    "jszip": "^3.10.1",
+    "mammoth": "^1.11.0",
+    "pptxgenjs": "^4.0.1",
+    "xlsx": "^0.18.5"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8"
+  },
+  "author": "kw78",
+  "homepage": "https://github.com/kw78/dsh-office-tools#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kw78/dsh-office-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kw78/dsh-office-tools/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "office",
+    "word",
+    "excel",
+    "powerpoint",
+    "docx",
+    "xlsx",
+    "pptx",
+    "tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@11.7.0"
+}