dsh-tower 2.0.4 → 2.1.0

package/scripts/issue-audit.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+// Offline tracker audit (#96, #79): every closed P0/P1 must point at evidence.
+//
+// A closure is checkable when its closing comment carries the two-line contract:
+//
+//   verified-by: tests/<file>.test.mjs
+//   commit: <sha>
+//
+// This script reads a *local tracker export* (no network, no credentials), finds
+// every closed P0/P1, and requires `verified-by:` to name a test file that exists
+// in the repository. A missing, nonexistent, non-test or repository-escaping
+// pointer exits non-zero, so "closed" stops being an assertion by the author.
+//
+// Usage:
+//   node scripts/issue-audit.mjs [--tracker <file>] [--root <dir>]
+//                                [--since <YYYY-MM-DD>] [--strict] [--json]
+//
+// CONTRIBUTING.md ("Commits, closures and evidence") documents the export
+// command and the rule; `npm run audit:issues` is the short form.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findingRecorder, parseArgs, runMain, UsageError } from './lib/cli.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const DEFAULT_TRACKER = path.join('tracker', 'issues.json')
+const TEST_PATTERN = /(?:^|\/)[^/]+\.(?:test|spec)\.[cm]?[jt]sx?$/
+const USAGE = `usage: node scripts/issue-audit.mjs [--tracker <file>] [--root <dir>] [--since <YYYY-MM-DD>] [--strict] [--json]
+
+  --tracker  local tracker export (default: tracker/issues.json)
+  --root     repository the verified-by paths resolve against (default: this package)
+  --since    only audit issues closed on or after this UTC date
+  --strict   treat a missing "commit:" field as an error
+  --json     print the report as JSON
+  --help     print this text
+
+The export is {"issues": [...]} or a bare array; each issue needs number, title,
+state (or closedAt), labels, body and comments. Produce it once with gh (see
+CONTRIBUTING.md); the audit itself never touches the network.`
+
+// `verified-by:` / `commit:` are line fields, not prose. Backticks, a leading
+// bullet or blockquote, and Windows path separators are tolerated because the
+// contract is about the pointer, not the formatting.
+function cleanValue(value) {
+  return String(value)
+    .trim()
+    .replace(/^`+|`+$/g, '')
+    .trim()
+    .replace(/^["']+|["']+$/g, '')
+    .trim()
+}
+
+export function extractFields(text) {
+  const fields = { verifiedBy: [], commit: null }
+  for (const rawLine of String(text ?? '').split(/\r?\n/)) {
+    const line = rawLine.replace(/^\s*(?:[-*+]\s+|>\s*)+/, '')
+    const match = /^(verified-by|commit)\s*:\s*(.+)$/i.exec(line)
+    if (!match) continue
+    const value = cleanValue(match[2])
+    if (!value) continue
+    if (match[1].toLowerCase() === 'verified-by') fields.verifiedBy.push(value)
+    else fields.commit = value
+  }
+  return fields
+}
+
+function textSources(issue) {
+  const sources = []
+  if (typeof issue.body === 'string' && issue.body.trim()) sources.push(issue.body)
+  const comments = Array.isArray(issue.comments) ? issue.comments : []
+  for (const comment of comments) {
+    const body = typeof comment === 'string' ? comment : comment?.body
+    if (typeof body === 'string' && body.trim()) sources.push(body)
+  }
+  return sources
+}
+
+// The newest text that carries a `verified-by:` line is the closure evidence;
+// an older comment cannot keep an issue closed after an edit. Every verified-by
+// line in that text is checked, so listing two tests cannot hide one gap.
+export function selectEvidence(issue) {
+  const sources = textSources(issue)
+  for (let index = sources.length - 1; index >= 0; index -= 1) {
+    const fields = extractFields(sources[index])
+    if (fields.verifiedBy.length > 0) return fields
+  }
+  return null
+}
+
+function labelsOf(issue) {
+  const labels = Array.isArray(issue.labels) ? issue.labels : []
+  return labels.map((label) => (typeof label === 'string' ? label : label?.name ?? '')).filter(Boolean)
+}
+
+export function priorityOf(issue) {
+  const labels = labelsOf(issue).map((label) => label.toUpperCase())
+  if (labels.includes('P0')) return 'P0'
+  if (labels.includes('P1')) return 'P1'
+  // The historical record uses `[P0]`/`[P1]` title prefixes; a label that was
+  // never backfilled must not make a critical closure invisible to the audit.
+  const match = /(?:^|\s)\[(P[01])\]/i.exec(String(issue.title ?? ''))
+  return match ? match[1].toUpperCase() : null
+}
+
+export function isClosed(issue) {
+  const state = String(issue.state ?? '').toLowerCase()
+  return state === 'closed' || Boolean(issue.closedAt ?? issue.closed_at)
+}
+
+function closedAtOf(issue) {
+  const raw = issue.closedAt ?? issue.closed_at
+  if (!raw) return null
+  const date = new Date(raw)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+// A pointer must stay inside the repository and name a real test file: an
+// existing script or doc is not evidence of a regression test.
+function inspectPointer(pointer, root) {
+  const normalized = String(pointer).replace(/\\/g, '/').trim()
+  if (!normalized) return { code: 'invalid-pointer', detail: 'empty' }
+  if (path.isAbsolute(normalized) || /^[A-Za-z]:\//.test(normalized) || normalized.startsWith('/')) {
+    return { code: 'invalid-pointer', detail: 'must be repository-relative' }
+  }
+  const resolved = path.resolve(root, normalized)
+  const relative = path.relative(root, resolved)
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return { code: 'invalid-pointer', detail: 'escapes the repository' }
+  }
+  if (!fs.existsSync(resolved)) return { code: 'missing-test', detail: 'does not exist' }
+  if (!fs.statSync(resolved).isFile()) return { code: 'missing-test', detail: 'is not a file' }
+  const isTest = normalized.startsWith('tests/') || TEST_PATTERN.test(normalized)
+  if (!isTest) return { code: 'not-a-test', detail: 'not under tests/ and not named *.test.* / *.spec.*' }
+  return null
+}
+
+export function parseTracker(text) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`tracker export is not valid JSON: ${error?.message ?? error}`)
+  }
+  const issues = Array.isArray(parsed) ? parsed : parsed?.issues
+  if (!Array.isArray(issues)) throw new Error('tracker export must be an array of issues or { "issues": [...] }')
+  for (const issue of issues) {
+    if (!issue || typeof issue !== 'object' || typeof issue.number !== 'number') {
+      throw new Error('tracker export must be an array of issues or { "issues": [...] }: every issue needs a numeric number')
+    }
+  }
+  return issues
+}
+
+export function auditIssues(issues, options = {}) {
+  const root = path.resolve(options.root ?? PACKAGE_ROOT)
+  const strict = Boolean(options.strict)
+  let since = null
+  if (options.since) {
+    since = new Date(`${String(options.since).slice(0, 10)}T00:00:00.000Z`)
+    if (Number.isNaN(since.getTime())) throw new UsageError(`--since is not a date: ${options.since}`)
+  }
+  const findings = []
+  let checked = 0
+  for (const issue of issues) {
+    if (!isClosed(issue)) continue
+    const priority = priorityOf(issue)
+    if (!priority) continue
+    const closedAt = closedAtOf(issue)
+    if (since && closedAt && closedAt < since) continue
+    checked += 1
+    const label = `#${issue.number} ${String(issue.title ?? '').trim()}`
+    const record = findingRecorder(findings, { number: issue.number, title: issue.title, priority })
+
+    const fields = selectEvidence(issue)
+    if (!fields) {
+      record('missing-evidence', 'error', `${label}: no verified-by: field in the body or comments`)
+      continue
+    }
+    for (const pointer of fields.verifiedBy) {
+      const problem = inspectPointer(pointer, root)
+      if (!problem) continue
+      if (problem.code === 'missing-test') {
+        record('missing-test', 'error', `${label}: verified-by names a missing test file: ${pointer}`)
+      } else if (problem.code === 'not-a-test') {
+        record('not-a-test', 'error', `${label}: verified-by is not a test file: ${pointer} (${problem.detail})`)
+      } else {
+        record('invalid-pointer', 'error', `${label}: verified-by must be a repository-relative path: ${pointer} (${problem.detail})`)
+      }
+    }
+    if (!fields.commit) {
+      record('missing-commit', strict ? 'error' : 'warning', `${label}: no commit: <sha> field (warning; --strict fails)`)
+    }
+  }
+  const errors = findings.filter((finding) => finding.level === 'error')
+  const warnings = findings.filter((finding) => finding.level === 'warning')
+  return {
+    ok: errors.length === 0,
+    checked,
+    findings,
+    errors: errors.length,
+    warnings: warnings.length,
+    strict,
+    since: options.since ?? null,
+  }
+}
+
+function parseOptions(argv) {
+  return parseArgs(argv, {
+    initial: { tracker: null, root: PACKAGE_ROOT, since: null, strict: false, json: false, help: false },
+    values: {
+      '--tracker': 'tracker',
+      '--root': { key: 'root', parse: path.resolve },
+      '--since': 'since',
+    },
+    flags: { '--strict': 'strict', '--json': 'json', '--help': 'help', '-h': 'help' },
+  })
+}
+
+function cli(argv) {
+  const options = parseOptions(argv)
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const tracker = options.tracker ? path.resolve(process.cwd(), options.tracker) : path.join(PACKAGE_ROOT, DEFAULT_TRACKER)
+  let text
+  try {
+    text = fs.readFileSync(tracker, 'utf8')
+  } catch (error) {
+    console.error(`issue-audit: cannot read tracker export ${tracker}: ${error?.message ?? error}`)
+    console.error('issue-audit: produce one with the gh command in CONTRIBUTING.md ("Commits, closures and evidence")')
+    return 2
+  }
+  let issues
+  let result
+  try {
+    issues = parseTracker(text)
+    result = auditIssues(issues, { root: options.root, since: options.since, strict: options.strict })
+  } catch (error) {
+    console.error(`issue-audit: ${error.message}`)
+    return 2
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ tracker, root: path.resolve(options.root), ...result }, null, 2))
+    return result.ok ? 0 : 1
+  }
+  console.log(`issue-audit: ${tracker}`)
+  console.log(`issue-audit: ${result.checked} closed P0/P1 checked, ${result.errors} errors, ${result.warnings} warnings`)
+  for (const finding of result.findings) console.log(`${finding.level} [${finding.code}] ${finding.message}`)
+  if (result.ok) {
+    console.log('issue-audit: every checked closure names an existing test file')
+  } else {
+    console.log(`issue-audit: ${result.errors} closure(s) are not verifiable; see CONTRIBUTING.md`)
+  }
+  return result.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => cli(process.argv.slice(2)), { errorPrefix: 'issue-audit', usage: USAGE })

