@twinsearth/w2m-dsh-plugin 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -4,8 +4,70 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.5] — 2026-10-11
+
+### Fixed
+
+* **The v0.5.4 loader failure, with the cause the loader actually reported** rather than the hypothesis
+  that stood in for it:
+
+  ```
+  w2m (@twinsearth/w2m-dsh-plugin/tools): Error: cannot get property "connection" without inject
+    at registerTargetRoutes (src/plugin/fleet-target.mjs:483:25)
+  ```
+
+  cordis throws on reading a service property the fiber never declared, so the entry died and took all
+  eight tools with it. **Every existing test was blind to this**, because they drive the plugin with a
+  plain-object context where an undeclared read merely yields `undefined` — the fake was more forgiving
+  than the runtime. Fixed with `ctx.inject(['connection'], …)`, which is also the only shape that can
+  work: in the real composition the service is genuinely absent while `apply()` runs, and siblings are
+  mounted concurrently.
+* **The client half was never composed either, for a second and independent reason:** the bundle row
+  named the subpath `@twinsearth/w2m-dsh-plugin/tools` instead of the package, and a client package is
+  identified by its Loader row specifier — a subpath resolves to no `package.json`, so `dsh.client` was
+  never read and no boot-graph row was built. The row now names the package.
+* **A silent route rejection:** the control fetched `/w2m/target`, but fetch routes are validated
+  against `/api/`, and the refusal failed only a child fiber, so nothing surfaced. Now
+  `/api/w2m/target`, mirrored in the shipped bundle.
+
+### Added
+
+* **`test/loader-entry.test.mjs`** — the test that would have caught v0.5.4: it packs the tree, installs
+  the tarball with the installation's own `dsh plugin add` into a throwaway profile under a throwaway
+  `DSH_HOME`, and boots it with the real `runProfile` under the Harness runtime, asserting that the
+  entry activates, all eight tools are registered, the boot-graph row is composed from the shipped
+  bundle, and no failed entry names the package. **Proved in both directions**: 6/6 pass on the fixed
+  tree and 6/6 fail against the preserved v0.5.4 tarball, failing on precisely the loader error quoted
+  above. It skips loudly, naming the probes it tried, when no installation is found.
+* Cheap always-on guards in `test/client-bundle.test.mjs` that need no Harness: the platform field, the
+  client export, the row must be the bare package name, and the bundle's route must equal the host's.
+
+### Notes
+
+* **An upgrade from v0.5.4 requires one edit outside this package:** `cordis.patch.yml` in the profile
+  must name the package (`@twinsearth/w2m-dsh-plugin`), not the `/tools` subpath. With the corrected
+  bundle row, a mismatch makes the loader skip the whole patch — silently reverting `rabbitUrl`,
+  `operatorToken`, `stateDir`, `projectDir`, `machineName`, `p2pMode` and `allowedCommands` to their
+  shipped defaults. Measured both ways with `--dump-config`.
+* **0.5.4 remains DO NOT INSTALL.** This release exists so that a rebuilt artifact is distinguishable
+  from the broken one by version alone.
+* Still unverified, and not claimed: how the control *renders*. No browser was opened. What is proven is
+  the entire host side — the entry activates, the eight tools register, the boot-graph row is composed
+  from the shipped bundle, the route is registered and attached — plus the seat shape in a VM test.
 ## [0.5.4] — 2026-10-11
 
+> **DO NOT INSTALL 0.5.4.** It fails to load in the Harness: the loader entry
+> include:@twinsearth/w2m-dsh-plugin/tools reports iberPhase: failed, so **all eight tools
+> disappear** and the client half never registers. The package verifies in isolation
+> (scripts/verify-installed.mjs reports 8 tools registered) and its exports map is complete, so the
+> failure is in the real loader path -- the newly declared dsh.client half being composed there, with
+> lib/client.js being browser code that has no window under a host-side load. That cause is a
+> hypothesis, not a measurement; the loader's own error is still to be read. 0.5.5 fixes it and adds the
+> test that should have caught it: **load the packed artifact through the real loader path**, which is
+> the step this release skipped. The tag and the npm version stay as published history; they are simply
+> not installable.
+
+
 ### Added
 
 * **A dispatch-target control inside the chat composer.** A client half registers into

