Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

dsh/check: stop telling a viewer package it has no agent.instructions

deeb0fe666e6cfa
diff --git a/cli/src/dsh/check.spec.ts b/cli/src/dsh/check.spec.ts
index c88a247c3..a718198e8 100644
--- a/cli/src/dsh/check.spec.ts
+++ b/cli/src/dsh/check.spec.ts
@@ -3,7 +3,7 @@ import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, realpathSync } f
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
-import { checkDsh } from './check.js'
+import { checkDsh, formatCheck } from './check.js'
const STARTER = realpathSync(fileURLToPath(new URL('../../../store/starter', import.meta.url)))
@@ -62,3 +62,163 @@ describe('checkDsh', () => {
expect(result.lines).toHaveLength(1)
})
})
+
+describe('checkDsh, every answer it gives', () => {
+ let dir: string
+ beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'dsh-check-each-')) })
+ afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+ /** Lay out a checkout and check it; the lines as the terminal prints them. A name ending in / is a folder. */
+ const check = (manifest: Record<string, unknown>, files: Record<string, string> = {}): { ok: boolean; out: string[] } => {
+ rmSync(dir, { recursive: true, force: true })
+ mkdirSync(dir)
+ for (const [name, body] of Object.entries(files)) {
+ mkdirSync(join(dir, name, '..'), { recursive: true })
+ if (name.endsWith('/')) mkdirSync(join(dir, name), { recursive: true })
+ else writeFileSync(join(dir, name), body)
+ }
+ writeFileSync(join(dir, 'harness.json'), JSON.stringify({ spec: 1, id: 'acme/thing', name: 'Thing', ...manifest }))
+ const result = checkDsh(dir)
+ return { ok: result.ok, out: formatCheck(result).split('\n') }
+ }
+ const complete = { engine: 'claude', author: 'Acme', description: 'A thing', agent: { instructions: 'AGENTS.md', skills: ['skills'] }, toolchain: { doctor: 'doctor.sh' } }
+ const completeFiles = { 'AGENTS.md': '# Thing\n', 'skills/draw/SKILL.md': '---\nname: draw\n---\n', 'doctor.sh': '#!/bin/sh\n' }
+
+ it('a complete tier-0 agent: every line ok, printed with its level in a column', () => {
+ const { ok, out } = check(complete, completeFiles)
+ expect(ok).toBe(true)
+ expect(out).toEqual([
+ 'ok harness.json parses · acme/thing "Thing" runs on claude',
+ 'ok agent.instructions AGENTS.md',
+ 'ok agent.skills skills/ · draw',
+ 'ok toolchain.doctor doctor.sh',
+ ])
+ })
+
+ it('warns about what a tile will lack: a description, an author, instructions, skills, a doctor', () => {
+ const { ok, out } = check({ engine: 'codex' })
+ expect(ok).toBe(true)
+ expect(out).toEqual([
+ 'ok harness.json parses · acme/thing "Thing" runs on codex',
+ 'warn no description — the picker tile will have none',
+ 'warn no author — the tile will not say who made it',
+ 'warn no agent.instructions — the agent gets no AGENTS.md from this harness',
+ 'warn no agent.skills — a tier-0 harness usually ships at least one',
+ 'warn no toolchain.doctor — Harness cannot tell the user what is missing before a create',
+ ])
+ })
+
+ it('a viewer package: named as one, no author or skills expected, a workspace or verdict warned', () => {
+ const { ok, out } = check({
+ kind: 'viewer', workspace: { marker: 'x' }, verdict: '.harness/verdict.json',
+ toolchain: { setup: 'npm ci --silent', doctor: 'doctor.sh' },
+ viewer: { command: 'viewer.sh', url: 'http://localhost:${port}/?file=${artifact}', artifactExtensions: ['.step'] },
+ }, { 'doctor.sh': '', 'viewer.sh': '' })
+ expect(ok).toBe(true)
+ expect(out).toEqual([
+ 'ok harness.json parses · acme/thing "Thing" is a viewer package',
+ 'warn no description',
+ 'warn a viewer package has no workspace of its own; workspace.* is ignored',
+ 'warn a viewer package writes no verdict; the harness that uses it does',
+ 'ok toolchain.setup is a shell line',
+ 'ok toolchain.doctor doctor.sh',
+ 'ok viewer.command viewer.sh',
+ ])
+ const lean = check({ kind: 'viewer', description: 'A pane', toolchain: { doctor: 'doctor.sh' }, viewer: { command: 'viewer.sh', url: 'http://127.0.0.1:${port}/' } }, { 'doctor.sh': '', 'viewer.sh': '' })
+ // nothing about instructions or skills: a viewer package may not have an agent section at all
+ expect(lean.out).toEqual(['ok harness.json parses · acme/thing "Thing" is a viewer package', 'ok toolchain.doctor doctor.sh', 'ok viewer.command viewer.sh'])
+ })
+
+ it('the workspace: a template with and without its marker, and an init as a script or a shell line', () => {
+ const markerMissing = check({ ...complete, workspace: { template: 'template', marker: 'deck.md', init: 'init.sh' } }, { ...completeFiles, 'template/other.md': '', 'init.sh': '' })
+ expect(markerMissing.out).toEqual(expect.arrayContaining([
+ 'ok workspace.template template/',
+ 'warn workspace.marker deck.md is not in the template, so a fresh workspace stays "fresh" until something else writes it',
+ 'ok workspace.init init.sh',
+ ]))
+ const noMarker = check({ ...complete, workspace: { template: 'template', init: 'npm run init' } }, { ...completeFiles, 'template/deck.md': '' })
+ expect(noMarker.out).toEqual(expect.arrayContaining([
+ 'warn workspace.template without workspace.marker: the template is copied on EVERY create',
+ 'ok workspace.init is a shell line',
+ ]))
+ const inTemplate = check({ ...complete, workspace: { template: 'template', marker: 'deck.md', init: 'missing-init.sh' } }, { ...completeFiles, 'template/deck.md': '' })
+ expect(inTemplate.ok).toBe(false)
+ expect(inTemplate.out.filter((line) => line.includes('workspace.'))).toEqual([
+ 'ok workspace.template template/',
+ 'fail workspace.init missing-init.sh does not exist',
+ ])
+ })
+
+ it('what a setup fetches is warned about; with no setup to fetch it, the same absence fails', () => {
+ const agent = { instructions: 'upstream/AGENTS.md', skills: ['upstream/skills'] }
+ const withoutSetup = check({ ...complete, agent }, { 'doctor.sh': '' })
+ expect(withoutSetup.ok).toBe(false)
+ expect(withoutSetup.out).toEqual(expect.arrayContaining([
+ 'fail agent.instructions upstream/AGENTS.md does not exist',
+ 'fail agent.skills upstream/skills is not a directory',
+ ]))
+ const withSetup = check({ ...complete, agent, toolchain: { setup: 'setup.sh', doctor: 'doctor.sh' } }, { 'doctor.sh': '', 'setup.sh': '' })
+ expect(withSetup.ok).toBe(true)
+ expect(withSetup.out).toEqual(expect.arrayContaining([
+ 'warn agent.instructions upstream/AGENTS.md is not in the checkout; toolchain.setup must create it',
+ 'warn agent.skills upstream/skills is not in the checkout; toolchain.setup must create it, or the agent gets no skills',
+ 'ok toolchain.setup setup.sh',
+ ]))
+ })
+
+ it('skills: a root that is itself one skill, and a root with none in it', () => {
+ const { ok, out } = check({ ...complete, agent: { instructions: 'AGENTS.md', skills: ['skills/draw', 'empty'] } }, { ...completeFiles, 'empty/': '' })
+ expect(ok).toBe(false)
+ expect(out).toEqual(expect.arrayContaining([
+ 'ok agent.skills skills/draw/ · .',
+ 'fail agent.skills empty has no SKILL.md-bearing directory',
+ ]))
+ })
+
+ it('env: HARNESS_* is reserved, an unknown ${var} is warned, the three Harness expands pass', () => {
+ const env = { HARNESS_WORKSPACE: '/x', TOOLS: '${dsh}/bin:${workspace}:${home}', ODD: '${user}/bin' }
+ const { ok, out } = check({ ...complete, agent: { ...complete.agent, env } }, completeFiles)
+ expect(ok).toBe(false)
+ expect(out.filter((line) => line.includes('agent.env'))).toEqual([
+ 'fail agent.env.HARNESS_WORKSPACE is reserved (HARNESS_* is set by Harness)',
+ 'warn agent.env.ODD uses a variable Harness does not expand: ${user}/bin',
+ ])
+ })
+
+ it('toolchain and viewer commands: a script that must exist, or a shell line that is not checked', () => {
+ const { ok, out } = check({ ...complete, toolchain: { setup: 'missing-setup.sh', doctor: './doctor.sh' }, viewer: { command: 'node viewer.mjs', url: 'https://example.com:${port}/' } }, completeFiles)
+ expect(ok).toBe(false)
+ expect(out.slice(-4)).toEqual([
+ 'fail toolchain.setup missing-setup.sh does not exist',
+ 'ok toolchain.doctor ./doctor.sh',
+ 'ok viewer.command is a shell line',
+ 'warn viewer.url is not loopback; the pane expects a local server',
+ ])
+ })
+
+ it('a viewer of its own: a missing command, a url with no port, ${artifact} with nothing to fill it', () => {
+ const { ok, out } = check({ ...complete, viewer: { command: 'viewer.sh', url: 'http://127.0.0.1:4000/?file=${artifact}' } }, completeFiles)
+ expect(ok).toBe(false)
+ expect(out.slice(-3)).toEqual([
+ 'fail viewer.command viewer.sh does not exist',
+ 'fail viewer.url has no ${port}: Harness picks the port, the URL must use it',
+ 'warn viewer.url uses ${artifact} but no artifactExtensions are declared: only a verdict can name one',
+ ])
+ })
+
+ it('a used viewer: installed with the harness; a narrowed url must still use the port', () => {
+ const plain = check({ ...complete, viewer: { use: 'acme/pane' } }, completeFiles)
+ expect(plain.ok).toBe(true)
+ expect(plain.out.at(-1)).toBe('ok viewer.use acme/pane — installed with this harness; its command and URL come from that package')
+ expect(check({ ...complete, viewer: { use: 'acme/pane', url: 'http://127.0.0.1:${port}/?file=${artifact}' } }, completeFiles).ok).toBe(true)
+ const portless = check({ ...complete, viewer: { use: 'acme/pane', url: 'http://127.0.0.1:4000/' } }, completeFiles)
+ expect(portless.ok).toBe(false)
+ expect(portless.out.at(-1)).toBe('fail viewer.url has no ${port}: Harness picks the port, the URL must use it')
+ })
+
+ it('a verdict outside .harness/ is allowed, and said', () => {
+ const { ok, out } = check({ ...complete, verdict: 'out/verdict.json' }, completeFiles)
+ expect(ok).toBe(true)
+ expect(out.at(-1)).toBe('warn verdict out/verdict.json is outside .harness/ — allowed, but the convention is .harness/verdict.json')
+ })
+})
diff --git a/cli/src/dsh/check.ts b/cli/src/dsh/check.ts
index 2c6695ca0..865db4347 100644
--- a/cli/src/dsh/check.ts
+++ b/cli/src/dsh/check.ts
@@ -9,7 +9,7 @@
*/
import { existsSync, statSync } from 'node:fs'
import { join, resolve } from 'node:path'
-import { isViewerPackage, readDshManifest, viewerUse, type DshManifest } from './manifest.js'
+import { isViewerPackage, readDshManifest, type DshManifest } from './manifest.js'
import { skillDirsIn } from './materialize.js'
export interface CheckLine {
@@ -82,7 +82,8 @@ export function checkDsh(path: string): CheckResult {
// arrive with it) has none of them on a plain checkout — by design, the same as fetched skills.
else if (manifest.toolchain?.setup) add('warn', `agent.instructions ${agent.instructions} is not in the checkout; toolchain.setup must create it`)
else add('fail', `agent.instructions ${agent.instructions} does not exist`)
- } else {
+ } else if (!viewerPkg) {
+ // A viewer package may not have an agent section at all, so it is never told it lacks one.
add('warn', 'no agent.instructions — the agent gets no AGENTS.md from this harness')
}
for (const root of agent?.skills ?? []) {
@@ -104,7 +105,8 @@ export function checkDsh(path: string): CheckResult {
else if (/\$\{(?!dsh\}|workspace\}|home\})/.test(value)) add('warn', `agent.env.${key} uses a variable Harness does not expand: ${value}`)
}
- for (const [name, command] of Object.entries(manifest.toolchain ?? {})) {
+ for (const name of ['setup', 'doctor'] as const) {
+ const command = manifest.toolchain?.[name]
if (!command) continue
const p = commandPath(dir, command)
if (p === null) add('ok', `toolchain.${name} is a shell line`)
@@ -114,11 +116,10 @@ export function checkDsh(path: string): CheckResult {
if (!manifest.toolchain?.doctor) add('warn', 'no toolchain.doctor — Harness cannot tell the user what is missing before a create')
const viewer = manifest.viewer
- const uses = viewerUse(manifest)
- if (uses) {
- add('ok', `viewer.use ${uses} — installed with this harness; its command and URL come from that package`)
- if (viewer && 'url' in viewer && viewer.url && !viewer.url.includes('${port}')) add('fail', 'viewer.url has no ${port}: Harness picks the port, the URL must use it')
- } else if (viewer && 'command' in viewer) {
+ if (viewer && 'use' in viewer) {
+ add('ok', `viewer.use ${viewer.use} — installed with this harness; its command and URL come from that package`)
+ if (viewer.url !== undefined && !viewer.url.includes('${port}')) add('fail', 'viewer.url has no ${port}: Harness picks the port, the URL must use it')
+ } else if (viewer) {
const p = commandPath(dir, viewer.command)
if (p === null) add('ok', 'viewer.command is a shell line')
else if (isFile(p)) add('ok', `viewer.command ${viewer.command}`)