dsh-foreman-node 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-foreman-node",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Device side of dsh-foreman: connects out to a foreman hub, takes a job into a local DSH session, reports back. No ledger, no policy, no database.",
   "type": "module",
   "main": "lib/index.js",
@@ -15,7 +15,8 @@
       "default": "./lib/protocol.js"
     },
     "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./client": "./lib/client.js"
   },
   "files": [
     "lib",
@@ -34,6 +35,15 @@
     },
     "engines": {
       "dsh": "^0.2.1-alpha.2"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ]
     }
   },
   "scripts": {
@@ -47,6 +57,10 @@
     "@deepseek-ai/cosmokit": "1.8.5",
     "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
     "@deepseek-ai/dsh-api-session-controller": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-alpha.2",
     "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
     "@deepseek-ai/dsh-permission-presets": "0.2.1-alpha.2",
     "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
@@ -55,6 +69,10 @@
     "@deepseek-ai/dsh-workspace": "0.2.1-alpha.2",
     "@deepseek-ai/schemastery": "3.18.5-alpha.1",
     "@types/node": "22.20.0",
+    "@types/react": "18.3.28",
+    "@types/react-dom": "18.3.7",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
     "tsdown": "0.22.14",
     "typescript": "6.0.3",
     "vitest": "4.1.8"
@@ -64,13 +82,19 @@
     "@deepseek-ai/cosmokit": "1.8.5",
     "@deepseek-ai/dsh-agent": "^0.2.1-alpha.2",
     "@deepseek-ai/dsh-api-session-controller": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.1-alpha.2",
     "@deepseek-ai/dsh-llm": "^0.2.1-alpha.2",
     "@deepseek-ai/dsh-permission-presets": "^0.2.1-alpha.2",
     "@deepseek-ai/dsh-session": "^0.2.1-alpha.2",
     "@deepseek-ai/dsh-session-persistence": "^0.2.1-alpha.2",
     "@deepseek-ai/dsh-tools": "^0.2.1-alpha.2",
     "@deepseek-ai/dsh-workspace": "^0.2.1-alpha.2",
-    "@deepseek-ai/schemastery": "3.18.5-alpha.1"
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   },
   "license": "MIT",
   "author": "niechao136",

package/src/client/index.tsx

