dsh-plugin-shop 0.8.3 → 0.8.4-beta.0

package/lib/types/host/compatibility.d.ts

@@ -0,0 +1,223 @@
+/** Harness compatibility as the AUTHOR states it: which `dsh.compatibility`
+ * declarations the running installation does not meet (design
+ * 2026-09-01-harness-compatibility §8.2, as amended §9.9). The presence check
+ * in `peers.ts` infers from what a plugin imports; this reads what its author
+ * wrote down. And, from dsh 0.1.7 on, what dsh ITSELF refuses: the harness
+ * peers its installer rejects an install on (`peerVerdictsOf`, design
+ * 2026-09-26-dsh-017-readiness, B1).
+ *
+ * Pure: the running version, the running profile, the harness's own
+ * template table and its peer check arrive as arguments, so fixtures drive
+ * every verdict and the reads of the installation stay outside — the running
+ * dsh, its template table and its peer check in `harness.ts`, the running
+ * profile's bundles and exemptions in the gateway. */
+import { type EntryIdentity } from '../shared/identity.ts';
+import type { PeerCheck } from './harness.ts';
+/** What an author declared in `dsh.compatibility` that this installation does
+ * not meet. Each half is present only when the author declared it AND it is
+ * unmet here, and carries both sides, so the reader is told what was declared
+ * and what is actually running rather than only that something is wrong. */
+export interface HarnessVerdict {
+    /** The declared `dsh` range, and the `@deepseek-ai/dsh` version running. */
+    dsh?: {
+        range: string;
+        running: string;
+    };
+    /** The declared profile templates, and the name of the profile this dsh was
+     * booted with. */
+    profile?: {
+        declared: string[];
+        running: string;
+    };
+    /** What the running dsh refuses this install on — no author's claim, and
+     * the one half the shop blocks an install for (`PeerVerdict`). */
+    peers?: PeerVerdict;
+}
+/**
+ * An install the running dsh will refuse (0.1.7 on): the harness peers it
+ * refuses, each with the range the package declared; the dsh version it
+ * judged them against; and the command that records dsh's exact-version
+ * exemption for this package on this dsh, after which dsh installs it. The
+ * command is null when dsh would refuse that too (`allowVersionCommand`).
+ */
+export interface PeerVerdict {
+    refused: Record<string, string>;
+    running: string;
+    allowCommand: string | null;
+}
+/** The running profile as the profile half needs it: its name, for the copy,
+ * and the bundles it composes, for the comparison. `bundles` is null when the
+ * profile manifest could not be read, which is no verdict rather than an
+ * accusation. */
+export interface RunningProfile {
+    name: string;
+    bundles: readonly string[] | null;
+}
+/** The running side of the comparison. `dshVersion` is null when the
+ * running dsh's version could not be read — this process was not started by
+ * dsh's CLI, or that CLI's manifest carries none (`harness.ts`). The profile
+ * is always known, because the gateway asking was booted inside one — but
+ * what it composes may not be. */
+export interface HarnessRuntime {
+    dshVersion: string | null;
+    profile: RunningProfile;
+}
+/** Harness profile template name → the bundles that template composes, or an
+ * empty record when the harness's own table could not be read. The names are
+ * matched against catalog input, so a reader takes own keys only
+ * (`unmetProfile`), and `profileTemplatesOf` builds one with no prototype. */
+export type ProfileTemplates = Readonly<Record<string, readonly string[]>>;
+/**
+ * Normalize the harness's OWN `PROFILE_TEMPLATES` into template name → bundle
+ * names, or an empty record for a shape this build does not know.
+ *
+ * Two shapes exist and both are live: 0.1.5-rc.3 maps a name to
+ * `{ bundles, patchReload }` (five templates), while the version this package
+ * pins as a devDependency maps it to a bare array (two). A name whose value is
+ * neither, or whose bundle list holds a non-string, is dropped rather than
+ * guessed at — an unreadable table means no profile verdict, never a wrong
+ * one. Copied from nowhere: the caller passes the harness's exported object.
+ *
+ * The record has NO PROTOTYPE, empty answer included. It is indexed by the
+ * profile names a catalog entry declares, which are hostile input, and a
+ * record built on `{}` answered `constructor`, `__proto__`, `toString`,
+ * `hasOwnProperty` and `valueOf` from `Object.prototype`: a value that passed
+ * the `undefined` guard and threw out of `compatibilityMap`, so one entry
+ * declaring `profiles: ["constructor"]` rejected every `catalog()` call for
+ * every user. Without a prototype there is also no `__proto__` setter, so a
+ * template exported under that name stays an own key instead of replacing
+ * the record's prototype. `unmetProfile` takes own keys only as well — the
+ * type is exported, and a caller may hand in a plain object.
+ */
+export declare function profileTemplatesOf(exported: unknown): ProfileTemplates;
+/**
+ * Install identity → the half or halves of an entry's declaration this
+ * installation does not meet. A key is present only when something was
+ * declared AND is unmet, so an absent key means "runs here, or we could not
+ * tell" — the rule `incompatibilityMap` follows, and for the same reason: one
+ * false warning teaches a reader to ignore every warning.
+ *
+ * The halves are judged apart, and an unknown on either side silences only its
+ * own half:
+ *
+ * - `dsh` needs a range semver can parse and a running version that is semver,
+ *   and is then `satisfies` with `includePrerelease`. That option is
+ *   load-bearing: the harness ships nothing but prereleases, and strict semver
+ *   refuses a prerelease against any range whose comparators carry none —
+ *   `0.1.5-rc.3` fails `>=0.1.0`, and even `*` — so every author who wrote a
+ *   plain range would be told they exclude a harness their range includes.
+ *
+ *   What the option does NOT do is read a range the way its author probably
+ *   meant it. Under it a prerelease is compared like any other version, and a
+ *   prerelease sorts BELOW its own release (measured with semver 7.8.5; the
+ *   rows are pinned in compatibility.test.ts):
+ *   - An upper bound written without `-0` admits the next line's
+ *     prereleases: `<0.2.0` and `>=0.1.0 <0.2.0` both admit `0.2.0-rc.1`.
+ *     Only a bound that desugars to `<0.2.0-0` refuses it — `^0.1.0`,
+ *     `~0.1.0` and `0.1.x` do, as does `<0.2.0-0` written out.
+ *   - A floor written without `-0` refuses its own prereleases: `>=0.1.5`,
+ *     `^0.1.5` and `0.1.5` all refuse `0.1.5-rc.3`, because `0.1.5` sorts
+ *     above it. `>=0.1.5-0` admits every `0.1.5-rc.N`.
+ *   So `>=0.1.5-0` and `<0.2.0-0` are the spellings that say what an author
+ *   usually means. The comparison stays semver's own and is never rewritten
+ *   here: a verdict that coerced prereleases would answer differently from
+ *   semver, which is what an author checks a range against. An exact list of
+ *   other versions — `@xmanrui/dsh-im`'s declaration — is refused, as it
+ *   should be.
+ * - `profile` is met when the running profile's NAME is one of the declared
+ *   names, or when it composes every bundle of a declared template.
+ *
+ *   The name is trusted for the names dsh ships, because for those it is not
+ *   the reader's choice. On 0.1.5-rc.3 both paths that create a missing
+ *   profile build one of a shipped name from that name's template
+ *   (dsh-app-boot's `loadProfile`, and `dsh plugin`), and dsh refuses a
+ *   shipped name as the target of `--from-default-profile`, so a profile
+ *   carrying one was built from that template. That is all the name
+ *   guarantees: which template the profile was built from, not what it
+ *   composes now. Nothing holds the bundle list to the template afterwards:
+ *   `dsh plugin`'s reconcile, not app-boot, appends each bundle it installs,
+ *   and app-boot's `normalizeShippedProfile` rewrites only a list that is
+ *   exactly a retired tuple or the current one. Bundles alone could not
+ *   decide there: a profile keeps the bundle list it was created with, so the
+ *   first harness release that added a bundle to `web` would badge every
+ *   `profiles: ["web"]` plugin (`@xmanrui/dsh-im`) on every existing `web`
+ *   profile, with copy saying it supports web and this dsh was launched with
+ *   web.
+ *
+ *   Any other name is the reader's choice — `dsh --profile rescue
+ *   --from-default-profile web` builds a profile called `rescue` from the web
+ *   bundles, and dsh records nothing about which template it came from — so a
+ *   running name no declaration matches is judged by what the profile IS:
+ *   each declared name is read as one of the harness's own templates, met
+ *   when every bundle of that template is in the running profile's bundles. A
+ *   declared name that is no template — an own key of the table, never an
+ *   inherited one — cannot be judged, and a list with such a name and no met
+ *   template gives no verdict. The half is unmet only when the running name is
+ *   not declared and every declared name is a template this profile does not
+ *   compose — see the amendment for the whole rule.
+ *
+ *   The residual, knowingly kept: a custom-named profile is still judged by
+ *   bundles, so a template that later gained a bundle would badge the custom
+ *   profiles created before the change. No PUBLISHED
+ *   `@deepseek-ai/dsh-app-boot` had changed a template's bundle list as of
+ *   2026-09-25: all 28 versions, read that day, give every template they
+ *   share the same list. One list was retired before the first publish:
+ *   every published app-boot, from the first, carries a retired `headless`
+ *   tuple (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`,
+ *   `@deepseek-ai/dsh-headless`) in `INSTALLATION_OWNED_PROFILE_TUPLES`, and
+ *   `normalizeShippedProfile` rewrites a `headless` profile carrying exactly
+ *   that list to the current template when it loads.
+ */
+export declare function compatibilityMap(entries: readonly (EntryIdentity & {
+    compatibility?: {
+        dsh?: string;
+        profiles?: string[];
+    };
+})[], runtime: HarnessRuntime, templates: ProfileTemplates): Record<string, HarnessVerdict>;
+/**
+ * Install identity → the refusal the running dsh will make, for each entry
+ * whose harness peers it refuses and the profile has not exempted. A key is
+ * present only for a refusal, so an absent key means "dsh installs it, or we
+ * could not tell".
+ *
+ * The rule is dsh's own (`check`, from the running app-boot), handed the
+ * manifest dsh's installer reads before it installs a registry spec — `pnpm
+ * view <spec> name version peerDependencies`, measured in dsh-plugin-manager
+ * 0.1.7-rc.2 — with the catalog's `dshPeers` for the peers. Those are the
+ * only peers the rule reads, verbatim. What this cannot see errs toward
+ * silence, never toward a refusal dsh would not make: a malformed peer range
+ * elsewhere in the manifest, which dsh rejects only after installing, and
+ * the plugins a bundle's patch rows name, which it checks then too. Those
+ * reach the reader as the install's own failure (`installFailureDetail`).
+ *
+ * npm entries only. dsh keys an exemption by the INSTALLED manifest's
+ * `name@version`, and a github entry's catalog version is a commit: its
+ * exemption status cannot be read, and a refusal named here could never be
+ * cleared from the shop. dsh refuses such an install itself, and says how
+ * to exempt it.
+ *
+ * A throw from the check forms no verdict for that entry, as a resolver's
+ * throw does in `incompatibilityMap`.
+ */
+export declare function peerVerdictsOf(entries: readonly (EntryIdentity & {
+    version: string;
+    dshPeers?: Record<string, string>;
+})[], check: PeerCheck, exemptions: Record<string, string[]>, profile: string): Record<string, PeerVerdict>;
+/**
+ * The command that records dsh's exact-version exemption for one refused
+ * install, spelled as dsh's own CLI prints it after a refusal — or null when
+ * `dsh plugin allow-version` would refuse the package or either version,
+ * which it checks against the grammar above. The name and version come from
+ * the catalog, which is hostile input bound for a terminal, and the two
+ * grammars admit no whitespace, quote, `$`, backtick, `;`, `|`, `&`,
+ * redirection or bracket, so no catalog value can add a command to the line
+ * it is pasted into.
+ *
+ * The profile is written as it is, as dsh prints it: it is the reader's own
+ * choice of name, never catalog input.
+ */
+export declare function allowVersionCommand(profile: string, issue: {
+    name: string;
+    version: string;
+    runtimeVersion: string;
+}): string | null;

