dsh-zen-remote 1.1.16 → 2.0.0

package/scripts/check-shares.mjs

@@ -0,0 +1,397 @@
+// Behaviour check for the T33b(+fix) session-sharing client data
+// (src/client-data/shares.ts), driven against the REAL admin/shares shapes
+// src/admin-routes.ts answers: `GET` → { ok, shares:[{ sessionId, sharedAt,
+// lastActivityAt, busy, remainingMs(null=忙碌), viewers, title }] }, `POST`
+// → { action, sessionId? } answered with { ok }. Covers the tolerant body
+// parse, describeShare's three states and countdown text (hours / minutes /
+// busy, with local decay from the parse stamp), and the shared store against
+// a FAKE fetch: the role gate (unknown wires nothing / client never polls /
+// host pulls immediately and a client→host flip recovers), latest-wins
+// sequencing, one-failed-round-only error semantics (404 included),
+// visibility-shaped polling, and POST-then-refresh for all three actions.
+//
+// Run: node scripts/check-shares.mjs   (needs Node >= 23.6 type stripping)
+import assert from 'node:assert/strict'
+import {
+  ADMIN_SHARES_ROUTE,
+  createSharesStore,
+  createZhShareFormatter,
+  describeShare,
+  documentVisibility,
+  parseSharesBody,
+  shareFailText,
+  SHARES_POLL_MS,
+} from '../src/client-data/shares.ts'
+
+// Tiny sequential runner so the file stays plain node:assert (no node:test import).
+let testChain = Promise.resolve()
+function test(name, fn) {
+  testChain = testChain
+    .then(fn)
+    .then(() => { console.log(`ok - ${name}`) })
+    .catch((error) => {
+      console.error(`not ok - ${name}`)
+      throw error
+    })
+  return testChain
+}
+
+const NOW = 1_700_000_000_000
+const HOUR = 3_600_000
+const MINUTE = 60_000
+const t = createZhShareFormatter()
+
+// ---- 1. parseSharesBody -----------------------------------------------------
+
+test('parseSharesBody: tolerant of garbage, drops broken rows, stamps asOf', () => {
+  assert.deepEqual(parseSharesBody(undefined, NOW), [])
+  assert.deepEqual(parseSharesBody(null, NOW), [])
+  assert.deepEqual(parseSharesBody({ ok: true }, NOW), [])
+  assert.deepEqual(parseSharesBody({ ok: true, shares: 'nope' }, NOW), [])
+  const entries = parseSharesBody({
+    ok: true,
+    shares: [
+      {
+        sessionId: 's1', sharedAt: NOW - 99, lastActivityAt: NOW - 5 * MINUTE,
+        busy: false, remainingMs: 31.4 * HOUR, viewers: 2, title: 'Refactor the gateway',
+      },
+      { sessionId: 's2', busy: true, remainingMs: null, title: null },
+      { sessionId: '', title: 'dropped' },
+      null,
+      { title: 'no id' },
+      { sessionId: 's3', busy: 'yes', remainingMs: 'x', viewers: -3, title: 42 },
+    ],
+  }, NOW)
+  assert.equal(entries.length, 3)
+  assert.deepEqual(entries[0], {
+    sessionId: 's1', sharedAt: NOW - 99, lastActivityAt: NOW - 5 * MINUTE,
+    busy: false, remainingMs: 31.4 * HOUR, viewers: 2, title: 'Refactor the gateway', asOf: NOW,
+  })
+  // busy: remainingMs null reads busy even without the flag.
+  assert.equal(entries[1].busy, true)
+  assert.equal(entries[1].title, null)
+  // Garbage fields fall back, never throw. A garbage remainingMs reads null,
+  // and null is the wire's busy mark — so the row counts as busy, matching
+  // how respondShares encodes it.
+  assert.equal(entries[2].busy, true)
+  assert.equal(entries[2].remainingMs, null)
+  assert.equal(entries[2].viewers, 0)
+  assert.equal(entries[2].title, null)
+  assert.equal(entries[2].asOf, NOW)
+})
+
+// ---- 2. describeShare -------------------------------------------------------
+
+const entry = (over = {}) => ({
+  sessionId: 's1', sharedAt: NOW - 99, lastActivityAt: NOW - 5 * MINUTE,
+  busy: false, remainingMs: 31.4 * HOUR, viewers: 0, title: 'Refactor', asOf: NOW, ...over,
+})
+
+test('describeShare: no entry reads off', () => {
+  assert.deepEqual(describeShare(undefined, NOW, t), { state: 'off', remainingText: '未开启远程' })
+  assert.deepEqual(describeShare(null, NOW, t), { state: 'off', remainingText: '未开启远程' })
+})
+
+test('describeShare: idle countdown in hours and minutes', () => {
+  assert.deepEqual(describeShare(entry(), NOW, t), { state: 'on', remainingText: '剩余闲置时间 31 小时' })
+  assert.equal(describeShare(entry({ remainingMs: 45 * MINUTE }), NOW, t).remainingText, '剩余闲置时间 45 分钟')
+  // Exactly the hour boundary flips the unit; a tie rounds to nearest.
+  assert.equal(describeShare(entry({ remainingMs: HOUR }), NOW, t).remainingText, '剩余闲置时间 1 小时')
+  assert.equal(describeShare(entry({ remainingMs: 1.5 * HOUR }), NOW, t).remainingText, '剩余闲置时间 2 小时')
+  // Sub-minute leftovers still read as one minute, never zero.
+  assert.equal(describeShare(entry({ remainingMs: 30_000 }), NOW, t).remainingText, '剩余闲置时间 1 分钟')
+})
+
+test('describeShare: busy reads the no-countdown copy', () => {
+  assert.deepEqual(describeShare(entry({ busy: true, remainingMs: null }), NOW, t), {
+    state: 'on', remainingText: '运行中，不计时',
+  })
+  assert.equal(describeShare(entry({ remainingMs: null }), NOW, t).remainingText, '运行中，不计时')
+})
+
+test('describeShare: viewers promote on -> watched, countdown stays in the text', () => {
+  assert.equal(describeShare(entry({ viewers: 1 }), NOW, t).state, 'watched')
+  assert.equal(describeShare(entry({ viewers: 3 }), NOW, t).remainingText, '剩余闲置时间 31 小时')
+  const busyWatched = describeShare(entry({ busy: true, remainingMs: null, viewers: 1 }), NOW, t)
+  assert.equal(busyWatched.state, 'watched')
+  assert.equal(busyWatched.remainingText, '运行中，不计时')
+})
+
+test('describeShare: the countdown decays locally from the parse stamp', () => {
+  // 55 min left as of 10 min ago -> 45 min now.
+  assert.equal(
+    describeShare(entry({ remainingMs: 55 * MINUTE, asOf: NOW - 10 * MINUTE }), NOW, t).remainingText,
+    '剩余闲置时间 45 分钟',
+  )
+  // Expired locally clamps at one minute instead of going negative.
+  assert.equal(
+    describeShare(entry({ remainingMs: MINUTE, asOf: NOW - 10 * MINUTE }), NOW, t).remainingText,
+    '剩余闲置时间 1 分钟',
+  )
+})
+
+// ---- 3. the store -----------------------------------------------------------
+
+/** One fake Response-shaped body. */
+const jsonRes = (status, body) => ({
+  ok: status >= 200 && status < 300,
+  status,
+  json: async () => body,
+})
+
+/** A fake fetch recording every call; programs replies from a queue. */
+function fakeFetch(replies) {
+  const calls = []
+  const queue = [...replies]
+  const fetchImpl = async (input, init) => {
+    calls.push({ input, init: init ?? null })
+    const next = queue.shift()
+    if (typeof next === 'function') return next(calls.length)
+    if (next !== undefined) return next
+    return jsonRes(200, { ok: true, shares: [] })
+  }
+  fetchImpl.calls = calls
+  fetchImpl.queue = queue
+  return fetchImpl
+}
+
+const bodyOf = (calls, index) => JSON.parse(calls[index]?.init?.body ?? 'null')
+
+const SHARES = [
+  { sessionId: 's1', sharedAt: NOW, lastActivityAt: NOW - MINUTE, busy: false, remainingMs: 2 * HOUR, viewers: 0, title: 'One' },
+  { sessionId: 's2', sharedAt: NOW, lastActivityAt: NOW, busy: true, remainingMs: null, viewers: 1, title: 'Two' },
+]
+
+test('refresh: ok body lands as ready, entries parsed', async () => {
+  const store = createSharesStore(fakeFetch([jsonRes(200, { ok: true, shares: SHARES })]))
+  store.setRole('host')
+  assert.equal(store.getSnapshot().ready, false)
+  assert.equal(await store.refresh(), true)
+  const snap = store.getSnapshot()
+  assert.equal(snap.ready, true)
+  assert.deepEqual(snap.entries.map((row) => row.sessionId), ['s1', 's2'])
+  assert.equal(snap.entries[1].busy, true)
+})
+
+test('refresh: latest-wins — a late stale body never overwrites a newer table', async () => {
+  // First GET hangs until we release it; the second GET answers immediately.
+  let releaseFirst
+  const first = new Promise((resolve) => { releaseFirst = () => resolve(jsonRes(200, { ok: true, shares: [{ sessionId: 'STALE' }] })) })
+  const store = createSharesStore(fakeFetch([() => first, jsonRes(200, { ok: true, shares: SHARES })]))
+  store.setRole('host')
+  const slow = store.refresh()
+  const fast = store.refresh()
+  assert.equal(await fast, true)
+  assert.deepEqual(store.getSnapshot().entries.map((row) => row.sessionId), ['s1', 's2'])
+  releaseFirst()
+  assert.equal(await slow, false, 'the late stale request is dropped')
+  assert.deepEqual(
+    store.getSnapshot().entries.map((row) => row.sessionId),
+    ['s1', 's2'],
+    'the stale body did not land',
+  )
+})
+
+test('refresh: a failed GET keeps the last ready table (one failed round, no latch)', async () => {
+  const store = createSharesStore(fakeFetch([
+    jsonRes(200, { ok: true, shares: SHARES }),
+    jsonRes(500, { ok: false }),
+    jsonRes(200, { ok: false }),
+    jsonRes(200, { ok: true, shares: [{ ...SHARES[0] }] }),
+  ]))
+  store.setRole('host')
+  await store.refresh()
+  assert.equal(await store.refresh(), false)
+  assert.equal(store.getSnapshot().ready, true, 'last ready data kept')
+  assert.deepEqual(store.getSnapshot().entries.map((row) => row.sessionId), ['s1', 's2'])
+  // A 200 whose body is not ok:true is a failed load too.
+  assert.equal(await store.refresh(), false)
+  assert.equal(store.getSnapshot().ready, true)
+  // The next round asks again and lands — nothing latched anywhere.
+  assert.equal(await store.refresh(), true)
+  assert.deepEqual(store.getSnapshot().entries.map((row) => row.sessionId), ['s1'])
+})
+
+test('refresh: 404 (plugin reload window) fails its own round and the next round recovers', async () => {
+  const fetchImpl = fakeFetch([
+    jsonRes(404, { ok: false }),
+    jsonRes(404, { ok: false }),
+    jsonRes(200, { ok: true, shares: SHARES }),
+  ])
+  const store = createSharesStore(fetchImpl)
+  store.setRole('host')
+  assert.equal(await store.refresh(), false)
+  assert.equal(await store.refresh(), false, 'the second round still asks')
+  assert.equal(store.getSnapshot().ready, false, 'nothing wrong was cached')
+  assert.equal(await store.refresh(), true, 'the round after the reload answers')
+  assert.deepEqual(store.getSnapshot().entries.map((row) => row.sessionId), ['s1', 's2'])
+  assert.equal(fetchImpl.calls.length, 3, 'no request was ever suppressed')
+})
+
+test('role: unknown wires nothing — no polling, parts would render nothing', async () => {
+  const fetchImpl = fakeFetch([jsonRes(200, { ok: true, shares: SHARES })])
+  const store = createSharesStore(fetchImpl)
+  const seen = []
+  const off = store.subscribe(() => { seen.push('x') })
+  await new Promise((resolve) => setImmediate(resolve))
+  assert.equal(store.getSnapshot().role, 'unknown')
+  assert.equal(fetchImpl.calls.length, 0, 'no role wired, no request — not even the first pull')
+  assert.deepEqual(seen, [])
+  off()
+})
+
+test('role: client stops polling and hides; host starts with an immediate pull and recovers', async () => {
+  const fetchImpl = fakeFetch([
+    jsonRes(200, { ok: true, shares: SHARES }),
+    // The client→host flip pulls immediately, then the cadence answers.
+    jsonRes(200, { ok: true, shares: [] }),
+    jsonRes(200, { ok: true, shares: [] }),
+  ])
+  // 5 ms cadence: the client phases below span several tick periods, so a
+  // timer that survived the client flip cannot hide behind the 30 s default.
+  const store = createSharesStore(fetchImpl, documentVisibility, 5)
+  store.setRole('client')
+  const seen = []
+  const off = store.subscribe(() => { seen.push('x') })
+  await new Promise((resolve) => setTimeout(resolve, 25))
+  assert.equal(fetchImpl.calls.length, 0, 'a client deployment never asks — not across several tick periods')
+  assert.equal(store.getSnapshot().role, 'client')
+  // Flip to host: immediate pull, table lands, parts may render.
+  store.setRole('host')
+  await new Promise((resolve) => setTimeout(resolve, 25))
+  assert.ok(fetchImpl.calls.length >= 2, `the host flip pulled at once and the cadence ticks (saw ${fetchImpl.calls.length})`)
+  assert.equal(store.getSnapshot().role, 'host')
+  assert.equal(store.getSnapshot().ready, true)
+  // Flipping back to client hides; several tick periods later no request
+  // has fired.
+  store.setRole('client')
+  assert.equal(store.getSnapshot().role, 'client')
+  const clientAt = fetchImpl.calls.length
+  await new Promise((resolve) => setTimeout(resolve, 40))
+  assert.equal(fetchImpl.calls.length, clientAt, 'client: timer torn down, no more rounds')
+  off()
+})
+
+test('visibility: hidden starts nothing; becoming visible pulls once immediately', async () => {
+  let visible = false
+  const visibilityFans = []
+  const visibility = {
+    visible: () => visible,
+    subscribe(listener) { visibilityFans.push(listener); return () => { visibilityFans.splice(visibilityFans.indexOf(listener), 1) } },
+  }
+  const fetchImpl = fakeFetch([jsonRes(200, { ok: true, shares: SHARES })])
+  // 5 ms cadence: the hidden phase below spans several real ticks, so a
+  // tick that kept running while hidden CANNOT hide behind the 30 s default.
+  const store = createSharesStore(fetchImpl, visibility, 5)
+  store.setRole('host')
+  const off = store.subscribe(() => {})
+  await new Promise((resolve) => setImmediate(resolve))
+  assert.equal(fetchImpl.calls.length, 0, 'hidden: no first pull, timer not started')
+  // Become visible: the source fires its listeners, the store pulls at once,
+  // and the cadence really runs — let a few ticks through.
+  visible = true
+  for (const fan of [...visibilityFans]) fan()
+  await new Promise((resolve) => setTimeout(resolve, 25))
+  assert.ok(fetchImpl.calls.length >= 2, `the cadence ticks while visible (saw ${fetchImpl.calls.length})`)
+  // Hide again: the timer is really stopped — several tick periods later
+  // the count must not have moved.
+  visible = false
+  for (const fan of [...visibilityFans]) fan()
+  const hiddenAt = fetchImpl.calls.length
+  await new Promise((resolve) => setTimeout(resolve, 40))
+  assert.equal(fetchImpl.calls.length, hiddenAt, 'no request fires while the page is hidden')
+  // Back to visible: one immediate pull, then the cadence resumes.
+  visible = true
+  for (const fan of [...visibilityFans]) fan()
+  await new Promise((resolve) => setTimeout(resolve, 25))
+  assert.ok(fetchImpl.calls.length > hiddenAt, 'becoming visible pulls immediately and resumes the cadence')
+  off()
+  assert.deepEqual(visibilityFans, [], 'unsubscribed: the visibility listener went with it')
+})
+
+test('subscribe: with a role wired, the first listener starts ONE poll, the last unsubscriber stops it', async () => {
+  const fetchImpl = fakeFetch([jsonRes(200, { ok: true, shares: SHARES })])
+  // 5 ms cadence: the post-unsubscribe window below spans several tick
+  // periods, so a surviving timer cannot hide behind the 30 s default.
+  const store = createSharesStore(fetchImpl, documentVisibility, 5)
+  store.setRole('host')
+  const seen = []
+  const offA = store.subscribe(() => { seen.push('a') })
+  const offB = store.subscribe(() => { seen.push('b') })
+  // Poll cadence matches the spec; the immediate pull is already landing.
+  assert.equal(SHARES_POLL_MS, 30_000)
+  await Promise.resolve()
+  await new Promise((resolve) => setImmediate(resolve))
+  assert.equal(fetchImpl.calls.length, 1, 'exactly one poll loop for two subscribers')
+  assert.deepEqual(seen, ['a', 'b'], 'both listeners heard the snapshot change')
+  // While BOTH listen the cadence really runs.
+  await new Promise((resolve) => setTimeout(resolve, 25))
+  assert.ok(fetchImpl.calls.length >= 2, `the cadence ticks while subscribed (saw ${fetchImpl.calls.length})`)
+  offA()
+  offB()
+  const unsubscribedAt = fetchImpl.calls.length
+  // Several tick periods later the count must not have moved: the last
+  // unsubscriber really stopped the loop.
+  await new Promise((resolve) => setTimeout(resolve, 40))
+  assert.equal(fetchImpl.calls.length, unsubscribedAt, 'unsubscribed: the timer is gone, no further rounds fire')
+})
+
+test('share / unshare / unshareAll: POST the documented shapes, then refresh immediately', async () => {
+  const fetchImpl = fakeFetch([
+    jsonRes(200, { ok: true, shares: [] }),
+    // share POST reply, then the follow-up GET.
+    jsonRes(200, { ok: true }),
+    jsonRes(200, { ok: true, shares: [{ ...SHARES[0] }] }),
+    // unshare POST reply, then the follow-up GET.
+    jsonRes(200, { ok: true }),
+    jsonRes(200, { ok: true, shares: [] }),
+    // unshare-all POST reply, then the follow-up GET.
+    jsonRes(200, { ok: true }),
+    jsonRes(200, { ok: true, shares: [] }),
+  ])
+  const store = createSharesStore(fetchImpl)
+  store.setRole('host')
+  await store.refresh()
+  assert.deepEqual(await store.share('s1'), { ok: true })
+  assert.equal(fetchImpl.calls[1].init.method, 'POST')
+  assert.deepEqual(bodyOf(fetchImpl.calls, 1), { action: 'share', sessionId: 's1' })
+  assert.equal(fetchImpl.calls[2].init.method, undefined, 'the follow-up is a GET')
+  assert.deepEqual(store.getSnapshot().entries.map((row) => row.sessionId), ['s1'])
+
+  assert.deepEqual(await store.unshare('s1'), { ok: true })
+  assert.deepEqual(bodyOf(fetchImpl.calls, 3), { action: 'unshare', sessionId: 's1' })
+  assert.deepEqual(store.getSnapshot().entries, [])
+
+  assert.deepEqual(await store.unshareAll(), { ok: true })
+  assert.deepEqual(bodyOf(fetchImpl.calls, 5), { action: 'unshare-all' })
+  assert.equal(fetchImpl.calls.length, 7, 'every action refreshed right after landing')
+})
+
+test('actions: a refused POST carries the server error code, no refresh', async () => {
+  const fetchImpl = fakeFetch([
+    jsonRes(400, { ok: false, error: { code: 'subagent-session', message: 'no' } }),
+    jsonRes(500, { ok: false, error: { code: 'internal', message: 'boom' } }),
+    jsonRes(200, { ok: false }),
+  ])
+  const store = createSharesStore(fetchImpl)
+  store.setRole('host')
+  assert.deepEqual(await store.share('sub-1'), { ok: false, code: 'subagent-session', message: 'no' })
+  assert.deepEqual(await store.unshare('gone'), { ok: false, code: 'internal', message: 'boom' })
+  assert.deepEqual(await store.unshareAll(), { ok: false })
+  assert.equal(fetchImpl.calls.length, 3, 'refused actions do not refresh')
+})
+
+test('shareFailText maps the server codes to the alert copy', () => {
+  assert.equal(shareFailText({ ok: false, code: 'subagent-session' }, 'share', t), '开启远程失败：子智能体会话不能单独开启')
+  assert.equal(shareFailText({ ok: false, code: 'no-session' }, 'share', t), '开启远程失败：会话暂无内容')
+  assert.equal(shareFailText({ ok: false }, 'share', t), '操作失败，请稍后再试')
+  // Even a mappable code reads generic on unshare.
+  assert.equal(shareFailText({ ok: false, code: 'subagent-session' }, 'unshare', t), '操作失败，请稍后再试')
+})
+
+test('the route constant matches the T33a wire path', () => {
+  assert.equal(ADMIN_SHARES_ROUTE, '/_dsh/zen-remote/admin/shares')
+})
+
+await testChain
+console.log('check-shares: ok')

