dsh-zen-remote 2.3.11 → 2.4.0

package/scripts/check-settings-view.mjs

@@ -0,0 +1,247 @@
+// Behaviour check for the MS-6 browser data layer — the multi-server view
+// pieces across src/client-data/{settings-form,wizard,remote-status}.ts,
+// driven against the REAL bodies src/client-routes.ts answers since MS-5:
+//
+// - `client/status` carries `servers: ClientServerStatusItem[]` (one row per
+//   paired pool entry) plus `maxServers` and the FIRST entry's top-level
+//   compatibility fields;
+// - `remote-status` carries `servers: Record<serverId, …>` keyed by the
+//   handshake serverId plus the FIRST entry's top-level mirror;
+// - the pairing gate judges "new address at the cap" against "existing
+//   address overwrite" (the cap never blocks a re-pair).
+//
+// Run: node scripts/check-settings-view.mjs   (needs Node >= 23.6 type stripping)
+import assert from 'node:assert/strict'
+import {
+  canSubmitClientPairing,
+  CLIENT_UNPAIR_ROUTE,
+  deriveClientStatusView,
+  MAX_PAIRED_SERVERS,
+  normalizePairingCode,
+} from '../src/client-data/settings-form.ts'
+import { deriveClientOverviewSummary, isWizardConfigured } from '../src/client-data/wizard.ts'
+import {
+  bannerText,
+  BRIDGE_STAMP_PLUGIN,
+  describeRemoteStatus,
+  parseRemoteStatusBody,
+  resolveServerStatusView,
+  shouldStampBridgeForSession,
+} from '../src/client-data/remote-status.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 t = (key) => `#${key}`
+
+/** One paired-server row exactly as client-routes.ts's poolStatusBodyOf
+ * serves it (no token anywhere). */
+function serverRow(over = {}) {
+  return {
+    entryId: over.serverUrl ?? 'http://a.local:3088',
+    serverId: 'aaaa1111',
+    serverUrl: over.serverUrl ?? 'http://a.local:3088',
+    serverName: 'A-main',
+    displayName: 'A-main',
+    state: 'online',
+    nextRetryAt: null,
+    lastError: 'offline',
+    compat: { identical: ['session'], different: ['workspace'], unavailable: [] },
+    pluginBridge: [{ plugin: BRIDGE_STAMP_PLUGIN, bridged: true, localVersion: '1.0', remoteVersion: '1.0', reason: undefined }],
+    ...over,
+  }
+}
+
+await test('the MS-6 constants name the cap and the unpair route', () => {
+  assert.equal(MAX_PAIRED_SERVERS, 8)
+  assert.equal(CLIENT_UNPAIR_ROUTE, '/_dsh/zen-remote/client/unpair')
+})
+
+await test('deriveClientStatusView parses the pool list: 0 … 8 rows, limitReached only at the cap', () => {
+  // An old single-server body (no servers field): empty list, default cap.
+  const single = deriveClientStatusView({ state: 'online', serverUrl: 'http://a.local:3088', serverName: 'A-main' })
+  assert.deepEqual(single.servers, [])
+  assert.equal(single.maxServers, 8)
+  assert.equal(single.limitReached, false)
+
+  // A real pool answer: rows ride through, top-level compat still parses.
+  const two = deriveClientStatusView({
+    state: 'online', serverUrl: 'http://a.local:3088', serverName: 'A-main', maxServers: 8,
+    servers: [
+      serverRow(),
+      serverRow({ serverId: 'bbbb2222', serverUrl: 'http://b.local:3088', serverName: 'B-backup', displayName: 'B-backup', state: 'offline', nextRetryAt: 5_000 }),
+    ],
+  })
+  assert.equal(two.servers.length, 2)
+  assert.deepEqual(two.servers[0], {
+    entryId: 'http://a.local:3088', serverId: 'aaaa1111', serverUrl: 'http://a.local:3088',
+    serverName: 'A-main', displayName: 'A-main', state: 'connected', nextRetryAt: undefined,
+    lastError: 'offline',
+    compat: { mismatchedGroups: ['workspace'], recentCalls: [] },
+    pluginBridge: [{ plugin: BRIDGE_STAMP_PLUGIN, localVersion: '1.0', stateKey: 'settings.bridge.stateBridged', serverVersion: undefined }],
+  })
+  assert.equal(two.servers[1].state, 'unreachable', 'the wire offline word maps like the top level does')
+  assert.equal(two.servers[1].nextRetryAt, 5_000)
+  assert.equal(two.limitReached, false)
+
+  // Eight rows: the cap is reached.
+  const full = deriveClientStatusView({
+    state: 'online', maxServers: 8,
+    servers: Array.from({ length: 8 }, (_, i) => serverRow({ serverId: `aaaa111${i}`, serverUrl: `http://${i}.local` })),
+  })
+  assert.equal(full.servers.length, 8)
+  assert.equal(full.maxServers, 8)
+  assert.equal(full.limitReached, true)
+
+  // The body's own maxServers decides when it carries one.
+  assert.equal(deriveClientStatusView({ state: 'online', maxServers: 4, servers: [serverRow(), serverRow({ serverUrl: 'b' }), serverRow({ serverUrl: 'c' }), serverRow({ serverUrl: 'd' })] }).limitReached, true)
+
+  // Garbage degrades: junk rows drop, junk fields default. A PRESENT but
+  // garbage compat still renders the empty group (the presence gate, like
+  // the top level); only an absent one stays undefined.
+  const junk = deriveClientStatusView({
+    state: 'online',
+    servers: ['garbage', null, { entryId: 'keep', serverId: 'aaaa1111', state: 'revoked', nextRetryAt: 'soon', compat: 'x', pluginBridge: 'x' }, 42],
+  })
+  assert.equal(junk.servers.length, 1)
+  assert.equal(junk.servers[0].entryId, 'keep')
+  assert.equal(junk.servers[0].state, 'revoked')
+  assert.equal(junk.servers[0].nextRetryAt, undefined)
+  assert.deepEqual(junk.servers[0].compat, { mismatchedGroups: [], recentCalls: [] })
+  assert.deepEqual(junk.servers[0].pluginBridge, [])
+  assert.equal(deriveClientStatusView({ state: 'online', servers: [{ entryId: 'quiet', serverId: 'aaaa1111' }] }).servers[0].compat, undefined)
+  assert.equal(deriveClientStatusView({ state: 'online', servers: 'garbage' }).servers.length, 0)
+  assert.equal(deriveClientStatusView({ state: 'online', servers: 'garbage' }).limitReached, false)
+  assert.equal(deriveClientStatusView({ state: 'online', maxServers: 'x' }).maxServers, 8)
+})
+
+await test('canSubmitClientPairing: new addresses respect the cap, existing ones overwrite through it', () => {
+  const one = [serverRow()]
+  const eight = Array.from({ length: 8 }, (_, i) => serverRow({ serverId: `aaaa111${i}`, serverUrl: `http://${i}.local` }))
+
+  // A clean new pairing under the cap.
+  assert.deepEqual(
+    canSubmitClientPairing({ pairUrl: 'http://new.local:3088', pairCode: 'ABCD2345', servers: one }),
+    { allowed: true, isOverwrite: false, blockedByLimit: false },
+  )
+
+  // Refusals that have nothing to do with the cap.
+  assert.equal(canSubmitClientPairing({ pairUrl: '', pairCode: 'ABCD2345', servers: [] }).allowed, false, 'no address, no pairing')
+  assert.equal(canSubmitClientPairing({ pairUrl: 'http://new.local', pairCode: '', servers: [] }).allowed, false, 'no code, no pairing')
+  assert.equal(canSubmitClientPairing({ pairUrl: 'http://new.local', pairCode: 'ABCD23', servers: [] }).allowed, false, 'a partial code is not a code')
+  assert.equal(canSubmitClientPairing({ pairUrl: 'http://new.local', pairCode: normalizePairingCode('ab-23'), servers: [] }).allowed, false)
+  assert.equal(canSubmitClientPairing({ pairUrl: 'http://new.local', pairCode: 'ABCD2345', servers: [], busy: true }).allowed, false, 'a claim in flight blocks a second')
+  assert.equal(canSubmitClientPairing({ pairUrl: 'http://new.local', pairCode: 'ABCD2345', servers: [], deviceNameInvalid: true }).allowed, false, 'an invalid device name blocks the claim (T60)')
+
+  // The cap blocks only NEW addresses.
+  assert.deepEqual(
+    canSubmitClientPairing({ pairUrl: 'http://9.local', pairCode: 'ABCD2345', servers: eight }),
+    { allowed: false, isOverwrite: false, blockedByLimit: true },
+    'a ninth new address is refused at 8/8',
+  )
+  // Overwrite: the SAME (normalized) address pairs straight through the cap.
+  assert.deepEqual(
+    canSubmitClientPairing({ pairUrl: 'http://3.local', pairCode: 'ABCD2345', servers: eight }),
+    { allowed: true, isOverwrite: true, blockedByLimit: false },
+    'an existing address re-pairs even at 8/8',
+  )
+  // Trailing slashes and padding do not make a new address.
+  assert.equal(canSubmitClientPairing({ pairUrl: '  http://3.local/  ', pairCode: 'ABCD2345', servers: eight }).isOverwrite, true)
+  // An explicit maxServers decides like the body's does.
+  assert.equal(canSubmitClientPairing({ pairUrl: 'http://z.local', pairCode: 'ABCD2345', servers: one, maxServers: 1 }).blockedByLimit, true)
+  assert.equal(canSubmitClientPairing({ pairUrl: 'http://a.local:3088/', pairCode: 'ABCD2345', servers: one, maxServers: 1 }).allowed, true)
+})
+
+await test('isWizardConfigured: pairedServerCount > 0 alone configures the overview', () => {
+  const nothingElse = {
+    effectiveClient: true,
+    wizardStatus: undefined,
+    pairedDeviceCount: 0,
+    hasSavedHostConfig: false,
+    tokenConfigured: false,
+    clientServerUrl: '',
+    clientState: undefined,
+  }
+  assert.equal(isWizardConfigured({ ...nothingElse, pairedServerCount: 2 }), true)
+  assert.equal(isWizardConfigured({ ...nothingElse, pairedServerCount: 0 }), false)
+  // Omitted keeps the pre-MS-6 verdict.
+  assert.equal(isWizardConfigured({ ...nothingElse }), false)
+})
+
+await test('deriveClientOverviewSummary: counts, cap and the two lights', () => {
+  // The summary consumes the DERIVED view list — the view vocabulary's state
+  // words (connected / unreachable / revoked), not the wire's.
+  const row = (state, url) => serverRow({ state, serverUrl: url, entryId: url })
+  // Empty pool.
+  assert.deepEqual(deriveClientOverviewSummary([]), {
+    totalCount: 0, onlineCount: 0, offlineCount: 0, revokedCount: 0,
+    maxServers: 8, limitReached: false, connectionLight: 'pending', serversLight: 'pending',
+  })
+  // All connected: both green.
+  assert.deepEqual(deriveClientOverviewSummary([row('connected', 'a'), row('connected', 'b')]), {
+    totalCount: 2, onlineCount: 2, offlineCount: 0, revokedCount: 0,
+    maxServers: 8, limitReached: false, connectionLight: 'pass', serversLight: 'pass',
+  })
+  // Mixed: offline stays amber unless a dead verdict rides along.
+  const mixed = deriveClientOverviewSummary([row('connected', 'a'), row('unreachable', 'b'), row('revoked', 'c')])
+  assert.equal(mixed.onlineCount, 1)
+  assert.equal(mixed.offlineCount, 1)
+  assert.equal(mixed.revokedCount, 1)
+  assert.equal(mixed.connectionLight, 'fail')
+  assert.equal(deriveClientOverviewSummary([row('connected', 'a'), row('unreachable', 'b')]).connectionLight, 'pending')
+  // The 8/8 cap is a servers fact: red servers light, green connection light.
+  const full = deriveClientOverviewSummary(Array.from({ length: 8 }, (_, i) => row('connected', `s${i}`)))
+  assert.equal(full.limitReached, true)
+  assert.equal(full.serversLight, 'fail')
+  assert.equal(full.connectionLight, 'pass')
+  // Seven of eight is under the cap.
+  assert.equal(deriveClientOverviewSummary(Array.from({ length: 7 }, (_, i) => row('connected', `s${i}`))).limitReached, false)
+  // An explicit maxServers.
+  assert.equal(deriveClientOverviewSummary([row('connected', 'a')], 1).limitReached, true)
+})
+
+await test('remote-status per-server acceptance: A online / B offline through the icon and banner', () => {
+  const view = parseRemoteStatusBody({
+    state: 'online', versionMismatch: false, serverName: 'A-main', closed: {},
+    bridgedPlugins: [BRIDGE_STAMP_PLUGIN],
+    servers: {
+      aaaa1111: { state: 'online', versionMismatch: false, serverName: 'A-main', bridgedPlugins: [BRIDGE_STAMP_PLUGIN] },
+      bbbb2222: { state: 'offline', versionMismatch: false, serverName: 'B-backup', bridgedPlugins: [] },
+    },
+  }, 1)
+
+  // The icon: A lit, B grey.
+  assert.deepEqual(describeRemoteStatus(view, t, 'zr~aaaa1111~s1'), { state: 'online', hoverText: '#remoteStatusOnline' })
+  assert.deepEqual(describeRemoteStatus(view, t, 'zr~bbbb2222~s2'), { state: 'offline', hoverText: '#remoteStatusOffline' })
+  // The banner: A clean, B temporarily readonly.
+  assert.equal(bannerText(view, 'zr~aaaa1111~s1', t), undefined)
+  assert.equal(bannerText(view, 'zr~bbbb2222~s2', t), '#remoteBannerOffline')
+  // The resolve seam the parts share: per-server entry, top-level fallback.
+  assert.equal(resolveServerStatusView(view, 'zr~aaaa1111~s1'), view.servers.aaaa1111)
+  assert.equal(resolveServerStatusView(view, 'zr~cccc3333~x'), view)
+})
+
+await test('remote-status per-server acceptance: the bridge stamp follows the session\u2019s server', () => {
+  const view = parseRemoteStatusBody({
+    state: 'online', versionMismatch: false, serverName: 'A-main', closed: {},
+    bridgedPlugins: [BRIDGE_STAMP_PLUGIN],
+    servers: {
+      aaaa1111: { state: 'online', versionMismatch: false, serverName: 'A-main', bridgedPlugins: [BRIDGE_STAMP_PLUGIN] },
+      bbbb2222: { state: 'offline', versionMismatch: false, serverName: 'B-backup', bridgedPlugins: [] },
+    },
+  }, 1)
+  assert.equal(shouldStampBridgeForSession(view, 'zr~aaaa1111~s1', BRIDGE_STAMP_PLUGIN), true)
+  assert.equal(shouldStampBridgeForSession(view, 'zr~bbbb2222~s2', BRIDGE_STAMP_PLUGIN), false)
+})
+
+console.log('check-settings-view: ok')