package/scripts/lib/cli.mjs

@@ -0,0 +1,76 @@
+// Shared CLI plumbing for the maintenance entry points under scripts/ (#94).
+//
+// scripts/release-check.mjs, scripts/issue-audit.mjs, scripts/mount-smoke.mjs
+// and scripts/mount-smoke/fixtures.mjs had near-identical `parseArgs`,
+// `UsageError`, `isMain` and exit-code blocks. This is that block once: each
+// script declares its flags and keeps its own usage text, messages and codes.
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export class UsageError extends Error {}
+
+function usageError(message) {
+  const error = new UsageError(message)
+  // Only argument-parsing failures print the usage block; a repository or file
+  // problem exits 2 with its message only.
+  error.showUsage = true
+  return error
+}
+
+/** True when this module is the program entry point, not an imported module. */
+export function isMain(importMetaUrl) {
+  return Boolean(process.argv[1]) && path.resolve(process.argv[1]) === fileURLToPath(importMetaUrl)
+}
+
+/**
+ * Parse `--name <value>` and boolean flags into a plain object.
+ *
+ * - `initial`: the object to start from (a copy is returned).
+ * - `flags`: flag -> property name for booleans.
+ * - `values`: flag -> property name, or `{ key, parse }`.
+ * - `error`: error factory for scripts whose argument errors are ordinary
+ *   failures rather than usage errors (the mount smoke exits 1, not 2).
+ * - `optionLikeValues`: reject a value that itself starts with `--`.
+ */
+export function parseArgs(
+  argv,
+  { initial = {}, flags = {}, values = {}, error = usageError, optionLikeValues = true } = {},
+) {
+  const parsed = { ...initial }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (Object.prototype.hasOwnProperty.call(flags, arg)) {
+      parsed[flags[arg]] = true
+      continue
+    }
+    if (!Object.prototype.hasOwnProperty.call(values, arg)) throw error(`unknown argument ${JSON.stringify(arg)}`)
+    const next = argv[index + 1]
+    if (next === undefined || (optionLikeValues && next.startsWith('--'))) throw error(`${arg} needs a value`)
+    index += 1
+    const spec = values[arg]
+    if (typeof spec === 'string') parsed[spec] = next
+    else parsed[spec.key] = spec.parse ? spec.parse(next) : next
+  }
+  return parsed
+}
+
+/** The finding recorder both gates use, so every call is `(code, level, message)`. */
+export function findingRecorder(findings, base = {}) {
+  return (code, level, message) => findings.push({ ...base, code, level, message })
+}
+
+/**
+ * Run a CLI as the program entry point: the returned exit code becomes
+ * `process.exitCode`. A UsageError exits 2 (printing the usage text when it
+ * came from argument parsing); any other error exits 1.
+ */
+export async function runMain(importMetaUrl, run, { errorPrefix, usage = null } = {}) {
+  if (!isMain(importMetaUrl)) return
+  try {
+    process.exitCode = await run()
+  } catch (error) {
+    console.error(`${errorPrefix}: ${error?.message ?? error}`)
+    if (usage && error?.showUsage) console.error(usage)
+    process.exitCode = error instanceof UsageError ? 2 : 1
+  }
+}

