@dsh-plugin/dsh-loader 1.0.0

package/src/index.js

@@ -0,0 +1,105 @@
+// dshloader host bundle entry (design.md §7.3 / §4.4).
+//
+// Exports the cordis function-plugin shape (`name`, `inject`, `apply`) and
+// wires the adapter registry → version detection → stable API onto
+// `ctx.dshLoader`. Service aliases / bridge routes register through
+// ctx.reflect.provide / ctx.effect so cordis auto-recycles them on fiber
+// unload — no manual dispose is required for v1's covered capabilities.
+import { LOADER_VERSION, LOG_PREFIX } from './version.js';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { AdapterRegistry, detectDshVersion, UnsupportedDshVersionError } from './registry.js';
+import { registerHostAdapters } from './adapters/index.js';
+import { createHostAPI } from './api.js';
+
+export const name = '@dsh-plugin/dsh-loader';
+// dshloader itself depends on `webServer` so its fiber only activates once
+// the real web server is provided — the alias then points `httpServer` at it.
+export const inject = ['webServer'];
+
+/**
+ * Read the profile-level dshloader config (exposeAllNamespaces etc.).
+ * Sources, in priority order:
+ *   1. process.env.DSHLOADER_EXPOSE_ALL_SETTINGS=1
+ *   2. profile package.json `dsh.dshloader.exposeAllNamespaces`
+ *   3. profile package.json `dshLoader.settings.exposeAllNamespaces`
+ */
+export function readLoaderConfig({ profileDir } = {}) {
+  const envOn = process.env.DSHLOADER_EXPOSE_ALL_SETTINGS === '1' || process.env.DSHLOADER_EXPOSE_ALL_SETTINGS === 'true';
+  let pkgOn = false;
+  try {
+    // Best-effort: read the profile manifest if reachable via cwd.
+    const dir = profileDir ?? join(process.env.DSH_HOME ?? '', 'profiles', 'web');
+    const manifest = JSON.parse(readFileSync(join(resolve(dir), 'package.json'), 'utf8'));
+    pkgOn = Boolean(
+      manifest.dsh?.dshloader?.exposeAllNamespaces ??
+        manifest.dshLoader?.settings?.exposeAllNamespaces,
+    );
+  } catch {
+    /* ignore */
+  }
+  return { exposeAllNamespaces: envOn || pkgOn };
+}
+
+/**
+ * Build the registry + select an adapter for the current dsh version, without
+ * touching the cordis context. Exported for tests and the `info` CLI command.
+ */
+export function selectAdapter({ dshVersion, registry } = {}) {
+  const reg = registry ?? registerHostAdapters(new AdapterRegistry());
+  const version = dshVersion ?? detectDshVersion();
+  if (version === undefined) {
+    throw new UnsupportedDshVersionError(
+      `${LOG_PREFIX} could not detect dsh version; set DSHLOADER_DSH_VERSION or install @deepseek-ai/dsh`,
+      { kind: 'too-new' },
+    );
+  }
+  const { factory, mode } = reg.select(version);
+  return { registry: reg, factory, mode, dshVersion: version };
+}
+
+/**
+ * Apply the selected adapter onto a cordis context and expose the stable API.
+ * @param {object} ctx cordis context
+ * @param {{ dshVersion?: string, config?: object, registry?: AdapterRegistry }} [opts]
+ * @returns {Promise<{ api: object, factory: object, mode: string, dshVersion: string }>}
+ */
+export async function applyAdapter(ctx, opts = {}) {
+  const config = opts.config ?? readLoaderConfig();
+  const selection = selectAdapter({ dshVersion: opts.dshVersion, registry: opts.registry });
+  const { factory, mode, dshVersion } = selection;
+
+  const adapter = factory.create(ctx, config);
+  await adapter.apply?.();
+
+  const api = createHostAPI({
+    ctx,
+    dshVersion,
+    factory,
+    adapter,
+    exposeAllNamespaces: config.exposeAllNamespaces,
+    hostPackageAliases: config.hostPackageAliases,
+  });
+  ctx.reflect.provide('dshLoader', api);
+
+  console.log(`${LOG_PREFIX} loaded adapter ${factory.name} for dsh ${dshVersion} (mode: ${mode})`);
+  console.log(`${LOG_PREFIX} registered stable API: settings, web, services`);
+  if (config.exposeAllNamespaces) {
+    console.warn(
+      `${LOG_PREFIX} exposeAllNamespaces enabled: bypassing official settings whitelist`,
+    );
+  }
+
+  return { api, factory, mode, dshVersion };
+}
+
+/** cordis function-plugin entry point. */
+export async function apply(ctx) {
+  if (process.env.DSHLOADER_DISABLE === '1' || process.env.DSHLOADER_DISABLE === 'true') {
+    console.log(`${LOG_PREFIX} disabled by env, skipping`);
+    return;
+  }
+  await applyAdapter(ctx);
+}
+
+export { LOADER_VERSION };

