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.

Add harness dsh check, the static conformance check for a harness checkout

deefc77f0d45ff8
diff --git a/cli/src/dsh/check.spec.ts b/cli/src/dsh/check.spec.ts
new file mode 100644
index 000000000..4959ab24a
--- /dev/null
+++ b/cli/src/dsh/check.spec.ts
@@ -0,0 +1,46 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { cpSync, mkdtempSync, rmSync, writeFileSync, realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { checkDsh } from './check.js'
+
+const STARTER = realpathSync(fileURLToPath(new URL('../../../dsh/starter-dsh', import.meta.url)))
+
+describe('checkDsh', () => {
+ let copy: string
+ beforeEach(() => { copy = mkdtempSync(join(tmpdir(), 'dsh-check-')); cpSync(STARTER, copy, { recursive: true }) })
+ afterEach(() => rmSync(copy, { recursive: true, force: true }))
+
+ it('passes the starter fixture with no failures', () => {
+ const result = checkDsh(STARTER)
+ expect(result.ok).toBe(true)
+ expect(result.lines.filter((l) => l.level === 'fail')).toEqual([])
+ expect(result.lines.some((l) => l.what.includes('skills/ · hello'))).toBe(true)
+ })
+
+ it('fails on a missing path, a reserved env key, and a viewer url without a port', () => {
+ writeFileSync(join(copy, 'harness.json'), JSON.stringify({
+ spec: 1, id: 'acme/broken', name: 'Broken', engine: 'claude',
+ workspace: { template: 'nope', marker: 'x' },
+ agent: { instructions: 'AGENTS.md', skills: ['skills'], env: { HARNESS_DSH: 'x', OK: '${dsh}/bin' } },
+ toolchain: { doctor: 'toolchain/missing.sh' },
+ viewer: { command: 'echo hi', url: 'http://127.0.0.1:4000/' },
+ }))
+ const result = checkDsh(copy)
+ expect(result.ok).toBe(false)
+ const fails = result.lines.filter((l) => l.level === 'fail').map((l) => l.what)
+ expect(fails.some((w) => w.includes('workspace.template nope'))).toBe(true)
+ expect(fails.some((w) => w.includes('agent.env.HARNESS_DSH is reserved'))).toBe(true)
+ expect(fails.some((w) => w.includes('toolchain.doctor toolchain/missing.sh'))).toBe(true)
+ expect(fails.some((w) => w.includes('viewer.url has no ${port}'))).toBe(true)
+ })
+
+ it('reports an unparseable manifest as the one failure', () => {
+ writeFileSync(join(copy, 'harness.json'), '{"spec": 3}')
+ const result = checkDsh(copy)
+ expect(result.ok).toBe(false)
+ expect(result.manifest).toBeNull()
+ expect(result.lines).toHaveLength(1)
+ })
+})
diff --git a/cli/src/dsh/check.ts b/cli/src/dsh/check.ts
new file mode 100644
index 000000000..5ddb37038
--- /dev/null
+++ b/cli/src/dsh/check.ts
@@ -0,0 +1,117 @@
+/**
+ * `harness dsh check <path>` — the conformance check a DSH must pass before the registry lists it,
+ * runnable by its author on a plain checkout. It answers the questions the loader would otherwise
+ * answer at create time, when the user is waiting: does the manifest parse, does every path it names
+ * exist, does every skills root carry a SKILL.md, is the viewer URL a template Harness can fill.
+ *
+ * Static only: nothing here runs setup, doctor, or the viewer. `harness dsh doctor` does that for an
+ * installed harness, and CI runs the real install in a clean container.
+ */
+import { existsSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { readDshManifest, type DshManifest } from './manifest.js'
+import { skillDirsIn } from './materialize.js'
+
+export interface CheckLine {
+ level: 'ok' | 'warn' | 'fail'
+ what: string
+}
+
+export interface CheckResult {
+ ok: boolean
+ lines: CheckLine[]
+ manifest: DshManifest | null
+}
+
+function isDir(path: string): boolean {
+ try { return statSync(path).isDirectory() } catch { return false }
+}
+
+function isFile(path: string): boolean {
+ try { return statSync(path).isFile() } catch { return false }
+}
+
+/** A command that looks like a path inside the harness must exist there; a shell line is not checked. */
+function commandPath(dir: string, command: string): string | null {
+ if (/[\s;&|<>$`'"\\]/.test(command)) return null
+ return join(dir, command)
+}
+
+export function checkDsh(path: string): CheckResult {
+ const dir = resolve(path)
+ const lines: CheckLine[] = []
+ const add = (level: CheckLine['level'], what: string): void => { lines.push({ level, what }) }
+ const read = readDshManifest(dir)
+ if (!read.ok) {
+ add('fail', read.error)
+ return { ok: false, lines, manifest: null }
+ }
+ const manifest = read.manifest
+ add('ok', `harness.json parses · ${manifest.id} "${manifest.name}" runs on ${manifest.engine}`)
+ if (!manifest.description) add('warn', 'no description — the picker tile will have none')
+
+ const ws = manifest.workspace
+ if (ws?.template) {
+ if (isDir(join(dir, ws.template))) add('ok', `workspace.template ${ws.template}/`)
+ else add('fail', `workspace.template ${ws.template} is not a directory`)
+ if (!ws.marker) add('warn', 'workspace.template without workspace.marker: the template is copied on EVERY create')
+ }
+ if (ws?.marker && ws.template && !existsSync(join(dir, ws.template, ws.marker))) {
+ add('warn', `workspace.marker ${ws.marker} is not in the template, so a fresh workspace stays "fresh" until something else writes it`)
+ }
+ if (ws?.init) {
+ const p = commandPath(dir, ws.init)
+ if (p === null) add('ok', `workspace.init is a shell line`)
+ else if (isFile(p)) add('ok', `workspace.init ${ws.init}`)
+ else add('fail', `workspace.init ${ws.init} does not exist`)
+ }
+
+ const agent = manifest.agent
+ if (agent?.instructions) {
+ if (isFile(join(dir, agent.instructions))) add('ok', `agent.instructions ${agent.instructions}`)
+ else add('fail', `agent.instructions ${agent.instructions} does not exist`)
+ } else {
+ add('warn', 'no agent.instructions — the agent gets no AGENTS.md from this harness')
+ }
+ for (const root of agent?.skills ?? []) {
+ const full = join(dir, root)
+ if (!isDir(full)) { add('fail', `agent.skills ${root} is not a directory`); continue }
+ const dirs = skillDirsIn(full)
+ if (!dirs.length) add('fail', `agent.skills ${root} has no SKILL.md-bearing directory`)
+ else add('ok', `agent.skills ${root}/ · ${dirs.map((d) => d.slice(full.length + 1) || '.').join(', ')}`)
+ }
+ if (!agent?.skills?.length) add('warn', 'no agent.skills — a tier-0 harness usually ships at least one')
+ for (const [key, value] of Object.entries(agent?.env ?? {})) {
+ if (key.startsWith('HARNESS_')) add('fail', `agent.env.${key} is reserved (HARNESS_* is set by Harness)`)
+ 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 ?? {})) {
+ if (!command) continue
+ const p = commandPath(dir, command)
+ if (p === null) add('ok', `toolchain.${name} is a shell line`)
+ else if (isFile(p)) add('ok', `toolchain.${name} ${command}`)
+ else add('fail', `toolchain.${name} ${command} does not exist`)
+ }
+ if (!manifest.toolchain?.doctor) add('warn', 'no toolchain.doctor — Harness cannot tell the user what is missing before a create')
+
+ const viewer = manifest.viewer
+ 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}`)
+ else add('fail', `viewer.command ${viewer.command} does not exist`)
+ if (!viewer.url.includes('${port}')) add('fail', 'viewer.url has no ${port}: Harness picks the port, the URL must use it')
+ if (!/^https?:\/\/(127\.0\.0\.1|localhost)[:/]/.test(viewer.url)) add('warn', 'viewer.url is not loopback; the pane expects a local server')
+ if (viewer.url.includes('${artifact}') && !viewer.artifactExtensions?.length) {
+ add('warn', 'viewer.url uses ${artifact} but no artifactExtensions are declared: only a verdict can name one')
+ }
+ }
+ if (manifest.verdict && !manifest.verdict.startsWith('.harness/')) add('warn', `verdict ${manifest.verdict} is outside .harness/ — allowed, but the convention is .harness/verdict.json`)
+
+ return { ok: !lines.some((line) => line.level === 'fail'), lines, manifest }
+}
+
+export function formatCheck(result: CheckResult): string {
+ return result.lines.map((line) => `${line.level.padEnd(4)} ${line.what}`).join('\n')
+}
diff --git a/cli/src/dsh/command.ts b/cli/src/dsh/command.ts
index 1d03ab6c8..455349b60 100644
--- a/cli/src/dsh/command.ts
+++ b/cli/src/dsh/command.ts
@@ -6,6 +6,7 @@ import { listDshState, installedDsh } from './installed.js'
import { dshTier } from './manifest.js'
import { bundledDshRegistry } from './registry.js'
import { installDsh, removeDsh, resolveInstallSource, runDshDoctor } from './install.js'
+import { checkDsh, formatCheck } from './check.js'
export function dshUsage(): string {
return `Domain-specific harnesses (a DSH turns Harness into a product for one domain — see dsh/README.md):
@@ -14,7 +15,8 @@ export function dshUsage(): string {
install by registry id (autonomous/circuit), git URL, or local path;
--link symlinks a local checkout instead of cloning it
harness dsh doctor <id> re-run the harness's own readiness check
- harness dsh remove <id> uninstall (a --link install removes only the link)`
+ harness dsh remove <id> uninstall (a --link install removes only the link)
+ harness dsh check <path> conformance check for a harness checkout (what the registry runs)`
}
function flagValue(argv: readonly string[], flag: string): string | undefined {
@@ -72,6 +74,13 @@ export async function dshCommand(verb: string | undefined, rest: readonly string
console.log(doctor.ok ? `${dsh.id} is ready` : `${dsh.id} is not ready`)
return doctor.ok ? 0 : 1
}
+ case 'check': {
+ const target = args[0] ?? '.'
+ const result = checkDsh(target)
+ console.log(formatCheck(result))
+ console.log(result.ok ? `${result.manifest?.id ?? target} conforms to spec 1` : `${result.manifest?.id ?? target} does not conform`)
+ return result.ok ? 0 : 1
+ }
case 'remove': {
const id = args[0]
if (!id) { console.error(dshUsage()); return 1 }