@goodandready/dsh-github-ops 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 Notable changes to `@goodandready/dsh-github-ops`.
 
+## 0.2.2
+
+### Fixed
+- Settings no longer wait on the removed settingsScope service. The client uses configForms (#39).
+
+## 0.2.1
+
+Two things: the Source Control tab learned to write, and a class of defect that silently killed
+tool results is closed for good.
+
+### The tab can write now
+
+- a commit bar: message, `amend`, Commit, Commit & push, and a button that pushes when the branch
+  is ahead and syncs (rebase pull with autostash, then push) when it is behind;
+- per-file stage and unstage, and discard behind a two-second-click confirmation;
+- branches: create from the current one, switch, delete and push; stashes: save with a message,
+  apply, pop and drop — the destructive ones behind the same confirmation;
+- an unfinished merge, rebase, cherry-pick or revert shows its own bar with continue and abort;
+- every write is a named action: the host builds validated argv (`lib/scm-write.js`) and never a
+  shell string, refuses the destructive ones without an explicit confirmation, and reports which
+  step failed and what git said.
+
+### Every tool result survives JSON without loss
+
+- a live call to `gh_repo_tree` failed with "value is not lossless JSON" because a directory entry
+  in a git tree has no `size`, and the result carried `size: undefined`; the harness refuses the
+  whole call for one value it cannot serialise;
+- `lib/lossless.js` now decides what a result may contain (dropping `undefined`, replacing `NaN`
+  and the infinities with `null`, converting `Date`, `Map`, `Set`, typed arrays, `Buffer` and
+  `BigInt`, naming a cycle instead of following it, dropping functions and symbols), and the tool
+  wrapper applies it to every result, success and failure alike, so no single tool has to remember
+  the rule;
+- `gh_repo_tree` no longer invents the field at all: a directory carries no `size` key;
+- the contract is written into `docs/design/DESIGN.md`, section 5.
+
+
 ## 0.2.0
 
 The development wave: reliability, reports, writing without a checkout, and the user surfaces.

package/lib/client.js

@@ -80,6 +80,32 @@ window.__ModuleLoader__.load({
       scmStashes: 'Stashes',
       scmInProgress: 'In progress',
       scmNoUpstream: 'no upstream',
+      scmCommit: 'Commit',
+      scmCommitPush: 'Commit & push',
+      scmSync: 'Sync',
+      scmAmend: 'amend',
+      scmMessage: 'Commit message',
+      scmStage: 'Stage',
+      scmUnstage: 'Unstage',
+      scmDiscard: 'Discard',
+      scmConfirm: 'Confirm?',
+      scmNewBranch: 'New branch',
+      scmCreate: 'Create',
+      scmDelete: 'Delete',
+      scmSwitch: 'Switch',
+      scmStashSave: 'Save stash',
+      scmStashApply: 'Apply',
+      scmStashPop: 'Pop',
+      scmStashDrop: 'Drop',
+      scmContinue: 'Continue',
+      scmAbort: 'Abort',
+      scmWorking: 'Working…',
+      scmActionFailed: 'git refused',
+      scmNoChanges: 'Nothing staged or changed',
+      scmBehindHint: 'Behind the upstream: sync pulls with rebase, then pushes',
+      scmPushBranch: 'Push branch',
+      scmRepoPath: 'Repository path (optional)',
+      scmRepoPathHint: 'Absolute path; empty means the session workspace',
       prBarBranch: 'to',
       prBarCommits: 'commit(s) ahead',
       panelTitle: 'GitHub',
@@ -155,6 +181,32 @@ window.__ModuleLoader__.load({
       scmStashes: '暂存',
       scmInProgress: '进行中',
       scmNoUpstream: '无上游',
+      scmCommit: '提交',
+      scmCommitPush: '提交并推送',
+      scmSync: '同步',
+      scmAmend: '修补',
+      scmMessage: '提交信息',
+      scmStage: '暂存',
+      scmUnstage: '取消暂存',
+      scmDiscard: '放弃更改',
+      scmConfirm: '确认？',
+      scmNewBranch: '新分支',
+      scmCreate: '创建',
+      scmDelete: '删除',
+      scmSwitch: '切换',
+      scmStashSave: '保存 stash',
+      scmStashApply: '应用',
+      scmStashPop: '弹出',
+      scmStashDrop: '删除',
+      scmContinue: '继续',
+      scmAbort: '中止',
+      scmWorking: '执行中…',
+      scmActionFailed: 'git 拒绝',
+      scmNoChanges: '没有已暂存或已修改的内容',
+      scmBehindHint: '落后于上游：同步会先 rebase 拉取，再推送',
+      scmPushBranch: '推送分支',
+      scmRepoPath: '仓库路径（可选）',
+      scmRepoPathHint: '绝对路径；留空则使用会话工作区',
       prBarBranch: '→',
       prBarCommits: '个提交领先',
       panelTitle: 'GitHub',
@@ -204,6 +256,24 @@ window.__ModuleLoader__.load({
       const [state, setState] = React.useState({ phase: 'loading' })
       const [selected, setSelected] = React.useState(null)
       const [diff, setDiff] = React.useState({ phase: 'idle', text: '' })
+      const [busy, setBusy] = React.useState('')
+      const [actionError, setActionError] = React.useState('')
+      const [message, setMessage] = React.useState('')
+      const [amend, setAmend] = React.useState(false)
+      const [confirming, setConfirming] = React.useState('')
+      const [branchName, setBranchName] = React.useState('')
+      const [stashMessage, setStashMessage] = React.useState('')
+      const [repoPath, setRepoPath] = React.useState(() => {
+        try { return localStorage.getItem('gho-scm-cwd') || '' } catch { return '' }
+      })
+
+      // The tab reads the session workspace by default; an explicit path lets it look at any
+      // repository the local user names.
+      const cwdQuery = repoPath ? `cwd=${encodeURIComponent(repoPath)}` : ''
+      const rememberPath = (value) => {
+        setRepoPath(value)
+        try { value ? localStorage.setItem('gho-scm-cwd', value) : localStorage.removeItem('gho-scm-cwd') } catch { /* private mode */ }
+      }
 
       const load = React.useCallback(() => {
         setState({ phase: 'loading' })
@@ -211,14 +281,41 @@ window.__ModuleLoader__.load({
           setState({ phase: 'error', message: 'fetch is unavailable in this client' })
           return
         }
-        fetch(SCM_PATH, { headers: { accept: 'application/json' } })
+        fetch(cwdQuery ? `${SCM_PATH}?${cwdQuery}` : SCM_PATH, { headers: { accept: 'application/json' } })
           .then((response) => (response.ok ? response.json() : Promise.reject(new Error(`HTTP ${response.status}`))))
           .then((payload) => setState({ phase: 'ready', payload }))
           .catch((err) => setState({ phase: 'error', message: String((err && err.message) || err) }))
-      }, [])
+      }, [repoPath])
 
       React.useEffect(() => { load() }, [load])
 
+      // Every write is one named action; the host validates it and runs argv, never a shell.
+      const runAction = (action, args) => {
+        if (typeof fetch !== 'function') return
+        setBusy(action)
+        setActionError('')
+        fetch(SCM_PATH, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json' },
+          body: JSON.stringify(repoPath ? { action, args: args || {}, cwd: repoPath } : { action, args: args || {} }),
+        })
+          .then((response) => (response.ok ? response.json() : Promise.reject(new Error(`HTTP ${response.status}`))))
+          .then((payload) => {
+            setBusy('')
+            setConfirming('')
+            if (!payload || payload.ok !== true) setActionError((payload && payload.error) || t('scmActionFailed'))
+            load()
+          })
+          .catch((err) => { setBusy(''); setActionError(String((err && err.message) || err)) })
+      }
+
+      // Destructive actions ask twice: the first click arms the button, the second runs it.
+      const armed = (key, action, args) => {
+        if (confirming !== key) { setConfirming(key); return }
+        setConfirming('')
+        runAction(action, args)
+      }
+
       const openDiff = (file, staged) => {
         setSelected({ path: file.path, staged })
         setDiff({ phase: 'loading', text: '' })
@@ -229,18 +326,34 @@ window.__ModuleLoader__.load({
           .catch((err) => setDiff({ phase: 'error', text: String((err && err.message) || err) }))
       }
 
-      const fileRow = (file, staged) => React.createElement('div', {
-        key: `${staged ? 's' : 'w'}-${file.path}`,
-        className: 'gho-scm-file',
-        role: 'button',
-        tabIndex: 0,
-        'aria-selected': selected && selected.path === file.path && selected.staged === staged,
-        onClick: () => openDiff(file, staged),
-        onKeyDown: (event) => { if (event.key === 'Enter' || event.key === ' ') openDiff(file, staged) },
-      },
-        React.createElement('span', { className: 'gho-scm-badge' }, file.status),
-        React.createElement('span', { className: 'gho-scm-path' }, file.renamedFrom ? `${file.renamedFrom} → ${file.path}` : file.path),
-      )
+      const button = (label, onClick, options) => React.createElement('button', {
+        type: 'button',
+        className: `gho-scm-btn${options && options.warn ? ' gho-scm-btn-warn' : ''}`,
+        disabled: Boolean(busy) || Boolean(options && options.disabled),
+        onClick,
+      }, label)
+
+      const fileRow = (file, staged) => {
+        const discardKey = `discard:${file.path}`
+        return React.createElement('div', {
+          key: `${staged ? 's' : 'w'}-${file.path}`,
+          className: 'gho-scm-file',
+          role: 'button',
+          tabIndex: 0,
+          'aria-selected': selected && selected.path === file.path && selected.staged === staged,
+          onClick: () => openDiff(file, staged),
+          onKeyDown: (event) => { if (event.key === 'Enter' || event.key === ' ') openDiff(file, staged) },
+        },
+          React.createElement('span', { className: 'gho-scm-badge' }, file.status),
+          React.createElement('span', { className: 'gho-scm-path' }, file.renamedFrom ? `${file.renamedFrom} → ${file.path}` : file.path),
+          React.createElement('span', { className: 'gho-scm-actions' },
+            staged
+              ? button(t('scmUnstage'), () => runAction('unstage', { path: file.path }))
+              : button(t('scmStage'), () => runAction('stage', { path: file.path })),
+            button(confirming === discardKey ? t('scmConfirm') : t('scmDiscard'), () => armed(discardKey, 'discard', { path: file.path, confirm: true }), { warn: true }),
+          ),
+        )
+      }
 
       const group = (title, files, staged) => (files && files.length
         ? React.createElement('div', { className: 'gho-scm-group', key: title },
@@ -254,7 +367,7 @@ window.__ModuleLoader__.load({
         return React.createElement('div', { className: 'gho-scm' },
           React.createElement('div', { className: 'gho-scm-group-head' }, t('scmError')),
           React.createElement('div', { className: 'gho-scm-meta' }, state.message),
-          React.createElement('button', { type: 'button', className: 'gho-link', onClick: load }, t('scmRefresh')),
+          button(t('scmRefresh'), load),
         )
       }
       const payload = state.payload || {}
@@ -262,25 +375,99 @@ window.__ModuleLoader__.load({
         return React.createElement('div', { className: 'gho-scm' },
           React.createElement('div', { className: 'gho-scm-group-head' }, t('scmNotRepo')),
           payload.error ? React.createElement('div', { className: 'gho-scm-meta' }, payload.error) : null,
-          React.createElement('button', { type: 'button', className: 'gho-link', onClick: load }, t('scmRefresh')),
+          button(t('scmRefresh'), load),
         )
       }
-      const files = payload.files || { staged: [], changes: [], untracked: [], unmerged: [] }
+      const files = payload.files || { staged: [], changes: [], untracked: [], unmerged: [], total: 0 }
       const clean = !files.total
+      const canCommit = files.staged.length > 0 && message.trim().length > 0 && !busy
+      const ahead = payload.ahead || 0
+      const behind = payload.behind || 0
+
+      const commitBar = React.createElement('div', { className: 'gho-scm-bar' },
+        React.createElement('input', {
+          type: 'text',
+          value: message,
+          placeholder: t('scmMessage'),
+          onChange: (event) => setMessage(event.target.value),
+          onKeyDown: (event) => { if (event.key === 'Enter' && canCommit) runAction('commit', { message, amend }) },
+        }),
+        React.createElement('label', { className: 'gho-scm-check' },
+          React.createElement('input', { type: 'checkbox', checked: amend, onChange: (event) => setAmend(event.target.checked) }),
+          t('scmAmend'),
+        ),
+        button(t('scmCommit'), () => runAction('commit', { message, amend }), { disabled: !canCommit }),
+        button(t('scmCommitPush'), () => runAction('commit', { message, amend, push: true }), { disabled: !canCommit }),
+        button(behind > 0 ? t('scmSync') : t('scmPushBranch'), () => runAction(behind > 0 ? 'sync' : 'push', {}), { disabled: Boolean(busy) || (ahead === 0 && behind === 0) }),
+      )
+
+      const mergeBar = payload.mergeState && payload.mergeState.inProgress
+        ? React.createElement('div', { className: 'gho-scm-bar' },
+          React.createElement('span', null, `${t('scmInProgress')}: ${payload.mergeState.kind}`),
+          button(t('scmContinue'), () => runAction('continue', { verb: payload.mergeState.kind })),
+          button(confirming === 'abort' ? t('scmConfirm') : t('scmAbort'), () => armed('abort', 'abort', { verb: payload.mergeState.kind, confirm: true }), { warn: true }),
+        )
+        : null
+
+      const branchBar = React.createElement('div', { className: 'gho-scm-bar' },
+        React.createElement('input', {
+          type: 'text',
+          value: branchName,
+          placeholder: t('scmNewBranch'),
+          onChange: (event) => setBranchName(event.target.value),
+        }),
+        button(t('scmCreate'), () => runAction('branchCreate', { branch: branchName }), { disabled: !branchName.trim() || Boolean(busy) }),
+        (payload.branches || []).filter((b) => !b.current).slice(0, 6).map((b) => button(
+          confirming === `branch:${b.name}` ? `${b.name}: ${t('scmConfirm')}` : `${t('scmSwitch')} ${b.name}`,
+          () => armed(`branch:${b.name}`, 'branchCheckout', { branch: b.name }),
+        )),
+        (payload.branches || []).filter((b) => !b.current).slice(0, 6).map((b) => button(
+          confirming === `del:${b.name}` ? `${t('scmDelete')}?` : `${t('scmDelete')} ${b.name}`,
+          () => armed(`del:${b.name}`, 'branchDelete', { branch: b.name, confirm: true }),
+          { warn: true },
+        )),
+      )
+
+      const stashBar = React.createElement('div', { className: 'gho-scm-bar' },
+        React.createElement('input', {
+          type: 'text',
+          value: stashMessage,
+          placeholder: t('scmStashSave'),
+          onChange: (event) => setStashMessage(event.target.value),
+        }),
+        button(t('scmStashSave'), () => runAction('stashPush', { message: stashMessage }), { disabled: Boolean(busy) }),
+        (payload.stashes || []).slice(0, 4).map((entry) => button(`${t('scmStashApply')} ${entry.ref}`, () => runAction('stashApply', { ref: entry.ref }))),
+        (payload.stashes || []).slice(0, 4).map((entry) => button(`${t('scmStashPop')} ${entry.ref}`, () => runAction('stashPop', { ref: entry.ref }))),
+        (payload.stashes || []).slice(0, 4).map((entry) => button(
+          confirming === `stash:${entry.ref}` ? `${entry.ref}: ${t('scmConfirm')}` : `${t('scmStashDrop')} ${entry.ref}`,
+          () => armed(`stash:${entry.ref}`, 'stashDrop', { ref: entry.ref, confirm: true }),
+          { warn: true },
+        )),
+      )
 
       return React.createElement('div', { className: 'gho-scm' },
         React.createElement('div', { className: 'gho-scm-head' },
           React.createElement('span', { className: 'gho-scm-repo' }, payload.cwd || ''),
           React.createElement('span', { className: 'gho-scm-branch' }, payload.branch),
           payload.upstream
-            ? React.createElement('span', { className: 'gho-scm-counts' }, `↑${payload.ahead ?? 0} ↓${payload.behind ?? 0}`)
+            ? React.createElement('span', { className: 'gho-scm-counts' }, `↑${ahead} ↓${behind}`)
             : React.createElement('span', { className: 'gho-scm-counts' }, t('scmNoUpstream')),
-          React.createElement('button', { type: 'button', className: 'gho-link', onClick: load }, t('scmRefresh')),
+          button(busy ? t('scmWorking') : t('scmRefresh'), load, { disabled: Boolean(busy) }),
         ),
-        payload.mergeState && payload.mergeState.inProgress
-          ? React.createElement('div', { className: 'gho-scm-meta' },
-            React.createElement('span', { className: 'gho-scm-chip' }, `${t('scmInProgress')}: ${payload.mergeState.kind}`))
-          : null,
+        React.createElement('div', { className: 'gho-scm-bar' },
+          React.createElement('input', {
+            type: 'text',
+            value: repoPath,
+            placeholder: t('scmRepoPath'),
+            title: t('scmRepoPathHint'),
+            onChange: (event) => rememberPath(event.target.value),
+            onKeyDown: (event) => { if (event.key === 'Enter') load() },
+          }),
+        ),
+        actionError ? React.createElement('div', { className: 'gho-scm-meta gho-scm-error' }, `${t('scmActionFailed')}: ${actionError}`) : null,
+        behind > 0 ? React.createElement('div', { className: 'gho-scm-meta' }, t('scmBehindHint')) : null,
+        mergeBar,
+        commitBar,
         clean ? React.createElement('div', { className: 'gho-scm-meta' }, t('scmNothing')) : null,
         group(t('scmConflicts'), files.unmerged, false),
         group(t('scmStaged'), files.staged, true),
@@ -290,15 +477,14 @@ window.__ModuleLoader__.load({
           ? React.createElement('pre', { className: 'gho-scm-diff' },
             diff.phase === 'loading' ? t('scmLoading') : (diff.text || t('scmDiffEmpty')))
           : null,
+        branchBar,
+        stashBar,
         React.createElement('div', { className: 'gho-scm-meta' },
-          React.createElement('span', null, `${t('scmBranches')}: ${(payload.branches || []).map((b) => (b.current ? `*${b.name}` : b.name)).join(', ') || '—'}`),
           React.createElement('span', null, `${t('scmTags')}: ${(payload.tags || []).join(', ') || '—'}`),
-          React.createElement('span', null, `${t('scmStashes')}: ${(payload.stashes || []).length}`),
         ),
       )
     }
 
-
     /**
      * The pull request bar above the composer.
      *
@@ -586,6 +772,14 @@ window.__ModuleLoader__.load({
         '.gho-panel-muted{color:var(--dsw-alias-label-tertiary)}',
         '.gho-panel-file{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}',
         '.gho-panel-pre{margin:0;max-height:340px;overflow:auto;background:var(--dsw-alias-bg-layer-3);border-radius:8px;padding:8px;white-space:pre;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}',
+        '.gho-scm-bar{display:flex;gap:6px;align-items:center;flex-wrap:wrap;border:1px solid var(--dsw-alias-border-l2);border-radius:10px;padding:8px 10px}',
+        '.gho-scm-bar input[type="text"]{flex:1;min-width:160px;height:28px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-3);color:var(--dsw-alias-label-primary);padding:0 8px;font:inherit}',
+        '.gho-scm-btn{appearance:none;font:inherit;font-size:12px;cursor:pointer;border:1px solid var(--dsw-alias-border-l2);background:0 0;color:var(--dsw-alias-label-primary);border-radius:8px;padding:3px 8px}',
+        '.gho-scm-btn[disabled]{opacity:.5;cursor:default}',
+        '.gho-scm-btn-warn{border-color:var(--dsw-alias-label-error,#c0392b);color:var(--dsw-alias-label-error,#c0392b)}',
+        '.gho-scm-actions{display:flex;gap:4px;margin-left:auto}',
+        '.gho-scm-check{display:flex;align-items:center;gap:4px;color:var(--dsw-alias-label-secondary)}',
+        '.gho-scm-error{color:var(--dsw-alias-label-error,#c0392b)}',
         '.gho-input-area{height:auto;min-height:64px;padding:8px 12px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;resize:vertical}',
         '.gho-input{height:34px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px}',
         '.gho-foot{border-top:1px solid var(--dsw-alias-border-l2);display:flex;justify-content:flex-end;align-items:center;gap:8px;padding:12px 0 4px}',
@@ -641,7 +835,7 @@ window.__ModuleLoader__.load({
 
       let scope = null
       try {
-        scope = ctx && ctx.settingsScope && ctx.settingsScope.bind({ namespace: NS })
+        scope = ctx && ctx.configForms && ctx.configForms.get(NS)
       } catch {
         scope = null
       }
@@ -896,10 +1090,15 @@ window.__ModuleLoader__.load({
         /* a core without the session view ring: the rest of the plugin still works */
       }
 
-    exports.inject = ['slots', 'locale', 'settingsScope']
+    exports.inject = ['slots', 'locale', 'configForms']
     exports.apply = apply
     exports.GitHubOpsCard = GitHubOpsCard
     exports.SourceControlView = SourceControlView
+    exports.SCM_ACTIONS = [
+      'stage', 'unstage', 'discard', 'commit', 'push', 'sync',
+      'branchCreate', 'branchCheckout', 'branchDelete',
+      'stashPush', 'stashApply', 'stashPop', 'stashDrop', 'continue', 'abort',
+    ]
     exports.PullRequestBar = PullRequestBar
     exports.GitHubPanel = GitHubPanel
     return module.exports

package/lib/index.js

@@ -31,6 +31,7 @@ import { accessFilePath, readAccessFile } from './auth-device.js'
 import { DEFAULT_CLIENT_ID, DEFAULT_SCOPE } from './auth-device.js'
 import { GUIDANCE_SECTION, GUIDANCE_ORDER, guidanceText } from './guidance.js'
 import { registerRoutes, STATUS_PATH, SCM_PATH, PANEL_PATH } from './routes.js'
+import { lossless } from './lossless.js'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
@@ -326,7 +327,9 @@ export function apply(ctx, rawConfig) {
               // a cache reset must never fail a successful call
             }
           }
-          return { ok: true, data: value }
+          // One place decides what a result may contain: the harness refuses a value that
+          // cannot be serialised losslessly, and it refuses the whole call for one undefined.
+          return { ok: true, data: lossless(value) }
         } catch (err) {
           const out = { ok: false, error: describeError(err) }
           if (err instanceof GitHubError) {
@@ -334,7 +337,7 @@ export function apply(ctx, rawConfig) {
             if (err.code) out.code = err.code
             if (err.rateLimit) out.rateLimit = err.rateLimit
           }
-          return out
+          return lossless(out)
         }
       },
     })

package/lib/lossless.js

@@ -0,0 +1,90 @@
+// Making every tool result survive JSON without losing anything.
+//
+// The harness refuses a tool result that cannot be serialised losslessly, and it refuses the
+// WHOLE call: one `undefined` deep inside a payload drops the answer the caller waited for. That
+// is how a directory entry without a `size` field took down `gh_repo_tree`, and how the same
+// class of defect took down two tools of another plugin.
+//
+// This module is the single place that decides what a result may contain. It is applied to every
+// tool result in one wrapper, so no individual tool has to remember the rule.
+
+const MAX_DEPTH = 40
+
+/**
+ * Return a value that serialises identically in every JSON implementation:
+ * - `undefined` is dropped from objects and becomes `null` inside arrays (JSON has no holes);
+ * - `NaN` and the infinities become `null` (they have no JSON form);
+ * - a `Date` becomes its ISO string; a `Map` an object; a `Set` and a typed array an array; a
+ *   `Buffer` a base64 string;
+ * - functions and symbols are dropped — they cannot be sent anywhere;
+ * - a `BigInt` becomes a string (JSON has no integer that large);
+ * - a cycle becomes the string "[circular]" instead of endless recursion.
+ */
+export function lossless(value, depth = 0, seen = new WeakSet()) {
+  if (value === null) return null
+  const type = typeof value
+  if (type === 'string' || type === 'boolean') return value
+  if (type === 'number') return Number.isFinite(value) ? value : null
+  if (type === 'bigint') return value.toString()
+  if (type === 'undefined' || type === 'function' || type === 'symbol') return undefined
+
+  if (depth > MAX_DEPTH) return '[too deep]'
+  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.toISOString() : null
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) return value.toString('base64')
+
+  if (typeof value === 'object') {
+    if (seen.has(value)) return '[circular]'
+    seen.add(value)
+
+    if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+      const out = Array.from(value, (item) => {
+        const converted = lossless(item, depth + 1, seen)
+        return converted === undefined ? null : converted
+      })
+      seen.delete(value)
+      return out
+    }
+    if (value instanceof Map) {
+      const out = {}
+      for (const [key, item] of value.entries()) {
+        const converted = lossless(item, depth + 1, seen)
+        if (converted !== undefined) out[String(key)] = converted
+      }
+      seen.delete(value)
+      return out
+    }
+    if (value instanceof Set) {
+      const out = []
+      for (const item of value.values()) {
+        const converted = lossless(item, depth + 1, seen)
+        out.push(converted === undefined ? null : converted)
+      }
+      seen.delete(value)
+      return out
+    }
+
+    const out = {}
+    for (const key of Object.keys(value)) {
+      const converted = lossless(value[key], depth + 1, seen)
+      if (converted !== undefined) out[key] = converted
+    }
+    seen.delete(value)
+    return out
+  }
+
+  return undefined
+}
+
+/**
+ * Whether a value would pass the harness's check. Kept as a separate, tiny predicate so tests can
+ * assert the rule instead of comparing strings.
+ */
+export function isLossless(value) {
+  try {
+    const once = JSON.stringify(value)
+    if (once === undefined) return false
+    return JSON.stringify(lossless(JSON.parse(once))) === once
+  } catch {
+    return false
+  }
+}

package/lib/routes.js

@@ -5,10 +5,11 @@
 // stays a composition: the card, the Source Control tab and the sidebar panel each need one
 // endpoint, and none of them needs a tool.
 
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { join as joinPath } from 'node:path'
 
 import { statusPayload, isTrustedRequest, sendJson } from './status.js'
+import { buildAction, validateCwd } from './scm-write.js'
 import { parseStatus, parseBranches, parseStashes, parseCount, scmPayload, mergeStateFrom } from './scm.js'
 import { listIssues } from './tools/issues.js'
 import { listRuns } from './tools/actions.js'
@@ -84,14 +85,68 @@ export function registerRoutes(ctx, deps) {
         kind: 'exact',
         path: SCM_PATH,
         handler: async (req, res) => {
-          if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed' })
+          if (req.method !== 'GET' && req.method !== 'POST') return sendJson(res, 405, { error: 'method not allowed' })
           if (!isTrustedRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
           const git = makeGitRunner()
-          const cwd = (typeof ctx.cwd === 'string' && ctx.cwd) || process.cwd()
+          // The tab may look at another directory than the session workspace; the value is
+          // validated, must exist and must be a directory.
+          const requested = validateCwd(url.searchParams.get('cwd') || '')
+          let cwd = (typeof ctx.cwd === 'string' && ctx.cwd) || process.cwd()
+          if (requested) {
+            if (!existsSync(requested) || !statSync(requested).isDirectory()) {
+              return sendJson(res, 400, { error: `not a directory: ${requested}` })
+            }
+            cwd = requested
+          }
           const url = new URL(req.url || '/', 'http://localhost')
           const file = url.searchParams.get('file') || ''
           const staged = url.searchParams.get('staged') === '1'
 
+          if (req.method === 'POST') {
+            // A write always comes from a click in the panel. The body names one action; the
+            // argv it becomes is built and validated in lib/scm-write.js, and every step is
+            // run on its own — never through a shell.
+            let body = {}
+            try {
+              body = await readJsonBody(req)
+            } catch (err) {
+              return sendJson(res, 400, { ok: false, error: String((err && err.message) || err) })
+            }
+            if (body.cwd) {
+              try {
+                const wanted = validateCwd(body.cwd)
+                if (wanted) {
+                  if (!existsSync(wanted) || !statSync(wanted).isDirectory()) {
+                    return sendJson(res, 400, { ok: false, error: `not a directory: ${wanted}` })
+                  }
+                  cwd = wanted
+                }
+              } catch (err) {
+                return sendJson(res, 400, { ok: false, error: String((err && err.message) || err) })
+              }
+            }
+            let built
+            try {
+              built = buildAction(body.action, body.args || body)
+            } catch (err) {
+              return sendJson(res, 400, { ok: false, error: String((err && err.message) || err) })
+            }
+            const steps = []
+            for (const argv of built.steps) {
+              const answer = await git(argv, { cwd, timeoutMs: 120000 })
+              steps.push({
+                argv,
+                code: answer.code,
+                stdout: String(answer.stdout || '').slice(0, 4000),
+                stderr: String(answer.stderr || '').slice(0, 4000),
+              })
+              if (answer.code !== 0) {
+                return sendJson(res, 200, { ok: false, action: built.action, summary: built.summary, steps, error: 'git refused the step' })
+              }
+            }
+            return sendJson(res, 200, { ok: true, action: built.action, summary: built.summary, steps })
+          }
+
           if (file) {
             // a single diff, capped: the tab shows a file at a time
             const args = staged ? ['diff', '--cached', '--', file] : ['diff', '--', file]
@@ -220,3 +275,35 @@ export function registerRoutes(ctx, deps) {
   })
 
 }
+
+/**
+ * Read a small JSON body, bounded, so a POST that names an action cannot exhaust memory.
+ * The panel sends a few hundred bytes; anything larger is refused rather than buffered.
+ */
+function readJsonBody(req, limit = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) {
+        reject(new Error('the request body is too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      const text = Buffer.concat(chunks).toString('utf8').trim()
+      if (!text) return resolve({})
+      try {
+        const parsed = JSON.parse(text)
+        if (!parsed || typeof parsed !== 'object') return reject(new Error('the request body must be a JSON object'))
+        resolve(parsed)
+      } catch {
+        reject(new Error('the request body is not valid JSON'))
+      }
+    })
+    req.on('error', (err) => reject(err))
+  })
+}

package/lib/scm-write.js

@@ -0,0 +1,144 @@
+// Writing to a working copy, from the Source Control tab.
+//
+// Every action is a list of argv arrays — never a shell string. The route runs them one by one
+// and stops at the first failure, so a caller can see exactly which step refused. Validation
+// lives here, next to the commands it protects, and the destructive actions require an explicit
+// confirmation from the human who clicked.
+//
+// Nothing in this module touches the filesystem or spawns a process: it only decides what would
+// be run, which makes the decisions testable without a repository.
+
+/** A branch name git will accept: no spaces, no leading dash, no shell metacharacters. */
+const BRANCH_RE = /^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]{1,120}$/
+
+/** A repository-relative path: no absolute paths, no traversal, no control characters. */
+const PATH_RE = /^(?!-)(?!\/)(?!.*\.\.)[^\u0000-\u001f]{1,500}$/
+
+export function validateBranch(name) {
+  const value = String(name == null ? '' : name).trim()
+  if (!BRANCH_RE.test(value)) throw new Error(`refusing an unsafe branch name: "${String(name).slice(0, 60)}"`)
+  return value
+}
+
+export function validatePath(path) {
+  const value = String(path == null ? '' : path).trim()
+  if (!PATH_RE.test(value)) throw new Error(`refusing an unsafe path: "${String(path).slice(0, 60)}"`)
+  return value
+}
+
+export function validateMessage(message) {
+  const value = String(message == null ? '' : message)
+  if (value.includes('\u0000')) throw new Error('refusing a message with a NUL byte')
+  const trimmed = value.trim()
+  if (!trimmed) throw new Error('a commit or stash needs a message')
+  if (trimmed.length > 5000) throw new Error('refusing a message longer than 5000 characters')
+  return trimmed
+}
+
+/** Stash references are `stash@{N}`; nothing else is accepted. */
+export function validateStashRef(ref) {
+  const value = String(ref == null ? '' : ref).trim()
+  if (!/^stash@\{\d{1,3}\}$/.test(value)) throw new Error(`refusing an unsafe stash reference: "${value.slice(0, 40)}"`)
+  return value
+}
+
+const CONTINUE_VERBS = ['merge', 'rebase', 'cherry-pick', 'revert']
+
+/**
+ * What a named action would run.
+ *
+ * @returns {{steps: string[][], mutating: true, destructive: boolean, needsConfirm: boolean, summary: string}}
+ */
+export function buildAction(action, args = {}) {
+  const name = String(action || '').trim()
+  const destructive = DESTRUCTIVE.has(name)
+  const needsConfirm = destructive
+  if (needsConfirm && args.confirm !== true) {
+    throw new Error(`refusing "${name}" without confirm: true — it cannot be undone`)
+  }
+
+  switch (name) {
+    case 'stage': {
+      const path = args.path ? validatePath(args.path) : ''
+      return result(name, [path ? ['add', '--', path] : ['add', '-A']], destructive, `stage ${path || 'everything'}`)
+    }
+    case 'unstage': {
+      const path = args.path ? validatePath(args.path) : ''
+      return result(name, [path ? ['reset', 'HEAD', '--', path] : ['reset', 'HEAD']], destructive, `unstage ${path || 'everything'}`)
+    }
+    case 'discard': {
+      const path = validatePath(args.path)
+      return result(name, [['checkout', '--', path]], destructive, `discard changes in ${path}`)
+    }
+    case 'commit': {
+      const message = validateMessage(args.message)
+      const steps = [args.amend === true ? ['commit', '--amend', '-m', message] : ['commit', '-m', message]]
+      if (args.push === true) steps.push(['push'])
+      return result(name, steps, destructive, args.amend ? 'amend the last commit' : 'create a commit')
+    }
+    case 'push':
+      return result(name, [args.setUpstream ? ['push', '-u', 'origin', validateBranch(args.branch)] : ['push']], destructive, 'push')
+    case 'sync':
+      return result(name, [['pull', '--rebase', '--autostash'], ['push']], destructive, 'pull with rebase, then push')
+    case 'branchCreate':
+      return result(name, [['checkout', '-b', validateBranch(args.branch)]], destructive, `create and switch to ${args.branch}`)
+    case 'branchCheckout':
+      return result(name, [['checkout', validateBranch(args.branch)]], destructive, `switch to ${args.branch}`)
+    case 'branchDelete':
+      return result(name, [['branch', '-D', validateBranch(args.branch)]], destructive, `delete ${args.branch}`)
+    case 'stashPush': {
+      const steps = args.message ? [['stash', 'push', '-m', validateMessage(args.message)]] : [['stash', 'push']]
+      return result(name, steps, destructive, 'save the working copy to a stash')
+    }
+    case 'stashApply':
+      return result(name, [['stash', 'apply', validateStashRef(args.ref)]], destructive, `apply ${args.ref}`)
+    case 'stashPop':
+      return result(name, [['stash', 'pop', validateStashRef(args.ref)]], destructive, `apply and drop ${args.ref}`)
+    case 'stashDrop':
+      return result(name, [['stash', 'drop', validateStashRef(args.ref)]], destructive, `drop ${args.ref}`)
+    case 'continue': {
+      const verb = String(args.verb || '').trim()
+      if (!CONTINUE_VERBS.includes(verb)) throw new Error(`refusing to continue an unknown operation: "${verb.slice(0, 20)}"`)
+      return result(name, [[verb, '--continue']], destructive, `continue the ${verb}`)
+    }
+    case 'abort': {
+      const verb = String(args.verb || '').trim()
+      if (!CONTINUE_VERBS.includes(verb)) throw new Error(`refusing to abort an unknown operation: "${verb.slice(0, 20)}"`)
+      return result(name, [[verb, '--abort']], destructive, `abort the ${verb}`)
+    }
+    default:
+      throw new Error(`unknown action: "${name.slice(0, 40)}"`)
+  }
+}
+
+const DESTRUCTIVE = new Set(['discard', 'branchDelete', 'stashDrop', 'abort'])
+
+function result(action, steps, destructive, summary) {
+  return { action, steps, mutating: true, destructive, needsConfirm: destructive, summary }
+}
+
+/** Every action the tab may ask for, for the client and for tests. */
+export const ACTIONS = Object.freeze([
+  'stage', 'unstage', 'discard', 'commit', 'push', 'sync',
+  'branchCreate', 'branchCheckout', 'branchDelete',
+  'stashPush', 'stashApply', 'stashPop', 'stashDrop',
+  'continue', 'abort',
+])
+
+/** The verbs the panel offers for an unfinished operation. */
+export const OPERATION_VERBS = Object.freeze(CONTINUE_VERBS.slice())
+
+/**
+ * An optional directory the tab should look at instead of the session workspace. The value is
+ * only ever used locally (the route answers a local caller and nothing else executes it), but it
+ * is still checked: absolute, without traversal or control bytes.
+ */
+export function validateCwd(path) {
+  const value = String(path == null ? '' : path).trim()
+  if (!value) return ''
+  if (!value.startsWith('/')) throw new Error('a repository path must be absolute')
+  if (value.includes('..')) throw new Error('a repository path may not contain ".."')
+  if (/[\u0000-\u001f]/.test(value)) throw new Error('a repository path may not contain control characters')
+  if (value.length > 500) throw new Error('a repository path is too long')
+  return value
+}

package/lib/tools/write-files.js

@@ -20,12 +20,12 @@ export async function repoTree(client, { owner, repo, ref, path, recursive = tru
   const { data } = await client.get(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(target)}${suffix}`, {
     query: recursive ? { recursive: '1' } : undefined,
   })
-  const entries = (data && Array.isArray(data.tree) ? data.tree : []).slice(0, capped).map((entry) => ({
-    path: entry.path,
-    type: entry.type,
-    size: entry.size,
-    sha: entry.sha,
-  }))
+  const entries = (data && Array.isArray(data.tree) ? data.tree : []).slice(0, capped).map((entry) => {
+    // a directory has no size in the API: say nothing rather than claiming undefined
+    const row = { path: entry.path, type: entry.type, sha: entry.sha }
+    if (typeof entry.size === 'number') row.size = entry.size
+    return row
+  })
   return {
     ref: target,
     path: path || '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-github-ops",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "GitHub operations for DeepSeek Harness: releases, tags, a guarded generic API pass-through, workflow runs, secrets and sanitized mirror publication.",
   "license": "MIT",
   "type": "module",
@@ -27,12 +27,13 @@
       "platform": "web",
       "inject": [
         "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-settings"
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-slots"
       ]
     }
   },
   "scripts": {
-    "pretest": "for f in lib/index.js lib/github.js lib/tools/*.js; do node --check \"$f\" || exit 1; done",
+    "pretest": "for f in lib/*.js lib/tools/*.js; do node --check \"$f\" || exit 1; done",
     "test": "node --test test/*.test.mjs"
   },
   "peerDependencies": {