@@ -0,0 +1,211 @@
+/**
+ * The device's configuration page, mounted in the DSH Plugin Manager.
+ *
+ * It does two things the page alone cannot: it lists the keys this machine has (through the device's own route, because
+ * a browser cannot read `~/.ssh`) and it tests one authentication (also through the device, because a browser cannot
+ * start ssh). Everything it *writes* goes through DSH's own configuration form, so the saved values land in the
+ * profile's patch exactly as if they had been typed there by hand.
+ */
+import { useEffect, useState } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import type { ConfigPageForm, PluginConfigViewProps } from '@deepseek-ai/dsh-client-ui-plugin-manager/client'
+import { configured, type NodeConfig } from '../config.ts'
+import type { SshKey } from '../keys.ts'
+import type { TestResult } from '../routes.ts'
+import { addressPreview, DEFAULT_SSH, editsOf, emptyFields, keyLabel, testMessage } from './page-state.ts'
+import { en, zh } from './locales.ts'
+
+/** The prefix the device's own routes answer under. */
+const API = '/foreman-node/api'
+
+/** A key list answer, as `GET /foreman-node/api/keys` sends it. */
+interface KeysAnswer { keys: SshKey[]; directory: string }
+
+/** Fetches a key list or runs one test; both need the marker header the device's same-origin check looks for. */
+async function ask<T>(path: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(new URL(`${API}/${path}`, window.location.href), {
+    ...init, headers: { 'x-orchestrator-request': '1', ...(init?.body === undefined ? {} : { 'content-type': 'application/json' }), ...init?.headers } })
+  if (!response.ok) throw new Error(`the device answered ${response.status}`)
+  return await response.json() as T
+}
+
+export const inject = ['locale', 'slots']
+export const name = 'dsh-foreman-node'
+
+/** The locale namespace this page registers its dictionaries under. */
+const NS = 'dshNode'
+
+/**
+ * The page itself. `t` comes from the host's locale service, like every other plugin's page.
+ *
+ * `initialKeys` and `keysFailed` exist so a test can render a page without a network or a web server. Production never
+ * passes them, so the page fetches as it otherwise would — they change nothing about how it behaves.
+ */
+function DevicePage({ form, t, initialKeys, keysFailed: prefailed }: {
+  t: (key: keyof typeof zh) => string
+  form: ConfigPageForm | undefined
+  initialKeys?: readonly SshKey[]
+  keysFailed?: boolean
+}) {
+  // The draft starts from the saved value when there is one, so the first render already shows the configuration
+  // rather than a loading line that only an effect would replace.
+  // The host hands over the section's raw value; every field is volatile, so it is unwrapped once here.
+  const saved = form?.state.value === undefined ? undefined : configured(form.state.value as Partial<NodeConfig>)
+  const editable = form?.state.status === 'ready' && form.state.writable
+  // The draft starts from the saved value when there is one, so the first render already shows the configuration
+  // rather than a loading line that only an effect would replace.
+  const [draft, setDraft] = useState<NodeConfig | undefined>(() =>
+    saved === undefined ? undefined : { ...saved, token: '', ssh: { ...DEFAULT_SSH, ...saved.ssh } })
+  // The stored token never reaches the page (it is a secret), so the box starts empty and is only written when
+  // someone types one. `keepsToken` is what tells the page it does not have to ask.
+  // A stored token cannot be detected: it is stripped before it reaches the page, so `saved.token` is always
+  // undefined. What can be known is that the section already exists, which is what the hint is based on.
+  const keepsToken = saved !== undefined
+  const [keys, setKeys] = useState<SshKey[] | undefined>(initialKeys === undefined ? undefined : [...initialKeys])
+  const [keysFailed, setKeysFailed] = useState(prefailed === true)
+  const [tested, setTested] = useState<TestResult>()
+  const [testing, setTesting] = useState(false)
+  const [notice, setNotice] = useState<string>()
+
+  // The form's value is the saved truth; the draft is what a person is editing on top of it, so it is only adopted
+  // when nothing has been typed yet — a form that reloads must not overwrite a half-finished edit.
+  useEffect(() => { if (saved !== undefined) setDraft(current => current ?? { ...saved, ssh: { ...DEFAULT_SSH, ...saved.ssh } }) }, [saved])
+  useEffect(() => {
+    if (initialKeys !== undefined || prefailed === true) return
+    ask<KeysAnswer>('keys').then(answer => setKeys(answer.keys), () => setKeysFailed(true))
+  }, [initialKeys, prefailed])
+
+  const patch = (change: Partial<NodeConfig>) => setDraft(current => current === undefined ? current : { ...current, ...change })
+  const patchSsh = (change: Partial<NodeConfig['ssh']>) =>
+    setDraft(current => current === undefined ? current : { ...current, ssh: { ...current.ssh, ...change } })
+
+  const test = async () => {
+    if (draft === undefined) return
+    setTesting(true); setTested(undefined)
+    try {
+      setTested(await ask<TestResult>('test', { method: 'POST', body: JSON.stringify({ host: draft.ssh.host.trim(),
+        port: draft.ssh.port, user: draft.ssh.user.trim(), keyPath: draft.ssh.keyPath.trim() }) }))
+    } catch (error) { setTested({ ok: false, output: String(error) }) } finally { setTesting(false) }
+  }
+
+  const save = async () => {
+    if (draft === undefined || form === undefined) return
+    setNotice(undefined)
+    try {
+      const ok = await form.mutate(editsOf(draft), form.state.revision)
+      setNotice(ok ? t('saved') : t('saveFailed'))
+    } catch { setNotice(t('saveFailed')) }
+  }
+
+  if (draft === undefined) return <div data-foreman-node-page="loading">{t('loading')}</div>
+  const address = addressPreview(draft)
+  const missing = emptyFields(draft, keepsToken)
+  return <div data-foreman-node-page="ready">
+    <h2>{t('title')}</h2>
+    <p className="dt-hint">{t('intro')}</p>
+
+    <section data-section="keys">
+      <h3>{t('keysSection')}</h3>
+      <p className="dt-hint">{t('keysHint')}</p>
+      {keysFailed
+        ? <p data-keys="unavailable">{t('keysUnavailable')}</p>
+        : keys === undefined ? <p>{t('loading')}</p>
+          : keys.length === 0 ? <p data-keys="empty">{t('keysEmpty')}</p>
+            : <select aria-label={t('keysSection')} data-node-key value={draft.ssh.keyPath}
+                onChange={event => patchSsh({ keyPath: event.target.value })}>
+                <option value="">—</option>
+                {keys.map(key => <option key={key.path} value={key.path}>{keyLabel(key)}</option>)}
+              </select>}
+      <label>{t('keyPath')}
+        <input data-node-key-path value={draft.ssh.keyPath} disabled={!editable}
+          onChange={event => patchSsh({ keyPath: event.target.value })} />
+      </label>
+    </section>
+
+    <section data-section="ssh">
+      <h3>{t('sshSection')}</h3>
+      <label><input type="checkbox" data-node-ssh-enabled checked={draft.ssh.enabled} disabled={!editable}
+        onChange={event => patchSsh({ enabled: event.target.checked })} />{t('sshEnabled')}</label>
+      <p className="dt-hint">{t('sshEnabledHint')}</p>
+      {draft.ssh.enabled && <>
+        <label>{t('host')}<input data-node-host value={draft.ssh.host} disabled={!editable}
+          onChange={event => patchSsh({ host: event.target.value })} /></label>
+        <label>{t('port')}<input type="number" data-node-port value={draft.ssh.port} disabled={!editable}
+          onChange={event => patchSsh({ port: Number(event.target.value) || DEFAULT_SSH.port })} /></label>
+        <label>{t('user')}<input data-node-user value={draft.ssh.user} disabled={!editable}
+          onChange={event => patchSsh({ user: event.target.value })} /></label>
+        <label>{t('remotePort')}<input type="number" data-node-remote-port value={draft.ssh.remotePort} disabled={!editable}
+          onChange={event => patchSsh({ remotePort: Number(event.target.value) || DEFAULT_SSH.remotePort })} /></label>
+        <label>{t('localPort')}<input type="number" data-node-local-port value={draft.ssh.localPort} disabled={!editable}
+          onChange={event => patchSsh({ localPort: Number(event.target.value) || DEFAULT_SSH.localPort })} /></label>
+        <button type="button" data-node-test data-testing={testing ? 'true' : undefined}
+          disabled={!draft.ssh.host.trim() || !draft.ssh.user.trim() || !draft.ssh.keyPath.trim()}
+          onClick={() => { void test() }}>{testing ? t('testing') : t('test')}</button>
+        {tested !== undefined && <p data-test-result={testMessage(tested)}>
+          {tested.ok ? t('testOk')
+            : testMessage(tested) === 'passphrase' ? t('testPassphrase')
+              : testMessage(tested) === 'unresolved' ? t('testUnresolved')
+                : testMessage(tested) === 'timeout' ? t('testTimeout')
+                  : `${t('testRefused')} ${tested.output}`}
+        </p>}
+      </>}
+    </section>
+
+    <section data-section="hub">
+      <h3>{t('hubSection')}</h3>
+      <label>{t('address')}
+        <input data-node-url value={address.address} readOnly={address.derived} disabled={!editable || address.derived}
+          onChange={event => patch({ url: event.target.value })} />
+      </label>
+      {address.derived && <p className="dt-hint">{t('addressDerived')}</p>}
+      <label>{t('deviceId')}<input data-node-device value={draft.deviceId} disabled={!editable}
+        onChange={event => patch({ deviceId: event.target.value })} /></label>
+      <label>{t('token')}<input type="password" data-node-token value={draft.token} disabled={!editable}
+        autoComplete="new-password" placeholder={keepsToken ? t('tokenStored') : ''}
+        onChange={event => patch({ token: event.target.value })} /></label>
+      <p className="dt-hint">{keepsToken ? t('tokenKeep') : t('tokenHint')}</p>
+    </section>
+
+    <section data-section="roots">
+      <h3>{t('rootsSection')}</h3>
+      <p className="dt-hint">{t('rootsHint')}</p>
+      {draft.roots.map((root, index) => <div key={index} data-root={index}>
+        <label>{t('project')}<input value={root.project} disabled={!editable}
+          onChange={event => patch({ roots: draft.roots.map((item, at) => at === index ? { ...item, project: event.target.value } : item) })} /></label>
+        <label>{t('path')}<input value={root.path} disabled={!editable}
+          onChange={event => patch({ roots: draft.roots.map((item, at) => at === index ? { ...item, path: event.target.value } : item) })} /></label>
+      </div>)}
+      <button type="button" disabled={!editable}
+        onClick={() => patch({ roots: [...draft.roots, { project: '', path: '' }] })}>{t('addRoot')}</button>
+    </section>
+
+    {missing.length > 0 && <p data-missing="true">{t('missing')}{missing.join(', ')}</p>}
+    {editable
+      ? <button type="button" data-node-save onClick={() => { void save() }}>{t('save')}</button>
+      : <p data-read-only="true">{t('readOnly')}</p>}
+    {notice !== undefined && <p data-notice>{notice}</p>}
+  </div>
+}
+
+/** The page as the Plugin Manager mounts it: locale and form come from the host. */
+interface PageProps extends PluginConfigViewProps {
+  t: (key: keyof typeof zh) => string
+}
+
+function Mounted({ t, view, form = undefined }: PageProps) {
+  // A summary row gets nothing: the full page belongs to the page view, and DSH's own config form shows the summary.
+  return view === 'summary' ? null : <DevicePage t={t} form={form} />
+}
+
+/** Registers the page for the `dsh-foreman-node` row. */
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-foreman-node: dictionaries')
+  const t = ctx.locale.bind(NS) as unknown as (key: keyof typeof zh) => string
+  ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
+    name: 'plugins.row.config', key: 'dsh-foreman-node#dsh-foreman-node', locale: NS },
+  (props: PluginConfigViewProps) => <Mounted {...props} t={(props as { t?: typeof t }).t ?? t} />))
+}
+
+export { DevicePage }