package/lib/types/host/dsh-cli.d.ts

@@ -23,6 +23,14 @@
  */
 /** The npm package the dsh CLI is published as. */
 export declare const DSH_PACKAGE = "@deepseek-ai/dsh";
+/**
+ * Whether dsh's CLI refuses this profile outright: `desktop`, in any letter
+ * case, "is managed exclusively by the Electron application" — refused for a
+ * launch and for `dsh plugin` alike (`rejectElectronProfile` in the CLI's
+ * `lib/bin.js`, the same in 0.1.5-rc.3 and 0.1.7-rc.2). Every command the
+ * shop spawns names a profile, so none of them can run for this one.
+ */
+export declare function isDesktopProfile(profile: string): boolean;
 /**
  * The command that starts `bin` through `execPath` when `bin` names a
  * JavaScript entry, or `null` when `bin` is a program to spawn as given.

package/lib/types/host/harness.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The harness this process runs: which `@deepseek-ai/dsh` it is, and that
+ * dsh's own profile-template table — the running side of the
+ * `dsh.compatibility` verdict (design 2026-09-01-harness-compatibility §9.9).
+ *
+ * Both used to be read from somewhere that is not the running harness, and
+ * both were wrong there:
+ *
+ * - The version was the first `node_modules/@deepseek-ai/dsh` found walking up
+ *   from the profile: what the profile can IMPORT, not what RUNS. A plugin
+ *   that depends on the dsh package gets its copy hoisted into
+ *   `<profile>/node_modules` — the listed `dsh-claude-tui@0.1.6` pulls
+ *   0.1.2-rc.1 — a second install sharing DSH_HOME re-points the link farm,
+ *   and under a packaged dsh the bin-only package gets no link-farm proxy at
+ *   all, so the read was dead or stale. The first was reproduced with real
+ *   installs on 2026-09-25 (the design's section 9.9 amendment): every
+ *   verdict said "running 0.1.2-rc.1" while 0.1.5-rc.3 ran.
+ * - The templates came from the shop's own `import * as appBoot`, which
+ *   resolves from the SHOP's real path: under a `link:` install that is this
+ *   repository's devDependency, 0.1.1-rc.2 with two templates, while
+ *   0.1.5-rc.3 with five runs — and in production a copy hoisted from some
+ *   plugin's dependencies can shadow it the same way.
+ *
+ * Both now come from the one thing that names the running harness: the script
+ * this process was started with. Resolved through symlinks, the package that
+ * owns it IS the dsh CLI that is running, if it is one at all; its manifest
+ * says its version, and the app-boot it imports says its templates.
+ */
+import { type ProfileTemplates } from './compatibility.ts';
+/** One package's harness peers as the running dsh judges them: app-boot's
+ * `evaluatePluginCompatibility` result, the shape 0.1.7 returns. */
+export interface PeerIssue {
+    name: string;
+    version: string;
+    /** The dsh version the check judged against — app-boot's own. */
+    runtimeVersion: string;
+    /** The refused peers, each with the range the package declared. */
+    peers: Record<string, string>;
+    /** Whether the profile holds dsh's exact-version exemption for this
+     * package on this dsh, in which case dsh accepts the install anyway. */
+    exempted: boolean;
+}
+/** The running dsh's own install-time check (app-boot, from 0.1.7): the rule
+ * it refuses an install by, and the exemptions a profile holds. Taken from the
+ * dsh that runs rather than reimplemented, so a verdict cannot drift from the
+ * refusal it predicts (design 2026-09-26-dsh-017-readiness, B1). */
+export interface PeerCheck {
+    /** `evaluatePluginCompatibility(manifest, exemptions, runtimeVersion)` with
+     * app-boot's own version as the runtime — the version dsh's installer
+     * judges by, since it passes none and the default reads app-boot's
+     * manifest. That version is read once, here, rather than per call: the
+     * default re-reads the file on every call, which measured 75 ms against
+     * 12 ms for 2,000 manifests on 0.1.7-rc.2. The incompatible harness peers
+     * of one manifest, or undefined when there are none. Throws for a manifest
+     * it cannot judge. */
+    evaluate(manifest: {
+        name: string;
+        version: string;
+        peerDependencies: Record<string, string>;
+    }, exemptions: Record<string, string[]>): PeerIssue | undefined;
+    /** `readProfileVersionExemptions(profileDir)`: exact `name@version` keys
+     * mapped to the dsh versions each is exempted on. */
+    exemptions(profileDir: string): Record<string, string[]>;
+}
+/** The running side of the `dsh.compatibility` verdict. The gateway reads it
+ * once and keeps it: a running process cannot change which dsh it is. */
+export interface RunningHarness {
+    /** The running dsh's own `version`, or null when this process was not
+     * started by dsh's CLI or its manifest carries no non-empty string there.
+     * Whether it is semver is `compatibilityMap`'s question. */
+    dshVersion: string | null;
+    /** That dsh's own `PROFILE_TEMPLATES`, normalized by `profileTemplatesOf`;
+     * empty whenever the table could not be read. */
+    templates: ProfileTemplates;
+    /** Whether that dsh reads a LIST-valued `dsh.bundle.patch`: its app-boot
+     * exports `bundlePatchFiles`, which 0.1.7 does and 0.1.5 does not. A dsh
+     * without it joins the declaration onto a path, so a package declaring a
+     * list stops the profile from starting (design 2026-09-26-dsh-017-readiness,
+     * B4). Null whenever the app-boot could not be read — unknown, which forms
+     * no verdict. */
+    patchLists: boolean | null;
+    /** That dsh's own install-time peer check, or null when its app-boot
+     * exports none (before 0.1.7, which refuses no install on peers) or could
+     * not be read — no verdict either way. */
+    peerCheck: PeerCheck | null;
+}
+/**
+ * The harness this process runs, identified from `script` — the gateway's
+ * `restartScript`, `process.argv[1]` in production — or nothing, never a
+ * guess:
+ *
+ * 1. `script` is resolved through symlinks, because `argv[1]` is the path the
+ *    shell ran — `<prefix>/bin/dsh`, a link — and only its target lies inside
+ *    the dsh package. No script, or one that does not resolve: nothing known.
+ *    An empty path is no script either: `realpathSync('')` answers the
+ *    working directory, which says where dsh was started, not what it is.
+ * 2. The package that owns it (`owningPackage`) must be `@deepseek-ai/dsh`.
+ *    Anything else — a test runner, another host embedding the shop — means
+ *    nothing here can say which harness runs, and both halves of the verdict
+ *    stay silent.
+ * 3. `dshVersion` is that manifest's `version` when it is a non-empty string.
+ * 4. `templates`, `patchLists` and `peerCheck` come from that dsh's own
+ *    app-boot (`appBootFacts`). Any failure there costs all three and keeps
+ *    the version.
+ *
+ * Never throws and never rejects: a harness nobody could identify forms no
+ * verdict, and must never be the reason the catalog fails to load.
+ */
+export declare function readRunningHarness(script: string | undefined): Promise<RunningHarness>;

