dsh-hitl 0.1.0

package/tests/docs.test.js

@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Guards the two READMEs against the drift this repository keeps fixing by hand:
+ * a screenshot that moved, a language link that points nowhere, and an appendix
+ * whose line counts or test counts describe a file as it was three edits ago.
+ *
+ * The counts exist for readers deciding where to start reading; a stale number
+ * is a small lie that costs a reader real time, so each one is asserted against
+ * the filesystem instead of trusted.
+ */
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** The English README is the package's front page; the Chinese one is its twin. */
+const READMES = [
+  { language: 'en', file: 'README.md', other: 'README.zh.md', suffix: '-en' },
+  { language: 'zh', file: 'README.zh.md', other: 'README.md', suffix: '-cn' },
+]
+
+const read = relative => readFileSync(join(root, relative), 'utf8')
+/** Line count by the `wc -l` convention: the number of newline characters. */
+const lineCount = relative => read(relative).split('\n').length - 1
+
+/** Every repository path a basename could name, so the appendix may spell either. */
+function locate(name) {
+  const candidates = [name, join('lib', name), join('tests', name), join('locale', name), join('docs', name)]
+  return candidates.find(candidate => existsSync(join(root, candidate))) ?? name
+}
+
+/** The file-structure appendix: the one text block that lists `client.js` and its size. */
+function appendixTree(text) {
+  const blocks = text.split('```').filter((_block, index) => index % 2 === 1)
+  const tree = blocks.find(block => block.includes('client.js') && block.includes('index.js'))
+  assert.notEqual(tree, undefined, 'the appendix file-structure block is missing')
+  const rows = new Map()
+  const testCounts = new Map()
+  for (const line of tree.split('\n')) {
+    const row = /^[│├└─\s]*([\w.\-]+\.(?:js|json|yml|svg|md))\s+(\d+)\b/.exec(line)
+    if (row === null) continue
+    rows.set(row[1], Number(row[2]))
+    const tests = /[（(](\d+)[）)]/.exec(line)
+    if (tests !== null && row[1].endsWith('.test.js')) testCounts.set(row[1], Number(tests[1]))
+  }
+  return { rows, testCounts }
+}
+
+describe('docs: the English and Chinese READMEs', () => {
+  it('links each language to the other', () => {
+    for (const readme of READMES) {
+      const text = read(readme.file)
+      assert.equal(text.includes(`](${readme.other})`), true, `${readme.file} must link to ${readme.other}`)
+      assert.equal(existsSync(join(root, readme.other)), true, `${readme.other} must exist`)
+    }
+    // The language line belongs in the header, before the first section.
+    for (const readme of READMES) {
+      const header = read(readme.file).split('\n').slice(0, 8).join('\n')
+      assert.equal(header.includes(readme.other), true, `${readme.file} must offer the switch near the top`)
+    }
+  })
+
+  it('shows every screenshot, and only its own language', () => {
+    const referenced = new Set()
+    const available = new Set(readdirSync(join(root, 'docs')))
+    for (const readme of READMES) {
+      const images = [...read(readme.file).matchAll(/!\[[^\]]*\]\((docs\/[^)]+)\)/g)].map(match => match[1])
+      assert.equal(images.length, 4, `${readme.file} must place all four screenshots`)
+      for (const image of images) {
+        const name = image.slice('docs/'.length)
+        assert.equal(available.has(name), true, `${readme.file} references a missing screenshot: ${image}`)
+        assert.equal(name.endsWith(`${readme.suffix}.png`), true, `${readme.file} must use its ${readme.suffix} screenshots`)
+        referenced.add(name)
+      }
+    }
+    for (const name of available) {
+      assert.equal(referenced.has(name), true, `docs/${name} is shipped but never shown`)
+    }
+  })
+
+  it('keeps both file-structure appendixes identical and true to disk', () => {
+    const trees = READMES.map(readme => appendixTree(read(readme.file)))
+    const [english, chinese] = trees
+    assert.deepEqual([...chinese.rows], [...english.rows], 'the two appendixes must declare the same sizes')
+    for (const [name, claimed] of english.rows) {
+      const path = locate(name)
+      assert.equal(existsSync(join(root, path)), true, `the appendix lists a file that is gone: ${name}`)
+      assert.equal(lineCount(path), claimed, `${path} is ${lineCount(path)} lines, the appendix says ${claimed}`)
+    }
+    // The READMEs are listed without a size on purpose: their own length would
+    // change with every edit that keeps the number honest, which has no fixed point.
+    const tree = read('README.md').split('```').filter((_b, i) => i % 2 === 1).find(b => b.includes('client.js'))
+    for (const name of ['README.md', 'README.zh.md']) {
+      assert.equal(tree.includes(name), true, `the appendix must list ${name}`)
+    }
+  })
+
+  it('keeps the per-file test counts honest', () => {
+    for (const readme of READMES) {
+      const { testCounts } = appendixTree(read(readme.file))
+      assert.equal(testCounts.size, readdirSync(join(root, 'tests')).filter(name => name.endsWith('.test.js')).length)
+      for (const [name, claimed] of testCounts) {
+        const declared = (read(join('tests', name)).match(/^\s*it\(/gm) ?? []).length
+        assert.equal(claimed, declared, `${name}: the appendix says ${claimed} cases, the file declares ${declared}`)
+      }
+    }
+  })
+
+  it('keeps the screenshot folder shipped', () => {
+    const manifest = JSON.parse(read('package.json'))
+    assert.equal(manifest.files.includes('docs'), true, '`docs` must be published with the screenshots')
+    assert.equal(manifest.files.includes('README.zh.md'), true, 'the Chinese README must be published too')
+  })
+})

