dsh-github-router 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,56 +1,70 @@
-# Changelog
-
-All notable changes to this project are documented in this file.
-
-The format is based on [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.3.1] - 2026-08-28
-
-### Fixed
-
-- Boot with DSH 0.1.2-alpha.4
-
-## [0.3.0] - 2026-08-28
-
-### Changed
-
-- Adapted to DeepSeek Harness 0.1.2-alpha.1
-
-## [0.2.1] - 2026-08-28
-
-### Changed
-
-- Declare compatibility for dsh 0.1.1-rc.2
-
-## [0.2.0] - 2026-08-21
-
-### Changed
-
-- **Migrated plugin configuration to the framework's plugin-settings mechanism** (requires DSH ≥ 0.1.0-rc.7, which serves every registered settings namespace and dispatches plugin-owned configuration cards). The browser half now registers a `settings.plugin.item` card keyed by the `dsh-github-router` namespace inside Settings → Plugins, bound through `ctx.settingsScope` (shared describe mirror, revision fencing, recovery reads, reconnect invalidation); the plugin-owned `/dsh-github-router/config` web routes and the standalone `settings.section` page are removed. The Host keeps the same `settings.register` seam and adds `applies: 'live'`.
-- The token control is now a true write-only field: the configured state comes from the describe mirror's secret slot list (badge: "已配置/configured"), a typed value writes the token, and a blank save clears a configured one.
-- Runtime requirements: the settings card needs DSH ≥ 0.1.0-rc.7; the Host-side settings seam alone still works on older compositions (tools resolve the composition config as before).
-
-## [0.1.0] - 2026-08-19
-
-First release.
-
-### Added
-
-- Five read-only model tools: `github_probe`, `github_pr`, `github_issue`, `github_file`, `github_api`
-- In-tool route ladder: api.github.com (direct → CONNECT-tunnel proxy) → gh CLI (read-only subcommands) → git protocol (plugin fetch cache + read-only local repo reads) → PR/issue page HTML (strict `react-app.embeddedData` JSON extraction) → user-configured raw mirrors (off by default), with per-part route attribution on every result
-- `github_probe` connectivity matrix with per-route timings and a recommended route chain
-- TTL response cache with atomic writes and corruption-tolerant reads
-- Settings: the `dsh-github-router` namespace on the official settings seam (secret token / `tokenEnv` credential ref, proxy, route switches, cache TTLs, byte caps, granted local repos), an independent Settings page (the dsh-notification `settings.section` mechanism; common fields up top, the long tail in a collapsed "Advanced settings" disclosure), and plugin-owned `/dsh-github-router/config` web routes (the dsh-market pattern) with same-origin enforcement and revision fencing
-- `github-router` skill and a system-prompt guidance section (order 118)
-- Zero runtime dependencies: zero-dependency CONNECT tunnel for proxied requests; peers resolve from the DSH profile
-- 72 offline tests (`node --test`) covering extraction, guards, cache, tunnel, tool wiring, client bundle, config routes, and localization compliance
-- Documentation: bilingual README, SECURITY, design notes, and a development guide
-
-### Security
-
-- Read-only by construction: no write/push/comment/mutation verb exists anywhere
-- Tokens attach only to api.github.com and are redacted on every wire boundary
-- Page HTML is parsed with `JSON.parse` only (never evaluated); a bounded BFS copies a whitelist of fields
-- Subprocess calls are argv arrays with fixed flag lists — no shell interpolation
-- Configuration writes require same-origin POSTs and are body-capped
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [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.3.2] - 2026-09-08
+
+### Fixed
+
+- The `gh` route now builds valid arguments for its viewers.
+- The `gh` route now returns the metadata URL field.
+- The proxy transport now decodes chunked responses.
+- The html route now handles the current GitHub pull request page payload.
+- Fallback routes are now entered only when a part could not be fetched.
+
+### Added
+
+- Offline regression tests for the `gh` route, chunked decoding, and failover gating.
+
+## [0.3.1] - 2026-08-28
+
+### Fixed
+
+- Boot with DSH 0.1.2-alpha.4
+
+## [0.3.0] - 2026-08-28
+
+### Changed
+
+- Adapted to DeepSeek Harness 0.1.2-alpha.1
+
+## [0.2.1] - 2026-08-28
+
+### Changed
+
+- Declare compatibility for dsh 0.1.1-rc.2
+
+## [0.2.0] - 2026-08-21
+
+### Changed
+
+- **Migrated plugin configuration to the framework's plugin-settings mechanism** (requires DSH ≥ 0.1.0-rc.7, which serves every registered settings namespace and dispatches plugin-owned configuration cards). The browser half now registers a `settings.plugin.item` card keyed by the `dsh-github-router` namespace inside Settings → Plugins, bound through `ctx.settingsScope` (shared describe mirror, revision fencing, recovery reads, reconnect invalidation); the plugin-owned `/dsh-github-router/config` web routes and the standalone `settings.section` page are removed. The Host keeps the same `settings.register` seam and adds `applies: 'live'`.
+- The token control is now a true write-only field: the configured state comes from the describe mirror's secret slot list (badge: "已配置/configured"), a typed value writes the token, and a blank save clears a configured one.
+- Runtime requirements: the settings card needs DSH ≥ 0.1.0-rc.7; the Host-side settings seam alone still works on older compositions (tools resolve the composition config as before).
+
+## [0.1.0] - 2026-08-19
+
+First release.
+
+### Added
+
+- Five read-only model tools: `github_probe`, `github_pr`, `github_issue`, `github_file`, `github_api`
+- In-tool route ladder: api.github.com (direct → CONNECT-tunnel proxy) → gh CLI (read-only subcommands) → git protocol (plugin fetch cache + read-only local repo reads) → PR/issue page HTML (strict `react-app.embeddedData` JSON extraction) → user-configured raw mirrors (off by default), with per-part route attribution on every result
+- `github_probe` connectivity matrix with per-route timings and a recommended route chain
+- TTL response cache with atomic writes and corruption-tolerant reads
+- Settings: the `dsh-github-router` namespace on the official settings seam (secret token / `tokenEnv` credential ref, proxy, route switches, cache TTLs, byte caps, granted local repos), an independent Settings page (the dsh-notification `settings.section` mechanism; common fields up top, the long tail in a collapsed "Advanced settings" disclosure), and plugin-owned `/dsh-github-router/config` web routes (the dsh-market pattern) with same-origin enforcement and revision fencing
+- `github-router` skill and a system-prompt guidance section (order 118)
+- Zero runtime dependencies: zero-dependency CONNECT tunnel for proxied requests; peers resolve from the DSH profile
+- 72 offline tests (`node --test`) covering extraction, guards, cache, tunnel, tool wiring, client bundle, config routes, and localization compliance
+- Documentation: bilingual README, SECURITY, design notes, and a development guide
+
+### Security
+
+- Read-only by construction: no write/push/comment/mutation verb exists anywhere
+- Tokens attach only to api.github.com and are redacted on every wire boundary
+- Page HTML is parsed with `JSON.parse` only (never evaluated); a bounded BFS copies a whitelist of fields
+- Subprocess calls are argv arrays with fixed flag lists — no shell interpolation
+- Configuration writes require same-origin POSTs and are body-capped

