dsh-github-router 0.3.2 → 0.4.0

package/lib/config.js

@@ -1,116 +1,167 @@
-/**
- * Settings schema and runtime-option resolution for dsh-github-router.
- *
- * The settings section (`dsh-github-router` namespace) is registered through
- * the official settings seam (`ctx.settings.register`, see `lib/settings.js`);
- * the Settings UI renders a plugin card for it (Settings → Plugins, DSH ≥
- * 0.1.0-rc.7). Secrets are declared with `.role('secret')` so they are
- * redacted on every wire boundary and rendered as write-only inputs.
- *
- * The schema is deliberately FLAT: the client settings scope writes scalar
- * fields by name (`scope.set(field, value)`), so nested objects cannot be
- * edited from the card. `resolveOptions` projects the flat section into the
- * nested runtime shape the core aggregators use.
- * @module dsh-github-router/config
- */
-import z from '@deepseek-ai/schemastery'
-
-/**
- * Settings namespace carrying the plugin's configuration.
- *
- * Since DSH 0.1.2-alpha.4 the namespace is a plain lowercase-hyphenated
- * string: `SettingsNamespace` is a type-only export and the runtime
- * `settingsNamespace()` helper was removed from the public API, with the
- * pattern check internalised in `ctx.settings.register`.
- */
-export const NAMESPACE = 'dsh-github-router'
-
-/** Composition/settings schema. All fields optional with safe defaults. */
-export const Config = z.object({
-  /** Literal GitHub token (redacted on wire). Prefer tokenEnv. */
-  token: z.string().role('secret'),
-  /** Environment variable / credential ref naming the token. */
-  tokenEnv: z.string().role('credential-ref').default('GITHUB_TOKEN'),
-  /** Proxy URL for proxy routes. '' = inherit ambient proxy env; 'direct' = never proxy. */
-  proxy: z.string().default(''),
-  directTimeoutMs: z.number().min(1000).max(60000).default(8000),
-  proxyTimeoutMs: z.number().min(1000).max(60000).default(15000),
-  /** Retries for idempotent GETs on 429/5xx. */
-  retries: z.number().min(0).max(3).default(1),
-  routesApi: z.boolean().default(true),
-  routesGh: z.boolean().default(true),
-  routesGit: z.boolean().default(true),
-  routesHtml: z.boolean().default(true),
-  /** Raw-content mirrors: OFF by default — the user must opt in. */
-  routesMirror: z.boolean().default(false),
-  /** Raw-content mirror base URLs, e.g. ["https://ghproxy.net"]. Empty = none. */
-  mirrors: z.array(z.string()).default([]),
-  /** PR/issue metadata cache TTL. */
-  cacheTtlMeta: z.number().min(0).default(300),
-  /** Immutable-ish content (files, commits, diffs at a sha) cache TTL. */
-  cacheTtlContent: z.number().min(0).default(86400),
-  /** Cap for every response body read by this plugin, in bytes. */
-  maxBytes: z.number().min(16384).max(8388608).default(1048576),
-  /** Local repo paths granted for read-only git-route reads (log/diff/show only). */
-  repos: z.array(z.string()).default([]),
-  /** Plugin-owned git fetch cache dir. '' = <DSH_HOME>/storages/dsh-github-router/git. */
-  gitCacheDir: z.string().default(''),
-})
-
-const PROXY_ENV_NAMES = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']
-
-/**
- * Resolve one settings/composition section into fully-defaulted runtime
- * options. A thunk-producing source is consumed at call time so a settings
- * change applies to the NEXT tool call.
- * @param section - the resolved settings section (already schema-defaulted).
- */
-export function resolveOptions(section) {
-  const s = section ?? {}
-  const proxy =
-    typeof s.proxy === 'string' && s.proxy.trim().length > 0
-      ? s.proxy.trim()
-      : undefined
-  const routes = {
-    api: s.routesApi !== false,
-    gh: s.routesGh !== false,
-    git: s.routesGit !== false,
-    html: s.routesHtml !== false,
-    mirror: s.routesMirror === true,
-  }
-  const mirrors = Array.isArray(s.mirrors)
-    ? s.mirrors.filter((m) => typeof m === 'string' && m.trim().length > 0).map((m) => m.trim())
-    : []
-  const repos = Array.isArray(s.repos)
-    ? s.repos.filter((r) => typeof r === 'string' && r.trim().length > 0).map((r) => r.trim())
-    : []
-  return {
-    token: typeof s.token === 'string' && s.token.length > 0 ? s.token : undefined,
-    tokenEnv: typeof s.tokenEnv === 'string' && s.tokenEnv.length > 0 ? s.tokenEnv : 'GITHUB_TOKEN',
-    proxy, // undefined = ambient env decides; 'direct' = never proxy
-    directTimeoutMs: Number.isFinite(s.directTimeoutMs) ? s.directTimeoutMs : 8000,
-    proxyTimeoutMs: Number.isFinite(s.proxyTimeoutMs) ? s.proxyTimeoutMs : 15000,
-    retries: Number.isFinite(s.retries) ? Math.min(3, Math.max(0, s.retries)) : 1,
-    routes,
-    mirrors,
-    cacheTtlSeconds: {
-      meta: Number.isFinite(s.cacheTtlMeta) ? s.cacheTtlMeta : 300,
-      content: Number.isFinite(s.cacheTtlContent) ? s.cacheTtlContent : 86400,
-    },
-    maxBytes: Number.isFinite(s.maxBytes) ? Math.min(8388608, Math.max(16384, s.maxBytes)) : 1048576,
-    repos,
-    gitCacheDir: typeof s.gitCacheDir === 'string' && s.gitCacheDir.trim().length > 0 ? s.gitCacheDir.trim() : undefined,
-  }
-}
-
-/** The proxy URL one route attempt uses: explicit override > ambient env > none. */
-export function effectiveProxy(options, explicit) {
-  if (explicit !== undefined && explicit !== null && explicit !== '') return explicit
-  if (options.proxy === 'direct') return undefined
-  if (options.proxy !== undefined && options.proxy !== '') return options.proxy
-  for (const name of PROXY_ENV_NAMES) {
-    const value = process.env[name]
-    if (value && value.length > 0) return value
-  }
-  return undefined
-}
+/**
+ * Plugin configuration schema and runtime-option resolution for
+ * dsh-github-router.
+ *
+ * The schema IS the settings surface. DSH reads the `Config` schema a plugin
+ * exports from its Loader entry, serves that entry's id
+ * (`dsh-github-router`) as the settings namespace to the browser, derives the
+ * configuration form from the schema, validates every write against it, and
+ * redacts `.role('secret')` fields on every wire boundary. There is no
+ * registration call anymore — `lib/settings.js` only reads the live values.
+ *
+ * Every field is `.volatile()`, which is what makes it editable from the
+ * configuration page AND live: the framework hands the plugin a Volatile
+ * reference whose `.get()` is the current value (user layer over composition
+ * layer over schema default), and a saved write applies to the NEXT tool call.
+ *
+ * The schema is deliberately FLAT: the plugin's card writes scalar fields by
+ * name, so nested objects cannot be edited from it. `resolveOptions` projects
+ * the flat section into the nested runtime shape the core aggregators use.
+ * @module dsh-github-router/config
+ */
+import z from '@deepseek-ai/schemastery'
+
+/**
+ * Settings namespace carrying the plugin's configuration.
+ *
+ * Since DSH 0.1.7-rc.2 the namespace is the Loader entry id the bundle patch
+ * declares (`cordis.patch.yml` inserts the row as `dsh-github-router`); the
+ * browser half addresses the same string through `ctx.configForms.get(...)`
+ * and keys its Plugins-page card with it.
+ */
+export const NAMESPACE = 'dsh-github-router'
+
+/** Composition/settings schema. All fields optional with safe defaults. */
+export const Config = z.object({
+  /** Literal GitHub token (redacted on wire). Prefer tokenEnv. */
+  token: z.string().role('secret').volatile(),
+  /** Environment variable / credential ref naming the token. */
+  tokenEnv: z.string().role('credential-ref').default('GITHUB_TOKEN').volatile(),
+  /** Proxy URL for proxy routes. '' = inherit ambient proxy env; 'direct' = never proxy. */
+  proxy: z.string().default('').volatile(),
+  directTimeoutMs: z.number().min(1000).max(60000).default(8000).volatile(),
+  proxyTimeoutMs: z.number().min(1000).max(60000).default(15000).volatile(),
+  /** Retries for idempotent GETs on 429/5xx. */
+  retries: z.number().min(0).max(3).default(1).volatile(),
+  routesApi: z.boolean().default(true).volatile(),
+  routesGh: z.boolean().default(true).volatile(),
+  routesGit: z.boolean().default(true).volatile(),
+  routesHtml: z.boolean().default(true).volatile(),
+  /** Raw-content mirrors: OFF by default — the user must opt in. */
+  routesMirror: z.boolean().default(false).volatile(),
+  /** Raw-content mirror base URLs, e.g. ["https://ghproxy.net"]. Empty = none. */
+  mirrors: z.array(z.string()).default([]).volatile(),
+  /** PR/issue metadata cache TTL. */
+  cacheTtlMeta: z.number().min(0).default(300).volatile(),
+  /** Immutable-ish content (files, commits, diffs at a sha) cache TTL. */
+  cacheTtlContent: z.number().min(0).default(86400).volatile(),
+  /** Cap for every response body read by this plugin, in bytes. */
+  maxBytes: z.number().min(16384).max(8388608).default(1048576).volatile(),
+  /** Local repo paths granted for read-only git-route reads (log/diff/show only). */
+  repos: z.array(z.string()).default([]).volatile(),
+  /** Plugin-owned git fetch cache dir. '' = <DSH_HOME>/storages/dsh-github-router/git. */
+  gitCacheDir: z.string().default('').volatile(),
+})
+
+/** Every schema field, in the order the configuration card renders them. */
+const CONFIG_FIELDS = [
+  'token',
+  'tokenEnv',
+  'proxy',
+  'directTimeoutMs',
+  'proxyTimeoutMs',
+  'retries',
+  'routesApi',
+  'routesGh',
+  'routesGit',
+  'routesHtml',
+  'routesMirror',
+  'mirrors',
+  'cacheTtlMeta',
+  'cacheTtlContent',
+  'maxBytes',
+  'repos',
+  'gitCacheDir',
+]
+
+/**
+ * Read one live configuration section out of the config the framework passes
+ * to `apply(ctx, config)`.
+ *
+ * A `.volatile()` field arrives as a Volatile reference, so its current value
+ * is read with `.get()` at the moment of the call; a plain value (a hand-built
+ * options object, or a unit test) passes through unchanged. Reading per call is
+ * what makes a settings write apply to the next tool call.
+ * @param config - the resolved plugin config, volatile references or plain values.
+ * @returns a flat section usable by {@link resolveOptions}.
+ */
+export function liveSection(config) {
+  const source = config ?? {}
+  const section = {}
+  for (const field of CONFIG_FIELDS) {
+    const value = source[field]
+    section[field] =
+      value !== null && typeof value === 'object' && typeof value.get === 'function'
+        ? value.get()
+        : value
+  }
+  return section
+}
+
+const PROXY_ENV_NAMES = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']
+
+/**
+ * Resolve one settings/composition section into fully-defaulted runtime
+ * options. A thunk-producing source is consumed at call time so a settings
+ * change applies to the NEXT tool call.
+ * @param section - the resolved settings section (already schema-defaulted).
+ */
+export function resolveOptions(section) {
+  const s = section ?? {}
+  const proxy =
+    typeof s.proxy === 'string' && s.proxy.trim().length > 0
+      ? s.proxy.trim()
+      : undefined
+  const routes = {
+    api: s.routesApi !== false,
+    gh: s.routesGh !== false,
+    git: s.routesGit !== false,
+    html: s.routesHtml !== false,
+    mirror: s.routesMirror === true,
+  }
+  const mirrors = Array.isArray(s.mirrors)
+    ? s.mirrors.filter((m) => typeof m === 'string' && m.trim().length > 0).map((m) => m.trim())
+    : []
+  const repos = Array.isArray(s.repos)
+    ? s.repos.filter((r) => typeof r === 'string' && r.trim().length > 0).map((r) => r.trim())
+    : []
+  return {
+    token: typeof s.token === 'string' && s.token.length > 0 ? s.token : undefined,
+    tokenEnv: typeof s.tokenEnv === 'string' && s.tokenEnv.length > 0 ? s.tokenEnv : 'GITHUB_TOKEN',
+    proxy, // undefined = ambient env decides; 'direct' = never proxy
+    directTimeoutMs: Number.isFinite(s.directTimeoutMs) ? s.directTimeoutMs : 8000,
+    proxyTimeoutMs: Number.isFinite(s.proxyTimeoutMs) ? s.proxyTimeoutMs : 15000,
+    retries: Number.isFinite(s.retries) ? Math.min(3, Math.max(0, s.retries)) : 1,
+    routes,
+    mirrors,
+    cacheTtlSeconds: {
+      meta: Number.isFinite(s.cacheTtlMeta) ? s.cacheTtlMeta : 300,
+      content: Number.isFinite(s.cacheTtlContent) ? s.cacheTtlContent : 86400,
+    },
+    maxBytes: Number.isFinite(s.maxBytes) ? Math.min(8388608, Math.max(16384, s.maxBytes)) : 1048576,
+    repos,
+    gitCacheDir: typeof s.gitCacheDir === 'string' && s.gitCacheDir.trim().length > 0 ? s.gitCacheDir.trim() : undefined,
+  }
+}
+
+/** The proxy URL one route attempt uses: explicit override > ambient env > none. */
+export function effectiveProxy(options, explicit) {
+  if (explicit !== undefined && explicit !== null && explicit !== '') return explicit
+  if (options.proxy === 'direct') return undefined
+  if (options.proxy !== undefined && options.proxy !== '') return options.proxy
+  for (const name of PROXY_ENV_NAMES) {
+    const value = process.env[name]
+    if (value && value.length > 0) return value
+  }
+  return undefined
+}