package/tests/fields.test.js

@@ -0,0 +1,269 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import {
+  REASON_PREFIX, buildFields, buildRequest, capReason, defaultFieldSpecs, describeDecision,
+  inferRender, isRevision, renderValue, revisionContext, revisionText,
+} from '../lib/fields.js'
+import { normalizeMount } from '../lib/resolve.js'
+
+/** Normalize one mount through the same path the host half uses. */
+function mountOf(input) {
+  const normalized = normalizeMount({ tool: 'demo', ...input }, 'test')
+  assert.equal(normalized.ok, true, normalized.warnings.join('; '))
+  return normalized.mount
+}
+
+/** One pending execution with the schema shape `tools/pre-execute` hands over. */
+function executionOf(argumentsValue, schema) {
+  return {
+    name: 'demo',
+    callId: 'call_1',
+    arguments: argumentsValue,
+    ...(schema === undefined ? {} : { schema: { name: 'demo', parameters: schema } }),
+  }
+}
+
+describe('fields: renderValue and inferRender', () => {
+  it('passes strings through and pretty-prints other values', () => {
+    assert.equal(renderValue('ls -la'), 'ls -la')
+    assert.equal(renderValue({ a: 1 }), '{\n  "a": 1\n}')
+    assert.equal(renderValue(3), '3')
+    assert.equal(renderValue(undefined), '(undefined)')
+    assert.equal(renderValue({ self: 1n }), '[object Object]')
+  })
+
+  it('defaults to the markdown box', () => {
+    assert.equal(inferRender(), 'markdown')
+  })
+})
+
+describe('fields: defaultFieldSpecs', () => {
+  it('uses every parameter in argument order', () => {
+    assert.deepEqual(defaultFieldSpecs(executionOf({ b: 1, a: 2 })), [{ param: 'b' }, { param: 'a' }])
+  })
+
+  it('falls back to one arguments field for empty or scalar arguments', () => {
+    assert.deepEqual(defaultFieldSpecs(executionOf({})), [{ param: '(arguments)', render: 'json' }])
+    assert.deepEqual(defaultFieldSpecs(executionOf('hello')), [{ param: '(arguments)', render: 'json' }])
+    assert.deepEqual(defaultFieldSpecs(executionOf([1, 2])), [{ param: '(arguments)', render: 'json' }])
+  })
+})
+
+describe('fields: buildFields defaults', () => {
+  it('titles each field with the parameter key and takes schema help when present', () => {
+    const fields = buildFields(executionOf({ command: 'ls -la', cwd: '/tmp' }, {
+      command: { title: '命令', description: '要执行的命令' },
+      cwd: { description: '工作目录' },
+    }), mountOf({}))
+    assert.deepEqual(fields, [
+      {
+        param: 'command',
+        title: '命令',
+        description: '要执行的命令',
+        render: 'markdown',
+        editable: true,
+        labels: [],
+        value: 'ls -la',
+        truncated: false,
+      },
+      {
+        param: 'cwd',
+        title: 'cwd',
+        description: '工作目录',
+        render: 'markdown',
+        editable: true,
+        labels: [],
+        value: '/tmp',
+        truncated: false,
+      },
+    ])
+  })
+
+  it('renders non-string values as JSON text in an editable markdown box', () => {
+    const [field] = buildFields(executionOf({ count: 3 }), mountOf({}))
+    assert.equal(field.render, 'markdown')
+    assert.equal(field.editable, true)
+    assert.equal(field.value, '3')
+  })
+
+  it('shows the whole scalar argument when arguments are not a record', () => {
+    const [field] = buildFields(executionOf('hello'), mountOf({}))
+    assert.equal(field.param, '(arguments)')
+    assert.equal(field.value, 'hello')
+  })
+
+  it('truncates a long value and says so', () => {
+    const [field] = buildFields(executionOf({ body: 'x'.repeat(50) }), mountOf({ maxFieldChars: 5 }))
+    assert.equal(field.truncated, true)
+    assert.equal(field.value.startsWith('xxxxx'), true)
+    assert.match(field.value, /已截断，共 50 字/)
+  })
+
+  it('sends no value for a hidden field', () => {
+    const [field] = buildFields(executionOf({ secret: 'shh' }), mountOf({ fields: [{ param: 'secret', render: 'hidden' }] }))
+    assert.deepEqual(field, { param: 'secret', title: 'secret', render: 'hidden', editable: false, labels: [], value: '', truncated: false })
+  })
+})
+
+describe('fields: configured fields', () => {
+  it('shows exactly the configured parameters', () => {
+    const fields = buildFields(executionOf({ file_path: '/a', content: 'x', extra: 'y' }), mountOf({
+      fields: ['file_path', { param: 'content', render: 'json' }],
+    }))
+    assert.deepEqual(fields.map(field => field.param), ['file_path', 'content'])
+    assert.equal(fields[1].render, 'json')
+    assert.equal(fields[1].editable, false)
+  })
+
+  it('pairs two parameters into one read-only diff and drops them from the list', () => {
+    const fields = buildFields(executionOf({
+      file_path: '/a.txt', old_string: 'one', new_string: 'two', extra: 'z',
+    }), mountOf({ diff: { path: 'file_path', before: 'old_string', after: 'new_string' } }))
+    assert.deepEqual(fields.map(field => field.param), ['file_path', 'extra', 'old_string→new_string'])
+    const diff = fields[2]
+    assert.equal(diff.render, 'diff')
+    assert.equal(diff.editable, false)
+    assert.deepEqual(diff.diff, { path: '/a.txt', oldText: 'one', newText: 'two' })
+  })
+
+  it('supports a field-level diff without a mount-level one', () => {
+    const fields = buildFields(executionOf({ old: 'a', next: 'b' }), mountOf({
+      fields: [{ param: 'content', render: 'diff', diff: { before: 'old', after: 'next' } }],
+    }))
+    assert.equal(fields.length, 1)
+    assert.deepEqual(fields[0].diff, { path: undefined, oldText: 'a', newText: 'b' })
+  })
+
+  it('falls back to the arguments field when a configured list selects nothing', () => {
+    const fields = buildFields(executionOf({ a: 1 }), mountOf({ fields: [] }))
+    assert.deepEqual(fields, [{ param: '(arguments)', title: '(arguments)', render: 'json', editable: false, labels: [], value: '{}', truncated: false }])
+  })
+})
+
+describe('fields: buildRequest', () => {
+  it('carries the call identity, the defaults, and no empty title', () => {
+    const request = buildRequest({
+      execution: executionOf({ command: 'ls' }), mount: mountOf({}), sessionId: 's1', id: 'r1', now: 1000,
+    })
+    assert.deepEqual(request, {
+      id: 'r1',
+      sessionId: 's1',
+      toolName: 'demo',
+      callId: 'call_1',
+      layout: 'stacked',
+      labels: [],
+      fields: [{
+        param: 'command', title: 'command', render: 'markdown', editable: true, labels: [], value: 'ls', truncated: false,
+      }],
+      buttons: { feedback: { enabled: false, required: false } },
+      countdown: null,
+      createdAt: 1000,
+    })
+  })
+
+  it('carries a countdown, label overrides, feedback settings, and a title', () => {
+    const request = buildRequest({
+      execution: executionOf({ command: 'ls' }),
+      mount: mountOf({
+        title: '确认执行',
+        labels: ['不可撤销'],
+        countdown: { seconds: 30 },
+        reject: { feedback: true, feedbackPrompt: '为什么？', requireFeedback: true },
+        labels2: undefined,
+      }),
+      sessionId: 's1',
+      id: 'r1',
+      now: 0,
+    })
+    assert.equal(request.title, '确认执行')
+    assert.deepEqual(request.labels, ['不可撤销'])
+    assert.deepEqual(request.countdown, { remainingMs: 30000, action: 'reject', freezeOnInteract: true })
+    assert.deepEqual(request.buttons.feedback, { enabled: true, prompt: '为什么？', required: true })
+  })
+
+  it('carries the button label overrides a mount configured', () => {
+    const request = buildRequest({
+      execution: executionOf({ command: 'ls' }),
+      mount: mountOf({ buttons: { approve: '同意', modify: '修改', reject: '拒绝' } }),
+      sessionId: 's1',
+      id: 'r1',
+    })
+    assert.deepEqual(request.buttons, {
+      approve: '同意', modify: '修改', reject: '拒绝', feedback: { enabled: false, required: false },
+    })
+  })
+
+  it('omits a call id the execution does not have', () => {
+    const request = buildRequest({
+      execution: { name: 'demo', arguments: {} }, mount: mountOf({}), sessionId: 's1', id: 'r1',
+    })
+    assert.equal('callId' in request, false)
+  })
+})
+
+describe('fields: decisions back to the model', () => {
+  const request = buildRequest({
+    execution: executionOf({ command: 'ls' }),
+    mount: mountOf({ countdown: { seconds: 30, action: 'notify' } }),
+    sessionId: 's1',
+    id: 'r1',
+    now: 0,
+  })
+
+  it('recognizes a revision', () => {
+    assert.equal(isRevision({ kind: 'modify', fields: [{ param: 'command', text: 'ls' }] }), true)
+    assert.equal(isRevision({ kind: 'approve' }), false)
+  })
+
+  it('renders revision text per field', () => {
+    assert.equal(revisionText({ kind: 'modify', fields: [{ param: 'a', text: '1' }, { param: 'b', text: '2' }] }), '- a:\n1\n- b:\n2')
+  })
+
+  it('reports a rejection with the user feedback verbatim', () => {
+    const reason = describeDecision(request, { kind: 'reject', feedback: '太危险' }, 'user')
+    assert.equal(reason.startsWith(`${REASON_PREFIX}: the user rejected tool "demo"`), true)
+    assert.equal(reason.includes('User feedback: 太危险'), true)
+  })
+
+  it('omits the feedback sentence when the user typed none', () => {
+    assert.equal(describeDecision(request, { kind: 'reject' }, 'user').includes('User feedback'), false)
+  })
+
+  it('turns a revision into a re-issue instruction', () => {
+    const reason = describeDecision(request, { kind: 'modify', fields: [{ param: 'command', text: 'rm -rf /' }] }, 'user')
+    assert.equal(reason.includes('Re-issue the call with these changes'), true)
+    assert.equal(reason.includes('- command:\nrm -rf /'), true)
+  })
+
+  it('distinguishes the three timeout policies', () => {
+    assert.equal(describeDecision(request, { kind: 'approve' }, 'timeout').includes("ran under the mount's timeout policy"), true)
+    assert.equal(describeDecision(request, { kind: 'reject' }, 'timeout').includes('Tell the user this call timed out'), true)
+    const strict = buildRequest({
+      execution: executionOf({ command: 'ls' }),
+      mount: mountOf({ countdown: { seconds: 10, action: 'reject' } }),
+      sessionId: 's1',
+      id: 'r2',
+    })
+    const reason = describeDecision(strict, { kind: 'reject' }, 'timeout')
+    assert.equal(reason.includes('did not run'), true)
+    assert.equal(reason.includes('timeout policy: reject'), true)
+  })
+
+  it('reports withdrawal for abort and host settlement', () => {
+    assert.equal(describeDecision(request, { kind: 'cancel' }, 'abort').includes('withdrawn before the user answered'), true)
+    assert.equal(describeDecision(request, { kind: 'cancel' }, 'host').includes('withdrawn before the user answered'), true)
+  })
+
+  it('reports an approval that carried edits', () => {
+    const context = revisionContext(request, { kind: 'modify', fields: [{ param: 'command', text: 'ls -la' }] })
+    assert.equal(context.includes('approved tool "demo" after editing the proposal'), true)
+    assert.equal(context.includes('- command:\nls -la'), true)
+  })
+
+  it('caps a very long model-facing text', () => {
+    const capped = capReason('x'.repeat(20000))
+    assert.equal(capped.length < 20000, true)
+    assert.equal(capped.includes('已截断'), true)
+  })
+})