package/scripts/check-upload-endpoint.mjs

@@ -157,9 +157,10 @@ try {
   await rm(trapWorkspace, { recursive: true, force: true })
 
   // Every rejection that reached the body is logged once, so a failing phone
-  // leaves a trail: 2x413, 404, 3x400 query, 1x400 symlink. The 405 and 403
-  // short-circuit before the try block and deliberately log nothing — they are
-  // the two an unpaired scanner can trigger at will.
+  // leaves a trail: 2x413, 404, 3x400 query, 1x400 symlink. The 405, 403 and
+  // (T17) the admission refusals short-circuit before the try block and
+  // deliberately log nothing — they are what an unpaired scanner can trigger
+  // at will, and they would otherwise flood the log.
   assert.equal(logged, 7, `expected the rejections to be logged, saw ${logged}`)
 
   // ---- the workspace holds exactly what was uploaded, nothing partial ------
@@ -167,6 +168,61 @@ try {
     'blob.bin', 'evil.txt', 'notes-1.txt', 'notes.txt',
   ])
 
+  // ---- T17: the admission wall the apply() wiring passes in ----------------
+  // The direct drives above pass no admit; production always does (the
+  // connection service, same first wall as the admin/client routes). A
+  // refusing admit answers before anything else — no log, no disk write; an
+  // admitting one leaves every behavior unchanged.
+  // The symlink trap section pointed sessions elsewhere; point them back.
+  ctx.sessions.get = (id) => (id === 'session-live' ? { header: { cwd: workspace } } : undefined)
+  let admitted = 0
+  const admits = (admission) => createServer((req, res) => {
+    void handleUpload(ctx, MAX_BYTES, req, res, () => {
+      if (admission === 'peer') {
+        admitted += 1
+        return { peer: {} }
+      }
+      return { rejection: admission }
+    })
+  })
+  const admitServers = [admits(401), admits(403), admits('peer')].map((server) => server)
+  const admitBases = []
+  for (const server of admitServers) {
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
+    admitBases.push(`http://127.0.0.1:${server.address().port}`)
+  }
+  try {
+    for (const [i, status] of [401, 403].entries()) {
+      const denied = await fetch(`${admitBases[i]}/_dsh/mobile-nav/upload?session=session-live&name=denied.txt`, {
+        method: 'POST',
+        headers: { origin: admitBases[i] },
+        body: 'x',
+        duplex: 'half',
+      })
+      assert.equal(denied.status, status)
+      const body = await denied.json()
+      assert.equal(body.ok, false)
+      assert.equal(body.error.code, status === 401 ? 'unauthorized' : 'forbidden')
+    }
+    assert.deepEqual(await readdir(join(workspace, UPLOAD_DIR)), [
+      'blob.bin', 'evil.txt', 'notes-1.txt', 'notes.txt',
+    ], 'a refused admit writes nothing')
+    assert.equal(logged, 7, 'the admission wall short-circuits before the logger, like the 405/403')
+
+    const allowed = await fetch(`${admitBases[2]}/_dsh/mobile-nav/upload?session=session-live&name=admitted.txt`, {
+      method: 'POST',
+      headers: { origin: admitBases[2] },
+      body: 'through the wall',
+      duplex: 'half',
+    })
+    assert.equal(allowed.status, 201)
+    assert.equal((await allowed.json()).relPath, `${UPLOAD_DIR}/admitted.txt`)
+    assert.equal(admitted, 1, 'the admitting admit was consulted exactly once')
+    assert.equal(await readFile(join(workspace, UPLOAD_DIR, 'admitted.txt'), 'utf8'), 'through the wall')
+  } finally {
+    for (const server of admitServers) await new Promise((resolve) => server.close(resolve))
+  }
+
   console.log('UPLOAD ENDPOINT CHECK OK')
 } finally {
   await new Promise((resolve) => server.close(resolve))

package/scripts/sync-doc-version.mjs

@@ -13,6 +13,10 @@
  *
  * Also usable standalone: `node scripts/sync-doc-version.mjs [--check]`.
  * `--check` reports drift without writing, for CI.
+ *
+ * The README's top badge row went all-dynamic (npm version / downloads /
+ * workflow status — no hardcoded version left to drift), so the only
+ * version-bearing marker left is the profile dependency example.
  */
 
 import { readFileSync, writeFileSync } from 'node:fs'
