@grapecity-software/dsh-spreadjs-editor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh plugin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# @grapecity-software/dsh-spreadjs-editor
+
+[GitHub](https://github.com/GrapeCityXA/dsh-plugin-spreadjs-editor)
+
+在 DeepSeek Harness Web UI 里，直接在右侧文件树中打开、查看和编辑 Excel / SpreadJS 文件。
+
+A DeepSeek Harness Web UI plugin that opens, views, and edits Excel / SpreadJS files directly from the right-side file tree.
+
+---
+
+## 中文说明
+
+### 功能
+
+- 支持 `.xlsx`、`.xlsm`、`.csv`、`.sjs`、`.ssjson` 文件。
+- 基于 GrapeCity 官方 SpreadJS 和 SpreadJS Designer，提供完整的表格编辑能力。
+- 与 ui-all 文件树集成，打开文件后立即进入编辑界面，不需要单独的编辑器页面。
+- Designer 界面自动跟随系统 light/dark 偏好。
+
+### 快速开始
+
+DSH 的 Web profile 使用 pnpm 10，而 pnpm 10 默认会拦截依赖包的生命周期脚本。安装前先把本包加入放行列表。
+
+编辑 Web profile 的 `pnpm-workspace.yaml`，通常位于：
+
+```text
+~/.dsh/profiles/web/pnpm-workspace.yaml
+```
+
+加入以下内容：
+
+```yaml
+onlyBuiltDependencies:
+  - @grapecity-software/dsh-spreadjs-editor
+```
+
+然后安装插件并启动：
+
+```sh
+dsh plugin --profile web add @grapecity-software/dsh-spreadjs-editor
+dsh web
+```
+
+启动后，在 Web UI 右侧文件树中打开 `.xlsx`、`.xlsm`、`.csv`、`.sjs` 或 `.ssjson` 文件即可。
+
+安装阶段会自动生成 SpreadJS 客户端，不需要再执行 `npm install` 或 `npm run build`。
+
+如果使用 npx 运行 DSH，使用同样的命令：
+
+```sh
+npx --yes @deepseek-ai/dsh@latest plugin --profile web add @grapecity-software/dsh-spreadjs-editor
+npx --yes @deepseek-ai/dsh@latest web
+```
+
+DeepSeek Harness CLI 是 `@deepseek-ai/dsh`，不要使用同名 npm 包 `dsh`。
+
+如果插件已经装好、之后才补放行配置，补一次构建即可：
+
+```sh
+pnpm --dir ~/.dsh/profiles/web rebuild @grapecity-software/dsh-spreadjs-editor
+```
+
+### 常见问题
+
+**我已经有 ui-all，还需要额外安装什么吗？**
+
+不需要。ui-all 自带 `dsh-better-sidebar`，本插件会直接注册到它。
+
+**安装完还需要手动构建吗？**
+
+不需要。只要安装前放行过 `onlyBuiltDependencies`，`dsh plugin add` 会同时完成安装和构建。
+
+**SpreadJS 会跟随每次安装自动升级吗？**
+
+不会自动跨版本升级。所有 GrapeCity 官方包在 `package.json` 中锁定为同一版本；维护者会在发布新版时统一同步。
+
+### 配置
+
+正式部署时，在 profile 的 `cordis.patch.yml` 中配置 license key：
+
+| Key | 默认值 | 说明 |
+| --- | --- | --- |
+| `licenseKey` | `''` | SpreadJS + Designer 部署 license key。留空时使用 evaluation 构建。 |
+
+### 支持的文件
+
+| 文件 | 说明 |
+| --- | --- |
+| `.xlsx` / `.xlsm` | Excel 工作簿 |
+| `.csv` | CSV 文本 |
+| `.sjs` | SpreadJS 原生工作簿格式 |
+| `.ssjson` | SpreadJS JSON 工作簿 |
+
+### 从源码安装
+
+如果你需要从源码运行或参与开发：
+
+```sh
+git clone https://github.com/GrapeCityXA/dsh-plugin-spreadjs-editor.git
+
+cd dsh-plugin-spreadjs-editor
+npm install
+npm run build
+
+dsh plugin --profile web add ../dsh-plugin-spreadjs-editor
+```
+
+### 许可
+
+插件代码使用 MIT。SpreadJS 是 GrapeCity 的商业产品，正式部署时请配置真实 license key。
+
+### 维护者
+
+发布新版前，统一把所有 GrapeCity 依赖同步到最新版本：
+
+```sh
+npm run grapecity:update -- --latest
+```
+
+---
+
+## English
+
+### Features
+
+- Opens `.xlsx`, `.xlsm`, `.csv`, `.sjs`, and `.ssjson` files.
+- Built on GrapeCity's official SpreadJS and SpreadJS Designer for full spreadsheet editing.
+- Integrated with the ui-all file tree: open a file and start editing immediately, with no separate editor page.
+- The Designer follows the OS light/dark preference.
+
+### Quick Start
+
+DSH's Web profile uses pnpm 10, which blocks dependency lifecycle scripts by default. Allow this package before installing.
+
+Edit the Web profile's `pnpm-workspace.yaml`, usually:
+
+```text
+~/.dsh/profiles/web/pnpm-workspace.yaml
+```
+
+Add:
+
+```yaml
+onlyBuiltDependencies:
+  - @grapecity-software/dsh-spreadjs-editor
+```
+
+Then install the plugin and start DSH:
+
+```sh
+dsh plugin --profile web add @grapecity-software/dsh-spreadjs-editor
+dsh web
+```
+
+After startup, open `.xlsx`, `.xlsm`, `.csv`, `.sjs`, or `.ssjson` from the right-side file tree.
+
+The SpreadJS client is generated automatically during install. There is no need to run `npm install` or `npm run build` separately.
+
+If you run DSH through npx, use the same commands:
+
+```sh
+npx --yes @deepseek-ai/dsh@latest plugin --profile web add @grapecity-software/dsh-spreadjs-editor
+npx --yes @deepseek-ai/dsh@latest web
+```
+
+Use `@deepseek-ai/dsh`; the unrelated npm package `dsh` is not the DeepSeek Harness CLI.
+
+If the plugin was already installed before the allow-list entry was added, run the build once:
+
+```sh
+pnpm --dir ~/.dsh/profiles/web rebuild @grapecity-software/dsh-spreadjs-editor
+```
+
+### FAQ
+
+**I already have ui-all. Do I need to install anything else?**
+
+No. ui-all bundles `dsh-better-sidebar`, and this plugin registers directly with it.
+
+**Do I need to build manually after installation?**
+
+No. If `onlyBuiltDependencies` is configured before installing, `dsh plugin add` installs and builds in one step.
+
+**Will SpreadJS upgrade automatically with every install?**
+
+No. All GrapeCity packages are pinned to the same version in `package.json`; maintainers sync them together before a new release.
+
+### Configuration
+
+For production use, set the license key in the profile's `cordis.patch.yml`:
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `licenseKey` | `''` | SpreadJS + Designer deployment license key. Empty runs the evaluation build. |
+
+### Supported files
+
+| File | Description |
+| --- | --- |
+| `.xlsx` / `.xlsm` | Excel workbook |
+| `.csv` | CSV text |
+| `.sjs` | SpreadJS native workbook format |
+| `.ssjson` | SpreadJS JSON workbook |
+
+### Install from source
+
+To run from source or contribute:
+
+```sh
+git clone https://github.com/GrapeCityXA/dsh-plugin-spreadjs-editor.git
+
+cd dsh-plugin-spreadjs-editor
+npm install
+npm run build
+
+dsh plugin --profile web add ../dsh-plugin-spreadjs-editor
+```
+
+### License
+
+MIT for the plugin code. SpreadJS is a commercial product by GrapeCity; configure a real license key for production use.
+
+### Maintainers
+
+Before a new release, sync all GrapeCity dependencies to the latest version:
+
+```sh
+npm run grapecity:update -- --latest
+```

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# dsh-spreadjs-editor bundle patch
+#
+# One row activates the whole plugin: the Loader imports the package's node
+# half (lib/index.js, the /spreadjs license/config endpoint) and the
+# client-modules scan picks up the `dsh.client` declaration for the browser
+# half (lib/client.js, which registers the SpreadJS viewer into
+# dsh-better-sidebar).
+#
+# The row must run only under the Web composition (it injects the webServer
+# service); a headless profile should not mount this bundle. The browser half
+# has no hard client dependency: it waits for `dsh-better-sidebar`, which is
+# bundled by @linxin666/dsh-web-all (ui-all).
+
+- insert:
+    - id: spreadjs-editor
+      name: @grapecity-software/dsh-spreadjs-editor
+      inject: [webServer]
+      config:
+        # Optional: your SpreadJS license key. Empty (default) runs the
+        # evaluation watermark build. Keep it out of the patch if you prefer
+        # to configure it per-deployment.
+        licenseKey: ''

package/lib/index.js

@@ -0,0 +1,45 @@
+//#region src/index.ts
+const name = "dsh-spreadjs-editor";
+/** Required service: the web server whose route table this plugin extends. */
+const inject = ["webServer"];
+function sendJson(res, status, body) {
+	const data = JSON.stringify(body);
+	res.writeHead(status, {
+		"Content-Type": "application/json; charset=utf-8",
+		"Content-Length": Buffer.byteLength(data),
+		"Cache-Control": "no-store"
+	});
+	res.end(data);
+}
+function readPathname(req) {
+	return new URL(req.url ?? "/", "http://localhost").pathname;
+}
+function apply(ctx, config = {}) {
+	const disposer = ctx.webServer.register({
+		kind: "prefix",
+		path: "/spreadjs",
+		handler: (req, res) => {
+			try {
+				const pathname = readPathname(req);
+				if (pathname === "/spreadjs/api/health") {
+					sendJson(res, 200, { ok: true });
+					return;
+				}
+				if (pathname === "/spreadjs/api/config") {
+					sendJson(res, 200, { licenseKey: config.licenseKey ?? "" });
+					return;
+				}
+				sendJson(res, 404, { error: "unknown endpoint" });
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				if (!res.headersSent) sendJson(res, 500, { error: message });
+				else res.destroy();
+			}
+		}
+	});
+	ctx.effect(() => disposer, "dsh-spreadjs-editor: /spreadjs routes");
+}
+//#endregion
+export { apply, inject, name };
+
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@grapecity-software/dsh-spreadjs-editor",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness Web UI plugin: SpreadJS viewer registered through dsh-better-sidebar (ui-all).",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "webui",
+    "plugin",
+    "spreadjs",
+    "excel"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "src",
+    "scripts",
+    "tsdown.config.ts",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "grapecity:update": "node scripts/update-grapecity.mjs",
+    "postinstall": "node scripts/build.mjs",
+    "prepare": "node scripts/build.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "rebuild": "node scripts/build.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GrapeCityXA/dsh-plugin-spreadjs-editor.git"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": []
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-client-runtime": ">=0.1.1-rc.2",
+    "dsh-better-sidebar": ">=0.6.0",
+    "react": "^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "dsh-better-sidebar": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@grapecity-software/spread-excelio": "19.1.4",
+    "@grapecity-software/spread-sheets": "19.1.4",
+    "@grapecity-software/spread-sheets-io": "19.1.4",
+    "@grapecity-software/spread-sheets-resources-zh": "19.1.4",
+    "@grapecity-software/spread-sheets-designer": "19.1.4",
+    "@grapecity-software/spread-sheets-designer-resources-cn": "19.1.4",
+    "@grapecity-software/spread-sheets-shapes": "19.1.4",
+    "@grapecity-software/spread-sheets-charts": "19.1.4",
+    "@grapecity-software/spread-sheets-slicers": "19.1.4",
+    "@grapecity-software/spread-sheets-sparklines": "19.1.4",
+    "@grapecity-software/spread-sheets-print": "19.1.4",
+    "@grapecity-software/spread-sheets-pdf": "19.1.4",
+    "@grapecity-software/spread-sheets-barcode": "19.1.4",
+    "@grapecity-software/spread-sheets-formula-panel": "19.1.4",
+    "@grapecity-software/spread-sheets-pivot-addon": "19.1.4",
+    "@grapecity-software/spread-sheets-tablesheet": "19.1.4",
+    "@grapecity-software/spread-sheets-datacharts-addon": "19.1.4",
+    "@grapecity-software/spread-sheets-ganttsheet": "19.1.4",
+    "@grapecity-software/spread-sheets-reportsheet-addon": "19.1.4",
+    "@grapecity-software/spread-sheets-languagepackages": "19.1.4",
+    "tsdown": "^0.22.0",
+    "typescript": "^5.9.0",
+    "unrun": "^0.3.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "react": "^18.2.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "MIT"
+}