package/src/client/locales.ts

@@ -0,0 +1,95 @@
+/** The device page's own words; the host renders them through its locale service. */
+export const zh = {
+  title: '设备连接',
+  intro: '这台机器用自己的密钥连上枢纽，隧道也由它自己开。填完保存后重启一次 DSH 生效。',
+  keysSection: '密钥',
+  keysHint: '从这台机器 ~/.ssh 里的密钥中挑一把。枢纽只认公钥，私钥不离开这里。',
+  keysEmpty: '~/.ssh 里没有可用的密钥（需要私钥和同名的 .pub 一起在）。',
+  keysUnavailable: '读不到密钥列表：配置页需要 DSH 的 Web 界面。',
+  keyPath: '私钥路径',
+  sshSection: 'SSH',
+  sshEnabled: '走 SSH 隧道',
+  sshEnabledHint: '枢纽只监听 127.0.0.1，所以别的机器要连它就得走隧道。关掉表示枢纽地址本身可达。',
+  host: '枢纽机器',
+  port: 'SSH 端口',
+  user: 'SSH 用户',
+  remotePort: '枢纽端口',
+  localPort: '本机端口',
+  test: '测试连接',
+  testing: '测试中…',
+  testPassphrase: '这台机器拒绝了这把钥匙。如果它有口令，请改用 ssh-agent，或换一把没有口令的。',
+  testUnresolved: '找不到这台枢纽机器，检查主机名。',
+  testTimeout: '超时了，网络不通或被防火墙挡住。',
+  testRefused: '连不上。',
+  testOk: '连上了。',
+  hubSection: '枢纽',
+  address: '设备将连接的地址',
+  addressDerived: '（由隧道推导，上面的地址不用于连接）',
+  deviceId: '设备 id',
+  token: '令牌',
+  tokenHint: '在枢纽的「设置 › 设备」里登记设备时得到，只显示那一次。',
+  tokenStored: '留空即保留已存的令牌',
+  tokenKeep: '已存的令牌不会显示在这里。留空表示不动它；只有要换一个时才需要填。',
+  rootsSection: '项目路径',
+  rootsHint: '枢纽把工单派到项目名；这里的路径是它在您这台机器上的位置。',
+  addRoot: '加一个项目',
+  project: '项目名',
+  path: '本机路径',
+  save: '保存',
+  saved: '已保存，重启 DSH 后生效。',
+  saveFailed: '保存失败。',
+  readOnly: '这个宿主不提供配置写入，请手工编辑 profile 的 cordis.patch.yml。',
+  loading: '读取配置…',
+  missing: '还需要填：',
+}
+
+export const en: typeof zh = {
+  title: 'Device connection',
+  intro: 'This machine reaches the hub with its own key and opens its own tunnel. Save, then restart DSH once.',
+  keysSection: 'Key',
+  keysHint: "Pick one of the keys in this machine's ~/.ssh. The hub only ever sees the public half.",
+  keysEmpty: 'No usable key in ~/.ssh: a private key needs its .pub beside it.',
+  keysUnavailable: 'The key list needs the DSH web interface.',
+  keyPath: 'Private key',
+  sshSection: 'SSH',
+  sshEnabled: 'Reach the hub through an SSH tunnel',
+  sshEnabledHint: 'The hub listens on 127.0.0.1 only, so another machine reaches it through a tunnel. Off means the hub address is already reachable.',
+  host: 'Hub machine',
+  port: 'SSH port',
+  user: 'SSH user',
+  remotePort: 'Hub port',
+  localPort: 'Local port',
+  test: 'Test connection',
+  testing: 'Testing…',
+  testPassphrase: 'This machine refused the key. If it has a passphrase, use ssh-agent or pick one without.',
+  testUnresolved: 'The hub machine does not resolve; check the host name.',
+  testTimeout: 'Timed out: the network is blocked or unreachable.',
+  testRefused: 'Could not connect.',
+  testOk: 'Connected.',
+  hubSection: 'Hub',
+  address: 'The address this device will dial',
+  addressDerived: ' (derived from the tunnel; the address above is not used)',
+  deviceId: 'Device id',
+  token: 'Token',
+  tokenHint: "Shown once when the device was registered, on the hub's Settings › Devices.",
+  tokenStored: 'leave empty to keep the stored token',
+  tokenKeep: 'The stored token is never shown here. Leave this empty to keep it; type a new one only to replace it.',
+  rootsSection: 'Project paths',
+  rootsHint: 'The hub assigns work by project name; this is where that project lives on this machine.',
+  addRoot: 'Add a project',
+  path: 'Local path',
+  project: 'Project',
+  save: 'Save',
+  saved: 'Saved. Restart DSH for it to take effect.',
+  saveFailed: 'Could not save.',
+  readOnly: "This host does not accept configuration writes; edit the profile's cordis.patch.yml by hand.",
+  loading: 'Reading configuration…',
+  missing: 'Still needed: ',
+}
+
+/** The page's key union, so a missing translation is a compile error rather than a raw key on screen. */
+export type DshNodeKey = keyof typeof zh
+
+declare module '@deepseek-ai/dsh-client-ui-renderer/client' {
+  interface LocaleNamespaceMap { dshNode: DshNodeKey }
+}