package/lib/index.js

@@ -19,12 +19,12 @@
  * 4. Plugin-owned state (fetch cache, response cache) lives under
  *    <DSH_HOME>/storages/dsh-github-router; user repositories are only ever
  *    read (log/diff/show) and only when explicitly granted.
- * 5. Configuration rides the official settings seam end to end
- *    (`dsh-github-router` namespace: durable document, schema validation,
- *    revision fencing). Since DSH 0.1.0-rc.7 the framework serves every
- *    registered settings namespace to the browser and renders the plugin's
- *    configuration card in Settings → Plugins, so no plugin-owned HTTP
- *    route exists.
+ * 5. Configuration is the exported `Config` schema (DSH ≥ 0.1.7-rc.2): the
+ *    framework serves the `dsh-github-router` entry id as the settings
+ *    namespace, derives the browser page from the schema, validates and
+ *    persists writes, and redacts the secret token field on every wire
+ *    boundary. The browser half renders that page in Settings → Plugins on
+ *    the bundle's row, so no plugin-owned HTTP route exists.
  * @module dsh-github-router
  */
 import { installSettings } from './settings.js'
@@ -36,6 +36,11 @@ import { registerIssueTool } from './tools/issue.js'
 import { registerPrTool } from './tools/pr.js'
 import { registerProbeTool } from './tools/probe.js'
 