package/scripts/lib/tmp.mjs

@@ -0,0 +1,20 @@
+// Best-effort temp-tree cleanup shared by the mount smoke and its fixtures (#91).
+//
+// Windows can hold a handle on a just-written file after a child process exits
+// (EPERM/EBUSY). Cleanup is never part of a proof, so retry briefly and give up:
+// a locked temp directory must not turn a green run red or hide the real cause
+// of a red one.
+import fs from 'node:fs'
+
+export function removeTreeQuietly(dir) {
+  if (!dir) return false
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+      return true
+    } catch {
+      // Still locked; try again, then leave the directory for the OS.
+    }
+  }
+  return false
+}

package/scripts/mount-smoke/fixtures.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// Seeded failure fixtures for the mount smoke (#95).
+//
+//   npm run smoke:fixtures
+//   node scripts/mount-smoke/fixtures.mjs --host-dir <installed-host> --keep
+//
+// The real smoke proves the current tree mounts. These fixtures prove it can
+// still fail for the right reason: each one copies the package into a temp
+// directory, breaks exactly one claim the bundle makes, runs the smoke against
+// the copy, and requires a red run that names the cause. A green control run
+// comes first, so a broken environment is never mistaken for a caught bug.
+//
+// The fixtures run in CI as the non-required `mount-fixtures` job, with one
+// cached host install shared by the control and both seeds through --host-dir;
+// locally the short form is `npm run smoke:fixtures`.
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs, runMain } from '../lib/cli.mjs'
+import { removeTreeQuietly } from '../lib/tmp.mjs'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.resolve(scriptDir, '..', '..')
+const smokePath = path.join(scriptDir, '..', 'mount-smoke.mjs')
+
+function parseOptions(argv) {
+  return parseArgs(argv, {
+    initial: { root: repoRoot, hostDir: undefined, keep: false },
+    values: {
+      '--root': { key: 'root', parse: path.resolve },
+      '--host-dir': { key: 'hostDir', parse: path.resolve },
+    },
+    flags: { '--keep': 'keep' },
+    error: (message) => new Error(message),
+    optionLikeValues: false,
+  })
+}
+
+function copyPackage(from, to) {
+  fs.cpSync(from, to, {
+    recursive: true,
+    filter: (source) => {
+      const base = path.basename(source)
+      return base !== 'node_modules' && base !== '.git'
+    },
+  })
+}
+
+function replaceOnce(text, search, replacement, label) {
+  const next = text.replace(search, replacement)
+  if (next === text) throw new Error(`seed did not apply: ${label}`)
+  return next
+}
+
+const fixtures = [
+  {
+    name: 'renamed-tool-id',
+    what: 'one tool module registers an id the bundle does not claim',
+    seed(root) {
+      const file = path.join(root, 'tools', 'doctor.js')
+      const text = fs.readFileSync(file, 'utf8')
+      fs.writeFileSync(file, replaceOnce(text, "name: 'tower_doctor'", "name: 'tower_doctor_renamed'", 'tools/doctor.js tower_doctor'))
+    },
+    expect: ['tool: missing tower_doctor', 'tool: unexpected tower_doctor_renamed'],
+  },
+  {
+    name: 'dropped-skills-section',
+    what: 'the tower-skills row is removed from the bundle patch',
+    seed(root) {
+      const file = path.join(root, 'cordis.patch.yml')
+      const text = fs.readFileSync(file, 'utf8')
+      const next = replaceOnce(
+        text,
+        /\n {8}- id: tower-skills\n {10}name: 'dsh-tower\/skills'/,
+        '',
+        'cordis.patch.yml tower-skills row',
+      )
+      fs.writeFileSync(file, next)
+    },
+    expect: ['skill: missing tower-worker-protocol', 'bundle: tower-bundle is missing child tower-skills'],
+  },
+]
+
+function runSmoke(root, hostDir) {
+  const result = spawnSync(process.execPath, [smokePath, '--root', root, '--host-dir', hostDir], {
+    encoding: 'utf8',
+    timeout: 600_000,
+    maxBuffer: 64 * 1024 * 1024,
+  })
+  return { status: result.status, output: `${result.stdout ?? ''}${result.stderr ?? ''}${result.error ? String(result.error) : ''}` }
+}
+
+function selfDescribing(output) {
+  const missing = []
+  if (!/^ {2}profile: /m.test(output)) missing.push('the resolved profile path')
+  if (!/^ {2}host: {4}@deepseek-ai\/dsh@/m.test(output)) missing.push('the host build')
+  return missing
+}
+
+function main() {
+  const options = parseOptions(process.argv.slice(2))
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-tower-mount-fixtures-'))
+  const hostDir = options.hostDir ?? path.join(tmp, 'host')
+  let failures = 0
+
+  try {
+    process.stdout.write(`control: the unmodified package mounts green\n`)
+    const control = runSmoke(options.root, hostDir)
+    if (control.status !== 0) {
+      console.error('control: FAILED — the fixtures cannot distinguish a seed from a broken environment')
+      console.error(control.output.slice(-4000))
+      failures += 1
+    } else {
+      console.log('control: PASS')
+    }
+
+    for (const fixture of fixtures) {
+      const copyRoot = path.join(tmp, fixture.name)
+      copyPackage(options.root, copyRoot)
+      try {
+        fixture.seed(copyRoot)
+      } catch (error) {
+        console.error(`fixture ${fixture.name}: FAILED to seed — ${error.message}`)
+        failures += 1
+        continue
+      }
+      const run = runSmoke(copyRoot, hostDir)
+      const problems = []
+      if (run.status === 0) problems.push('the smoke stayed green; the seeded break was not detected')
+      for (const marker of fixture.expect) if (!run.output.includes(marker)) problems.push(`the red run did not say: ${marker}`)
+      for (const missing of selfDescribing(run.output)) problems.push(`the red run did not print ${missing}`)
+      if (run.status !== 0 && !run.output.includes('workspace kept:')) problems.push('the red run did not keep its workspace')
+
+      if (problems.length > 0) {
+        console.error(`fixture ${fixture.name}: FAILED (${fixture.what})`)
+        for (const problem of problems) console.error(`  - ${problem}`)
+        console.error(run.output.slice(-4000))
+        failures += 1
+      } else {
+        const kept = /workspace kept: (.+)/.exec(run.output)?.[1]?.trim()
+        console.log(`fixture ${fixture.name}: PASS — the smoke failed and named the cause${kept ? ` (workspace ${kept})` : ''}`)
+      }
+    }
+  } finally {
+    if (options.keep) {
+      console.log(`fixtures workspace kept: ${tmp}`)
+    } else {
+      removeTreeQuietly(tmp)
+    }
+  }
+
+  if (failures > 0) {
+    console.error(`mount smoke fixtures: ${failures} of ${fixtures.length + 1} expectations failed`)
+    return 1
+  }
+  console.log(`mount smoke fixtures: control + ${fixtures.length} seeded failures behave as required`)
+  return 0
+}
+
+await runMain(import.meta.url, main, { errorPrefix: 'mount smoke fixtures failed' })

