diff --git a/AGENTS.md b/AGENTS.md index ee74fe7..2662e23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,7 @@ This repository is the DeepSeek Harness port of pstack 0.15.43, pinned to https: - `.agents/skills//SKILL.md` holds every skill. DSH discovers this directory as a project skill root; `lib/index.js` serves the same tree when the package is installed as a profile bundle. - `lib/` is the bundle's skill provider. `lib/parse.js` is the pure frontmatter reader used by tests. - `cordis.patch.yml` inserts the `pstack` row into a profile. `package.json` declares the bundle through `dsh.bundle.patch`. +- `COMPATIBILITY.md` records the DSH metadata limits and the history of the icon regression. Read it before changing the package manifest, icon, locale, or detail document. - `docs/guide/` is the user guide. `docs/harness/dsh.md` maps the Cursor names the upstream content inherited. - `automations/benny/` is a dormant Slack triage and repro pack. It is not registered as a skill. @@ -18,6 +19,7 @@ This repository is the DeepSeek Harness port of pstack 0.15.43, pinned to https: - Do not reintroduce Cursor or Antigravity fields such as `subagent_type`, `environment`, `Workspace`, `TypeName`, `model` slugs, `~/.cursor`, or `~/.gemini`. - Route guidance lives in `~/.agents/pstack-models.md`. A missing file or line means `inherit`. Pass `provider`, `model`, and `reasoning_effort` only when the `subagent` tool exposes them. - DSH subagents share this machine. Isolate writers with a git worktree passed as `cwd`. +- When porting upstream, re-encode the icon instead of copying `assets/logo.png`. DSH rejects icons over 256 KiB. `COMPATIBILITY.md` records the limit and the measured pixel delta, and `npm test` enforces the limit. ## Validate @@ -26,4 +28,4 @@ npm install --omit=peer npm test ``` -`npm test` checks skill frontmatter, the poteto-mode principle and playbook indexes, relative Markdown links, the bundle manifest, and leftover Cursor/Antigravity tokens. CI also runs the shell and TypeScript script checks under `.agents/skills/poteto-mode/scripts`. The slow statechart integration suite runs in a separate scheduled job. +`npm test` checks skill frontmatter, the poteto-mode principle and playbook indexes, relative Markdown links, the bundle manifest, the plugin icon limits, and leftover Cursor/Antigravity tokens. CI also runs the shell and TypeScript script checks under `.agents/skills/poteto-mode/scripts`. The slow statechart integration suite runs in a separate scheduled job. diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000..3887e95 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,81 @@ +# DSH compatibility + +DeepSeek Harness reads a bundle's display metadata from package files before it evaluates any plugin code. A value that breaks a limit is reported in **Settings → Plugins** as a **Package metadata error**, for example: + +```text +Package metadata error: Plugin metadata for dsh-pstack: Error: /…/node_modules/dsh-pstack/package.json: icon exceeds 256 KiB +``` + +The skills still load, but the plugin row loses its icon and the profile reports a broken package. This file records the limits that produce that error, the rules that keep this repository inside them, and the history of the one time we crossed a limit. + +## Metadata limits + +| Surface | Limit | This bundle | +| --- | --- | --- | +| `package.json` `icon` | At most 262,144 bytes (256 KiB). SVG, PNG, JPEG, or WebP. A path relative to the package root that stays inside the package after resolving symlinks, and names a regular file. A manifest `icon` wins over an exported `./icon`. | [`assets/logo.webp`](./assets/logo.webp), 236,818 bytes, 512×512 WebP. See [Icon encoding](#icon-encoding). | +| Locale | `locale/en.json`; `meta.title` and `meta.description` must be non-empty strings. Other locale files use a language id as the filename. | Not exported. DSH falls back to `package.json` `name` and `description`. | +| Detail document | The file named by `meta.detail` is limited to `pluginManager.detailMaxBytes`, 1 MiB by default. | Not exported. DSH shows [README.md](./README.md). | +| Bundle patch | `dsh.bundle.patch` must name an existing file. The patch must insert a row whose `name` equals the package name. | `./cordis.patch.yml` inserts the `pstack` row. | +| Runtime | Node `^22.19.0 || >=24.0.0`; peers `@deepseek-ai/cordis@^4.0.1` and `@deepseek-ai/dsh-skill@^0.2.1-rc.2`. | DSH skips the whole bundle when its peers do not match the running runtime. See [README.md](./README.md#compatibility). | + +DSH measures the raw file bytes, not decoded pixels. A 512×512 image can pass or fail depending only on how it is encoded. The host limit is `MAX_ICON_BYTES = 256 * 1024` in the package metadata reader; the same reader rejects absolute paths, URLs, files outside the package, unsupported extensions, and non-regular files. + +## Rules for this repository + +- **Never copy the upstream icon byte-for-byte.** `cursor/plugins` ships `assets/logo.png` at 361,140 bytes (353 KiB), which DSH rejects. Re-encode it. Lossless PNG and lossless WebP of those pixels are still over 262,144 bytes. The shipped file is [`assets/logo.webp`](./assets/logo.webp). Its pixel delta is in [Icon encoding](#icon-encoding). +- **Keep the icon in `files`.** `npm pack` filters by the `files` list; the `assets` directory entry covers the icon. +- **Run the gate before opening a PR.** `npm test` fails when the declared icon is missing, outside the package, not SVG/PNG/JPEG/WebP, over 256 KiB, inconsistent with its extension's magic bytes, or absent from `files`. +- **Check the packed artifact when packaging changes.** `npm pack --dry-run` must list the icon, and a scratch profile install must render it without a metadata diagnostic. +- **Do not raise the limit.** The 256 KiB ceiling belongs to DSH, not this package. Shrink or re-encode the image instead. +- **Do not edit the installed copy by hand.** Fix the package, reinstall it into the profile, and restart the profile. + +## Icon encoding + +The upstream artwork is the 361,140-byte file at `71980e0` (`assets/logo.png`, 512×512, 8-bit RGB, 30,424 colors). DSH's limit is 262,144 raw bytes. These lossless encodings keep every RGB pixel and still miss that limit. + +| Encoder | Bytes | +| --- | --- | +| oxipng 9.1.5 `-o max --zopfli --zi 15` | 360,735 | +| zopflipng 1.0.3 `--iterations=15 --filters=0me` | 361,471, larger than the input, so the 361,140-byte file remains | +| cwebp 1.5.0 `-lossless -z 9 -metadata none` | 270,696 | +| cwebp 1.3.2 `-lossless -z 9 -metadata none`, and Pillow 10.2 lossless WebP | 275,910 | + +Pull request review 5934203113 measured a Pillow lossless WebP of this artwork at 270,552 bytes. That figure and the 270,696-byte cwebp 1.5.0 file are both above 262,144. Decoded pixels for every lossless row in the table match the upstream file. + +The shipped file is `assets/logo.webp`, 236,818 bytes, from libwebp 1.5.0. Regenerate it from the upstream bytes at `71980e0`: + +```bash +git show 71980e071d3fe27e4db538c74a16c6a0c3f9f04b:assets/logo.png > /tmp/upstream-logo.png +cwebp -near_lossless 99 -z 9 -metadata none /tmp/upstream-logo.png -o assets/logo.webp +``` + +`-near_lossless` moves some pixels by a small integer, then compresses the result losslessly. For this image, levels 80 through 99 emit the same bytes. Level 100 is the 270,696-byte lossless file. + +Compare RGB after decoding. An RGBA `ImageChops` bounding box stays empty when every alpha difference is 0, including when RGB differs. A changed pixel is one whose R, G, or B differs. Channel delta is the absolute difference in one channel. Channel-sum is those three differences added at one pixel. Alpha is counted on its own. `dwebp` from libwebp 1.5.0 and Pillow 10.2 decode this WebP to the same RGB pixels. + +| Asset | Bytes | Pixels changed | Max channel delta | Max channel-sum | Alpha delta | +| --- | --- | --- | --- | --- | --- | +| Upstream 8-bit RGB | 361,140 | 0 / 262,144 | 0 | 0 | 0 | +| Shipped WebP | 236,818 | 102,105 / 262,144 | 1 | 3 | 0 | +| `fbc1aae` palette PNG | 59,835 | 252,331 / 262,144 | 29 | 62 | 0 | + +The shipped WebP's absolute RGB channel differences sum to 176,315. Every changed pixel moves by 1 in one or more channels, and no channel moves by more than 1. The palette PNG is the previous 211-color stand-in. Its RGBA difference has no bounding box because the alpha difference is 0 everywhere, while the RGB difference covers the whole 512×512 image. + +Lossy WebP at `-q 100` fits in 95,282 bytes and is a worse picture. 251,832 pixels change, and the max channel delta is 86. + +## Why the regression happened + +- **2026-10-26, `fbc1aae`:** the original 361,140-byte icon was replaced with a 59,835-byte palette PNG. DSH accepted the bundle. That file is not the same artwork. The delta is in the table above. +- **2026-11-09, `e12d636` ("Fix portreview audit issues 16-27"):** audit issue #27 restored the upstream icon byte-for-byte to match `cursor/plugins` at `c742dd6`. That brought back the 361,140-byte file and produced the error in 0.15.43. +- **Fix:** ship the 236,818-byte WebP and gate `npm test` on the icon, so copying the upstream file back fails CI instead of failing at install time. Do not put the `fbc1aae` palette PNG back. + +## Recovering an installed profile + +A profile installed before the fix keeps the oversized icon in its own `node_modules`. Reinstall the bundle and restart the profile: + +```bash +dsh plugin --profile add github:pstack-ports/dsh-pstack +dsh --profile +``` + +Then confirm the pstack row in **Settings → Plugins** shows the logo and no red metadata error. diff --git a/README.md b/README.md index a944ba0..9f4a691 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,8 @@ two things that look like bugs but are not: - DSH reads `package.json` — `dsh.bundle.patch`, `icon`, and `engines.dsh` when present. it does not read `plugin.json`; that manifest is for other agent-plugin ecosystems. - the `@deepseek-ai/*` peers come from the DSH installation, not from this package, so install it with `dsh plugin add`. a standalone `npm install` will not resolve them. +the packaging limits that produce a **Package metadata error** — including the 256 KiB icon ceiling — are in [COMPATIBILITY.md](./COMPATIBILITY.md). + ## get started two steps: diff --git a/assets/logo.png b/assets/logo.png deleted file mode 100644 index 3754e87..0000000 Binary files a/assets/logo.png and /dev/null differ diff --git a/assets/logo.webp b/assets/logo.webp new file mode 100644 index 0000000..55ec8cb Binary files /dev/null and b/assets/logo.webp differ diff --git a/package.json b/package.json index 7634a5e..d4deab0 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "url": "git+https://github.com/pstack-ports/dsh-pstack.git" }, "license": "MIT", - "icon": "./assets/logo.png", + "icon": "./assets/logo.webp", "type": "module", "main": "lib/index.js", "exports": { @@ -29,6 +29,7 @@ "cordis.patch.yml", "plugin.json", "AGENTS.md", + "COMPATIBILITY.md", "README.md", "LICENSE" ], diff --git a/scripts/validate.mjs b/scripts/validate.mjs index 8a89b63..8389bb3 100644 --- a/scripts/validate.mjs +++ b/scripts/validate.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node -import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs' -import { dirname, join, relative, resolve, sep } from 'node:path' +import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs' +import { dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path' import process from 'node:process' import { fileURLToPath } from 'node:url' import { parse as parseYaml } from 'yaml' @@ -99,7 +99,7 @@ for (const field of ['name', 'version', 'description']) { if (manifest.dsh?.bundle?.patch !== './cordis.patch.yml') { fail('package.json must declare dsh.bundle.patch = ./cordis.patch.yml') } -for (const required of ['lib', '.agents', 'cordis.patch.yml', 'plugin.json', 'AGENTS.md', 'README.md', 'LICENSE']) { +for (const required of ['lib', '.agents', 'cordis.patch.yml', 'plugin.json', 'AGENTS.md', 'COMPATIBILITY.md', 'README.md', 'LICENSE']) { if (!(manifest.files ?? []).includes(required)) fail(`package.json files must include "${required}"`) } const plugin = JSON.parse(readFileSync(join(ROOT, 'plugin.json'), 'utf8')) @@ -123,6 +123,67 @@ else { } } +// 3b. The declared icon stays inside the DSH metadata limits. +// DSH reads package.json without evaluating the plugin; an oversized icon +// becomes "Package metadata error: ... icon exceeds 256 KiB" in the plugin row. +const MAX_ICON_BYTES = 256 * 1024 +const ICON_EXTENSIONS = new Set(['.svg', '.png', '.jpg', '.jpeg', '.webp']) + +function iconProblem(icon) { + if (typeof icon !== 'string' || icon.trim() === '') { + return 'package.json must declare a non-empty "icon" path so DSH can render the plugin row' + } + if (isAbsolute(icon) || win32.isAbsolute(icon) || /^[A-Za-z][A-Za-z\d+.-]*:/u.test(icon)) { + return `package.json icon "${icon}" must be a relative file path` + } + const declared = join(ROOT, icon) + if (!existsSync(declared)) return `package.json icon "${icon}" does not exist` + const file = realpathSync(declared) + const local = relative(realpathSync(ROOT), file) + if (local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) { + return `package.json icon "${icon}" must remain inside the package` + } + const extension = extname(file).toLowerCase() + if (!ICON_EXTENSIONS.has(extension)) { + return `package.json icon "${icon}" must be SVG, PNG, JPEG, or WebP` + } + const stat = statSync(file) + if (!stat.isFile()) return `package.json icon "${icon}" must be a regular file` + if (stat.size > MAX_ICON_BYTES) { + return `package.json icon "${icon}" is ${stat.size} bytes and exceeds 256 KiB (${MAX_ICON_BYTES} bytes); DSH will reject it. Re-encode the image.` + } + const bytes = readFileSync(file) + if (bytes.length > MAX_ICON_BYTES) { + return `package.json icon "${icon}" is ${bytes.length} bytes and exceeds 256 KiB (${MAX_ICON_BYTES} bytes); DSH will reject it. Re-encode the image.` + } + const head = bytes.subarray(0, 512) + const isJpeg = head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff + let valid = false + if (extension === '.png') { + valid = head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) + } else if (extension === '.jpg' || extension === '.jpeg') { + valid = isJpeg + } else if (extension === '.webp') { + valid = head.subarray(0, 4).toString('ascii') === 'RIFF' + && head.subarray(8, 12).toString('ascii') === 'WEBP' + } else { + valid = /]/u.test(bytes.toString('utf8')) + } + if (!valid) { + return `package.json icon "${icon}" does not contain ${extension.slice(1).toUpperCase()} data` + } + const packed = relative(ROOT, file).split(sep).join('/') + const covered = (manifest.files ?? []).some((entry) => { + const path = entry.replace(/^\.\//u, '').replace(/\/$/u, '') + return packed === path || packed.startsWith(`${path}/`) + }) + if (!covered) return `package.json files must include icon "${icon}"` + return undefined +} + +const iconFailure = iconProblem(manifest.icon) +if (iconFailure !== undefined) fail(iconFailure) + // 4. Relative Markdown links resolve. function checkLinks(file) { const raw = readFileSync(file, 'utf8') @@ -139,7 +200,7 @@ function checkLinks(file) { } } } -for (const file of [join(ROOT, 'README.md')]) checkLinks(file) +for (const file of [join(ROOT, 'README.md'), join(ROOT, 'COMPATIBILITY.md')]) checkLinks(file) walk(join(ROOT, 'docs'), (file) => { if (file.endsWith('.md')) checkLinks(file) }) @@ -180,4 +241,4 @@ if (problems.length > 0) { for (const problem of problems) console.error(`ERROR: ${problem}`) process.exit(1) } -console.log(`Validated ${candidates.length} skills, ${diskPlaybooks.size} playbooks, ${indexedPrinciples.size} principles, and the DSH bundle manifest.`) +console.log(`Validated ${candidates.length} skills, ${diskPlaybooks.size} playbooks, ${indexedPrinciples.size} principles, the DSH bundle manifest, and the plugin icon.`)