package/src/registry.js

@@ -0,0 +1,242 @@
+/**
+ * Adapter registry + dsh version detection (design.md §3.1 / §3.2).
+ *
+ * Selection rules (mirrors design.md §3.1, five rules):
+ *   1. exact match        — adapter.supports === version
+ *   2. range match        — semver.satisfies(version, supports); when several
+ *                           ranges cover the version, pick the narrowest; ties
+ *                           broken by last-registered-wins.
+ *   3. nearest-low fallback — no exact/range hit, but some adapters only cover
+ *                           versions below the real one: pick the one whose
+ *                           upper bound is closest, mark mode 'fallback', warn.
+ *   4. version too old    — real version is below every adapter's lower bound:
+ *                           throw UnsupportedDshVersionError with a "too old"
+ *                           message and the lowest supported version.
+ *   5. version too new / empty registry — throw UnsupportedDshVersionError with
+ *                           an "upgrade dshloader" message.
+ *
+ * Version detection priority (design.md §3.2):
+ *   1. DSHLOADER_DSH_VERSION env var (highest; for tests/CI override)
+ *   2. node_modules/@deepseek-ai/dsh/package.json#version
+ *   3. ctx.runtime?.version — reserved for the future, NOT consulted in v1.
+ * child_process `dsh --version` is deliberately NOT used (design.md §3.2).
+ */
+import { readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import semver from 'semver';
+import { LOG_PREFIX } from './version.js';
+
+const require = createRequire(import.meta.url);
+
+export class UnsupportedDshVersionError extends Error {
+  constructor(message, { kind, version, minSupported } = {}) {
+    super(message);
+    this.name = 'UnsupportedDshVersionError';
+    this.kind = kind; // 'too-old' | 'too-new'
+    this.version = version;
+    this.minSupported = minSupported;
+  }
+}
+
+export class InvalidVersionError extends Error {
+  constructor(message, { version } = {}) {
+    super(message);
+    this.name = 'InvalidVersionError';
+    this.version = version;
+  }
+}
+
+/**
+ * Resolve the installed dsh version.
+ *
+ * @param {{ profileDir?: string, dshPkgPath?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {string|undefined} semver version string, or undefined when unreachable
+ */
+export function detectDshVersion(opts = {}) {
+  const env = opts.env ?? process.env;
+  const envVal = env.DSHLOADER_DSH_VERSION;
+  if (typeof envVal === 'string' && envVal.trim() !== '') {
+    return envVal.trim();
+  }
+  const candidates = [];
+  if (opts.dshPkgPath) candidates.push(opts.dshPkgPath);
+  if (opts.profileDir) {
+    candidates.push(join(opts.profileDir, 'node_modules', '@deepseek-ai', 'dsh', 'package.json'));
+  }
+  // Resolve from the loader's own location (profile node_modules sits beside it).
+  try {
+    candidates.push(require.resolve('@deepseek-ai/dsh/package.json'));
+  } catch { /* not installed — skip */ }
+  // Global node_modules — dsh is typically installed globally (the runtime
+  // that loads profiles, not a profile dependency). Derive from the Node.js
+  // executable: /opt/homebrew/bin/node → /opt/homebrew/lib/node_modules.
+  const globalRoot = resolve(dirname(process.execPath), '..', 'lib', 'node_modules');
+  candidates.push(join(globalRoot, '@deepseek-ai', 'dsh', 'package.json'));
+  // Walk up from cwd as a last resort.
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i += 1) {
+    candidates.push(join(dir, 'node_modules', '@deepseek-ai', 'dsh', 'package.json'));
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const path of candidates) {
+    try {
+      const pkg = JSON.parse(readFileSync(path, 'utf8'));
+      if (typeof pkg.version === 'string' && pkg.version.trim() !== '') {
+        return pkg.version.trim();
+      }
+    } catch { /* try next */ }
+  }
+  return undefined;
+}
+
+/**
+ * Parse a semver range into { lower, upper } bounds. Each bound is
+ * { v: SemVer, inc: boolean } or null when unbounded on that side.
+ */
+function rangeBounds(range) {
+  const r = new semver.Range(range);
+  let lower = null;
+  let upper = null;
+  for (const group of r.set) {
+    for (const c of group) {
+      const op = c.operator;
+      const v = c.semver; // parsed SemVer (c.value is the raw comparator string)
+      if (op === '' || op === '=') {
+        lower = { v, inc: true };
+        upper = { v, inc: true };
+      } else if (op === '>') {
+        lower = { v, inc: false };
+      } else if (op === '>=') {
+        lower = { v, inc: true };
+      } else if (op === '<') {
+        upper = { v, inc: false };
+      } else if (op === '<=') {
+        upper = { v, inc: true };
+      }
+    }
+  }
+  return { lower, upper };
+}
+
+/** True when every version the range covers is strictly below `version`. */
+function isLowerCandidate(range, version) {
+  const { upper } = rangeBounds(range);
+  if (!upper) return false; // unbounded above → can cover version, not a lower candidate
+  return upper.inc ? semver.gt(version, upper.v) : semver.gte(version, upper.v);
+}
+
+/** Lowest version that satisfies the range (semver.minVersion). */
+function rangeMinVersion(range) {
+  const min = semver.minVersion(range);
+  return min ? min.version : null;
+}
+
+export class AdapterRegistry {
+  constructor() {
+    /** @type {Array<{supports: string, name: string, create: Function}>} */
+    this.adapters = [];
+  }
+
+  register(factory) {
+    if (!factory || typeof factory.supports !== 'string' || typeof factory.create !== 'function') {
+      throw new TypeError('AdapterFactory must expose { supports: string, create: function }');
+    }
+    this.adapters.push(factory);
+    return this;
+  }
+
+  /**
+   * @param {string} version real dsh version
+   * @returns {{ factory: object, mode: 'exact'|'range'|'fallback' }}
+   */
+  select(version) {
+    if (!semver.valid(version)) {
+      throw new InvalidVersionError(
+        `${LOG_PREFIX} cannot parse dsh version "${version}" as semver`,
+        { version },
+      );
+    }
+    if (this.adapters.length === 0) {
+      throw new UnsupportedDshVersionError(
+        `${LOG_PREFIX} no adapter registered for dsh ${version}; please upgrade @dsh-plugin/dsh-loader`,
+        { kind: 'too-new', version },
+      );
+    }
+
+    // Rule 1 + 2: exact and range matches.
+    const matches = [];
+    for (const factory of this.adapters) {
+      if (factory.supports === version) {
+        matches.push({ factory, mode: 'exact' });
+      } else if (semver.satisfies(version, factory.supports)) {
+        matches.push({ factory, mode: 'range' });
+      }
+    }
+    if (matches.length > 0) {
+      // Narrowest range wins; tie → last registered.
+      let best = matches[matches.length - 1];
+      for (let i = matches.length - 1; i >= 0; i -= 1) {
+        const candidate = matches[i];
+        const narrowest = matches.every((other, j) => {
+          if (i === j) return true;
+          try {
+            return semver.subset(candidate.factory.supports, other.factory.supports);
+          } catch {
+            return false;
+          }
+        });
+        if (narrowest) {
+          best = candidate;
+          break;
+        }
+      }
+      // Exact match always beats a range match on the same version.
+      const exact = matches.find((m) => m.mode === 'exact');
+      if (exact) best = exact;
+      return { factory: best.factory, mode: best.mode };
+    }
+
+    // Rule 3: nearest-low fallback.
+    const lowers = this.adapters
+      .filter((f) => isLowerCandidate(f.supports, version))
+      .map((f) => {
+        const { upper } = rangeBounds(f.supports);
+        return { factory: f, upper };
+      });
+    if (lowers.length > 0) {
+      lowers.sort((a, b) => {
+        const cmp = semver.compare(b.upper.v, a.upper.v);
+        if (cmp !== 0) return cmp;
+        // exclusive upper is "higher" than inclusive at the same version
+        return (b.upper.inc ? 0 : 1) - (a.upper.inc ? 0 : 1);
+      });
+      const chosen = lowers[0];
+      console.warn(
+        `${LOG_PREFIX} no exact adapter for dsh ${version}; falling back to "${chosen.factory.name}" (supports ${chosen.factory.supports})`,
+      );
+      return { factory: chosen.factory, mode: 'fallback' };
+    }
+
+    // Rule 4 vs 5: too old vs too new.
+    const minVersions = this.adapters
+      .map((f) => rangeMinVersion(f.supports))
+      .filter(Boolean)
+      .map((v) => semver.parse(v));
+    if (minVersions.length > 0) {
+      const lowest = minVersions.reduce((acc, v) => (semver.lt(v, acc) ? v : acc));
+      if (semver.lt(version, lowest)) {
+        throw new UnsupportedDshVersionError(
+          `${LOG_PREFIX} current dsh version ${version} is too old; dshloader minimum supported is ${lowest.version}. Please upgrade dsh or use an older dshloader release.`,
+          { kind: 'too-old', version, minSupported: lowest.version },
+        );
+      }
+    }
+    throw new UnsupportedDshVersionError(
+      `${LOG_PREFIX} no adapter covers dsh ${version}; please upgrade @dsh-plugin/dsh-loader`,
+      { kind: 'too-new', version },
+    );
+  }
+}