package/cordis.patch.yml

@@ -1,7 +1,30 @@
 # This file is the bundle patch declared by package.json's `dsh.bundle.patch`.
-# It mounts the plugin explicitly at `./tools` rather than relying on a
-# "root export is the plugin" convention, so reading this file tells you which
-# module of the package becomes the plugin.
+# It mounts the plugin by its package name, whose root export is the plugin
+# (`lib/index.js` re-exports `./tools.js`), so reading this file tells you which
+# package becomes the plugin.
+#
+# ---------------------------------------------------------------------------
+# Why the row names the package and not the `/tools` subpath (v0.5.4)
+# ---------------------------------------------------------------------------
+# Until v0.5.4 this row said `name: '@twinsearth/w2m-dsh-plugin/tools'`, and for a
+# host-only plugin that was fine. It stops being fine the moment the package also
+# ships a browser half, because the client module system identifies a package by
+# the *package specifier* its Loader row carries:
+#
+#   client-modules: resolveMeta(loaderName, baseUrl)   (dsh-client-modules)
+#     exactPackageSpecifier('@twinsearth/w2m-dsh-plugin/tools') -> undefined
+#     ... -> locatePkgJson returns undefined -> the entry is not a client package
+#
+# A subpath specifier resolves to no package manifest at all, so a `/tools` row is
+# invisible to the scan: `lib/client.js` is never composed into `__DSH_BOOT__`, and
+# the composer control can never register -- whatever else is fixed. Measured on the
+# 0.5.4 tarball through the real Loader: the composed boot graph held rows for
+# `@deepseek-ai/dsh-typert-registry` and `@deepseek-ai/dsh-api-gateway` and none for
+# this package. Naming the bare package fixes it, because the root export already
+# re-exports exactly what `/tools` exports (`test/tools.test.mjs` asserts the two
+# carry the same `inject`), so the host half is unchanged. `./tools` remains a
+# supported mount point for anyone who wants it -- it is simply not the one this
+# bundle uses.
 #
 # ---------------------------------------------------------------------------
 # Why this is an `insert:` list and not a bare `- id: w2m`
@@ -83,7 +106,7 @@
 # is visible rather than assumed.
 - insert:
     - id: w2m
-      name: '@twinsearth/w2m-dsh-plugin/tools'
+      name: '@twinsearth/w2m-dsh-plugin'
       config:
         rabbitUrl: ''
         operatorToken: ''

package/lib/client.js

