dsh-tower 2.0.4 → 2.1.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.0.4",
+  "version": "2.1.0-beta.1",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -19,6 +19,7 @@
     "url": "git+https://github.com/louifinn/dsh-tower.git"
   },
   "homepage": "https://github.com/louifinn/dsh-tower#readme",
+  "types": "types/index.d.ts",
   "bugs": {
     "url": "https://github.com/louifinn/dsh-tower/issues"
   },
@@ -41,18 +42,25 @@
     "skills.js",
     "skills/",
     "lib/*.js",
+    "domain/**/*.js",
+    "app/*.js",
+    "tools/*.js",
+    "adapters/*.js",
+    "types/",
     "cordis.patch.yml",
     "scripts/",
     "locale/*.json",
     "icon.svg",
     "README.md",
     "README.en.md",
+    "COMPATIBILITY.md",
     "CHANGELOG.md",
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
     "docs/",
-    "ui-bundle/"
+    "ui-bundle/",
+    "ports/*.js"
   ],
   "dsh": {
     "bundle": {
@@ -63,11 +71,31 @@
     "test": "node --test tests/*.test.mjs",
     "test:watch": "node --test --watch tests/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage tests/*.test.mjs",
+    "smoke:mount": "node scripts/mount-smoke.mjs",
+    "smoke:fixtures": "node scripts/mount-smoke/fixtures.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "audit:issues": "node scripts/issue-audit.mjs",
     "dev:hmr": "node scripts/enable-dev-hmr.mjs",
     "docs:check": "node scripts/check-docs.mjs",
-    "check": "npm test && npm run docs:check"
+    "docs:generate:errors": "node scripts/generate-error-reference.mjs",
+    "docs:check:generated": "node scripts/generate-error-reference.mjs --check",
+    "docs:generate:tools": "node scripts/generate-tools-reference.mjs",
+    "docs:check:generated:tools": "node scripts/generate-tools-reference.mjs --check",
+    "docs:generate:config": "node scripts/generate-config-reference.mjs",
+    "docs:check:generated:config": "node scripts/generate-config-reference.mjs --check",
+    "pack:check": "node scripts/check-pack.mjs",
+    "architecture:check": "node scripts/architecture.mjs",
+    "types:check": "tsc --noEmit",
+    "check": "npm test && npm run docs:check && npm run pack:check && npm run architecture:check && npm run types:check && npm run domain:check",
+    "domain:metrics": "node scripts/domain-metrics.mjs",
+    "domain:check": "node scripts/domain-metrics.mjs --check"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "~3.18.5"
+    "@deepseek-ai/schemastery": "~3.18.5",
+    "@sinclair/typebox": "^0.34.41"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "~5.9.3"
   }
 }

package/ports/clock.js

@@ -0,0 +1,6 @@
+// Clock port (#56).
+/**
+ * @typedef {object} ClockPort
+ * @property {() => number} now
+ */
+export {}

package/ports/ids.js

@@ -0,0 +1,7 @@
+// Ids port (#56).
+/**
+ * @typedef {object} IdsPort
+ * @property {() => string} uuid
+ * @property {(text: string) => string} shortHash
+ */
+export {}

package/ports/index.js

@@ -0,0 +1,2 @@
+// Explicit ports consumed by app use cases (#56).
+export {}

package/ports/store.js

@@ -0,0 +1,11 @@
+// Store port (#56). Implementation: adapters/store-fs.js.
+/**
+ * @typedef {object} StorePort
+ * @property {(file: string) => Promise<boolean>} exists
+ * @property {(dir: string) => Promise<void>} ensureDir
+ * @property {(file: string) => Promise<any>} readJson
+ * @property {(file: string, value: unknown) => Promise<void>} writeJsonAtomic
+ * @property {(file: string, value: unknown) => Promise<void>} appendJsonl
+ * @property {(paths: object, fn: () => Promise<any>, options?: object) => Promise<any>} withLock
+ */
+export {}