package/scripts/build.mjs

@@ -0,0 +1,31 @@
+/**
+ * Build entry. tsdown 0.22 uses `Promise.withResolvers` (ES2024), which is
+ * missing on Node 20; polyfill it here, then run the real tsdown CLI.
+ */
+if (typeof Promise.withResolvers !== 'function') {
+  Promise.withResolvers = function withResolvers() {
+    let resolve
+    let reject
+    const promise = new Promise((res, rej) => {
+      resolve = res
+      reject = rej
+    })
+    return { promise, resolve, reject }
+  }
+}
+
+// Resolve tsdown by package location so pnpm's isolated store layout works:
+// the dependency may live in a parent node_modules layer, and tsdown does not
+// export its dist/run.mjs entry through package exports.
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const require = createRequire(import.meta.url)
+const tsdownPackage = require.resolve('tsdown/package.json')
+
+// tsdown's default TS config loader hits a known Node.js bug when the config
+// lives under node_modules. unrun handles that path on Node 20-24.
+process.argv.push('--config-loader', 'unrun')
+
+await import(pathToFileURL(join(dirname(tsdownPackage), 'dist/run.mjs')).href)

package/scripts/smoke-client.mjs

@@ -0,0 +1,47 @@
+// Structural smoke check for the BUILT browser half (lib/client.js).
+//
+// A full runtime load (factory → apply → betterSidebar registration) requires a real
+// browser: SpreadJS touches DOM + canvas at module init, which jsdom cannot
+// satisfy without the native `canvas` package. That end-to-end load is left to
+// the harness browser (see README "Verification"). What we CAN assert here
+// without a browser is every structural contract of the artifact:
+//   - the __ModuleLoader__.load closure factory wrapper with the plugin id
+//   - the module-table externals stay require()'d (not inlined)
+//   - SpreadJS + its stylesheets are inlined (no @grapecity require remains)
+//   - the injected style strings are embedded
+import { readFileSync } from 'node:fs'
+
+const code = readFileSync(new URL('../lib/client.js', import.meta.url), 'utf8')
+
+let pass = 0
+let fail = 0
+function check(label, cond, detail = '') {
+  if (cond) {
+    pass++
+    console.log(`  ok  ${label}`)
+  } else {
+    fail++
+    console.log(`FAIL  ${label}${detail ? ` — ${detail}` : ''}`)
+  }
+}
+
+// The only non-SpreadJS runtime externals are React and its jsx-runtime.
+// @deepseek-ai/dsh-client-runtime/client is consumed type-only and erased.
+const EXTERNALS = [
+  'react',
+  'react/jsx-runtime',
+]
+
+check('loader wrapper opens with plugin id', /window\.__ModuleLoader__\.load\(\{\s*id: "dsh-spreadjs-editor"/.test(code))
+check('loader factory signature', /factory: \(require\) =>/.test(code))
+check('closure return (module.exports)', /return module\.exports;/.test(code))
+for (const ext of EXTERNALS) {
+  check(`external require("${ext}") present`, new RegExp(`require\\("${ext.replace(/[/.]/g, '\\$&')}"\\)`).test(code))
+}
+check('no @grapecity require remains (inlined)', !/require\("@grapecity/.test(code))
+check('spread-sheets css string embedded', code.includes('gc-spread-sheets'))
+check('designer css string embedded', /SpreadJS Designer Library \d+\.\d+\.\d+/.test(code))
+check('editor css string embedded', code.includes('.dsh-spreadjs-panel'))
+
+console.log(`\n${pass} passed, ${fail} failed`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/smoke-node.mjs

@@ -0,0 +1,88 @@
+// Smoke test for the BUILT node half (lib/index.js): load it exactly as the
+// harness loader would and drive the /spreadjs config/health handler with mock
+// req/res.
+import { Writable } from 'node:stream'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../lib/index.js')
+
+let pass = 0
+let fail = 0
+function check(label, cond, detail = '') {
+  if (cond) {
+    pass++
+    console.log(`  ok  ${label}`)
+  } else {
+    fail++
+    console.log(`FAIL  ${label}${detail ? ` — ${detail}` : ''}`)
+  }
+}
+
+// --- capture the handler like the harness would ---------------------------
+let handler
+const disposers = []
+const ctx = {
+  webServer: {
+    register(route) {
+      handler = route.handler
+      const d = () => {}
+      disposers.push(d)
+      return d
+    },
+  },
+  effect(fn) {
+    disposers.push(fn)
+  },
+}
+
+pkg.apply(ctx, { licenseKey: 'SMOKE-KEY' })
+check('registers /spreadjs route', handler !== undefined)
+check('registers effect disposers', disposers.length === 2)
+
+function makeRes() {
+  const chunks = []
+  const state = { status: 200, headers: {}, headersSent: false, body: '' }
+  const res = new Writable({
+    write(chunk, _e, cb) {
+      chunks.push(Buffer.from(chunk))
+      cb()
+    },
+  })
+  res.writeHead = (s, h) => {
+    state.status = s
+    if (h) state.headers = h
+    state.headersSent = true
+  }
+  Object.defineProperty(res, 'headersSent', { get: () => state.headersSent })
+  res.destroy = () => {}
+  return {
+    res,
+    finish: new Promise(r => res.on('finish', r)),
+    get state() {
+      state.body = Buffer.concat(chunks).toString()
+      return state
+    },
+  }
+}
+
+async function req(url) {
+  const r = makeRes()
+  await handler({ url }, r.res)
+  await r.finish
+  return r.state
+}
+
+// --- drive the endpoints ---------------------------------------------------
+let r = await req('/spreadjs/api/health')
+check('health -> 200', r.status === 200, `got ${r.status}`)
+check('health body', r.body === JSON.stringify({ ok: true }), r.body)
+
+r = await req('/spreadjs/api/config')
+check('config -> licenseKey', JSON.parse(r.body).licenseKey === 'SMOKE-KEY', r.body)
+
+r = await req('/spreadjs/api/unknown')
+check('unknown -> 404', r.status === 404, `got ${r.status}`)
+
+console.log(`\n${pass} passed, ${fail} failed`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/update-grapecity.mjs

@@ -0,0 +1,34 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url))
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+
+let version = process.argv[2]
+if (version === '--latest') {
+  const res = await fetch(
+    'https://registry.npmjs.org/@grapecity-software/spread-sheets/latest',
+  )
+  if (!res.ok) throw new Error(`npm registry returned ${res.status}`)
+  version = (await res.json()).version
+}
+
+if (!version) {
+  console.error('Usage: node scripts/update-grapecity.mjs <version> | --latest')
+  process.exit(1)
+}
+
+let changed = 0
+for (const [name, spec] of Object.entries(pkg.dependencies ?? {})) {
+  if (name.startsWith('@grapecity-software/') && spec !== version) {
+    pkg.dependencies[name] = version
+    changed += 1
+  }
+}
+
+if (changed === 0) {
+  console.log(`GrapeCity dependencies already at ${version}`)
+} else {
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
+  console.log(`Updated ${changed} GrapeCity dependencies to ${version}`)
+}

package/src/augment.ts

@@ -0,0 +1,11 @@
+/**
+ * Pull the harness packages' declaration merges into the TS program.
+ *
+ * The node half reads `ctx.webServer` from @deepseek-ai/dsh-host-webserver;
+ * the browser half imports `ClientContext` directly from
+ * @deepseek-ai/dsh-client-runtime/client. This module exists for the
+ * typechecker only and is never part of a bundle.
+ */
+import type {} from '@deepseek-ai/dsh-host-webserver'
+
+export {}