dsh-plugin-toolkit 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.1
+
+- Ship a composite GitHub Action (`action.yml`), so a plugin repository can run the same checks with `uses: WJDdidi-1/dsh-plugin-toolkit@v1`.
+
+## 0.1.0
+
+First cut: `doctor`, `index`, `release`.
+
+- `doctor` checks the manifest, the README's stated host range, the bundle patch, the client entry, and whether `files` ships everything `package.json` points at.
+- `index` audits `market/index.json` and names every version that cannot state a host range.
+- `release` runs preflight → tag → registry wait → index entry, prints every GitHub step, and refuses to run on a dirty tree or an existing tag.
+- Registry checks read the registry's own document (and `time`), because `npm view` answers from a cache.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 WJDdidi-1
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# dsh-plugin-toolkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A preflight and release tool for [DeepSeek Harness](https://github.com/deepseek-ai/dsh) plugins, plus the pieces of the publishing ritual that kept going wrong by hand.
+
+```
+npx dsh-plugin doctor .          # can this plugin be loaded and installed?
+npx dsh-plugin index             # does every market-index version state a host range?
+npx dsh-plugin release --dry-run # what would shipping this version do?
+```
+
+## Requirements
+
+- Node.js 18 or newer (`node --fetch` is used to read the registry; no dependencies)
+- Git and `gh` on `PATH` for the steps that touch GitHub
+- DeepSeek Harness `>=0.2.0` — the version whose market index carries `engines.dsh`, which is what makes the range check meaningful
+
+## Why this exists
+
+Releasing one plugin fifteen times taught me three things the ecosystem's tooling does not cover:
+
+1. **A version is not shipped when npm accepts it.** Registry propagation took two to eight minutes every time. `npm view` answered from a stale local cache, so I repeatedly believed a release had failed when it had not — and once believed it had succeeded when the market still could not see it.
+2. **The market index is a second release, done by hand.** Each version needs an entry carrying `publishTimestamp` from the registry and `engines.dsh` from the manifest. Forget the range and the index validator rejects the PR with `Engines mismatch` — after the tag is already public.
+3. **Reading a manifest is not the same as checking it.** A plugin can have a valid `package.json` and still be uninstallable: `files` that omit the entry the manifest points at, a bundle patch that does not exist, a README that never states the host range it declares.
+
+
+## Use it in CI
+
+The same checks run as a GitHub Action, so a tag cannot go out on a plugin that would not install:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: WJDdidi-1/dsh-plugin-toolkit@v1
+  with:
+    dir: plugin        # the folder holding the plugin's package.json
+```
+
+`command: index` audits `market/index.json` instead, and fails on any version that cannot state a host range.
+
+## What `doctor` checks
+
+| Check | Why it matters |
+| --- | --- |
+| `version` | The tag is built from it; a malformed version produces a tag nobody can install |
+| `engines.dsh` | The market index copies this into every version entry. Missing it fails the index PR |
+| `readme` | A `Requirements` section that states the declared range, so an install failure is predictable |
+| `dsh field` | `dsh.bundle.patch` must exist for the host to load the plugin |
+| `patch file` | The path declared above must be a real file |
+| `client entry` | If `dsh.client` is declared, the bundle has to be there |
+| `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files` |
+
+Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged.
+
+## What `release` does
+
+`release` runs the sequence in the order that fails cheapest first:
+
+1. Preflight (`doctor`) — stop before tagging anything.
+2. Refuse to run on a dirty tree, or if the tag already exists.
+3. Create and push the tag, which starts the plugin's release workflow.
+4. Poll the registry until it actually serves that version, reporting each wait.
+5. Write the index entry with the publish time **the registry reports**, not the local clock.
+6. Print the exact `git add` / `gh pr create` commands for the index change.
+
+Steps that touch your repository are printed, never guessed at. `--dry-run` prints the whole sequence with the commands it would run.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Done, or nothing to complain about |
+| 1 | A check failed, or the release stopped (the failing stage is named) |
+| 2 | Unknown command |
+
+## Looking at it without a Harness
+
+The fixtures under `test/fixtures/` are three tiny plugins — one good, one missing its host range, one whose README contradicts its manifest — and the tests run every check against them:
+
+```
+npm test
+```
+
+## Roadmap
+
+- `testkit`: load a single-file client bundle in a DOM with a fake host ctx, so panel behaviour can be asserted in CI instead of by hand.
+- `dev`: watch a client bundle and push it to a running app, instead of restarting the app for every change.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/bin/dsh-plugin.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from '../lib/cli.mjs';
+
+run(process.argv.slice(2)).then((code) => {
+  process.exitCode = typeof code === 'number' ? code : 0;
+}).catch((error) => {
+  console.error(`dsh-plugin: ${error.message}`);
+  if (process.env.DSH_PLUGIN_DEBUG === '1') console.error(error.stack);
+  process.exitCode = 1;
+});

package/lib/cli.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * `dsh-plugin <command>` — small enough to read in one sitting, which is the
+ * point: a release tool that hides what it does is worse than a checklist.
+ */
+import path from 'node:path';
+
+import { doctor } from './doctor.mjs';
+import { plan, release } from './release.mjs';
+import { auditVersions, readIndex } from './index-file.mjs';
+
+export const HELP = `dsh-plugin — preflight and release DeepSeek Harness plugins
+
+  dsh-plugin doctor [dir]            check the manifest, README and bundle
+  dsh-plugin release [dir] [flags]   tag, wait for npm, update the market index
+  dsh-plugin index [dir]             audit every version in market/index.json
+
+Flags
+  --dry-run                 show the steps without touching anything
+  --index <path>            index file, default market/index.json
+  --tag-prefix <prefix>     default plugin-v
+  --budget <seconds>        how long to wait for npm, default 480
+`;
+
+function flags(argv) {
+  const parsed = { positional: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--dry-run') parsed.dryRun = true;
+    else if (token === '--index') parsed.index = argv[++index];
+    else if (token === '--tag-prefix') parsed.tagPrefix = argv[++index];
+    else if (token === '--budget') parsed.budget = Number(argv[++index]);
+    else if (token.startsWith('--') === true) throw new Error(`unknown flag ${token}`);
+    else parsed.positional.push(token);
+  }
+  return parsed;
+}
+
+function printFailures(failures, io = console) {
+  for (const failure of failures) {
+    io.error(`  ✗ ${failure.check}: ${failure.message}`);
+  }
+}
+
+export async function run(argv, io = console) {
+  const [command, ...rest] = argv;
+  const options = flags(rest);
+  const dir = path.resolve(options.positional[0] ?? '.');
+
+  if (command === undefined || command === 'help' || command === '--help') {
+    io.log(HELP);
+    return 0;
+  }
+
+  if (command === 'doctor') {
+    const report = doctor(dir);
+    if (report.failures.length === 0) {
+      io.log(`ok  ${report.manifest.name}@${report.notes.version} (host ${report.notes.hostRange})`);
+      return 0;
+    }
+    io.error(`dsh-plugin doctor: ${report.failures.length} problem(s) in ${dir}`);
+    printFailures(report.failures, io);
+    return 1;
+  }
+
+  if (command === 'index') {
+    const target = options.index ?? (dir.endsWith('.json') === true ? dir : path.join(dir, 'market/index.json'));
+    const index = readIndex(target);
+    let problems = 0;
+    for (const plugin of index.plugins ?? []) {
+      const audit = auditVersions(index, plugin.name);
+      if (audit.length === 0) {
+        io.log(`ok  ${plugin.name}: ${plugin.versions.length} version(s) all carry engines.dsh`);
+        continue;
+      }
+      problems += audit.length;
+      io.error(`dsh-plugin index: ${plugin.name}`);
+      for (const finding of audit) {
+        io.error(`  ✗ ${finding.version ?? ''} ${finding.problem}`);
+      }
+    }
+    return problems === 0 ? 0 : 1;
+  }
+
+  if (command === 'release') {
+    const report = doctor(dir);
+    const name = report.manifest?.name ?? '(no name)';
+    const version = report.notes?.version ?? '(no version)';
+
+    if (options.dryRun === true) {
+      io.log(`dry run: ${name}@${version}`);
+      const planned = plan({ dir, version, name, tagPrefix: options.tagPrefix, indexFile: options.index });
+      for (const step of planned.steps) {
+        io.log(`  ${step.runs === false ? '·' : '→'} ${step.title}`);
+        io.log(`      ${step.command}`);
+      }
+      if (report.failures.length > 0) {
+        io.error('  the real run would stop at preflight:');
+        printFailures(report.failures, io);
+        return 1;
+      }
+      return 0;
+    }
+
+    const result = await release({
+      dir,
+      indexFile: options.index,
+      tagPrefix: options.tagPrefix,
+      budgetMs: options.budget === undefined ? undefined : options.budget * 1000,
+      onWait: ({ attempts, waitedMs }) => {
+        io.log(`  … ${name}@${version} not on the registry yet (${attempts} checks, ${Math.round(waitedMs / 1000)}s)`);
+      },
+    });
+
+    if (result.ok === false) {
+      io.error(`dsh-plugin release stopped at ${result.stage}`);
+      printFailures(result.failures, io);
+      return 1;
+    }
+
+    io.log(`tagged ${result.tag}, npm served ${name}@${version} after ${Math.round(result.waitedMs / 1000)}s`);
+    if (result.indexUpdate !== null) {
+      io.log(`updated ${result.indexUpdate.file} — commit it and open the PR:`);
+      io.log(`  git add ${result.indexUpdate.file} && git commit -m "market: ${version}" && gh pr create --fill`);
+    } else {
+      io.log('no market/index.json here, so only the tag and the publish happened');
+    }
+    return 0;
+  }
+
+  io.error(`unknown command "${command}"\n`);
+  io.error(HELP);
+  return 2;
+}

package/lib/doctor.mjs

@@ -0,0 +1,159 @@
+/**
+ * The checks a plugin has to pass before a release is worth starting.
+ *
+ * Every check answers a question that has actually gone wrong somewhere:
+ * a tag that did not match package.json, a market entry missing `engines`, a
+ * README that promised a host version the manifest did not require. Each one
+ * returns either null (fine) or a line a human can act on.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const RANGE = /^\s*[><=^~*]|\s*\|\||\s*-\s/;
+
+export function readManifest(dir) {
+  const manifestPath = path.join(dir, 'package.json');
+  if (fs.existsSync(manifestPath) === false) {
+    throw new Error(`no package.json in ${dir}`);
+  }
+  return { manifest: JSON.parse(fs.readFileSync(manifestPath, 'utf8')), manifestPath };
+}
+
+export function version(manifest) {
+  return typeof manifest.version === 'string' ? manifest.version : null;
+}
+
+/** The host range a version declares is the one the market index must repeat. */
+export function hostRange(manifest) {
+  const engines = manifest.engines;
+  if (engines === undefined || engines === null) return null;
+  const dsh = engines.dsh;
+  return typeof dsh === 'string' && dsh.trim() !== '' ? dsh.trim() : null;
+}
+
+export function checkVersion(manifest) {
+  const value = version(manifest);
+  if (value === null) return 'package.json has no version';
+  if (SEMVER.test(value) === false) return `version "${value}" is not semver`;
+  return null;
+}
+
+export function checkDshField(manifest) {
+  if (manifest.dsh === undefined || manifest.dsh === null) {
+    return 'package.json has no "dsh" field, so the host will not load it as a plugin';
+  }
+  const bundle = manifest.dsh.bundle;
+  if (bundle === undefined || bundle === null) {
+    return 'dsh.bundle is missing; the host needs the patch file it points at';
+  }
+  if (typeof bundle.patch === 'string' && bundle.patch !== '') {
+    return { patch: bundle.patch };
+  }
+  return 'dsh.bundle.patch is missing';
+}
+
+export function checkHostRange(manifest) {
+  const range = hostRange(manifest);
+  if (range === null) return 'engines.dsh is missing, so the market index cannot state the host requirement';
+  if (RANGE.test(range) === false) return `engines.dsh "${range}" is not a semver range`;
+  return null;
+}
+
+export function checkReadme(dir) {
+  const readmePath = path.join(dir, 'README.md');
+  if (fs.existsSync(readmePath) === false) return 'README.md is missing';
+  const text = fs.readFileSync(readmePath, 'utf8');
+  if (/^#{1,3}\s*Requirements/im.test(text) === false) {
+    return 'README.md has no Requirements section, so users cannot tell which host it needs';
+  }
+  const range = hostRange(JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')));
+  // ">= 0.2.0" and ">=0.2.0" are the same range; authors write both.
+  const squeeze = (value) => value.replace(/\s+/g, '');
+  if (range !== null && squeeze(text).includes(squeeze(range)) === false) {
+    return `README.md does not mention the host range "${range}" it declares`;
+  }
+  return null;
+}
+
+export function checkPatchFile(dir, manifest) {
+  const bundle = manifest.dsh?.bundle;
+  if (bundle === undefined || typeof bundle.patch !== 'string') return null;
+  const patchPath = path.join(dir, bundle.patch);
+  if (fs.existsSync(patchPath) === true) return null;
+  return `dsh.bundle.patch points at ${bundle.patch}, which does not exist`;
+}
+
+export function checkClientEntry(dir, manifest) {
+  const client = manifest.dsh?.client;
+  if (client === undefined || client === null) return null;
+  const entries = ['client.js', 'lib/client.js', 'dist/client.js'];
+  const found = entries.some((entry) => fs.existsSync(path.join(dir, entry)));
+  return found ? null : `dsh.client is declared but none of ${entries.join(', ')} exists`;
+}
+
+/** Every path the manifest points at: exports, the bundle patch, the client entry. */
+export function declaredPaths(manifest) {
+  const paths = new Set();
+  const add = (value) => {
+    if (typeof value !== 'string') return;
+    if (value.startsWith('./')) paths.add(value.slice(2));
+    else if (value.startsWith('.')) paths.add(value.slice(1));
+  };
+  const walk = (value) => {
+    if (typeof value === 'string') add(value);
+    else if (value !== null && typeof value === 'object') Object.values(value).forEach(walk);
+  };
+  walk(manifest.exports);
+  walk(manifest.dsh?.bundle?.patch);
+  walk(manifest.dsh?.client?.entry);
+  walk(manifest.main);
+  walk(manifest.types);
+  return [...paths];
+}
+
+/** A `files` entry covers a path when it is equal, a parent folder, or a glob prefix. */
+export function isShipped(target, files) {
+  return files.some((entry) => {
+    const clean = entry.replace(/^\//, '');
+    if (clean.includes('*') === true) {
+      const [head] = clean.split('*');
+      return head === '' || target.startsWith(head);
+    }
+    if (clean.endsWith('/') === true) return target.startsWith(clean);
+    return target === clean;
+  });
+}
+
+export function checkFilesList(manifest) {
+  const files = manifest.files;
+  if (Array.isArray(files) === false) {
+    return 'package.json has no "files" list, so the tarball ships whatever happens to be in the folder';
+  }
+  const declared = declaredPaths(manifest);
+  const missing = declared.filter((entry) => isShipped(entry, files) === false);
+  if (missing.length > 0) {
+    return `files does not ship ${missing.join(', ')}, which package.json points at, so the installed plugin would be missing its own code`;
+  }
+  return null;
+}
+
+/** Runs every check and returns `{ failures, notes }`. */
+export function doctor(dir) {
+  const { manifest } = readManifest(dir);
+  const checks = [
+    ['version', checkVersion(manifest)],
+    ['engines.dsh', checkHostRange(manifest)],
+    ['readme', checkReadme(dir)],
+    ['dsh field', checkDshField(manifest)],
+    ['patch file', checkPatchFile(dir, manifest)],
+    ['client entry', checkClientEntry(dir, manifest)],
+    ['files list', checkFilesList(manifest)],
+  ];
+  const failures = checks.filter(([, result]) => result !== null && typeof result === 'string');
+  return {
+    manifest,
+    failures: failures.map(([name, message]) => ({ check: name, message })),
+    notes: { hostRange: hostRange(manifest), version: version(manifest) },
+  };
+}

package/lib/index-file.mjs

@@ -0,0 +1,61 @@
+/**
+ * The market index is a list of versions with a host range per version.
+ * Adding an entry is small; getting it right is what broke a release before —
+ * a version object without `engines` makes the entry uninstallable, and the
+ * validator only tells you after you have already opened the PR.
+ */
+import fs from 'node:fs';
+
+export function readIndex(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function findPlugin(index, name) {
+  const plugins = Array.isArray(index.plugins) ? index.plugins : [];
+  return plugins.find((entry) => entry.name === name) ?? null;
+}
+
+/** The version objects the validator understands, newest first. */
+export function buildEntry({ version, publishTimestamp, hostRange }) {
+  const entry = {
+    version,
+    publishTimestamp,
+    source: { type: 'npm' },
+  };
+  if (hostRange !== null && hostRange !== undefined) {
+    entry.engines = { dsh: hostRange };
+  }
+  return entry;
+}
+
+export function addVersion(index, name, entry) {
+  const plugin = findPlugin(index, name);
+  if (plugin === null) {
+    throw new Error(`the index has no plugin called "${name}"`);
+  }
+  const versions = Array.isArray(plugin.versions) ? plugin.versions : [];
+  if (versions.some((existing) => existing.version === entry.version)) {
+    throw new Error(`${name}@${entry.version} is already in the index`);
+  }
+  return {
+    ...index,
+    plugins: index.plugins.map((candidate) => {
+      if (candidate.name !== name) return candidate;
+      return { ...candidate, versions: [entry, ...versions] };
+    }),
+  };
+}
+
+/** Every version must carry the host range, not just the newest one. */
+export function auditVersions(index, name) {
+  const plugin = findPlugin(index, name);
+  if (plugin === null) return [{ problem: `no plugin called "${name}"` }];
+  const versions = Array.isArray(plugin.versions) ? plugin.versions : [];
+  return versions
+    .filter((entry) => typeof entry.engines?.dsh !== 'string' || entry.engines.dsh.trim() === '')
+    .map((entry) => ({ version: entry.version, problem: 'no engines.dsh' }));
+}
+
+export function writeIndex(file, index) {
+  fs.writeFileSync(file, `${JSON.stringify(index, null, 2)}\n`);
+}

package/lib/registry.mjs

@@ -0,0 +1,64 @@
+/**
+ * Talking to npm without lying to yourself.
+ *
+ * `npm view` hits a local cache and can answer with a version that the registry
+ * is still not serving; the only honest question is "does the registry's own
+ * document list this version". That is what `versionsOf` asks, and the release
+ * command waits on it instead of on a sleep.
+ */
+export const REGISTRY = 'https://registry.npmjs.org';
+
+export async function packument(name, options = {}) {
+  const base = options.registry ?? REGISTRY;
+  const request = options.fetch ?? fetch;
+  const response = await request(`${base}/${name.replace('/', '%2F')}`, {
+    headers: { accept: 'application/vnd.npm.install-v1+json' },
+  });
+  if (response.status === 404) return null;
+  if (response.ok === false) {
+    throw new Error(`registry answered ${response.status} for ${name}`);
+  }
+  return response.json();
+}
+
+/** The publish time the index should carry, straight from the registry. */
+export function publishedAt(document, version) {
+  const time = document?.time?.[version];
+  if (typeof time !== 'string') return null;
+  const seconds = Math.floor(Date.parse(time) / 1000);
+  return Number.isFinite(seconds) ? seconds : null;
+}
+
+export function hasVersion(document, version) {
+  // `versions` is what an install sees; `time` is what a publish writes first.
+  // Either one means the registry is serving this version.
+  return Boolean(document?.versions?.[version]) || typeof document?.time?.[version] === 'string';
+}
+
+/**
+ * Polls until the version is visible or the budget runs out.
+ * `onWait` is called after each miss so the CLI can report progress.
+ */
+export async function waitForVersion(name, version, options = {}) {
+  const budgetMs = options.budgetMs ?? 8 * 60 * 1000;
+  const intervalMs = options.intervalMs ?? 10 * 1000;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const started = now();
+  let attempts = 0;
+
+  for (;;) {
+    attempts += 1;
+    const document = await packument(name, options);
+    if (hasVersion(document, version) === true) {
+      return { document, attempts, waitedMs: now() - started };
+    }
+    if (now() - started >= budgetMs) {
+      return { document, attempts, waitedMs: now() - started, timedOut: true };
+    }
+    if (typeof options.onWait === 'function') {
+      options.onWait({ attempts, waitedMs: now() - started, version });
+    }
+    await sleep(intervalMs);
+  }
+}

package/lib/release.mjs

@@ -0,0 +1,137 @@
+/**
+ * The release sequence, as a function instead of a checklist in my head.
+ *
+ * Order matters: verify the manifest first (cheap), then tag, then wait for the
+ * registry, then touch the index — the index entry carries the publish time the
+ * registry reported, so writing it earlier would mean guessing.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { doctor } from './doctor.mjs';
+import { addVersion, buildEntry, readIndex, writeIndex } from './index-file.mjs';
+import { publishedAt, waitForVersion } from './registry.mjs';
+
+function git(dir, args) {
+  return execFileSync('git', args, { cwd: dir, encoding: 'utf8' }).trim();
+}
+
+export function tagName(version, prefix = 'plugin-v') {
+  return `${prefix}${version}`;
+}
+
+export function tagExists(dir, tag) {
+  try {
+    git(dir, ['rev-parse', `refs/tags/${tag}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function workingTreeIsClean(dir) {
+  return git(dir, ['status', '--porcelain']) === '';
+}
+
+/**
+ * Steps a human must do, and steps the tool can do. Returning this list before
+ * anything runs is what makes `--dry-run` useful: it shows the whole sequence
+ * and the exact commands.
+ */
+export function plan({ dir = process.cwd(), version, name, tagPrefix = 'plugin-v', indexFile = 'market/index.json' }) {
+  const report = doctor(dir);
+  const resolvedName = name ?? report.manifest.name ?? 'this-plugin';
+  const resolvedVersion = version ?? report.manifest.version ?? '0.0.0';
+  const tag = tagName(resolvedVersion, tagPrefix);
+  const steps = [
+    { title: 'Read the manifest and check it can be loaded', command: 'dsh-plugin doctor', runs: true },
+    { title: `Create the tag ${tag}`, command: `git tag ${tag}`, runs: true },
+    { title: 'Push the tag, which starts the release workflow', command: `git push origin ${tag}`, runs: true },
+    { title: `Wait until the registry serves ${resolvedName}@${resolvedVersion}`, command: `GET /${resolvedName}`, runs: true },
+    { title: 'Write the version into the market index, with the publish time the registry reported', command: `patch ${indexFile}`, runs: true },
+    { title: 'Open the index pull request', command: 'gh pr create', runs: false },
+    { title: 'Re-read the live index and confirm the version is listed', command: 'GET market/index.json', runs: false },
+  ];
+  return { tag, name: resolvedName, version: resolvedVersion, indexFile, steps };
+}
+
+export async function release(options) {
+  const {
+    dir = process.cwd(),
+    registry,
+    tagPrefix = 'plugin-v',
+    indexFile = 'market/index.json',
+    budgetMs,
+    intervalMs,
+    sleep,
+    now,
+    onChange,
+  } = options;
+
+  const report = doctor(dir);
+  if (report.failures.length > 0) {
+    return { ok: false, stage: 'preflight', failures: report.failures };
+  }
+
+  const name = report.manifest.name;
+  const version = report.manifest.version;
+  const tag = tagName(version, tagPrefix);
+
+  if (tagExists(dir, tag) === true) {
+    return { ok: false, stage: 'tag', failures: [{ check: 'tag', message: `${tag} already exists` }] };
+  }
+  if (workingTreeIsClean(dir) === false) {
+    return {
+      ok: false,
+      stage: 'git',
+      failures: [{ check: 'git', message: 'the working tree has uncommitted changes' }],
+    };
+  }
+
+  git(dir, ['tag', tag]);
+  git(dir, ['push', 'origin', tag]);
+
+  const waited = await waitForVersion(name, version, {
+    registry,
+    budgetMs,
+    intervalMs,
+    sleep,
+    now,
+    onWait: options.onWait,
+  });
+  if (waited.timedOut === true) {
+    return {
+      ok: false,
+      stage: 'registry',
+      failures: [
+        {
+          check: 'registry',
+          message: `${name}@${version} is not on the registry after ${Math.round(waited.waitedMs / 1000)}s (tag ${tag} is pushed; re-run when npm catches up)`,
+        },
+      ],
+    };
+  }
+
+  const timestamp = publishedAt(waited.document, version);
+  const entry = buildEntry({ version, publishTimestamp: timestamp, hostRange: report.notes.hostRange });
+  const indexPath = path.join(dir, indexFile);
+  let indexUpdate = null;
+  if (fs.existsSync(indexPath) === true) {
+    const before = readIndex(indexPath);
+    const after = addVersion(before, name, entry);
+    writeIndex(indexPath, after);
+    indexUpdate = { file: indexFile, version, entry };
+    if (typeof onChange === 'function') onChange(indexUpdate);
+  }
+
+  return {
+    ok: true,
+    stage: 'index',
+    tag,
+    version,
+    attempts: waited.attempts,
+    waitedMs: waited.waitedMs,
+    indexUpdate,
+  };
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Preflight, release and test DeepSeek Harness plugins: checks what the host needs, waits for npm to actually serve the version, and keeps the market index honest.",
+  "type": "module",
+  "bin": {
+    "dsh-plugin": "bin/dsh-plugin.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "plugin-tooling",
+    "release",
+    "preflight"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WJDdidi-1/dsh-plugin-toolkit.git"
+  },
+  "homepage": "https://github.com/WJDdidi-1/dsh-plugin-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/WJDdidi-1/dsh-plugin-toolkit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "node --check bin/dsh-plugin.mjs"
+  }
+}