+// The framework reads this entry's `Config` export as the settings schema and
+// serves the entry id as its namespace; re-exporting keeps the schema in the
+// module the Loader checks.
+export { Config } from './config.js'
+
 export const name = 'dsh-github-router'
 export const inject = ['tools', 'subprocess', 'skills', 'systemPrompt']
 

package/lib/settings.js

@@ -1,38 +1,40 @@
 /**
  * Host-side settings wiring for dsh-github-router.
  *
- * The `dsh-github-router` namespace rides the official settings seam
- * (`ctx.settings.register`): the framework persists the section in the user
- * settings document, validates it against the schema, fences writes with
- * revisions, and redacts secret-role fields on every wire boundary.
+ * Since DSH 0.1.7-rc.2 a plugin declares its configuration by EXPORTING a
+ * `Config` schema from its Loader entry (see `lib/index.js` and
+ * `lib/config.js`): the framework serves the entry id as the settings
+ * namespace to the (loopback) browser, derives the configuration form from the
+ * schema, validates and persists every write with revision fencing, redacts
+ * `role('secret')` fields on every wire boundary, and hands the plugin Volatile
+ * references for the live values. The old
+ * `ctx.settings.register(namespace, schema, …)` seam no longer exists, so this
+ * module keeps only the two things that remain plugin-owned:
  *
- * Since DSH 0.1.0-rc.7 the api-proxy serves every registered settings
- * namespace to the (loopback) browser and the Settings → Plugins section
- * dispatches a plugin-owned card for it, so the client half binds the same
- * namespace through `ctx.settingsScope` and the plugin needs no HTTP routes
- * of its own. This module only registers the namespace and exposes the
- * runtime-options thunk the tools consume; a settings change therefore
- * applies to the NEXT tool call.
+ * 1. `configure({ auto: false })` — the plugin ships its own page
+ *    (`plugins.row.config`, see `lib/client.js`), so the framework must not
+ *    auto-generate a second one for the same namespace.
+ * 2. `options()` — project the live volatile section into the runtime options
+ *    the tools consume. The section is read per call, so a saved settings
+ *    change applies to the NEXT tool call.
  * @module dsh-github-router/settings
  */