@@ -52,10 +52,12 @@ window.__ModuleLoader__.load({
     // Wire
     // -------------------------------------------------------------------------------------------
     //
-    // Mirrors TARGET_ROUTE_PATH in src/plugin/fleet-target.mjs. Plain same-origin `fetch` rather
-    // than a Remote method: the route is mounted inside the host's authentication fence, so the
-    // page's own cookie is the credential and there is no descriptor to keep in sync.
-    const ROUTE = '/w2m/target';
+    // Mirrors TARGET_ROUTE_PATH in src/plugin/fleet-target.mjs, `/api` prefix included: the host's
+    // Connection service mounts its exact-fetch-route registry under that channel and refuses any
+    // path that does not start with `/api/`. Plain same-origin `fetch` rather than a Remote method:
+    // the route is mounted inside the host's authentication fence, so the page's own cookie is the
+    // credential and there is no descriptor to keep in sync.
+    const ROUTE = '/api/w2m/target';
 
     /**
      * The locale namespace and its two dictionaries.

package/lib/index.js

@@ -3,22 +3,27 @@
  *
  * TWO READERS, ONE EXPORT LIST
  *
- * `cordis.patch.yml` names the `tools` subpath explicitly, and that stays true: mounting this
- * profile reads the patch, sees `@twinsearth/w2m-dsh-plugin/tools`, and loads `./tools.js`. Nothing
- * about the mounted plugin changes because of this file.
+ * `cordis.patch.yml` mounts this file: the profile reads the patch, sees
+ * `@twinsearth/w2m-dsh-plugin`, and loads `./index.js`. It names the *package* rather than the
+ * `tools` subpath on purpose, and the reason is measured rather than stylistic: the client module
+ * system (`@deepseek-ai/dsh-client-modules`) identifies a client package by the specifier its Loader
+ * row carries (`exactPackageSpecifier`), so a row naming `…/tools` resolves to no package.json at all
+ * — `dsh.client` is never read and the browser half is never composed into `__DSH_BOOT__`. The host
+ * would keep working and the composer control would silently never arrive; that is what v0.5.4
+ * shipped, and `test/loader-entry.test.mjs` now catches it through the real Loader.
  *
- * But the root entry is what everything else looks at. The DSH plugin listing requirements -- and
- * the marketplace checklists that copy them -- ask for a package that "exports an `apply(ctx)`
- * module", and a package that does not is one of the most common reasons a submission is refused.
- * This file used to be documentation only, so importing the package root yielded **no exports at
- * all** (`Object.keys() === []`): a plugin that works perfectly when mounted by its patch and looks
- * like an empty package to every tool that inspects it. That is a bad trade for one re-export line.
+ * `./tools.js` remains a supported mount point for anyone who wants it, and it is still what the
+ * DSH plugin listing requirements look at: the checklist asks for a package that "exports an
+ * `apply(ctx)` module", and this root is that module. It used to be documentation only, so importing
+ * the package root yielded **no exports at all** (`Object.keys() === []`): a plugin that works
+ * perfectly when mounted by its patch and looks like an empty package to every tool that inspects it.
+ * That is a bad trade for one re-export line.
  *
  * WHY NOT MOVE THE PLUGIN HERE
  *
  * Re-exporting is not relocating: `./tools.js` stays the single definition, so there is still
  * exactly one implementation of the plugin surface to keep in sync. Mounting *both* this entry and
- * the subpath would register the eight tools twice, which is why the patch keeps naming the subpath
- * instead of falling back to the "the root is the plugin" convention.
+ * the subpath would register the eight tools twice, which is why the patch mounts exactly one of
+ * them.
  */
 export { apply, inject, resetDefineToolCacheForTests } from './tools.js';

package/lib/tools.js

@@ -1,9 +1,15 @@
 /**
  * Package-facing plugin entry: `@twinsearth/w2m-dsh-plugin/tools`.
  *
- * This is the module named by `cordis.patch.yml`, so it is the seam between the
- * published package layout (`lib/`, what npm ships as the documented entry) and
- * the implementation (`src/`, where the code is actually readable).
+ * The documented subpath entry point, and the seam between the published package
+ * layout (`lib/`, what npm ships as the documented entry) and the implementation
+ * (`src/`, where the code is actually readable).
+ *
+ * `cordis.patch.yml` mounts the package *root* (`lib/index.js`), which re-exports
+ * this file, because the client module system only recognises a package whose
+ * Loader row carries the bare package specifier. Both paths land on the same
+ * `apply` and `inject` -- `test/tools.test.mjs` asserts that -- so this remains a
+ * supported mount point for a profile that prefers it.
  *
  * Nothing is re-implemented here on purpose: a second definition of the plugin
  * surface would be a second thing to keep in sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/src/plugin/fleet-target.mjs

@@ -27,10 +27,12 @@
  *
  * # The wire, and why it is this small
  *
- * Two exact Fetch routes on the host's `/api` carrier, mounted inside its authentication fence:
+ * Two exact Fetch routes on the host's `/api` carrier, mounted inside its authentication fence.
+ * The `/api` prefix is the registry's own channel — see {@link TARGET_ROUTE_PATH} — so these are the
+ * paths as the host registers them, and the page fetches the same path document-relative:
  *
- *   GET  /w2m/target?session_id=…   the fleet and this session's selection, as one snapshot
- *   POST /w2m/target                { session_id, machine_id|null } → the same snapshot
+ *   GET  /api/w2m/target?session_id=…   the fleet and this session's selection, as one snapshot
+ *   POST /api/w2m/target                { session_id, machine_id|null } → the same snapshot
  *
  * Plain `Response.json`, no Typert descriptor: this package is dependency-free, and a generated
  * strict Remote contribution is neither reachable from plain JavaScript nor worth a codec for one
@@ -48,8 +50,19 @@
  * get.
  */
 
-/** Both routes hang off this exact path; the browser half reads the same constant. */
-export const TARGET_ROUTE_PATH = '/w2m/target';
+/**
+ * Both routes hang off this exact path; the browser half reads the same constant.
+ *
+ * The `/api` prefix is not decoration and not ours: `@deepseek-ai/dsh-client-connection` mounts the
+ * whole fetch-route registry under its `/api` channel and validates every registration with
+ * `endpointFromPath('/api', path)`, which returns undefined for anything that does not start with
+ * `/api/`. A `/w2m/target` registration is therefore refused — `connection: invalid exact Fetch route
+ * "/w2m/target"` — inside the injected callback, where it failed the *child* fiber and left the host
+ * entry looking perfectly healthy. The shipped browser halves all follow the same rule
+ * (`dsh-client-file-upload` uses `/api/session/uploadFileBinary`), and the page fetches the same
+ * document-relative path.
+ */
+export const TARGET_ROUTE_PATH = '/api/w2m/target';
 
 /**
  * The store bucket used when a dispatch carries no session.
@@ -460,16 +473,40 @@ export function createLocalIdentity(read) {
   };
 }
 
+/** The one diagnostic for "this host cannot carry the composer control", shared by both causes. */
+const NO_ROUTE_REGISTRY =
+  'this host provides no `connection.fetch` route registry, so the composer control cannot reach the plugin';
+
 /**
  * Mount the two browser routes, if this host has a fetch-route registry to mount them on.
  *
  * Returning a status object instead of throwing keeps the one interesting case loud *and*
  * survivable: a host built without `@deepseek-ai/dsh-client-connection` still gets a working plugin
- * with seven tools and no composer control, which is strictly better than a plugin that refuses to
- * load because a UI nicety has nowhere to attach.
- *
- * @param {object|null|undefined} ctx Cordis context; only `ctx.connection.fetch` is read, and it is
- *   read defensively because a host may not provide one.
+ * with all eight tools and no composer control, which is strictly better than a plugin that refuses
+ * to load because a UI nicety has nowhere to attach.
+ *
+ * # Why the service is declared with `ctx.inject`, and never read as `ctx.connection`
+ *
+ * Cordis resolves services per fiber: a property read of a name this plugin did not declare in its
+ * `inject` list **throws** — `cannot get property "connection" without inject` — and it throws
+ * whether or not some other plugin provides that service. `ctx.inject(names, callback)` is the
+ * declaration that makes the read legal, and it is the *optional* form: the plugin's own list stays
+ * `['tools']`, so a host with no Connection service still activates and still registers all eight
+ * tools — the callback below simply never runs. v0.5.4 shipped the plain property read, and the whole
+ * entry then failed on a web host and on a base-only host alike, because the throw does not depend on
+ * the service existing.
+ *
+ * `ctx.inject` also drops the ordering assumption a one-shot read would carry: the Loader creates
+ * sibling entries concurrently (`EntryGroup.update` → `Promise.all`), so a host that *does* provide
+ * Connection may still be activating it while this plugin's `apply` runs. A synchronous read would
+ * report "no registry" for a control that was about to become attachable.
+ *
+ * The status object is mutated in place when the callback runs, so `w2m_status` — called long after
+ * activation — reads what happened rather than what was knowable at `apply` time.
+ *
+ * @param {object|null|undefined} ctx Cordis context; `ctx.inject(['connection'], …)` is how the
+ *   optional service is declared and read. A context without `inject` gets no route and no warning,
+ *   which is the same status as a host that has no Connection at all.
  * @param {object} deps
  * @param {() => object} deps.cfg Current merged plugin config.
  * @param {object} deps.store The selection store.
@@ -480,17 +517,43 @@ export function createLocalIdentity(read) {
  *   when the host has a Connection service that lacks the registry — the one case worth a warning.
  */
 export function registerTargetRoutes(ctx, deps) {
-  const connection = ctx?.connection ?? null;
+  const status = {
+    mounted: false,
+    unexpected: false,
+    reason: NO_ROUTE_REGISTRY,
+  };
+  if (typeof ctx?.inject === 'function') {
+    ctx.inject(['connection'], (webCtx) => {
+      mountTargetRoutes(webCtx.connection, deps, status, ctx.logger);
+    });
+  }
+  return status;
+}
+
+/**
+ * Attach the route pair to one host's fetch registry, recording the outcome on `status`.
+ *
+ * The registration is owned by the context it is made through — `register` is a Connection method
+ * bound to the calling fiber, so it is released with the injected child fiber — which is why there
+ * is no `ctx.effect` wrapper here.
+ *
+ * @param {object|null|undefined} connection The `connection` service, when the host has one.
+ * @param {object} deps
+ * @param {{mounted: boolean, unexpected: boolean, reason: string|null}} status Mutated in place.
+ * @param {object} [logger] The plugin's logger, for the one mismatch worth a line.
+ * @returns {void}
+ */
+function mountTargetRoutes(connection, deps, status, logger) {
   const registry = connection?.fetch;
   if (registry === undefined || typeof registry.register !== 'function') {
-    return {
-      mounted: false,
-      // The distinction matters to the caller's log: a host with **no** Connection at all is simply
-      // not a web composition, and warning about it would be noise on every headless run. A host
-      // that has Connection but no fetch registry is a real mismatch worth one line.
-      unexpected: connection !== null && connection !== undefined,
-      reason: 'this host provides no `connection.fetch` route registry, so the composer control cannot reach the plugin',
-    };
+    // The distinction matters to the log: a host with **no** Connection at all is simply not a web
+    // composition, and warning about it would be noise on every headless run. A host that has
+    // Connection but no fetch registry is a real mismatch worth one line.
+    status.unexpected = connection !== null && connection !== undefined;
+    if (status.unexpected) {
+      logger?.warn?.(`w2m: the composer target control is inactive — ${NO_ROUTE_REGISTRY}`);
+    }
+    return;
   }
 
   let cache = { at: 0, value: null };
@@ -599,5 +662,6 @@ export function registerTargetRoutes(ctx, deps) {
     },
   });
 
-  return { mounted: true, unexpected: false, reason: null };
+  status.mounted = true;
+  status.reason = null;
 }

