dsh-plugin-shop 0.6.0 → 0.7.0

package/lib/typert.remote-client.js

@@ -151,7 +151,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopCatalogResult',
         schema: dsh_plugin_shop_shop_catalog_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":543,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":568,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installed',
@@ -166,7 +166,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop#shop/installed:result',
         schema: dsh_plugin_shop_shop_installed_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":723,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":748,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStart',
@@ -192,7 +192,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallResult',
         schema: dsh_plugin_shop_shop_installStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":593,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":618,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStatus',
@@ -217,7 +217,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallStatusResult',
         schema: dsh_plugin_shop_shop_installStatus_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":712,"column":3},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":737,"column":3},
     },
     {
       id: 'dsh-plugin-shop#shop/restart',
@@ -232,7 +232,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopRestartResult',
         schema: dsh_plugin_shop_shop_restart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":873,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":898,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/setEnabled',
@@ -257,7 +257,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopSetEnabledResult',
         schema: dsh_plugin_shop_shop_setEnabled_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":460,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":466,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/uninstallStart',
@@ -283,7 +283,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUninstallResult',
         schema: dsh_plugin_shop_shop_uninstallStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":815,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":840,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/updateStart',
@@ -308,7 +308,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUpdateResult',
         schema: dsh_plugin_shop_shop_updateStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":933,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":958,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/version',
@@ -323,7 +323,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopVersionResult',
         schema: dsh_plugin_shop_shop_version_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":917,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":942,"column":9},
     },
   ],
 }

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

@@ -1,4 +1,5 @@
 /** Catalog fetch, verification, and disk cache — the Host's only network path. */
+import { type CatalogOrigin } from './origin.ts';
 import type { CatalogEntry, DeniedEntry } from './types.ts';
 /** Highest schemaVersion this build understands; a higher one is refused (§10).
  * 3 adds `source` and repo entries (github install channel); 4 adds `subdir`
@@ -27,7 +28,11 @@ export interface CatalogFs {
     write: (path: string, data: string) => void;
 }
 export interface LoadCatalogOptions {
-    baseUrl: string;
+    /** A single HTTP origin — the explicit-override spelling. Mutually
+     * exclusive with `origins`; exactly one must be given. */
+    baseUrl?: string;
+    /** Origins to race (design §3). */
+    origins?: CatalogOrigin[];
     cacheDir: string;
     refresh?: boolean;
     fetchImpl?: typeof fetch;