package/src/services/services.js

@@ -0,0 +1,28 @@
+// Services stable API (design.md §3.3 / §4.1 `ctx.dshLoader.services`).
+//
+// Thin read/alias helpers over the cordis service registry. `alias()` is a
+// low-level escape hatch for plugin authors who need a one-hop alias beyond
+// what the selected adapter already provides; it never overwrites an existing
+// service (mirrors the adapter safety rule in design.md §5.1).
+
+import { LOG_PREFIX } from '../version.js';
+
+export function createServicesAPI({ ctx }) {
+  return {
+    get(name) {
+      return ctx.get(name);
+    },
+    alias(from, to) {
+      if (ctx.get(from) !== undefined) {
+        console.warn(`${LOG_PREFIX} services.alias: "${from}" already exists, skip alias`);
+        return;
+      }
+      const target = ctx.get(to);
+      if (target === undefined) {
+        console.warn(`${LOG_PREFIX} services.alias: target "${to}" unavailable, cannot alias "${from}"`);
+        return;
+      }
+      ctx.reflect.provide(from, target);
+    },
+  };
+}

package/src/services/settings.js

@@ -0,0 +1,174 @@
+// Settings stable API (design.md §3.3.1 / §4.1 / §4.2).
+//
+// Two concerns are deliberately separated:
+//   1. naming/shape differences — handled by proxying to ctx.get('settings').
+//   2. access scope (security)  — `exposeAllNamespaces` controls whether
+//      `describe` returns only the official browser whitelist namespaces
+//      (default, matches official behavior) or every registered namespace.
+//
+// Host-side writes always proxy through to the real settings service: host
+// plugin code is already trusted (it runs in the dsh Node process and could
+// call ctx.get('settings').update directly). The whitelist is a browser-side
+// default-deny boundary owned by dsh-host-apiproxy; the browser path is
+// covered separately by the client fetch interceptor (src/client.js).
+import { LOG_PREFIX } from '../version.js';
+
+/**
+ * Official browser-writable settings namespaces (dsh-host-apiproxy
+ * WEB_SETTINGS_NAMESPACES), as documented in dsh-upstream-fixes/README.md.
+ * Product namespaces and dynamic model-provider namespaces are not enumerable
+ * without dsh internals; callers may extend this set via `extraWhitelist`.
+ */
+export const DEFAULT_WEB_SETTINGS_NAMESPACES = new Set([
+  'agent-loop',
+  'shell',
+  'locale',
+  'permission',
+  'ui-conversation',
+  'ui-theme',
+  'web-search-deepseek',
+]);
+
+/**
+ * Shape a raw settings descriptor into the official NamespaceView wire shape
+ * (mirrors dsh-upstream-fixes/lib/index.js `namespaceView`).
+ */
+export function toNamespaceView(descriptor) {
+  const view = {
+    ns: String(descriptor.ns),
+    schema: descriptor.schema,
+    value: descriptor.value,
+    ...(descriptor.base === undefined ? {} : { base: descriptor.base }),
+    ...(descriptor.user === undefined ? {} : { user: descriptor.user }),
+    applies: descriptor.applies,
+    secrets: (descriptor.secrets ?? []).map((s) => ({ path: [...s.path], set: s.set })),
+    revision: descriptor.revision,
+  };
+  return view;
+}
+
+/**
+ * Map a thrown settings error into a SettingsResult, preserving the official
+ * `settings-conflict` / `settings-rejected` classification.
+ */
+export function settingsErrorToResult(error, ns, method) {
+  const isObject = error !== null && typeof error === 'object';
+  const isConflict = isObject && ('expected' in error || 'actual' in error);
+  if (isConflict) {
+    return {
+      ok: false,
+      code: 'settings-conflict',
+      message: error.message ?? String(error),
+      details: {
+        ns,
+        ...(error.expected === undefined ? {} : { expected: error.expected }),
+        ...(error.actual === undefined ? {} : { actual: error.actual }),
+      },
+    };
+  }
+  return {
+    ok: false,
+    code: 'settings-rejected',
+    message: error instanceof Error ? error.message : String(error),
+    details: { ns, method },
+  };
+}
+
+/**
+ * Build the `ctx.dshLoader.settings` stable API.
+ *
+ * @param {{ ctx: object, exposeAllNamespaces: boolean, whitelist?: Set<string> }} opts
+ */
+export function createSettingsAPI({ ctx, exposeAllNamespaces, whitelist }) {
+  const allowed = whitelist ?? DEFAULT_WEB_SETTINGS_NAMESPACES;
+
+  function getSettings() {
+    return ctx.get('settings');
+  }
+
+  function filterNamespaces(views) {
+    if (exposeAllNamespaces) return views;
+    return views.filter((v) => allowed.has(String(v.ns)));
+  }
+
+  const api = {
+    exposeAllNamespaces: Boolean(exposeAllNamespaces),
+
+    /**
+     * Register a settings namespace. Proxies to the real settings service's
+     * `register(ns, schema, options)` and returns the owner scope
+     * ({ get, watch }) — the same shape the official service returns.
+     *
+     * Unlike describe/update/replace/mutate, register is NOT filtered by the
+     * whitelist: host plugin code is trusted and registering a namespace is
+     * a composition-time act, not a browser-facing read/write.
+     *
+     * @param {string} ns - unique namespace (lowercase kebab-case)
+     * @param {object} schema - schemastery schema for this namespace
+     * @param {{ base?: object, applies?: 'live'|'restart', validate?: (value:any)=>void }} [options]
+     * @returns {{ get: () => any, watch: (cb: (value:any)=>void) => () => void } | undefined}
+     */
+    register(ns, schema, options) {
+      const settings = getSettings();
+      if (settings === undefined || typeof settings.register !== 'function') {
+        console.warn(`${LOG_PREFIX}:settings.register settings service unavailable`);
+        return undefined;
+      }
+      return settings.register(ns, schema, options);
+    },
+
+    describe(options = {}) {
+      const settings = getSettings();
+      if (settings === undefined || typeof settings.describe !== 'function') {
+        return [];
+      }
+      const redactSecrets = options.redactSecrets !== false;
+      const descriptors = settings.describe({ redactSecrets });
+      const views = (descriptors ?? []).map(toNamespaceView);
+      return filterNamespaces(views);
+    },
+
+    async _write(method, ns, section, expectedRevision) {
+      const settings = getSettings();
+      if (settings === undefined) {
+        return {
+          ok: false,
+          code: 'internal',
+          message: `${LOG_PREFIX}:settings.${method} settings service unavailable`,
+          details: { ns },
+        };
+      }
+      try {
+        if (method === 'update') await settings.update(ns, section, expectedRevision);
+        else if (method === 'replace') await settings.replace(ns, section, expectedRevision);
+        else await settings.mutate(ns, section, expectedRevision);
+      } catch (error) {
+        return settingsErrorToResult(error, ns, method);
+      }
+      const descriptor = settings
+        .describe({ redactSecrets: true })
+        .find((d) => String(d.ns) === String(ns));
+      if (descriptor === undefined) {
+        return {
+          ok: false,
+          code: 'internal',
+          message: `${LOG_PREFIX}:settings.${method} namespace disposed after write`,
+          details: { ns },
+        };
+      }
+      return { ok: true, value: toNamespaceView(descriptor) };
+    },
+
+    update(ns, section, expectedRevision) {
+      return api._write('update', ns, section, expectedRevision);
+    },
+    replace(ns, section, expectedRevision) {
+      return api._write('replace', ns, section, expectedRevision);
+    },
+    mutate(ns, ops, expectedRevision) {
+      return api._write('mutate', ns, ops, expectedRevision);
+    },
+  };
+
+  return api;
+}