package/scripts/mount-smoke/host.json

@@ -0,0 +1,4 @@
+{
+  "dsh": "0.2.1-rc.2",
+  "pnpm": "11.28.5"
+}

package/scripts/mount-smoke/probe.mjs

@@ -0,0 +1,125 @@
+// Boot one throwaway profile through the real DSH loader and report its
+// loaded surface as JSON (#95).
+//
+// This is the only file that touches host internals. It is spawned by
+// scripts/mount-smoke.mjs against the pinned @deepseek-ai/dsh install, so the
+// entry points below are the ones `dsh` itself calls: `runProfile` composes the
+// profile's patch layers, mounts the tree, and hands back the root context.
+// No model call, no browser, no session.
+//
+// Usage: node probe.mjs --home <DSH_HOME> --host <host-install> --profile <name> --out <json>
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+function parseArgs(argv) {
+  const options = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const key = argv[index]
+    const value = argv[index + 1]
+    if (!key.startsWith('--') || value === undefined) throw new Error(`probe: bad argument ${JSON.stringify(key)}`)
+    options[key.slice(2)] = value
+    index += 1
+  }
+  for (const required of ['home', 'host', 'profile', 'out']) {
+    if (!options[required]) throw new Error(`probe: --${required} is required`)
+  }
+  return options
+}
+
+const options = parseArgs(process.argv.slice(2))
+const home = path.resolve(options.home)
+const host = path.resolve(options.host)
+
+// Read by dsh-home-paths through the host's own module graph, so this must be
+// set before anything from the host is imported.
+process.env.DSH_HOME = home
+process.env.DSH_TELEMETRY_DISABLED = '1'
+
+const hostPackage = path.join(host, 'node_modules', '@deepseek-ai', 'dsh', 'package.json')
+const hostVersion = JSON.parse(fs.readFileSync(hostPackage, 'utf8')).version
+const profileBoot = path.join(host, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'profile-boot.js')
+const appBoot = path.join(host, 'node_modules', '@deepseek-ai', 'dsh-app-boot', 'lib', 'index.js')
+for (const file of [profileBoot, appBoot]) {
+  if (!fs.existsSync(file)) throw new Error(`probe: ${file} is missing; host ${hostVersion} does not expose the loader entry point`)
+}
+
+const { runProfile } = await import(pathToFileURL(profileBoot).href)
+const { loadLayeredEnv } = await import(pathToFileURL(appBoot).href)
+if (typeof runProfile !== 'function') throw new Error(`probe: host ${hostVersion} does not export runProfile`)
+
+/** Run one surface read, keeping a missing service a reportable value. */
+async function read(run) {
+  try {
+    return { value: await run() }
+  } catch (error) {
+    return { error: String(error?.message ?? error) }
+  }
+}
+
+const { ctx, shutdown } = await runProfile({
+  environment: loadLayeredEnv('dsh'),
+  profile: options.profile,
+  patchFiles: [],
+  args: [],
+})
+
+const surface = { host: { version: hostVersion }, profile: {}, tools: null, skills: null, presets: null, commands: null, tree: null }
+try {
+  const profileContext = ctx.get('profileContext')
+  surface.profile = {
+    name: options.profile,
+    dir: profileContext?.dir ?? path.join(home, 'profiles', options.profile),
+    patchPath: profileContext?.patchPath ?? null,
+  }
+
+  const tools = ctx.get('tools')
+  surface.tools = tools
+    ? await read(() => tools.schemas().map((tool) => tool.name))
+    : { error: 'the tools service is not mounted' }
+
+  const skills = ctx.get('skills')
+  surface.skills = skills
+    ? await read(async () => {
+        const all = await skills.list()
+        return { tower: all.filter((skill) => skill.provider === 'dsh-tower').map((skill) => skill.name), total: all.length }
+      })
+    : { error: 'the skills service is not mounted' }
+
+  const presets = ctx.get('agentPresets')
+  surface.presets = presets
+    ? await read(async () => (await presets.list()).map((preset) => preset.id))
+    : { error: 'the agentPresets service is not mounted (profile has no preset registry)' }
+
+  const commands = ctx.get('commands')
+  surface.commands = commands
+    ? await read(() => commands.list(undefined).map((command) => command.name))
+    : { error: 'the commands service is not mounted' }
+
+  const loader = ctx.get('loader')
+  surface.tree = loader
+    ? await read(() => {
+        // `boot` mounts the profile behind one root include plugin; the composed
+        // rows live in that include's subtree. Stay correct if the root ever
+        // carries the tree directly.
+        const includeRow = loader.root.data.find((row) => row && row.name === 'cordis:include')
+        const tree = (includeRow && loader.store[includeRow.id]?.subtree) || loader
+        const top = tree.root.data.map((row) => ({
+          id: row?.id ?? null,
+          name: row?.name ?? null,
+          group: row?.group === true,
+          disabled: row?.disabled === true,
+          childIds: Array.isArray(row?.config)
+            ? row.config.map((child) => (child && typeof child === 'object' && child.id !== undefined ? String(child.id) : null)).filter(Boolean)
+            : [],
+        }))
+        const states = Object.fromEntries(Object.entries(tree.store).map(([id, entry]) => [id, entry?.fiber?.state ?? null]))
+        return { top, states }
+      })
+    : { error: 'the loader service is not mounted' }
+} finally {
+  await shutdown.shutdown(0)
+}
+
+fs.writeFileSync(options.out, `${JSON.stringify(surface, null, 2)}\n`)
+process.exit(0)