package/scripts/check-wizard-ui.mjs

@@ -24,6 +24,7 @@ import {
   tunnelCheckCopy,
   tunnelFailureCopy,
   caddySnippetText,
+  deriveClientServerLights,
   deriveClientWizardLights,
   deriveWizardLights,
   formSeedOf,
@@ -229,6 +230,30 @@ await test('deriveClientWizardLights: reflects token and client connection state
   )
 })
 
+await test('deriveClientServerLights: one paired server row drives the wizard step-3 lights (MS-8)', () => {
+  // A minimal pool row: the view shape deriveClientStatusView answers.
+  const row = (state, extra = {}) => ({
+    entryId: 'e1', serverId: 's1', serverUrl: 'http://x.local:3088', serverName: 'srv',
+    displayName: 'srv', state, nextRetryAt: undefined, lastError: '', compat: undefined, pluginBridge: [],
+    ...extra,
+  })
+  // Nothing selected (no pool rows at all): all three stay amber.
+  assert.deepEqual(deriveClientServerLights(undefined), { credential: 'pending', connection: 'pending', sync: 'pending' })
+  // A healthy connected row: everything green.
+  assert.deepEqual(deriveClientServerLights(row('connected')), { credential: 'pass', connection: 'pass', sync: 'pass' })
+  // Connected but the interface groups differ from the server's: sync red.
+  assert.deepEqual(
+    deriveClientServerLights(row('connected', { compat: { mismatchedGroups: ['session'], recentCalls: [] } })),
+    { credential: 'pass', connection: 'pass', sync: 'fail' },
+  )
+  // Revoked: the credential AND the connection are both dead, sync stays amber.
+  assert.deepEqual(deriveClientServerLights(row('revoked')), { credential: 'fail', connection: 'fail', sync: 'pending' })
+  // Offline mid-retry: the token is fine, the connection is red, sync waits.
+  assert.deepEqual(deriveClientServerLights(row('unreachable')), { credential: 'pass', connection: 'fail', sync: 'pending' })
+  // Incompatible: connection red, credential still fine.
+  assert.deepEqual(deriveClientServerLights(row('incompatible')), { credential: 'pass', connection: 'fail', sync: 'pending' })
+})
+
 await test('formSeedOf: the configure forms seed from the wizard projection, not admin/status (GW-fix-3/M1)', () => {
   // The projection carries the ingress fields; admin/status does not (GW-1
   // strips them) — seeding from there would silently never backfill.
@@ -415,6 +440,14 @@ const WIZARD_KEYS = [
   'wizard.modal.saveAndNext', 'wizard.modal.finish',
   'wizard.light.probing', 'wizard.overview.manageDevices',
   'wizard.devicesModal.title', 'wizard.devicesModal.subtitle', 'wizard.devicesModal.retest',
+  'wizard.overview.clientSyncLabel', 'wizard.overview.syncOk', 'wizard.overview.syncBad', 'wizard.overview.syncPending',
+  'wizard.overview.clientOnlineCount', 'wizard.overview.clientOfflineCount', 'wizard.overview.clientRevokedCount',
+  'wizard.overview.clientAllOnline', 'wizard.overview.clientServersLabel', 'wizard.overview.clientPairedFull',
+  'wizard.overview.clientPairedNames', 'wizard.overview.limitNote',
+  'wizard.overview.manageServers', 'wizard.overview.addServer',
+  'wizard.serversModal.title', 'wizard.serversModal.subtitle', 'wizard.serversModal.viewStatus',
+  'wizard.client.poolCapNote', 'wizard.client.continueAdd', 'wizard.client.serverPicker',
+  'wizard.desktop.addressFallback', 'wizard.desktop.copiedText',
 ]
 
 // The cards' step counts are part of the walkthrough contract (GW-11).
@@ -452,6 +485,10 @@ await test('the browser snippet mirrors are byte-identical to the host templates
   assert.equal(nginxSnippetText(SNIPPET_INPUT), nginxSnippet(SNIPPET_INPUT).text)
   assert.equal(caddySnippetText(SNIPPET_INPUT), caddySnippet(SNIPPET_INPUT).text)
   assert.deepEqual(luckyStepTexts(SNIPPET_INPUT), luckySteps(SNIPPET_INPUT).steps)
+  const enInput = { ...SNIPPET_INPUT, lang: 'en' }
+  assert.equal(nginxSnippetText(enInput), nginxSnippet(enInput).text)
+  assert.equal(caddySnippetText(enInput), caddySnippet(enInput).text)
+  assert.deepEqual(luckyStepTexts(enInput), luckySteps(enInput).steps)
   // The mirrors refuse the same inputs the host refuses.
   for (const bad of [{ ...SNIPPET_INPUT, domain: 'a b' }, { ...SNIPPET_INPUT, upstreamHost: 'x/y' }, { ...SNIPPET_INPUT, upstreamPort: 0 }]) {
     assert.equal(nginxSnippetText(bad), null)

package/src/adapters/dsh-better-sidebar/index.ts

@@ -1,10 +1,11 @@
 /**
  * The dsh-better-sidebar adapter (PB-12), written against EXACTLY
- * versions 0.25.0, 0.26.0, 0.26.1, 0.28.0-alpha.0, 0.28.0, 0.28.1, 0.28.2 and 0.30.0 (PB-15 widened the list; 0.26.1 is a
+ * versions 0.25.0, 0.26.0, 0.26.1, 0.28.0-alpha.0, 0.28.0, 0.28.1, 0.28.2,
+ * 0.30.0 and 0.30.1 (PB-15 widened the list; 0.26.1 is a
  * perf-only patch with the same wire surface as 0.26.0; 0.26.0 is a JSON-api
  * superset of 0.25.0 — it grows fs.readPage and the sidechat dequeue/model/
  * models methods, and moves fs.write's content onto the new raw-text
- * /sidebar/write route). Everything the adapter knows about the plugin came
+ * /sidebar/write route; 0.30.1 is a wire-identical patch of 0.30.0). Everything the adapter knows about the plugin came
  * off `/tmp/bs-versions/{0.25.0,0.26.0}/lib/index.js`; the method table
  * lives in `methods.ts` beside this file, and the test suite re-extracts
  * the plugin's real method-name set (the two-version UNION) to catch a
@@ -85,7 +86,10 @@ export const dshBetterSidebarAdapter: BridgeAdapter = {
   // below on its `childId`. `sidechat.prompt` grows an `images` array (base64,
   // up to ~27.7 MiB body) — the api route cap widens to that. GenUI, quote
   // chips and editor draft backup are client-only (no new host routes).
-  versions: ['0.25.0', '0.26.0', '0.26.1', '0.28.0-alpha.0', '0.28.0', '0.28.1', '0.28.2', '0.30.0'],
+  // 0.30.1: a patch release whose wire surface is byte-for-byte the 0.30.0
+  // generation's (digest `394de9f588d37092` — same JSON-api method set, same
+  // routes and WebSockets), so it lists under the same surface digest.
+  versions: ['0.25.0', '0.26.0', '0.26.1', '0.28.0-alpha.0', '0.28.0', '0.28.1', '0.28.2', '0.30.0', '0.30.1'],
   // PB-19 (ADR-0003): the wire-surface whitelist. Keys are digest16 over the
   // PB-18 extractor's reduction (`surface.ts` beside this file) of the npm
   // builds' lib/index.js, computed off /tmp/bs-versions/{version}/lib/index.js:

package/src/admin-routes.ts

@@ -653,9 +653,13 @@ export function createAdminHandler(options: AdminHandlerOptions): AdminHandler {
         // through the gateway is refused — consent is granted on the server
         // machine, by its owner, period.
         if (req.headers['x-zen-remote-via'] !== undefined) {
+          const isEn = options.getConfig().values.lang === 'en'
           responseJson(res, 403, {
             ok: false,
-            error: { code: 'via-gateway', message: '插件桥设置只能在服务端本机操作' },
+            error: {
+              code: 'via-gateway',
+              message: isEn ? 'Plugin bridge settings can only be modified on the server machine' : '插件桥设置只能在服务端本机操作',
+            },
           })
           return
         }
@@ -693,9 +697,13 @@ export function createAdminHandler(options: AdminHandlerOptions): AdminHandler {
         // same-origin (the gateway rewrites Origin/Host), so the marker is
         // the only signal that says "this did not start on this machine".
         if (req.headers['x-zen-remote-via'] !== undefined) {
+          const isEn = options.getConfig().values.lang === 'en'
           responseJson(res, 403, {
             ok: false,
-            error: { code: 'via-gateway', message: '配对与设备管理只能在服务端本机操作' },
+            error: {
+              code: 'via-gateway',
+              message: isEn ? 'Pairing and device management are only available on the server machine' : '配对与设备管理只能在服务端本机操作',
+            },
           })
           return
         }

package/src/cli/args.ts

@@ -0,0 +1,289 @@
+/**
+ * CLI-2 command-line parsing: the whole `dsh-zen-remote` grammar in one pure
+ * function. It answers WHAT the user asked for — command routing, option
+ * values, targets — and deliberately does not VALIDATE cross-field rules
+ * (role gates, required targets): the command layer renders those verdicts
+ * through the i18n dictionary. Two things the parser does decide on its own:
+ * `--role peer` (and any unknown role value) is flagged `roleIssue` because
+ * SPEC pins the "peer is not enabled" refusal at every entry point, and
+ * `--debug`'s optional path argument is consumed only when it does not look
+ * like another flag.
+ *
+ * Global flags may appear before or after the command word; the leading
+ * positional tokens ARE the command (`host device revoke dev-7` → three
+ * command words + one target), everything flag-like is an option.
+ */
+
+export type CliCommand =
+  | 'help'
+  | 'version'
+  | 'unknown'
+  | 'setup'
+  | 'status'
+  | 'host.device.pair'
+  | 'host.device.list'
+  | 'host.device.revoke'
+  | 'host.ingress.start'
+  | 'host.ingress.stop'
+  | 'host.ingress.verify'
+  | 'host.ingress.snippet'
+  | 'client.pair'
+  | 'client.unpair'
+  | 'client.list'
+
+/** Why a `--role` value cannot be used as-is. `peer-not-enabled` covers the
+ * SPEC's reserved role; `invalid` covers everything the vocabulary does not
+ * know. Absent when the value is `host` or `client`. */
+export type CliRoleIssue = 'peer-not-enabled' | 'invalid'
+
+export interface CliOptions {
+  /** Raw `--lang` value — `resolveCliLang` (i18n.ts) interprets it later. */
+  lang?: string
+  json: boolean
+  yes: boolean
+  noWait: boolean
+  /** Explicit IPC socket path; discovery probes only this when present. */
+  socket?: string
+  /** Seconds to wait for DSH to come up; default 20. */
+  wait: number
+  /** `status --debug` without a path: write the default filename. */
+  debug: boolean
+  /** `status --debug <outPath>`: the exact output file. */
+  debugPath?: string
+  /** Raw `--role` value, preserved verbatim. */
+  role?: string
+  roleIssue?: CliRoleIssue
+  /** `--profile p1,p2` split on commas, trimmed, empties dropped. */
+  profile?: string[]
+  /** `--ingress` value (caddy | cloudflared | external | lan). */
+  ingress?: string
+  /** `--mode` — a synonym of `--ingress`, kept separately for callers that
+   * want to know which spelling the user used. */
+  mode?: string
+  domain?: string
+  cfToken?: string
+  email?: string
+  httpsPort?: number
+  publicUrl?: string
+  tunnelId?: string
+  proxy?: string
+  deviceRole?: string
+  hostUrl?: string
+  code?: string
+  name?: string
+  all: boolean
+  /** Unrecognized `--flags`, collected instead of crashing — the command
+   * layer decides whether to warn. */
+  unknownFlags: string[]
+}
+
+export interface ParsedCliArgs {
+  command: CliCommand
+  options: CliOptions
+  /** The positional argument after the command words (a device id, a host
+   * URL, an entry id). `--all` as the revoke/unpair target becomes
+   * `options.all` instead. */
+  target?: string
+  /** The unrecognized command words, joined for the error message. */
+  unknownCommand?: string
+}
+
+/** `--flag value` options, mapped onto CliOptions field names. */
+const VALUE_OPTIONS: Readonly<Record<string, 'lang' | 'socket' | 'wait' | 'role' | 'profile' | 'ingress' | 'mode' | 'domain' | 'cfToken' | 'email' | 'httpsPort' | 'publicUrl' | 'tunnelId' | 'proxy' | 'deviceRole' | 'hostUrl' | 'code' | 'name'>> = {
+  '--lang': 'lang',
+  '--socket': 'socket',
+  '--wait': 'wait',
+  '--role': 'role',
+  '--profile': 'profile',
+  '--ingress': 'ingress',
+  '--mode': 'mode',
+  '--domain': 'domain',
+  '--cf-token': 'cfToken',
+  '--email': 'email',
+  '--https-port': 'httpsPort',
+  '--public-url': 'publicUrl',
+  '--tunnel-id': 'tunnelId',
+  '--proxy': 'proxy',
+  '--device-role': 'deviceRole',
+  '--host-url': 'hostUrl',
+  '--code': 'code',
+  '--name': 'name',
+}
+
+/** Boolean switches. `-y` is the only short alias (the one SPEC names). */
+const BOOLEAN_OPTIONS: Readonly<Record<string, 'json' | 'yes' | 'noWait' | 'all'>> = {
+  '--json': 'json',
+  '--yes': 'yes',
+  '-y': 'yes',
+  '--no-wait': 'noWait',
+  '--all': 'all',
+}
+
+const KNOWN_ROLES = new Set(['host', 'client', 'peer'])
+
+function defaultOptions(): CliOptions {
+  return {
+    json: false,
+    yes: false,
+    noWait: false,
+    wait: 20,
+    debug: false,
+    all: false,
+    unknownFlags: [],
+  }
+}
+
+function assignValue(field: (typeof VALUE_OPTIONS)[string], raw: string, options: CliOptions): void {
+  switch (field) {
+    case 'wait': {
+      const seconds = Number(raw)
+      if (Number.isFinite(seconds) && seconds >= 0) options.wait = seconds
+      // A garbage value keeps the 20s default instead of poisoning the wait.
+      return
+    }
+    case 'profile': {
+      const names = raw.split(',').map((name) => name.trim()).filter((name) => name !== '')
+      options.profile = names
+      return
+    }
+    case 'httpsPort': {
+      const port = Number(raw)
+      if (Number.isInteger(port) && port > 0) options.httpsPort = port
+      return
+    }
+    case 'role': {
+      options.role = raw
+      if (raw === 'peer') options.roleIssue = 'peer-not-enabled'
+      else if (!KNOWN_ROLES.has(raw)) options.roleIssue = 'invalid'
+      return
+    }
+    case 'lang': options.lang = raw; return
+    case 'socket': options.socket = raw; return
+    case 'ingress': options.ingress = raw; return
+    case 'mode': options.mode = raw; return
+    case 'domain': options.domain = raw; return
+    case 'cfToken': options.cfToken = raw; return
+    case 'email': options.email = raw; return
+    case 'publicUrl': options.publicUrl = raw; return
+    case 'tunnelId': options.tunnelId = raw; return
+    case 'proxy': options.proxy = raw; return
+    case 'deviceRole': options.deviceRole = raw; return
+    case 'hostUrl': options.hostUrl = raw; return
+    case 'code': options.code = raw; return
+    case 'name': options.name = raw; return
+  }
+}
+
+function setBooleanFlag(field: (typeof BOOLEAN_OPTIONS)[string], options: CliOptions): void {
+  switch (field) {
+    case 'json': options.json = true; return
+    case 'yes': options.yes = true; return
+    case 'noWait': options.noWait = true; return
+    case 'all': options.all = true; return
+  }
+}
+
+/** Route the leading positional words into a command. Returns `undefined`
+ * when the words name a valid command with a target slot still open
+ * (`host device revoke …`), and a full verdict otherwise. */
+function routeCommand(positionals: readonly string[], options: CliOptions): ParsedCliArgs {
+  const c1 = positionals[0]
+  const c2 = positionals[1]
+  const c3 = positionals[2]
+  const unknown = (words: readonly (string | undefined)[]): ParsedCliArgs => ({
+    command: 'unknown',
+    options,
+    unknownCommand: words.filter((word) => word !== undefined).join(' '),
+  })
+
+  if (c1 === 'setup') {
+    // `setup <hostUrl>` — the client branch's pairing address as a positional
+    // (equivalent to `--host-url`; the flag still wins when both appear).
+    return { command: 'setup', options, ...(c2 === undefined ? {} : { target: c2 }) }
+  }
+  if (c1 === 'status') return { command: 'status', options }
+
+  if (c1 === 'host') {
+    if (c2 === 'device' && (c3 === 'pair' || c3 === 'list' || c3 === 'revoke')) {
+      // `revoke <id|--all>` is the only device verb with a target slot; an
+      // `--all` positional means the flag, not a device literally named
+      // "--all".
+      let target = c3 === 'revoke' ? positionals[3] : undefined
+      if (target === '--all') {
+        options.all = true
+        target = undefined
+      }
+      return { command: `host.device.${c3}`, options, ...(target === undefined ? {} : { target }) }
+    }
+    if (c2 === 'ingress' && (c3 === 'start' || c3 === 'stop' || c3 === 'verify' || c3 === 'snippet')) {
+      return { command: `host.ingress.${c3}`, options }
+    }
+    return unknown([c1, c2, c3])
+  }
+
+  if (c1 === 'client') {
+    if (c2 === 'pair' || c2 === 'unpair') {
+      const target = positionals[2]
+      return { command: `client.${c2}`, options, ...(target === undefined ? {} : { target }) }
+    }
+    if (c2 === 'list') return { command: 'client.list', options }
+    return unknown([c1, c2])
+  }
+
+  return unknown([c1])
+}
+
+/**
+ * Parse `argv` (without the node binary and script path) into a structured
+ * command. `--help` / `-h` anywhere wins over everything, then `--version` /
+ * `-v`; flags with no command still route to `help` (running the binary bare
+ * must not fall into the interactive wizard).
+ */
+export function parseCliArgs(argv: readonly string[]): ParsedCliArgs {
+  const options = defaultOptions()
+  const positionals: string[] = []
+  let index = 0
+  while (index < argv.length) {
+    const token = argv[index]
+    if (token === undefined) break
+    index += 1
+    if (token === '--help' || token === '-h' || token === '--version' || token === '-v') {
+      continue
+    }
+    if (token === '--debug') {
+      // `--debug [outPath]`: a following non-flag token is the output path,
+      // anything else (nothing, another flag) means the default filename.
+      const next = argv[index]
+      if (next !== undefined && !next.startsWith('-')) {
+        options.debugPath = next
+        index += 1
+      } else {
+        options.debug = true
+      }
+      continue
+    }
+    const booleanField = BOOLEAN_OPTIONS[token]
+    if (booleanField !== undefined) {
+      setBooleanFlag(booleanField, options)
+      continue
+    }
+    const valueField = VALUE_OPTIONS[token]
+    if (valueField !== undefined) {
+      const next = argv[index]
+      if (next === undefined || next.startsWith('-')) continue // missing value — leave the field unset
+      index += 1
+      assignValue(valueField, next, options)
+      continue
+    }
+    if (token.startsWith('-') && token.length > 1) {
+      options.unknownFlags.push(token)
+      continue
+    }
+    positionals.push(token)
+  }
+
+  if (argv.includes('--help') || argv.includes('-h')) return { command: 'help', options }
+  if (argv.includes('--version') || argv.includes('-v')) return { command: 'version', options }
+  if (positionals.length === 0) return { command: 'help', options }
+  return routeCommand(positionals, options)
+}