package/ports/vcs.js

@@ -0,0 +1,11 @@
+// Vcs port (#56). Implementation: adapters/vcs-git.js.
+/**
+ * @typedef {object} VcsPort
+ * @property {(cwd: string, args: string[], options?: object) => Promise<string>} git
+ * @property {(cwd: string, args: string[], options?: object) => Promise<string|null>} tryGit
+ * @property {(cwd: string, ref: string) => Promise<string>} revParse
+ * @property {(cwd: string) => Promise<boolean>} isClean
+ * @property {(cwd: string, a: string, b: string) => Promise<boolean>} isAncestor
+ * @property {(repoRoot: string) => Promise<{root:string, commonDir:string, branch:string|null}>} resolveRepo
+ */
+export {}

package/scripts/architecture.mjs

@@ -0,0 +1,94 @@
+// Architecture fitness functions (#55).
+//
+// Rules are intentionally staged: rules for not-yet-migrated areas are
+// warnings (printed, exit 0) and flip to errors in the PR that makes them true.
+// The evaluator is exported so tests can seed one fixture violation per rule.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const ROOTS = ['lib', 'app', 'domain', 'tools', 'adapters', 'ports']
+const CHILD_PROCESS_ALLOWED = new Set(['adapters/vcs-git.js'])
+const FS_ALLOWED = new Set(['adapters/store-fs.js'])
+// Composition roots own the only intentional process-wide mutable state.
+const AMBIENT_ALLOWED = new Set(['lib/config.js', 'lib/git.js'])
+// The registration aggregator wires tool modules together; the thinness rule
+// applies to the individual modules under tools/.
+const TOOLS_REGISTRATION = new Set(['tools/index.js'])
+// The registration aggregator is the only tools/ module above the 200-line
+// per-tool ceiling: it wires the individual modules together. P3c split
+// tower_spawn, so every tool module now enforces the ceiling.
+const TOOLS_SIZE_ALLOWED = new Set(['tools/index.js'])
+const LITERAL_PATTERN = /enum:\s*\[\s*'(?:planned|active|completed|blocked|paused|abandoned|worker|reviewer|bug|improve|vuln|idea|low|medium|high|critical|open|triaged|fixed|wontfix)'/
+const TOOL_LITERAL_PATTERN = /(?:===|!==|==|!=|\.includes\(|case\s+)'?(?:planned|active|completed|blocked|paused|abandoned|worker|reviewer|bug|improve|vuln|idea|low|medium|high|critical|open|triaged|fixed|wontfix|create|abandon|close|status|merge|fix-then-merge|hold|acquire|release|map|user|failure|resource|dependency|json|markdown)'/
+
+function walk(root, relative = '') {
+  const dir = path.join(root, relative)
+  if (!fs.existsSync(dir)) return []
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const next = path.join(relative, entry.name)
+    if (entry.isDirectory()) out.push(...walk(root, next))
+    else if (entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) out.push(next.split(path.sep).join('/'))
+  }
+  return out
+}
+
+function evaluator(root) {
+  const files = ROOTS.flatMap((dir) => walk(root, dir)).filter((file) => !file.includes('/node_modules/'))
+  const violations = []
+  const record = (rule, file, detail, level) => violations.push({ rule, file, detail, level })
+
+  for (const file of files) {
+    const text = fs.readFileSync(path.join(root, file), 'utf8')
+    const lines = text.split('\n')
+    const imports = [...text.matchAll(/from\s+'([^']+)'|require\('([^']+)'\)/g)].map((match) => match[1] ?? match[2])
+    if (file.startsWith('domain/') && imports.some((spec) => /^(node:fs|node:fs\/promises|node:child_process|\.\.\/adapters|adapters\/)/.test(spec))) {
+      record('domain-pure', file, 'domain imports I/O or adapters', 'error')
+    }
+    if (imports.includes('node:child_process') && !CHILD_PROCESS_ALLOWED.has(file)) {
+      record('child-process-surface', file, 'only adapters/** may spawn processes', 'error')
+    }
+    if (imports.some((spec) => spec === 'node:fs' || spec === 'node:fs/promises') && !FS_ALLOWED.has(file)) {
+      record('fs-surface', file, 'only adapters/** may use fs', 'error')
+    }
+    if (file.startsWith('tools/')) {
+      if (imports.some((spec) => spec.startsWith('node:') && spec !== 'node:path')) {
+        record('tools-thin', file, 'tools/** may import only node:path', 'error')
+      }
+      if (LITERAL_PATTERN.test(text) || TOOL_LITERAL_PATTERN.test(text)) {
+        record('tools-vocabulary', file, 'status/type/role literal in tools/**', 'error')
+      }
+      if (lines.length < 40 || lines.length > 200) {
+        record('aggregate-size', file, `${lines.length} lines outside 40-200`, 'error')
+      }
+    } else if (lines.length > 800) {
+      record('aggregate-size', file, `${lines.length} lines exceeds 800`, 'error')
+    }
+    if (/^(?:export\s+)?let\s+/m.test(text) && !AMBIENT_ALLOWED.has(file) && (file.startsWith('lib/') || file.startsWith('app/') || file.startsWith('domain/'))) {
+      record('ambient-state', file, 'top-level let outside an allow-list', 'error')
+    }
+  }
+  return { ok: violations.every((violation) => violation.level !== 'error'), violations }
+}
+
+const rootArg = process.argv.indexOf('--root')
+const root = rootArg > 0 ? path.resolve(process.argv[rootArg + 1]) : PACKAGE_ROOT
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+  const result = evaluator(root)
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    for (const violation of result.violations) {
+      const line = `architecture ${violation.level}: [${violation.rule}] ${violation.file}: ${violation.detail}`
+      if (violation.level === 'error') console.error(line)
+      else console.warn(line)
+    }
+    if (result.violations.length === 0) console.log('architecture: ok')
+  }
+  process.exit(result.ok ? 0 : 1)
+}
+
+export { evaluator }