-import { Config, NAMESPACE, resolveOptions } from './config.js'
+import { liveSection, resolveOptions } from './config.js'
 
 /**
- * Register the settings namespace and return the runtime-options thunk.
+ * Wire the plugin's settings surface and return the runtime-options thunk.
  * @param ctx - the plugin context.
- * @param config - the composition-layer config subset (the `base` layer).
+ * @param config - the config the framework resolved for this entry (volatile references).
  */
 export function installSettings(ctx, config) {
-  const holder = { scope: null }
-
   ctx.inject(['settings'], (sctx) => {
-    holder.scope = sctx.settings.register(NAMESPACE, Config, { base: config, applies: 'live' })
-    sctx.effect(() => () => {
-      holder.scope = null
-    }, 'dsh-github-router: settings scope teardown')
+    sctx.effect(
+      () => sctx.settings.configure({ auto: false }, ctx.fiber),
+      'dsh-github-router: settings presentation',
+    )
   })
 
   return {
-    options: () => (holder.scope !== null ? resolveOptions(holder.scope.get()) : resolveOptions(config)),
+    options: () => resolveOptions(liveSection(config)),
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-github-router",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "DeepSeek Harness plugin: read-only GitHub access for agents (github_probe / github_pr / github_issue / github_file / github_api). Routes every request inside the tool — api.github.com (direct or proxy), gh CLI, git protocol (plugin-owned fetch cache plus read-only local repo reads), PR/issue page HTML with strict JSON embeddedData extraction, and optional user-configured raw mirrors — so agents never burn turns fighting sandbox TLS/proxy failures in a shell. No write/push capability exists anywhere in the plugin.",
   "keywords": [
     "dsh-plugin",
@@ -47,36 +47,30 @@
   ],
   "dsh": {
     "compatibility": {
-      "node": ">=20",
+      "node": ">=22.19.0",
       "dshReleases": {
-        "0.1.2-alpha.4": "compatible",
-        "0.1.2-alpha.1": "compatible",
-        "0.1.1-rc.2": "incompatible"
+        "0.1.7-rc.2": "compatible",
+        "0.1.2-alpha.4": "incompatible"
       }
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-store"
-      ]
+      "platform": "web"
     }
   },
   "engines": {
-    "node": ">=20.18.0"
+    "node": ">=22.19.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-credentials": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.1"
+    "@deepseek-ai/cordis": "^4.0.4"
   },
   "publishConfig": {
     "access": "public"