package/tests/manifest.test.js

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Guards the package files a DSH profile reads *about* this plugin rather than
+ * from it: the manifest the Loader resolves, and the `locale/*.json` resources
+ * the plugin list shows.
+ *
+ * The loader reads `parsed.meta.title` / `parsed.meta.description` from each
+ * language file (`app-boot` `package-meta.ts`), and it reaches those files only
+ * through the `exports` map. Get either wrong and the plugin still works while
+ * its card silently falls back to the bare package name — a defect nobody
+ * notices, which is exactly why it is asserted here.
+ */
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+
+const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+
+/** Language ids the shipped dictionaries and the browser half both carry. */
+const LANGUAGES = ['en', 'zh']
+
+describe('manifest: what a profile reads about this plugin', () => {
+  it('resolves the resources the Loader asks for by name', () => {
+    assert.equal(manifest.name, 'dsh-hitl')
+    assert.equal(typeof manifest.description, 'string')
+    assert.equal(manifest.exports['.'], './index.js')
+    assert.equal(manifest.exports['./client'], './client.js')
+    // The locale resources are subpaths: without the pattern the loader cannot
+    // resolve them at all, and the card title falls back to the package name.
+    assert.equal(manifest.exports['./locale/*.json'], './locale/*.json')
+    assert.equal(manifest.files.includes('locale'), true, 'the published files must carry the locale directory')
+    assert.equal(manifest.files.includes('client.js'), true)
+    assert.equal(manifest.files.includes('lib'), true)
+  })
+
+  it('declares the bundle patch and the browser half the bundle needs', () => {
+    assert.equal(manifest.dsh.bundle.patch, './cordis.patch.yml')
+    assert.equal(manifest.dsh.client.platform, 'web')
+    assert.equal(manifest.dsh.client.immediately, true)
+    for (const dependency of ['@deepseek-ai/dsh-client-ui-conversation', '@deepseek-ai/dsh-client-ui-session']) {
+      assert.equal(manifest.dsh.client.inject.includes(dependency), true, `${dependency} must stay injected`)
+    }
+  })
+
+  it('gives every shipped language the meta envelope the loader reads', () => {
+    const files = readdirSync(join(root, 'locale')).filter(name => name.endsWith('.json'))
+    assert.deepEqual(files.map(name => name.slice(0, -5)).sort(), [...LANGUAGES].sort())
+    for (const language of LANGUAGES) {
+      const resource = JSON.parse(readFileSync(join(root, 'locale', `${language}.json`), 'utf8'))
+      assert.equal(typeof resource.meta, 'object', `locale/${language}.json must wrap its copy in "meta"`)
+      assert.equal(typeof resource.meta.title, 'string', `locale/${language}.json: meta.title`)
+      assert.equal(typeof resource.meta.description, 'string', `locale/${language}.json: meta.description`)
+      // A bare top-level title is the shape the loader ignores.
+      assert.equal(resource.title, undefined, `locale/${language}.json must not put title at the top level`)
+    }
+  })
+})