package/lib/types/host/hot.d.ts

@@ -51,19 +51,19 @@ export interface PluginHandle {
  * Why a restart is needed after the hot path ran — a stable code the client
  * turns into copy in the reader's own dsh language.
  *
- * Four of the five say the MOUNT could not activate, and distinguish
+ * Five of the six say the MOUNT could not activate, and distinguish
  * "restart will fix it" (`timeout`, `mount-failed`) from "this package can
  * never hot-mount" (`no-patch`, `not-simple`) and "this harness cannot"
  * (`host-unsupported`).
  *
- * `client-half` is the one that does not: the mount SUCCEEDED and the host
- * half is running, but the package declares `dsh.client` and a hot mount does
- * not enter the composition the client registry enumerates, so no reload can
- * fetch its browser half (measured 2026-09-14 — see `activation.ts`). It
- * exists so the reader is not told "installed; restart dsh to activate"
- * about a plugin that is demonstrably already running.
+ * `already-loaded` is the one that does not: no mount was attempted, because
+ * this process may already hold the package's module, and Node caches a
+ * module by its URL — the new files sit at the old URL, so a mount would re-run
+ * the old code under the new version's name (design
+ * 2026-09-26-market-borrowings §1). The gateway decides it before calling
+ * `hotMount`, which never returns it.
  */
-export type HotRestartReason = 'no-patch' | 'not-simple' | 'host-unsupported' | 'timeout' | 'mount-failed' | 'client-half';
+export type HotRestartReason = 'no-patch' | 'not-simple' | 'host-unsupported' | 'timeout' | 'mount-failed' | 'already-loaded';
 export interface HotMountResult {
     ok: boolean;
     /** null exactly when ok. */