@@ -46,3 +51,16 @@ export interface LoadCatalogOptions {
  * included, degrades to no stars (spec §5).
  */
 export declare function loadCatalog(options: LoadCatalogOptions): Promise<CatalogResult>;
+/** The catalog base the shipped `cordis.patch.yml` names. A row carrying
+ * exactly this value expresses no preference, so the loader races its
+ * defaults; anything else is a deliberate override and is used alone. */
+export declare const DEFAULT_CATALOG_URL = "https://LivXue.github.io/dsh-plugin-shop/v1/";
+/** The npm package carrying the same `v1/` tree (design §2). */
+export declare const CATALOG_PACKAGE = "dsh-plugin-shop-catalog";
+/**
+ * The origins to race for this installation (design §3).
+ *
+ * @param catalogUrl - the row's configured base.
+ * @param npmRegistry - the user's own registry from `~/.npmrc`, or null.
+ */
+export declare function catalogOrigins(catalogUrl: string, fetchImpl: typeof fetch, npmRegistry: string | null): CatalogOrigin[];

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

@@ -238,6 +238,9 @@ export declare class ShopGateway extends TypertRemoteService {
     /** The install gate runs against the last loaded snapshot, never a fresh
      * fetch per request (§7.2: the Host's cached snapshot is the truth). */
     private lastSnapshot;
+    /** The origin list built for the last-seen `catalogUrl`, memoised so the
+     * user's npmrc is read at most once per gateway (see `originsFor`). */
+    private originCache;
     /** The incompatibility map already computed for `lastSnapshot`, keyed by
      * that snapshot's own object identity. Design §3 asks for the verdict
      * once per loaded snapshot, not once per RPC call: `loadCatalog` serves
@@ -294,6 +297,10 @@ export declare class ShopGateway extends TypertRemoteService {
         enabled: boolean;
     }): Promise<ShopSetEnabledResult>;
     private rowConfig;
+    /** The origins to race for this row's catalog. Read once per gateway: the
+     * user's npmrc does not change under a running dsh, and re-reading it on
+     * every catalog call would put a filesystem read on the hot path. */
+    private originsFor;
     /** The explicit restart override. Only the row's `config:` sub-object is
      * passed to a plugin — a top-level `allowRestart:` beside `name:` would be
      * silently ignored by the loader (dsh-market README, #227). */

package/lib/types/host/npm-origin.d.ts

@@ -0,0 +1,24 @@
+/** The npm transport (design §2, §3): the catalog as a package.
+ *
+ * Shell — this and `origin.ts`'s fetch half are the only places the catalog
+ * loader touches the network. The payoff is measured, not assumed: the same
+ * bytes reach a China-side machine at 12.53 MB/s from npmmirror against
+ * 0.03 MB/s from GitHub Pages. */
+import { type CatalogOrigin } from './origin.ts';
+/** Normalise to a trailing slash so relative `URL` resolution against a
+ * registry that carries a path — every corporate registry, e.g.
+ * `https://artifactory.corp/api/npm/npm-repo` — keeps that path instead of
+ * eating its last segment; a host-root registry's trailing slash is already
+ * a no-op either way. Exported so `catalog.ts`'s dedupe compares against the
+ * same normalised form `npmOrigin` races on. */
+export declare function normalizeRegistryUrl(url: string): string;
+/**
+ * An origin that reads the catalog out of `<registryUrl>`'s copy of
+ * `<packageName>`.
+ *
+ * The probe is the abbreviated `latest` manifest — 13.5 KB against the live
+ * registry — so the race is decided without downloading anything large. The
+ * tarball is fetched lazily on the first `pointer()` or `file()` and kept on
+ * the handle, so one origin download serves the whole load.
+ */
+export declare function npmOrigin(rawRegistryUrl: string, packageName: string, fetchImpl: typeof fetch): CatalogOrigin;

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

@@ -0,0 +1,23 @@
+/** The user's configured npm registry, if they have one (design §3).
+ *
+ * Pure: the caller injects the read. This is a deliberately partial reading
+ * of npm's config resolution — only the user-level `registry=` line — and
+ * that is safe precisely because the origin list is raced: a registry we
+ * guess wrong about loses a 400-byte request and nothing else.
+ *
+ * That property only holds for a value that is actually a URL, which is why
+ * the value is VALIDATED here rather than left to the caller. `npmOrigin`
+ * addresses its probe with `new URL(<pkg>/latest, registryUrl)`, which
+ * throws a raw `TypeError` — not a `TransportError` — for anything that is
+ * not an absolute URL, and `catalog.ts`'s race loop rethrows everything that
+ * is not a `TransportError`. An unvalidated `registry=` line would therefore
+ * fail the WHOLE load with npmmirror, npmjs and Pages all healthy and no
+ * cache fallback: the opposite of the stated property. Not a hypothetical
+ * shape either — `registry=${NPM_REGISTRY}/` is npm's own documented config
+ * expansion, it works perfectly for npm, and a reader that does not expand
+ * it captures the literal. */
+/**
+ * @param readFile - returns the file's text, or null when it does not exist.
+ * @param home - the user's home directory.
+ */
+export declare function npmrcRegistry(readFile: (path: string) => string | null, home: string): string | null;

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

@@ -0,0 +1,40 @@
+/** The transport seam under `loadCatalog` (design §3).
+ *
+ * An origin answers a cheap probe, then serves the pointer and the files the
+ * pointer names. HTTP and npm are interchangeable behind it, so every line of
+ * cache and validation logic in `catalog.ts` stays transport-blind. */
+/** A failure of the link, not of the content: the wire threw, or answered
+ * non-2xx. This is the ONLY class `loadCatalog` retries on another origin.
+ * A bad schema, a sha mismatch, or a refused url is an interpretation
+ * failure and throws — masking a corrupt origin behind a healthy one is
+ * exactly the silent-wrongness this project refuses. */
+export declare class TransportError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface OriginHandle {
+    readonly id: string;
+    /** The pointer JSON text. Cheap: the probe has already paid for it. */
+    pointer: () => Promise<string>;
+    /** One file named by the pointer, by the pointer's own raw url string.
+     * Callers pass that string verbatim — never a basename, which would strip
+     * a hostile absolute url into a fetchable relative one. */
+    file: (url: string) => Promise<string>;
+}
+export interface CatalogOrigin {
+    readonly id: string;
+    /** Cheap reachability + identity request. Resolving means this origin can
+     * serve; the expensive work happens on the returned handle. */
+    probe: (signal: AbortSignal) => Promise<OriginHandle>;
+}
+/** Resolve the pointer's data URL against the catalog base. An absolute URL —
+ * any scheme, or a protocol-relative `//host/...` — would hand the pointer a
+ * fetch primitive to arbitrary hosts, so it is refused loudly before any
+ * fetch (§9.2). The guard is the resolved origin, not the raw string: WHATWG
+ * normalization strips leading whitespace and accepts backslash spellings
+ * before the string could be inspected, so only comparing the resolved URL's
+ * origin to the base's closes every spelling class. */
+export declare function resolveDataUrl(baseUrl: string, url: string): string;
+/** The transport this project has always used: a static `v1/` tree. */
+export declare function httpOrigin(baseUrl: string, fetchImpl: typeof fetch): CatalogOrigin;

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

@@ -0,0 +1,41 @@
+/** Settle a set of promises in the order they finish (design §3).
+ *
+ * Pure and timer-free. `Promise.any` would give only the first success and
+ * discard the rest; the origin race needs the losers too, in order, so a
+ * probe that "won" but then fails to produce a pointer can fall through to
+ * the next-finishing probe instead of failing the whole load — this is how
+ * an npm origin's bulk tarball download, which happens inside `pointer()`,
+ * gets a fall-through on failure.
+ *
+ * That is deliberately narrower than "any bulk fetch falls through to
+ * another origin." This module only ever wraps `probe()` promises; once
+ * `catalog.ts` has committed to a handle and calls `file()` for the data
+ * file, that call happens outside this generator entirely, and a
+ * TransportError there falls back to the disk cache instead (see
+ * `catalog.ts`'s `cachedOrThrow`), never back into a race. Do not "fix"
+ * that path to match this comment — the split is intentional. */
+export type Settled<T> = {
+    index: number;
+    value: T;
+} | {
+    index: number;
+    reason: unknown;
+};
+/**
+ * Yield each promise's outcome as it settles, tagged with its argument index.
+ *
+ * Deliberately NOT an `async function*`. Two properties depend on that:
+ *
+ * 1. **Handlers attach synchronously, at call time.** An async generator's
+ *    body does not run until its first `next()`, so wiring the handlers
+ *    inside one would leave a rejection unhandled for as long as the caller
+ *    waits before iterating — which crashes the process under Node's default
+ *    unhandled-rejection policy.
+ * 2. **Order is recorded when each promise settles**, not when a consumer
+ *    asks. Re-racing the survivors on every turn tie-breaks on argument
+ *    order instead: `Promise.race` over promises that are ALREADY settled
+ *    resolves with the first in iteration order, not the first to have
+ *    settled — and a consumer doing any work between yields, which is
+ *    exactly this module's use case, is what lets two settle inside one turn.
+ */
+export declare function inCompletionOrder<T>(promises: readonly Promise<T>[]): AsyncGenerator<Settled<T>>;

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

@@ -0,0 +1,13 @@
+/** A read-only ustar parser: the npm transport's only way into a tarball.
+ *
+ * Pure — bytes in, a path-to-bytes map out. It handles exactly what `npm
+ * pack` emits and refuses everything else loudly, because the alternative to
+ * a small strict reader is a fourth runtime dependency (design §4). */
+/**
+ * Parse an uncompressed tar archive into path → bytes.
+ *
+ * Directory entries and every non-regular type (symlinks, pax and GNU
+ * extension headers) are skipped: npm packs regular files under `package/`,
+ * and a catalog tarball that needs anything else is not one we published.
+ */
+export declare function readTar(buffer: Buffer): Map<string, Buffer>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-shop",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The DeepSeek Harness plugin shop: browse, install, enable, and update dsh plugins from a git-auditable catalog.",
   "repository": {
     "type": "git",