dsh-bundle-dedup-guard

dsh-bundle-dedup-guard

A DeepSeek Harness plugin that catches duplicate loader entry ids in profile bundle lists — on every plugin load.

If a profile's dsh.profile.bundles lists an aggregate bundle (a bundle whose patch inserts all of its sub-plugins, e.g. @linxin666/dsh-web-ui-all) and its sub-plugins individually, the loader receives the same loader-entry id twice. EntryGroup.update throws duplicate loader entry id: <id> before any plugin starts, and the whole profile fails to boot. This plugin exists so that never happens silently again.

---

Why this exists

Incident, 2026-08-18: a web profile listed @linxin666/dsh-web-ui-all (which aggregates 13 sub-plugins into one patch) and all 13 sub-plugins separately. Every sub-plugin id was inserted twice; the first collision reported was duplicate loader entry id: ui-dsh-aionui-panel. Fixing only the bundles list was not enough — the dsh plugin command's reconcilePlugins re-appends every dependencies entry that declares dsh.bundle to the bundle list after each pnpm operation, so the sub-plugins came back an hour later and crashed the next boot.

Full incident record: docs/KNOWN-ISSUE-bundle-duplicate.md.

How it works

The loader's failure path is: cordis-plugin-include's applyEntryPatches flattens every bundle's insert entries without deduplicating, then cordis-plugin-loader's EntryGroup.update dedups by id and throws on the first duplicate — before any plugin entry is created. This plugin re-implements exactly that "flatten + dedup by id" semantics in pure Node, and reports the offending ids, their sources (which bundle/patch inserted each), and the fix.

Checks on every plugin load

Trigger	When	Notes
Apply	every boot	instant health check as the plugin mounts
Loader events	loader/entry-init / loader/partial-dispose	runtime hot loads / plugin additions, debounced 800 ms
Manifest watch	fs.watch on the profile dir	the moment package.json or cordis.patch.yml changes — i.e. dsh plugin add, marketplace installs, or hand edits — warn immediately, before the next restart

What it reports

• Duplicate loader entry ids — each id inserted by more than one source, with the full source chain (e.g. ui-dsh-aionui-panel: @linxin666/dsh-web-ui-all ← @linxin666/dsh-client-ui-aionui-panel).
• Unresolved bundles — listed in bundles but not resolvable (the loader would loud-fail too).
• Bundle-less packages — listed but without a dsh.bundle.patch (a misconfiguration per the loader contract).
• Predictive reconcile warning — a dependencies entry that declares dsh.bundle but is not in bundles. dsh plugin's reconcile will append it on the next install/update; if it's a sub-plugin covered by an aggregate, that re-creates the crash. The warning names the covered ids. Fix: move such packages to devDependencies (reconcile only reads dependencies).

Reports are written to $DSH_HOME/dsh-bundle-dedup-guard/reports/<profile>-<timestamp>.json and <profile>.latest.json.

Known limitation

The loader deduplicates before creating any plugin entry, so when duplicates already exist at boot, an in-process check cannot run — the tree never mounts. For that case use the standalone CLI below: it is pure disk reads and works even when boot is broken.

Installation

As a profile bundle (recommended while in development):

1. Add to the profile's package.json dependencies:

   "dsh-bundle-dedup-guard": "link:F:/path/to/dsh-bundle-dedup-guard"
   

2. Add "dsh-bundle-dedup-guard" to dsh.profile.bundles (first entry is fine).
3. Link it into the profile's node_modules (pnpm does this for dsh plugin add).

From npm:

dsh plugin --profile web add dsh-bundle-dedup-guard

Usage

The plugin checks automatically — no interaction needed. For manual diagnosis (including when boot already crashed):

# check all profiles (DSH_HOME defaults to ~/.dsh)
node bin/check.mjs

# a specific profile
node bin/check.mjs --profile web

# a specific manifest file (e.g. a pre-fix backup, for testing)
node bin/check.mjs --manifest <path-to-package.json>

# machine-readable JSON, skip report files
node bin/check.mjs --profile web --json --no-write

Exit codes: 0 = healthy, 1 = duplicates / unresolved bundles / bundle-less packages found (useful as a CI gate).

Fixing duplicates

Edit dsh.profile.bundles so each id has exactly one source. The common shape is "aggregate + sub-plugins":

• keep the aggregate (e.g. @linxin666/dsh-web-ui-all)
• remove the individually listed sub-plugin entries
• also move the sub-plugins from dependencies to devDependencies — otherwise dsh plugin reconcile re-appends them on the next install/update (the exact recurrence from 2026-08-18)

Then re-run node bin/check.mjs --profile <name> until green, and restart.

Development

npm test          # node --test, zero dependencies
npm run check     # run the guard against your local profiles

• lib/check.mjs — the check core (pure Node, no third-party deps)
• index.mjs — the Cordis plugin entry (apply + listeners)
• bin/check.mjs — standalone CLI (works without a booted tree)
• test/ — unit tests with fixture profiles

License

MIT