package/src/services/web.js

@@ -0,0 +1,71 @@
+// Web server stable API (design.md §3.3.2 / §4.1).
+//
+// Routes every registration through the real `webServer` (or `httpServer`
+// alias) `register({ kind, ... })` call shape used by dsh 1.x, mirroring
+// dsh-upstream-fixes/lib/index.js `registerRoutes`. Each method returns a
+// dispose function that removes the registration when the underlying
+// service supports it.
+import { LOG_PREFIX } from '../version.js';
+
+export class DshLoaderWebError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DshLoaderWebError';
+  }
+}
+
+/** Resolve the active web server service (webServer preferred, httpServer alias next). */
+function resolveWebServer(ctx) {
+  return ctx.get('webServer') ?? ctx.get('httpServer');
+}
+
+/**
+ * Build the `ctx.dshLoader.web` stable API.
+ * @param {{ ctx: object }} opts
+ */
+export function createWebAPI({ ctx }) {
+  function server() {
+    const web = resolveWebServer(ctx);
+    if (web === undefined || typeof web.register !== 'function') {
+      throw new DshLoaderWebError(
+        `${LOG_PREFIX}:web webServer service unavailable`,
+      );
+    }
+    return web;
+  }
+
+  return {
+    register(prefix, handler) {
+      const web = server();
+      return web.register({ kind: 'prefix', path: prefix, handler }) ?? (() => {});
+    },
+    get(path, handler) {
+      const web = server();
+      return web.register({ kind: 'route', method: 'GET', path, handler }) ?? (() => {});
+    },
+    post(path, handler) {
+      const web = server();
+      return web.register({ kind: 'route', method: 'POST', path, handler }) ?? (() => {});
+    },
+    use(middleware) {
+      const web = server();
+      return web.register({ kind: 'middleware', handler: middleware }) ?? (() => {});
+    },
+    /**
+     * Register a WebSocket upgrade route for an exact pathname.
+     * Proxies to `webServer.registerUpgrade({ path, handler })`.
+     *
+     * @param {{ path: string, handler: (req: any, socket: any, head: Buffer) => void }} route
+     * @returns {() => void} dispose function that removes the upgrade route
+     */
+    registerUpgrade(route) {
+      const web = server();
+      if (typeof web.registerUpgrade !== 'function') {
+        throw new DshLoaderWebError(
+          `${LOG_PREFIX}:web.registerUpgrade webServer does not support upgrade routes (registerUpgrade missing)`,
+        );
+      }
+      return web.registerUpgrade(route) ?? (() => {});
+    },
+  };
+}