package/src/plugin/tools.mjs

@@ -131,7 +131,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.5.4';
+const PLUGIN_VERSION = '0.5.5';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -2872,6 +2872,12 @@ export async function apply(ctx, config = {}) {
   // host without `connection.fetch` still gets every tool, and `w2m_status` reports the absence —
   // which is the honest place for it, since a host that has no Connection at all is simply not a web
   // composition and does not need a warning on every headless run.
+  //
+  // Nothing here reads the service: `registerTargetRoutes` declares the optional dependency with
+  // `ctx.inject` and attaches from that callback (the comment there records why a plain
+  // `ctx.connection` read fails the whole entry, and why the read cannot be synchronous anyway). The
+  // one mismatch worth a log line — a Connection that carries no fetch registry — is logged where it
+  // is observed, inside that callback, so this call returns a status object that stays live.
   const targetRoutes = registerTargetRoutes(ctx, {
     cfg: () => cfg,
     store: defaultSelectionStore,
@@ -2879,9 +2885,6 @@ export async function apply(ctx, config = {}) {
     request,
     resolveToken,
   });
-  if (targetRoutes.unexpected) {
-    ctx.logger?.warn?.(`w2m: the composer target control is inactive — ${targetRoutes.reason}`);
-  }
 
   /** Text output: rendered as JSON, because every one of these tools answers with a structure. */
   const jsonOutput = {