package/src/client/page-state.ts

@@ -0,0 +1,99 @@
+/**
+ * What the device's configuration page decides, as pure functions.
+ *
+ * The page itself is thin React: it renders these results and sends the field edits back through DSH's configuration
+ * form. Keeping the decisions here — which keys to offer, what the address becomes, what to say about a failed test —
+ * means they are provable without a DOM, which matters for a package this small.
+ */
+import type { NodeConfig, SshConfig } from '../config.ts'
+import type { SshKey } from '../keys.ts'
+import type { TestResult } from '../routes.ts'
+
+/** A key as one line of the picker: the filename and, when it has one, the comment that tells it apart. */
+export function keyLabel(key: SshKey): string {
+  return key.comment === '' ? key.name : `${key.name} · ${key.comment}`
+}
+
+/**
+ * The address the device will dial, spelled out for the page.
+ *
+ * With the tunnel on this is the local end of it and `url` is not used — which is the point a person most easily
+ * gets wrong, so the page says the address rather than leaving them to infer it.
+ */
+export function addressPreview(config: Pick<NodeConfig, 'url' | 'ssh'>): { address: string; derived: boolean } {
+  return config.ssh.enabled
+    ? { address: `ws://127.0.0.1:${config.ssh.localPort}`, derived: true }
+    : { address: config.url, derived: false }
+}
+
+/**
+ * The names of the fields that still have to be filled in, in the order the page shows them.
+ *
+ * This mirrors `missingConfiguration` for the page's benefit: the host reports the same thing in one sentence, and a
+ * form that highlights the empty field is the difference between reading a sentence and fixing it.
+ */
+export function emptyFields(config: NodeConfig, tokenPresent = true): string[] {
+  const empty: string[] = []
+  if (config.ssh.enabled) {
+    if (config.ssh.host.trim() === '') empty.push('ssh.host')
+    if (config.ssh.port === 0) empty.push('ssh.port')
+    if (config.ssh.user.trim() === '') empty.push('ssh.user')
+    if (config.ssh.keyPath.trim() === '') empty.push('ssh.keyPath')
+  } else if (config.url.trim() === '') empty.push('url')
+  if (config.deviceId.trim() === '') empty.push('deviceId')
+  // The token is a secret: it never reaches the page, so an absent value means "already stored", not "missing".
+  // A page that asked for it here would nag about a field it cannot see and cannot show.
+  if (!tokenPresent) empty.push('token')
+  return empty
+}
+
+/**
+ * What to say about one authentication test.
+ *
+ * A passphrase-protected key fails with the same words as a wrong one, so the message names both possibilities; the
+ * other failures are ssh's own and are shown as they are, which is enough for someone who can read them.
+ */
+/** Whether the page should ask for a token: only when nothing is stored yet. */
+export function needsToken(config: Pick<NodeConfig, 'token'>): boolean {
+  return typeof config.token !== 'string' || config.token.trim() === ''
+}
+
+export function testMessage(result: TestResult): string {
+  if (result.ok) return 'ok'
+  if (/Permission denied \(publickey/.test(result.output)) return 'passphrase'
+  if (/Could not resolve hostname/.test(result.output)) return 'unresolved'
+  if (/timed out/i.test(result.output)) return 'timeout'
+  return result.output.trim() === '' ? 'refused' : result.output
+}
+
+/** One field write, in the shape DSH's configuration form takes. */
+export interface Edit { op: 'set'; path: (string | number)[]; value: unknown }
+
+/**
+ * The edits the page sends, one `set` per field it actually holds.
+ *
+ * This is deliberately not one `set` at the root. A root write replaces the whole section, and the page never
+ * receives the token — the host strips it as a secret — so a root write erased the stored token on every save and
+ * left the device unable to authenticate. It did exactly that on a real machine: one save took the device offline.
+ *
+ * Writing only the fields this page holds leaves every other key untouched, the token included. An empty token box
+ * means "keep whatever is stored", and that is one value the page cannot read at all.
+ */
+export function editsOf(draft: NodeConfig): Edit[] {
+  const edits: Edit[] = [
+    { op: 'set', path: ['url'], value: draft.url.trim() },
+    { op: 'set', path: ['deviceId'], value: draft.deviceId.trim() },
+    { op: 'set', path: ['roots'], value: draft.roots.map(root => ({ project: root.project.trim(), path: root.path.trim() })) },
+  ]
+  // The ssh block is written field by field: a whole-block set would replace its default with the page's view.
+  for (const key of ['enabled', 'host', 'port', 'user', 'keyPath', 'remotePort', 'localPort'] as const) {
+    const value = draft.ssh[key]
+    edits.push({ op: 'set', path: ['ssh', key], value: typeof value === 'string' ? value.trim() : value })
+  }
+  const token = typeof draft.token === 'string' ? draft.token.trim() : ''
+  if (token !== '') edits.push({ op: 'set', path: ['token'], value: token })
+  return edits
+}
+
+/** The SSH block a fresh page starts from, matching the schema's defaults so an untouched field is not a change. */
+export const DEFAULT_SSH: SshConfig = { enabled: false, host: '', port: 22, user: '', keyPath: '', remotePort: 8790, localPort: 8790 }

package/src/config.ts

@@ -0,0 +1,100 @@
+/**
+ * The device's configuration shape, with no Node imports.
+ *
+ * This module exists so the browser page and the Node plugin can share one definition. The page must not import
+ * `index.ts`: that file pulls in `node:net`, `node:child_process` and the job-session code, and a browser bundle that
+ * reaches them fails to load at boot — which is exactly how the first 0.2.0 build broke.
+ */
+
+/** One project this device can work on: the hub's logical name and this machine's own absolute path. */
+export interface NodeRoot { project: string; path: string }
+
+/**
+ * How the device reaches a hub it cannot reach directly.
+ *
+ * The hub listens on loopback only — a deliberate constraint, because the ledger is the one thing worth protecting —
+ * so a device on another machine reaches it through a tunnel. With `enabled` the device opens that tunnel itself and
+ * dials its own end of it; `url` is then unused, not overridden, so switching back to a direct address restores it.
+ */
+export interface SshConfig {
+  /** Open a tunnel to the hub instead of dialling `url` directly. */
+  enabled: boolean
+  /** The hub machine: an address or a `~/.ssh/config` alias. */
+  host: string
+  /** The hub machine's SSH port. */
+  port: number
+  /** The SSH user on the hub machine. */
+  user: string
+  /** The private key this device authenticates with. The configuration page lists these from `~/.ssh`. */
+  keyPath: string
+  /** The port the hub listens on, on the hub machine. */
+  remotePort: number
+  /** The local port the tunnel listens on; the device dials this. */
+  localPort: number
+}
+
+/** What the `dsh-foreman-node` entry in a profile's patch configures. */
+export interface NodeConfig {
+  /** The hub's stable address; the device dials out to it. Blank until someone fills it in. */
+  url: string
+  /** This device's id, as registered on the hub with `Devices.add`. Blank until someone fills it in. */
+  deviceId: string
+  /** This device's token; sent in the hello and nowhere else. Blank until someone fills it in. */
+  token: string
+  /** The projects this device can work on. */
+  roots: NodeRoot[]
+  /** How often to tell the hub this device is alive, in milliseconds. */
+  heartbeatMs: number
+  /** Delay before the first reconnect attempt, in milliseconds. */
+  reconnectMs: number
+  /** How to reach a hub that is not directly reachable. */
+  ssh: SshConfig
+}
+
+/** The SSH defaults, spread over whatever the host hands in, so a partial block is still complete. */
+export const SSH_DEFAULTS: SshConfig = { enabled: false, host: '', port: 22, user: '', keyPath: '', remotePort: 8790, localPort: 8790 }
+
+/** A volatile field arrives wrapped; this reads it either way, so callers do not have to know which. */
+const valueOf = <T>(field: T | { get(): T } | undefined, fallback: T): T => {
+  if (field === undefined) return fallback
+  if (typeof field === 'object' && field !== null && 'get' in field && typeof (field as { get?: unknown }).get === 'function') {
+    return (field as { get(): T }).get()
+  }
+  return field as T
+}
+
+/**
+ * Unwrap a whole configuration: every field may be a volatile wrapper, a plain value, or absent.
+ *
+ * `Config` already applies defaults, so `apply` sees a complete object. This is for the paths that do not go through
+ * the schema: the configuration page's read, and a `cordis.patch.yml` written before a field existed.
+ */
+/**
+ * Unwrap the `ssh` block.
+ *
+ * Its fields are volatile for the same reason the top level is, so each may arrive wrapped. Reading them all through
+ * `valueOf` keeps one unwrapping rule instead of two, and it means a plain partial block (an older patch file) works
+ * just as well as a wrapped one.
+ */
+function unwrapSsh(block: unknown): Partial<SshConfig> {
+  if (block === null || typeof block !== 'object') return {}
+  const source = block as Record<string, unknown>
+  return {
+    enabled: valueOf(source['enabled'] as boolean, SSH_DEFAULTS.enabled),
+    host: valueOf(source['host'] as string, SSH_DEFAULTS.host),
+    port: valueOf(source['port'] as number, SSH_DEFAULTS.port),
+    user: valueOf(source['user'] as string, SSH_DEFAULTS.user),
+    keyPath: valueOf(source['keyPath'] as string, SSH_DEFAULTS.keyPath),
+    remotePort: valueOf(source['remotePort'] as number, SSH_DEFAULTS.remotePort),
+    localPort: valueOf(source['localPort'] as number, SSH_DEFAULTS.localPort),
+  }
+}
+
+export function configured(config: object | undefined): NodeConfig {
+  const source = (config ?? {}) as Record<string, unknown>
+  return { url: valueOf(source['url'] as string, ''), deviceId: valueOf(source['deviceId'] as string, ''),
+    token: valueOf(source['token'] as string, ''), roots: valueOf(source['roots'] as NodeRoot[], []),
+    heartbeatMs: valueOf(source['heartbeatMs'] as number, 15_000), reconnectMs: valueOf(source['reconnectMs'] as number, 1_000),
+    // `ssh` holds volatile fields too, so each one is unwrapped like the top level.
+    ssh: { ...SSH_DEFAULTS, ...unwrapSsh(source['ssh']) } }
+}