package/scripts/check-docs.mjs

@@ -9,14 +9,20 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const read = (file) => fs.readFileSync(path.join(root, file), 'utf8')
 const exists = (file) => fs.existsSync(path.join(root, file))
 
-const toolsSource = read('lib/tools.js') + read('index.js')
+const toolModuleSources = fs.existsSync(path.join(root, 'tools'))
+  ? fs.readdirSync(path.join(root, 'tools'))
+      .filter((name) => name.endsWith('.js'))
+      .map((name) => read(`tools/${name}`))
+      .join('\n')
+  : ''
+const toolsSource = read('tools/index.js') + toolModuleSources + read('lib/tool-registry.js') + read('index.js')
 const documentedTools = read('docs/reference/tools.md')
 const toolNames = [...new Set([...toolsSource.matchAll(/name: '(tower_[a-z_]+)'/g)].map((match) => match[1]))]
   .filter((name) => name !== 'tower-control')
   .sort()
 const missingTools = toolNames.filter((name) => !documentedTools.includes(`\`${name}\``))
 
-const towerSource = read('lib/tower.js')
+const towerSource = read('app/tower.js')
 const blockersSource = read('docs/reference/blockers.md')
 const blockerCodes = new Set()
 for (const match of towerSource.matchAll(/push\(\s*'([a-z][a-z-]+)'/g)) blockerCodes.add(match[1])
@@ -90,7 +96,7 @@ const eventNames = [
 const documentedEvents = read('docs/reference/events.md')
 const missingEvents = eventNames.filter((name) => !documentedEvents.includes(`\`tower/${name}\``))
 
-const errorsSource = read('lib/errors.js')
+const errorsSource = read('domain/errors.js')
 const documentedErrors = read('docs/reference/errors.md')
 const errorCodes = [...new Set([...errorsSource.matchAll(/^ {2}'([a-z][a-z-]+)':/gm)].map((match) => match[1]))].sort()
 const missingErrors = errorCodes.filter((code) => !documentedErrors.includes(`\`${code}\``))

package/scripts/check-pack.mjs

@@ -0,0 +1,49 @@
+// Fail when the published file list drifts from the reviewed snapshot.
+// Run: node scripts/check-pack.mjs [--write]
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const manifestFile = path.join(root, 'scripts', 'pack-manifest.txt')
+const write = process.argv.includes('--write')
+
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+let parsed
+try {
+  const output = execFileSync(npm, ['pack', '--dry-run', '--json'], {
+    cwd: root,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  parsed = JSON.parse(output)
+} catch (error) {
+  console.error(`pack check: npm pack failed: ${String(error?.message ?? error)}`)
+  process.exit(1)
+}
+
+const entry = Array.isArray(parsed) ? parsed[0] : parsed
+const paths = (entry?.files ?? []).map((file) => file.path).filter(Boolean).sort()
+if (write) {
+  fs.writeFileSync(manifestFile, `${paths.join('\n')}\n`)
+  console.log(`pack check: wrote ${paths.length} paths to ${path.relative(root, manifestFile)}`)
+  process.exit(0)
+}
+const expected = fs.readFileSync(manifestFile, 'utf8').split('\n').filter(Boolean).sort()
+const added = paths.filter((file) => !expected.includes(file))
+const removed = expected.filter((file) => !paths.includes(file))
+if (added.length > 0 || removed.length > 0) {
+  console.error('pack check: published file list changed; review and update scripts/pack-manifest.txt')
+  if (added.length > 0) console.error(`  added: ${added.join(', ')}`)
+  if (removed.length > 0) console.error(`  removed: ${removed.join(', ')}`)
+  process.exit(1)
+}
+const required = ['cordis.patch.yml', 'index.js', 'locale/en.json', 'locale/zh.json', 'ui-bundle/index.js', 'COMPATIBILITY.md']
+const missing = required.filter((file) => !paths.includes(file))
+if (missing.length > 0) {
+  console.error(`pack check: required runtime files missing: ${missing.join(', ')}`)
+  process.exit(1)
+}
+console.log(`pack check: ${paths.length} files match scripts/pack-manifest.txt`)

package/scripts/domain-metrics.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const SOURCE_ROOTS = ['domain', 'app', 'tools', 'adapters', 'lib']
+const ENTRY_FILES = ['index.js', 'worker.js', 'reviewer.js', 'skills.js']
+const PURE_ROOTS = ['domain']
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) walk(full, out)
+    else if (entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) out.push(full)
+  }
+  return out
+}
+
+function loc(file) {
+  return fs.readFileSync(file, 'utf8').split('\n').length
+}
+
+const files = SOURCE_ROOTS.flatMap((dir) => walk(path.join(root, dir)))
+for (const file of ENTRY_FILES) {
+  const full = path.join(root, file)
+  if (fs.existsSync(full)) files.push(full)
+}
+let pure = 0
+let total = 0
+for (const file of files) {
+  const lines = loc(file)
+  total += lines
+  const relative = path.relative(root, file).split(path.sep).join('/')
+  if (PURE_ROOTS.some((prefix) => relative === prefix || relative.startsWith(`${prefix}/`))) pure += lines
+}
+const share = total === 0 ? 0 : pure / total
+const result = { pure, total, share: Number(share.toFixed(4)) }
+if (process.argv.includes('--json')) console.log(JSON.stringify(result))
+else if (process.argv.includes('--check')) {
+  if (share < 0.35) {
+    console.error(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% < 35% (${pure}/${total})`)
+    process.exit(1)
+  }
+  console.log(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% (${pure}/${total})`)
+} else {
+  console.log(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% (${pure}/${total})`)
+}

package/scripts/generate-config-reference.mjs

@@ -0,0 +1,46 @@
+// Generate the config reference from the schemastery schema (#46).
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Config, resolveTowerConfig } from '../domain/config/schema.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const target = path.join(root, 'docs', 'reference', 'config.generated.md')
+const defaults = resolveTowerConfig({})
+const rows = []
+for (const [key, schema] of Object.entries(Config.dict ?? {})) {
+  const dict = schema?.dict
+  if (dict && typeof dict === 'object') {
+    for (const [child, childSchema] of Object.entries(dict)) {
+      rows.push(format(`${key}.${child}`, childSchema, schema))
+    }
+  } else {
+    rows.push(format(key, schema, Config))
+  }
+}
+function format(key, schema, parent) {
+  const value = key.split('.').reduce((current, part) => (current == null ? undefined : current[part]), defaults)
+  const fallback = value === undefined ? '' : JSON.stringify(value)
+  const description = String(schema?.meta?.description ?? parent?.meta?.description ?? '').replace(/\s+/g, ' ').trim()
+  return `| \`${key}\` | \`${fallback}\` | ${description} |`
+}
+const expected = `# Config reference (generated)
+
+> Generated by \`npm run docs:generate:config\` from \`domain/config/schema.js\`. Values are defaults before repo config.
+
+| Key | Default | Description |
+|---|---|---|
+${rows.join('\n')}
+`
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error('config reference is stale; run npm run docs:generate:config')
+    process.exit(1)
+  }
+  console.log(`config reference: ${rows.length} keys in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${rows.length} keys)`)
+}

package/scripts/generate-error-reference.mjs

@@ -0,0 +1,29 @@
+// Generate the error-code reference from domain/errors.js so the catalog and docs
+// cannot disagree (#46). Usage: node scripts/generate-error-reference.mjs [--check]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { ERROR_CODES } from '../domain/errors.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const target = path.join(root, 'docs', 'reference', 'errors.generated.md')
+const expected = `# Error code catalog (generated)
+
+> Generated by \`npm run docs:generate:errors\` from \`domain/errors.js\`. Do not edit by hand.
+
+| Code | Description |
+|---|---|
+${Object.entries(ERROR_CODES).map(([code, description]) => `| \`${code}\` | ${description} |`).join('\n')}
+`
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error(`error reference is stale; run npm run docs:generate:errors`)
+    process.exit(1)
+  }
+  console.log(`error reference: ${Object.keys(ERROR_CODES).length} codes in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${Object.keys(ERROR_CODES).length} codes)`)
+}

package/scripts/generate-tools-reference.mjs

@@ -0,0 +1,56 @@
+// Generate the tools overview from the registered tool definitions (#46).
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { registerTowerTools } from '../tools/index.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const target = path.join(root, 'docs', 'reference', 'tools.generated.md')
+const tools = new Map()
+const ctx = {
+  get() {
+    return undefined
+  },
+  effect(fn) {
+    const dispose = fn()
+    return typeof dispose === 'function' ? dispose : () => {}
+  },
+  systemPrompt: { section() {} },
+  tools: {
+    register(definition) {
+      tools.set(definition.name, definition)
+      return () => {}
+    },
+    guard() {
+      return () => {}
+    },
+    restrict() {
+      return () => {}
+    },
+  },
+}
+registerTowerTools(ctx)
+const rows = [...tools.values()]
+  .sort((a, b) => a.name.localeCompare(b.name))
+  .map((tool) => `| \`${tool.name}\` | ${String(tool.description ?? '').replace(/\s+/g, ' ').trim()} |`)
+const expected = `# Tools overview (generated)
+
+> Generated by \`npm run docs:generate:tools\` from the registered tool definitions. Do not edit by hand.
+
+| Tool | Description |
+|---|---|
+${rows.join('\n')}
+`
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error('tools reference is stale; run npm run docs:generate:tools')
+    process.exit(1)
+  }
+  console.log(`tools reference: ${tools.size} tools in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${tools.size} tools)`)
+}
+process.exit(0)