package/docs/design.md

@@ -189,9 +189,11 @@ within one host process.
 
 ## Known limitations
 
-- **Fallback routes are unexercised while the API is healthy.** The ladder
-  is failover, not fan-out: when api succeeds, gh/html/git are not called
-  (saving quota). Forcing a specific route per call is not yet supported.
+- **Fallback routes are failover, not fan-out.** A ladder is entered only
+  when a part could not be fetched by the route above it: a successfully
+  fetched empty list (an issue with no comments, a PR with no reviews) is
+  authoritative and does not trigger gh/html/git, saving quota. Forcing a
+  specific route per call is not yet supported.
 - **Anonymous quota is shared per IP** (60 req/h). A PR aggregation costs
   up to six calls. Token configuration is the intended mitigation; the
   cache is the second line.

package/lib/core/issue.js

@@ -1,202 +1,212 @@
-/**
- * Issue aggregation: api.github.com → gh CLI → page HTML, with per-part
- * route attribution and structured failure.
- * @module dsh-github-router/core/issue
- */
-import { ghAuthed, ghIssueView, ghVersion } from '../routes/gh.js'
-import { fetchAndParsePage } from '../routes/html.js'
-import { guardByteCount, guardOwnerRepo, guardPrNumber, truncateText } from '../util.js'
-import { attemptLadder, buildRuntime, rateNote } from './runtime.js'
-
-const BODY_CAP = 20000
-
-function shapeApiIssue(meta, owner, repo, number) {
-  return {
-    owner,
-    repo,
-    number,
-    title: meta.title ?? null,
-    body: truncateText(meta.body ?? '', BODY_CAP).text,
-    state: meta.state ?? null,
-    stateReason: meta.state_reason ?? null,
-    author: meta.user && meta.user.login ? meta.user.login : null,
-    createdAt: meta.created_at ?? null,
-    updatedAt: meta.updated_at ?? null,
-    closedAt: meta.closed_at ?? null,
-    commentsCount: meta.comments ?? null,
-    labels: Array.isArray(meta.labels) ? meta.labels.map((l) => l.name ?? null).filter((n) => n !== null) : [],
-    url: meta.html_url ?? null,
-  }
-}
-
-function shapeGhIssue(json, owner, repo, number) {
-  return {
-    owner,
-    repo,
-    number,
-    title: json.title ?? null,
-    body: truncateText(json.body ?? '', BODY_CAP).text,
-    state: json.state ?? null,
-    stateReason: json.stateReason ?? null,
-    author: json.author && json.author.login ? json.author.login : null,
-    createdAt: json.createdAt ?? null,
-    updatedAt: json.updatedAt ?? null,
-    closedAt: json.closedAt ?? null,
-    commentsCount: Array.isArray(json.comments) ? json.comments.length : null,
-    labels: Array.isArray(json.labels) ? json.labels.map((l) => (typeof l === 'string' ? l : l.name ?? null)).filter((n) => n !== null) : [],
-    url: null,
-  }
-}
-
-function capItems(items, maxItems, notes, label) {
-  if (items.length <= maxItems) return items
-  notes.push(`${label}: showing ${maxItems} of ${items.length}`)
-  return items.slice(0, maxItems)
-}
-
-export async function aggregateIssue(ctx, options, args) {
-  const owner = guardOwnerRepo(args.owner, 'owner')
-  const repo = guardOwnerRepo(args.repo, 'repo')
-  const number = guardPrNumber(args.number, 'number')
-  const maxComments = guardByteCount(args.maxComments, 'maxComments', 50, 5, 200)
-  const forceRefresh = args.forceRefresh === true
-  const { signal } = args
-
-  const runtime = buildRuntime(ctx, options)
-  const { subprocess, fetchImpl, cache, api } = runtime
-  const token = await runtime.resolveToken()
-  const state = {
-    issue: null,
-    comments: [],
-    routes: { meta: null, comments: null },
-    notes: [],
-  }
-
-  if (options.routes.api) {
-    try {
-      const attempt = await attemptLadder(
-        (proxy) =>
-          api.getJson(`/repos/${owner}/${repo}/issues/${number}`, {
-            token,
-            signal,
-            proxy,
-            cache,
-            ttlMs: options.cacheTtlSeconds.meta,
-            forceRefresh,
-            fetchImpl,
-          }),
-        options,
-      )
-      state.issue = shapeApiIssue(attempt.value, owner, repo, number)
-      state.routes.meta = 'api'
-      rateNote(attempt.value._headers, state.notes)
-    } catch (error) {
-      state.notes.push(`api issue: ${String(error && error.message ? error.message : error).slice(0, 220)}`)
-    }
-  }
-
-  if (state.issue !== null) {
-    try {
-      const attempt = await attemptLadder(
-        (proxy) =>
-          api.getJson(`/repos/${owner}/${repo}/issues/${number}/comments`, {
-            token,
-            signal,
-            proxy,
-            cache,
-            ttlMs: options.cacheTtlSeconds.meta,
-            forceRefresh,
-            fetchImpl,
-            query: { per_page: 100 },
-          }),
-        options,
-      )
-      state.comments = capItems(
-        (Array.isArray(attempt.value) ? attempt.value : []).map((c) => ({
-          kind: 'comment',
-          author: c.user && c.user.login ? c.user.login : null,
-          createdAt: c.created_at ?? null,
-          body: truncateText(c.body ?? '', BODY_CAP).text,
-          url: c.html_url ?? null,
-        })),
-        maxComments,
-        state.notes,
-        'comments',
-      )
-      state.routes.comments = 'api'
-    } catch (error) {
-      state.notes.push(`api comments: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
-    }
-  }
-
-  if (options.routes.gh && subprocess !== undefined && (state.issue === null || state.comments.length === 0)) {
-    let ghUsable = false
-    try {
-      ghUsable = (await ghVersion(subprocess, signal)) && (await ghAuthed(subprocess, signal))
-    } catch { ghUsable = false }
-    if (ghUsable) {
-      try {
-        const g = await ghIssueView(subprocess, owner, repo, number, { signal })
-        if (state.issue === null) {
-          state.issue = shapeGhIssue(g, owner, repo, number)
-          state.routes.meta = 'gh'
-        }
-        if (state.comments.length === 0 && Array.isArray(g.comments)) {
-          state.comments = capItems(
-            g.comments.map((c) => ({
-              kind: 'comment',
-              author: c.author && c.author.login ? c.author.login : null,
-              createdAt: c.createdAt ?? null,
-              body: truncateText(c.body ?? '', BODY_CAP).text,
-              url: c.url ?? null,
-            })),
-            maxComments,
-            state.notes,
-            'comments',
-          )
-          state.routes.comments = 'gh'
-        }
-      } catch (error) {
-        state.notes.push(`gh issue view: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
-      }
-    } else {
-      state.notes.push('gh route skipped: gh CLI not installed or not authenticated')
-    }
-  }
-
-  if (options.routes.html && (state.issue === null || state.comments.length === 0)) {
-    try {
-      await attemptLadder(
-        async (proxy) => {
-          const parsed = await fetchAndParsePage(owner, repo, number, 'issues', {
-            fetchImpl,
-            proxy,
-            signal,
-            timeoutMs: proxy !== undefined ? options.proxyTimeoutMs : options.directTimeoutMs,
-          })
-          if (state.issue === null && parsed.issue !== null) {
-            state.issue = { ...parsed.issue, owner, repo, number }
-            state.routes.meta = 'html'
-          }
-          if (state.comments.length === 0 && parsed.discussion.length > 0) {
-            state.comments = capItems(parsed.discussion, maxComments, state.notes, 'comments')
-            state.routes.comments = 'html'
-          }
-        },
-        options,
-        { proxyFirst: true },
-      )
-    } catch (error) {
-      state.notes.push(`html page: ${String(error && error.message ? error.message : error).slice(0, 220)}`)
-    }
-  }
-
-  if (state.issue === null) {
-    return {
-      error: `all GitHub routes failed to load issue ${owner}/${repo}#${number}`,
-      routes: state.routes,
-      notes: state.notes,
-    }
-  }
-  return { issue: state.issue, comments: state.comments, routes: state.routes, notes: state.notes }
-}
+/**
+ * Issue aggregation: api.github.com → gh CLI → page HTML, with per-part
+ * route attribution and structured failure.
+ * @module dsh-github-router/core/issue
+ */
+import { ghAuthed, ghIssueView, ghVersion } from '../routes/gh.js'
+import { fetchAndParsePage } from '../routes/html.js'
+import { guardByteCount, guardOwnerRepo, guardPrNumber, truncateText } from '../util.js'
+import { attemptLadder, buildRuntime, rateNote } from './runtime.js'
+
+const BODY_CAP = 20000
+
+function shapeApiIssue(meta, owner, repo, number) {
+  return {
+    owner,
+    repo,
+    number,
+    title: meta.title ?? null,
+    body: truncateText(meta.body ?? '', BODY_CAP).text,
+    state: meta.state ?? null,
+    stateReason: meta.state_reason ?? null,
+    author: meta.user && meta.user.login ? meta.user.login : null,
+    createdAt: meta.created_at ?? null,
+    updatedAt: meta.updated_at ?? null,
+    closedAt: meta.closed_at ?? null,
+    commentsCount: meta.comments ?? null,
+    labels: Array.isArray(meta.labels) ? meta.labels.map((l) => l.name ?? null).filter((n) => n !== null) : [],
+    url: meta.html_url ?? null,
+  }
+}
+
+function shapeGhIssue(json, owner, repo, number) {
+  return {
+    owner,
+    repo,
+    number,
+    title: json.title ?? null,
+    body: truncateText(json.body ?? '', BODY_CAP).text,
+    state: json.state ?? null,
+    stateReason: json.stateReason ?? null,
+    author: json.author && json.author.login ? json.author.login : null,
+    createdAt: json.createdAt ?? null,
+    updatedAt: json.updatedAt ?? null,
+    closedAt: json.closedAt ?? null,
+    commentsCount: Array.isArray(json.comments) ? json.comments.length : null,
+    labels: Array.isArray(json.labels) ? json.labels.map((l) => (typeof l === 'string' ? l : l.name ?? null)).filter((n) => n !== null) : [],
+    url: json.url ?? null,
+  }
+}
+
+function capItems(items, maxItems, notes, label) {
+  if (items.length <= maxItems) return items
+  notes.push(`${label}: showing ${maxItems} of ${items.length}`)
+  return items.slice(0, maxItems)
+}
+
+export async function aggregateIssue(ctx, options, args) {
+  const owner = guardOwnerRepo(args.owner, 'owner')
+  const repo = guardOwnerRepo(args.repo, 'repo')
+  const number = guardPrNumber(args.number, 'number')
+  const maxComments = guardByteCount(args.maxComments, 'maxComments', 50, 5, 200)
+  const forceRefresh = args.forceRefresh === true
+  const { signal } = args
+
+  const runtime = buildRuntime(ctx, options)
+  const { subprocess, fetchImpl, cache, api } = runtime
+  const token = await runtime.resolveToken()
+  const state = {
+    issue: null,
+    comments: [],
+    routes: { meta: null, comments: null },
+    notes: [],
+    // Which parts a route actually served. A successfully fetched empty
+    // list is authoritative and must NOT trigger a fallback ladder — the
+    // routes are failover, not fan-out (docs/design.md).
+    fetched: { meta: false, comments: false },
+  }
+
+  if (options.routes.api) {
+    try {
+      const attempt = await attemptLadder(
+        (proxy) =>
+          api.getJson(`/repos/${owner}/${repo}/issues/${number}`, {
+            token,
+            signal,
+            proxy,
+            cache,
+            ttlMs: options.cacheTtlSeconds.meta,
+            forceRefresh,
+            fetchImpl,
+          }),
+        options,
+      )
+      state.issue = shapeApiIssue(attempt.value, owner, repo, number)
+      state.routes.meta = 'api'
+      state.fetched.meta = true
+      rateNote(attempt.value._headers, state.notes)
+    } catch (error) {
+      state.notes.push(`api issue: ${String(error && error.message ? error.message : error).slice(0, 220)}`)
+    }
+  }
+
+  if (state.issue !== null) {
+    try {
+      const attempt = await attemptLadder(
+        (proxy) =>
+          api.getJson(`/repos/${owner}/${repo}/issues/${number}/comments`, {
+            token,
+            signal,
+            proxy,
+            cache,
+            ttlMs: options.cacheTtlSeconds.meta,
+            forceRefresh,
+            fetchImpl,
+            query: { per_page: 100 },
+          }),
+        options,
+      )
+      state.comments = capItems(
+        (Array.isArray(attempt.value) ? attempt.value : []).map((c) => ({
+          kind: 'comment',
+          author: c.user && c.user.login ? c.user.login : null,
+          createdAt: c.created_at ?? null,
+          body: truncateText(c.body ?? '', BODY_CAP).text,
+          url: c.html_url ?? null,
+        })),
+        maxComments,
+        state.notes,
+        'comments',
+      )
+      state.routes.comments = 'api'
+      state.fetched.comments = true
+    } catch (error) {
+      state.notes.push(`api comments: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+    }
+  }
+
+  if (options.routes.gh && subprocess !== undefined && (state.issue === null || !state.fetched.comments)) {
+    let ghUsable = false
+    try {
+      ghUsable = (await ghVersion(subprocess, signal)) && (await ghAuthed(subprocess, signal))
+    } catch { ghUsable = false }
+    if (ghUsable) {
+      try {
+        const g = await ghIssueView(subprocess, owner, repo, number, { signal })
+        if (state.issue === null) {
+          state.issue = shapeGhIssue(g, owner, repo, number)
+          state.routes.meta = 'gh'
+          state.fetched.meta = true
+        }
+        if (!state.fetched.comments && Array.isArray(g.comments)) {
+          state.comments = capItems(
+            g.comments.map((c) => ({
+              kind: 'comment',
+              author: c.author && c.author.login ? c.author.login : null,
+              createdAt: c.createdAt ?? null,
+              body: truncateText(c.body ?? '', BODY_CAP).text,
+              url: c.url ?? null,
+            })),
+            maxComments,
+            state.notes,
+            'comments',
+          )
+          state.routes.comments = 'gh'
+          state.fetched.comments = true
+        }
+      } catch (error) {
+        state.notes.push(`gh issue view: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+      }
+    } else {
+      state.notes.push('gh route skipped: gh CLI not installed or not authenticated')
+    }
+  }
+
+  if (options.routes.html && (state.issue === null || !state.fetched.comments)) {
+    try {
+      await attemptLadder(
+        async (proxy) => {
+          const parsed = await fetchAndParsePage(owner, repo, number, 'issues', {
+            fetchImpl,
+            proxy,
+            signal,
+            timeoutMs: proxy !== undefined ? options.proxyTimeoutMs : options.directTimeoutMs,
+          })
+          if (state.issue === null && parsed.issue !== null) {
+            state.issue = { ...parsed.issue, owner, repo, number }
+            state.routes.meta = 'html'
+            state.fetched.meta = true
+          }
+          if (!state.fetched.comments && parsed.discussion.length > 0) {
+            state.comments = capItems(parsed.discussion, maxComments, state.notes, 'comments')
+            state.routes.comments = 'html'
+            state.fetched.comments = true
+          }
+        },
+        options,
+        { proxyFirst: true },
+      )
+    } catch (error) {
+      state.notes.push(`html page: ${String(error && error.message ? error.message : error).slice(0, 220)}`)
+    }
+  }
+
+  if (state.issue === null) {
+    return {
+      error: `all GitHub routes failed to load issue ${owner}/${repo}#${number}`,
+      routes: state.routes,
+      notes: state.notes,
+    }
+  }
+  return { issue: state.issue, comments: state.comments, routes: state.routes, notes: state.notes }
+}