@@ -25,23 +29,12 @@ const checkOnly = process.argv.includes('--check')
 
 /**
  * Each target names the file, what it looks for, and what it becomes. Both
- * READMEs carry the same three markers, and both are required: a missing one
- * means the docs moved and this script has to be updated, which is the whole
- * point of failing loudly.
+ * READMEs carry the same marker, and both are required: a missing one means
+ * the docs moved and this script has to be updated, which is the whole point
+ * of failing loudly. (Until the badge row went all-dynamic there were two
+ * more — a hardcoded release badge and its alt text; both are gone.)
  */
 const targets = ['README.md', 'README.zh-CN.md'].flatMap((file) => [
-  {
-    file,
-    label: 'release badge',
-    pattern: /badge\/release-v\d+\.\d+\.\d+-/,
-    replace: `badge/release-v${version}-`,
-  },
-  {
-    file,
-    label: 'release badge alt text',
-    pattern: /alt="v\d+\.\d+\.\d+"/,
-    replace: `alt="v${version}"`,
-  },
   {
     file,
     label: 'profile dependency example',

package/scripts/verify-fingerprint-live.mjs

@@ -0,0 +1,111 @@
+// Live fingerprint verification (T42) — NOT part of `pnpm test`.
+//
+// Computes the interface fingerprints of a REAL DSH closure the way the
+// plugin's registry tier normalizes them (the exact same
+// lib/fingerprint.js code path: descriptors minus sourceLocation, schemas
+// projected to JSON Schema, keys sorted, sha256 truncated to 12 hex chars)
+// and prints one JSON document per closure root, so the acceptance check
+// can diff an npm install against a packaged App side by side:
+//
+//   node scripts/verify-fingerprint-live.mjs                    # this checkout's dev closure
+//   node scripts/verify-fingerprint-live.mjs /path/to/App/node_modules \
+//                                            /path/to/npm/node_modules
+//
+// Expected verdict for same-interface closures (docs/spike-relay.md §2.3):
+// every group's hash is IDENTICAL across roots — including across DSH
+// 0.1.7 / 0.2.0, whose remote interfaces are byte-identical even though the
+// versions differ. The spike recorded be9ab393695a there for the
+// session-controller group under its key-sorting-only normalization; this
+// canonicalization is strictly stronger (recursive schema-key sorting), so
+// the comparable anchor over the 0.1.7-rc.2 dev closure is r:211083a84f52 —
+// the cross-root identity verdict below is the property that matters here.
+//
+// The descriptors come from each package's generated
+// `lib/typert.remote-client.js` — inside a real DSH process the registry
+// tier reads `ctx.typert.local.list()` instead, but the spike verified the
+// generated files are byte-identical between the App and npm for the same
+// interfaces, so this offline stand-in measures the same thing (and is the
+// only way to check a closure without starting DSH).
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+// The fingerprint helpers import node: builtins only — safe to load from the
+// built lib. A missing build gets a loud, actionable failure instead.
+const { FINGERPRINT_GROUP_PACKAGES, EVENTS_GROUP, fingerprintDescriptors, fingerprintForwardedEvents } = await import(
+  pathToFileURL(join(pluginRoot, 'lib', 'fingerprint.js')).href
+)
+
+const roots = process.argv.slice(2)
+const effectiveRoots = roots.length > 0 ? roots : [join(pluginRoot, 'node_modules')]
+
+/** sha256 over the stripped remote-client file — the task's documented
+ * file-tier fallback, printed beside the normalized hash for reference. */
+function fileTierHash(packageDir) {
+  const file = join(packageDir, 'lib', 'typert.remote-client.js')
+  if (!existsSync(file)) return null
+  const text = readFileSync(file, 'utf8')
+  return createHash('sha256').update(text.replace(/sourceLocation:\s*\{[^{}]*\}/gu, ''), 'utf8').digest('hex').slice(0, 12)
+}
+
+const report = {}
+for (const root of effectiveRoots) {
+  const entry = {}
+  for (const [group, packageName] of Object.entries(FINGERPRINT_GROUP_PACKAGES)) {
+    const packageDir = join(root, packageName)
+    const remoteClient = join(packageDir, 'lib', 'typert.remote-client.js')
+    if (!existsSync(remoteClient)) {
+      entry[group] = { package: packageName, fingerprint: 'unavailable', note: 'lib/typert.remote-client.js not found in this closure' }
+      continue
+    }
+    const mod = await import(pathToFileURL(remoteClient).href)
+    const descriptors = mod.default?.descriptors
+    if (!Array.isArray(descriptors)) {
+      entry[group] = { package: packageName, fingerprint: 'unavailable', note: 'no descriptors export' }
+      continue
+    }
+    entry[group] = {
+      package: packageName,
+      endpoints: descriptors.length,
+      fingerprint: fingerprintDescriptors(descriptors),
+      fileTier: fileTierHash(packageDir),
+    }
+  }
+  // The events whitelist from dsh-api-remotes — the same input the runtime
+  // events group hashes.
+  const remotesFile = join(root, '@deepseek-ai', 'dsh-api-remotes', 'lib', 'index.js')
+  if (existsSync(remotesFile)) {
+    const remotes = await import(pathToFileURL(remotesFile).href)
+    const events = remotes.API_REMOTE_FORWARDED_EVENTS
+    entry[EVENTS_GROUP] = Array.isArray(events)
+      ? {
+          package: '@deepseek-ai/dsh-api-remotes',
+          endpoints: events.length,
+          fingerprint: fingerprintForwardedEvents(events),
+        }
+      : { package: '@deepseek-ai/dsh-api-remotes', fingerprint: 'unavailable', note: 'API_REMOTE_FORWARDED_EVENTS is not an array' }
+  } else {
+    entry[EVENTS_GROUP] = { package: '@deepseek-ai/dsh-api-remotes', fingerprint: 'unavailable', note: 'package not found in this closure' }
+  }
+  report[root] = entry
+}
+
+console.log(JSON.stringify(report, null, 2))
+
+// Cross-root verdict: groups present in EVERY root must hash identically —
+// that is the property the version-tolerance layer stands on.
+if (effectiveRoots.length > 1) {
+  const groups = Object.keys(FINGERPRINT_GROUP_PACKAGES).concat(EVENTS_GROUP)
+  const mismatches = []
+  for (const group of groups) {
+    const values = effectiveRoots.map((root) => report[root][group]?.fingerprint)
+    if (values.some((value) => value === undefined || value === 'unavailable')) continue
+    if (new Set(values).size > 1) mismatches.push(group)
+  }
+  console.error(mismatches.length === 0
+    ? `verify-fingerprint-live: all comparable groups identical across ${effectiveRoots.length} closures`
+    : `verify-fingerprint-live: DIFFERING groups: ${mismatches.join(', ')}`)
+}