dsh-standards 0.0.3 → 1.0.0

package/40-checker/scripts/governance-check.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * governance-check.mjs — validate the machine-readable governance files.
+ *
+ * It checks the rules that must not rot:
+ *   - exactly one human organizer;
+ *   - every AI role is a bot and never holds a forbidden permission;
+ *   - Class A decisions are human-only; Class B can be drafted by AI but not decided;
+ *   - AI merge allowlist/denylist still protect spec/governance/checker;
+ *   - contributors and reviewers reference an existing role and a known terms version.
+ *
+ * Exit codes: 0 all checks pass; 2 at least one error.
+ *
+ * Usage:
+ *   node 40-checker/scripts/governance-check.mjs [--root <dir>] [--format text|json]
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const DEFAULT_ROOT = path.resolve(HERE, '..', '..')
+const TERMS_VERSION = 'dsh-ct/1'
+const VALUES = new Set(['allow', 'allow-with-allowlist', 'propose', 'review', 'deny'])
+const LEVELS = new Set(['signed', 'verified', 'trusted', 'entity-covered'])
+const REVIEW_STATUS = new Set(['provisional', 'active', 'dormant', 'revoked'])
+
+function readJson(root, rel) {
+  const file = path.join(root, rel)
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+export function validateGovernance({ roles, contributors, reviewers, coi }) {
+  const errors = []
+  const warnings = []
+  const err = (m) => errors.push(m)
+  const warn = (m) => warnings.push(m)
+
+  if (!roles || roles.schema !== 'dsh-governance/1') err('roles.schema must be dsh-governance/1')
+  if (!contributors || contributors.schema !== 'dsh-contributors/1') err('contributors.schema must be dsh-contributors/1')
+  if (!reviewers || reviewers.schema !== 'dsh-reviewers/1') err('reviewers.schema must be dsh-reviewers/1')
+  if (!coi || coi.schema !== 'dsh-coi/1') err('coi.schema must be dsh-coi/1')
+  if (!roles || !roles.roles || !roles.matrix) {
+    return { errors: errors.concat('roles.json must contain roles and matrix'), warnings }
+  }
+
+  // 1. Roles and matrix.
+  const roleIds = Object.keys(roles.roles)
+  const humanRoles = roleIds.filter((id) => roles.roles[id].humanOnly === true)
+  const organizers = roleIds.filter((id) => id === 'organizer' || roles.roles[id].appointment === 'creator')
+  if (organizers.length !== 1) err(`exactly one organizer is required, found ${organizers.length}`)
+  if (!humanRoles.includes('organizer')) err('organizer must be humanOnly')
+  if (roles.roles.organizer && roles.roles.organizer.maxHolders !== 1) err('organizer.maxHolders must be 1')
+  if (!humanRoles.includes('maintainer')) err('maintainer must be humanOnly')
+  if (!humanRoles.includes('reviewer')) err('reviewer must be humanOnly')
+
+  const permissions = roles.permissions
+  if (!Array.isArray(permissions) || permissions.length < 10) err('roles.permissions must list the permission keys')
+  for (const id of roleIds) {
+    const role = roles.roles[id]
+    if (typeof role.label !== 'string' || !role.label) err(`${id}.label is required`)
+    if (role.bot === true && role.humanOnly === true) err(`${id} cannot be both bot and humanOnly`)
+    if (typeof role.bot !== 'boolean') err(`${id}.bot must be boolean`)
+    if (typeof role.humanOnly !== 'boolean') err(`${id}.humanOnly must be boolean`)
+    const row = roles.matrix[id]
+    if (!row) { err(`matrix.${id} is missing`); continue }
+    for (const permission of permissions) {
+      if (!(permission in row)) err(`matrix.${id}.${permission} is missing`)
+      else if (!VALUES.has(row[permission])) err(`matrix.${id}.${permission} has invalid value ${row[permission]}`)
+    }
+    for (const key of Object.keys(row)) {
+      if (!permissions.includes(key)) err(`matrix.${id}.${key} is not a declared permission`)
+    }
+  }
+
+  // 2. AI boundaries.
+  const ai = roles.ai || {}
+  const forbidden = new Set(ai.forbiddenPermissions || [])
+  for (const id of roleIds.filter((rid) => roles.roles[rid].bot === true)) {
+    for (const permission of forbidden) {
+      const value = roles.matrix[id]?.[permission]
+      if (value && value !== 'deny' && value !== 'propose') {
+        err(`AI role ${id} must not hold ${permission} (got ${value})`)
+      }
+    }
+    if (roles.matrix[id]?.['appeal.decide'] !== 'deny') err(`AI role ${id} must not decide appeals`)
+    if (roles.matrix[id]?.['repo.merge.main'] === 'allow') err(`AI role ${id} needs allow-with-allowlist, not allow`)
+  }
+  if (!Array.isArray(ai.mergeAllowlist) || ai.mergeAllowlist.length === 0) err('ai.mergeAllowlist must not be empty')
+  if (!Array.isArray(ai.mergeDenylist)) err('ai.mergeDenylist must be an array')
+  for (const required of ['spec/', 'governance/', '40-checker/']) {
+    if (!(ai.mergeDenylist || []).includes(required)) err(`ai.mergeDenylist must include ${required}`)
+  }
+  if (!Array.isArray(ai.mustNot) || ai.mustNot.length < 3) warn('ai.mustNot should list the hard prohibitions')
+
+  // 3. Decision classes.
+  for (const [cls, rule] of Object.entries(roles.decisions || {})) {
+    const approvers = rule.approver || []
+    if (approvers.length === 0) err(`decision ${cls} has no approver`)
+    for (const approver of approvers) {
+      if (!roles.roles[approver]) err(`decision ${cls} references unknown role ${approver}`)
+    }
+    if (cls === 'A') {
+      if (rule.aiAllowed !== false) err('decision A must set aiAllowed=false')
+      for (const approver of approvers) {
+        if (roles.roles[approver]?.humanOnly !== true) err(`decision A approver ${approver} must be human`)
+      }
+    }
+    if (cls === 'B') {
+      if (rule.aiAllowed !== true) err('decision B should allow AI drafting')
+      if (rule.aiRole !== 'draft-only') err('decision B aiRole must be draft-only')
+    }
+    if (cls === 'D') {
+      for (const approver of approvers) {
+        if (roles.roles[approver]?.bot !== true) err(`decision D approver ${approver} must be an AI role`)
+      }
+    }
+  }
+
+  // 4. Quorum must never give AI a vote.
+  for (const [stage, rule] of Object.entries(roles.quorum || {})) {
+    if (typeof rule.claim !== 'string' || !/official|provisional|reviewed|consensus/i.test(rule.claim)) {
+      warn(`quorum.${stage}.claim should state the claim limit`)
+    }
+  }
+
+  // 5. Contributors.
+  const contributorHandles = new Set()
+  for (const entry of contributors.contributors || []) {
+    if (!entry.handle) { err('contributor entry without handle'); continue }
+    if (contributorHandles.has(entry.handle)) err(`duplicate contributor ${entry.handle}`)
+    contributorHandles.add(entry.handle)
+    if (!LEVELS.has(entry.level)) err(`contributor ${entry.handle} has invalid level ${entry.level}`)
+    if (entry.signedOff !== true) err(`contributor ${entry.handle} has no DCO sign-off`)
+    if (entry.terms !== contributors.terms) err(`contributor ${entry.handle} terms mismatch`)
+    if (entry.terms !== TERMS_VERSION) err(`contributor ${entry.handle} must use ${TERMS_VERSION}`)
+    if (entry.entityCla !== null && !/^[0-9a-f]{64}$/.test(entry.entityCla || '')) {
+      err(`contributor ${entry.handle} entityCla must be null or a sha256`)
+    }
+    if (!Array.isArray(entry.coi)) err(`contributor ${entry.handle} must declare coi[]`)
+  }
+
+  // 6. Reviewers.
+  for (const entry of reviewers.reviewers || []) {
+    if (!entry.handle) { err('reviewer entry without handle'); continue }
+    if (!REVIEW_STATUS.has(entry.status)) err(`reviewer ${entry.handle} has invalid status ${entry.status}`)
+    if (!Array.isArray(entry.scopes) || entry.scopes.length === 0) err(`reviewer ${entry.handle} needs scopes[]`)
+    if (!entry.expiresAt || Number.isNaN(Date.parse(entry.expiresAt))) err(`reviewer ${entry.handle} needs expiresAt`)
+    if (!Array.isArray(entry.coi)) err(`reviewer ${entry.handle} needs coi[]`)
+    if (roles.roles[entry.role]?.humanOnly !== true) err(`reviewer ${entry.handle} must reference a human role`)
+  }
+
+  // 7. COI declarations.
+  for (const entry of coi.declarations || []) {
+    if (!entry.handle) { err('coi entry without handle'); continue }
+    for (const field of roles.coi?.requiredFields || []) {
+      if (!(field in entry)) err(`coi ${entry.handle} is missing ${field}`)
+    }
+    if (entry.reviewDue && Number.isNaN(Date.parse(entry.reviewDue))) err(`coi ${entry.handle} reviewDue is invalid`)
+    if (entry.reviewDue && Date.parse(entry.reviewDue) < Date.now()) warn(`coi ${entry.handle} review is overdue`)
+  }
+
+  // 8. Basic consistency between registries.
+  for (const entry of reviewers.reviewers || []) {
+    if (entry.handle && !contributorHandles.has(entry.handle)) warn(`reviewer ${entry.handle} is not in contributors.json`)
+  }
+
+  return { errors, warnings }
+}
+
+export function main(argv = process.argv.slice(2)) {
+  let root = DEFAULT_ROOT
+  let format = 'text'
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--root') root = path.resolve(argv[++i])
+    else if (argv[i] === '--format') format = argv[++i]
+    else if (argv[i] === '--help' || argv[i] === '-h') {
+      console.log('usage: governance-check.mjs [--root <dir>] [--format text|json]')
+      return 0
+    } else {
+      console.error(`unknown argument: ${argv[i]}`)
+      return 2
+    }
+  }
+  let data
+  try {
+    data = {
+      roles: readJson(root, 'governance/roles.json'),
+      contributors: readJson(root, 'governance/contributors.json'),
+      reviewers: readJson(root, 'governance/reviewers.json'),
+      coi: readJson(root, 'governance/coi.json'),
+    }
+  } catch (error) {
+    console.error(`governance-check: cannot read input: ${error.message}`)
+    return 2
+  }
+  const result = validateGovernance(data)
+  if (format === 'json') {
+    console.log(JSON.stringify({ ok: result.errors.length === 0, ...result }, null, 2))
+  } else {
+    for (const warning of result.warnings) console.log(`WARN ${warning}`)
+    for (const error of result.errors) console.log(`FAIL ${error}`)
+    console.log(`${result.errors.length === 0 ? 'PASS' : 'FAIL'} governance: ${result.errors.length} error(s), ${result.warnings.length} warning(s)`)
+  }
+  return result.errors.length === 0 ? 0 : 2
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main()
+}

package/40-checker/scripts/host-farm.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * Build a temporary host farm for L1-L3 runs.
+ *
+ * The checker itself stays zero-dependency. This script is a *test utility*:
+ * it links a DSH checkout's installed dependencies plus every `@deepseek-ai/*`
+ * workspace/vendor package into a temp `node_modules`, copies one plugin into
+ * `farm/plugins/<name>`, and optionally runs `npm install` / `npm run build`.
+ *
+ * Linux/WSL is the supported environment (symlinks). Windows may need
+ * Developer Mode or an elevated shell for directory junctions.
+ *
+ * Usage:
+ *   node scripts/host-farm.mjs \
+ *     --plugin /tmp/dsh-verify-samples/foo \
+ *     --farm /tmp/dsh-farm \
+ *     --host <dsh-checkout> \
+ *     --install --build
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+function parse(argv) {
+  const options = { plugin: null, farm: null, host: '<dsh-checkout>', install: false, build: false, link: false, quiet: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--plugin') options.plugin = argv[++i]
+    else if (arg === '--farm') options.farm = argv[++i]
+    else if (arg === '--host') options.host = argv[++i]
+    else if (arg === '--install') options.install = true
+    else if (arg === '--build') options.build = true
+    else if (arg === '--link') options.link = true
+    else if (arg === '--quiet') options.quiet = true
+    else if (arg === '--help' || arg === '-h') { console.log(fs.readFileSync(new URL(import.meta.url), 'utf8').split('\n').slice(0, 20).join('\n')); process.exit(0) }
+    else throw new Error(`unknown option: ${arg}`)
+  }
+  if (!options.plugin) throw new Error('--plugin is required')
+  if (!options.farm) throw new Error('--farm is required')
+  return options
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true })
+}
+
+function link(source, dest) {
+  try {
+    if (fs.existsSync(dest) || fs.lstatSync(dest, { throwIfNoEntry: false })) return false
+  } catch { /* lstat can throw for broken links; fall through */ }
+  try {
+    fs.symlinkSync(source, dest, process.platform === 'win32' ? 'junction' : 'dir')
+    return true
+  } catch {
+    return false
+  }
+}
+
+function linkNodeModules(host, farm) {
+  const sourceModules = path.join(host, 'node_modules')
+  const destModules = path.join(farm, 'node_modules')
+  ensureDir(destModules)
+  let linked = 0
+  if (fs.existsSync(sourceModules)) {
+    for (const entry of fs.readdirSync(sourceModules, { withFileTypes: true })) {
+      if (entry.name === '@deepseek-ai') continue
+      const source = path.join(sourceModules, entry.name)
+      const dest = path.join(destModules, entry.name)
+      if (entry.name.startsWith('@') && entry.isDirectory()) {
+        ensureDir(dest)
+        for (const child of fs.readdirSync(source, { withFileTypes: true })) {
+          if (link(path.join(source, child.name), path.join(dest, child.name))) linked += 1
+        }
+      } else if (link(source, dest)) linked += 1
+    }
+  }
+  return linked
+}
+
+function linkWorkspacePackages(host, farm) {
+  const scope = path.join(farm, 'node_modules', '@deepseek-ai')
+  ensureDir(scope)
+  let linked = 0
+  const seen = new Set()
+  const walk = (directory) => {
+    if (!fs.existsSync(directory)) return
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      if (entry.name === 'node_modules' || entry.name === '.git') continue
+      const absolute = path.join(directory, entry.name)
+      const manifestPath = path.join(absolute, 'package.json')
+      if (fs.existsSync(manifestPath)) {
+        try {
+          const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+          if (typeof manifest.name === 'string' && manifest.name.startsWith('@deepseek-ai/')) {
+            const short = manifest.name.slice('@deepseek-ai/'.length)
+            if (!seen.has(short)) {
+              seen.add(short)
+              if (link(absolute, path.join(scope, short))) linked += 1
+            }
+          }
+        } catch { /* ignore malformed package.json */ }
+      }
+      if (entry.name === 'packages' || entry.name === 'vendor') walk(absolute)
+      else if (absolute.startsWith(path.join(host, 'packages')) || absolute.startsWith(path.join(host, 'vendor'))) walk(absolute)
+    }
+  }
+  walk(path.join(host, 'packages'))
+  walk(path.join(host, 'vendor'))
+  return linked
+}
+
+function copyPlugin(plugin, farm, asLink) {
+  const name = path.basename(path.resolve(plugin))
+  const dest = path.join(farm, 'plugins', name)
+  ensureDir(path.dirname(dest))
+  if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true })
+  if (asLink) {
+    fs.symlinkSync(path.resolve(plugin), dest, process.platform === 'win32' ? 'junction' : 'dir')
+  } else {
+    fs.cpSync(plugin, dest, { recursive: true, dereference: false })
+  }
+  return { name, dest }
+}
+
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit', env: { ...process.env, npm_config_audit: 'false', npm_config_fund: 'false' } })
+  if (result.error) return { ok: false, error: String(result.error) }
+  return { ok: result.status === 0, status: result.status }
+}
+
+function main() {
+  const options = parse(process.argv.slice(2))
+  const farm = path.resolve(options.farm)
+  const plugin = path.resolve(options.plugin)
+  if (!fs.existsSync(path.join(plugin, 'package.json'))) throw new Error(`not a package directory: ${plugin}`)
+  if (!fs.existsSync(options.host)) throw new Error(`host checkout not found: ${options.host}`)
+  ensureDir(farm)
+  const modules = linkNodeModules(options.host, farm)
+  const workspace = linkWorkspacePackages(options.host, farm)
+  const copied = copyPlugin(plugin, farm, options.link)
+  let install = null
+  let build = null
+  if (options.install) {
+    const manifest = JSON.parse(fs.readFileSync(path.join(copied.dest, 'package.json'), 'utf8'))
+    if (manifest.dependencies && Object.keys(manifest.dependencies).length > 0) {
+      install = run('npm', ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], copied.dest)
+    }
+  }
+  if (options.build) {
+    const manifest = JSON.parse(fs.readFileSync(path.join(copied.dest, 'package.json'), 'utf8'))
+    if (manifest.scripts?.build) build = run('npm', ['run', 'build'], copied.dest)
+  }
+  const summary = { farm, plugin: copied.dest, linkedModules: modules, linkedWorkspace: workspace, install, build }
+  if (!options.quiet) console.log(JSON.stringify(summary, null, 2))
+  return copied.dest
+}
+
+try {
+  const plugin = main()
+  console.log(plugin)
+} catch (error) {
+  console.error(`host-farm: ${error.message}`)
+  process.exitCode = 3
+}

package/40-checker/scripts/journey-config-observe.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * J3 + J7 runtime probe on a fixture plugin.
+ *
+ * J3: an invalid config value must fail loudly with a field path; a valid value
+ *     and the default must boot.
+ * J7: the start line must name the package/version; a keyless boot must reach a
+ *     diagnosable credential boundary.
+ *
+ * This is fixture-level evidence. It does not prove that every plugin validates
+ * its config or logs a start line.
+ *
+ * Usage:
+ *   node 40-checker/scripts/journey-config-observe.mjs \
+ *     --package 40-checker/fixtures/flow-config \
+ *     --dsh /tmp/dsh022/node_modules/@deepseek-ai/dsh/lib/bin.js --json
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+function parse(argv) {
+  const out = { package: null, dsh: process.env.DSH_BIN || 'dsh', json: false, timeout: 120_000 }
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--package') out.package = argv[++i]
+    else if (argv[i] === '--dsh') out.dsh = argv[++i]
+    else if (argv[i] === '--json') out.json = true
+    else if (argv[i] === '--timeout') out.timeout = Number(argv[++i])
+    else if (argv[i] === '--help' || argv[i] === '-h') { console.log('usage: journey-config-observe.mjs --package <dir> [--dsh <bin>] [--json]'); process.exit(0) }
+    else throw new Error(`unknown option: ${argv[i]}`)
+  }
+  if (!out.package) throw new Error('--package is required')
+  return out
+}
+
+function sh(cmd, args, env, timeout) {
+  return spawnSync(cmd, args, { encoding: 'utf8', timeout, env, maxBuffer: 8 * 1024 * 1024 })
+}
+
+function main() {
+  const options = parse(process.argv.slice(2))
+  const pkg = path.resolve(options.package)
+  const manifest = JSON.parse(fs.readFileSync(path.join(pkg, 'package.json'), 'utf8'))
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-config-'))
+  const profile = 'flow-config'
+  const env = { ...process.env, DSH_HOME: home }
+  delete env.DEEPSEEK_API_KEY
+  delete env.OPENAI_API_KEY
+  const checks = []
+  let dshVersion = null
+  const add = (id, result, reason) => checks.push({ id, result, reason })
+  try {
+    const version = sh(options.dsh, ['--version'], env, 20_000)
+    dshVersion = (version.stdout || '').trim()
+    const create = sh(options.dsh, ['--profile', profile, '--from-default-profile', 'headless', '--dump-config'], env, options.timeout)
+    if (create.status !== 0) {
+      add('setup.profile', 'BLOCKED', `profile create exit=${create.status}`)
+    } else {
+      const install = sh(options.dsh, ['plugin', '--profile', profile, 'add', pkg], env, options.timeout)
+      add('setup.install', install.status === 0 ? 'PASS' : 'BLOCKED', `plain dependency install exit=${install.status}`)
+
+      const overlay = path.join(home, 'flow-config.yml')
+      const write = (config) => {
+        const body = config === undefined
+          ? `- insert:\n    - id: flow-config\n      name: '${manifest.name}'\n`
+          : `- insert:\n    - id: flow-config\n      name: '${manifest.name}'\n      config:\n        port: ${JSON.stringify(config)}\n`
+        fs.writeFileSync(overlay, body)
+      }
+      const boot = () => sh(options.dsh, ['--profile', profile, '--patch', overlay, 'reply with one short sentence'], env, 60_000)
+
+      write('not-a-number')
+      const invalid = boot()
+      const invalidText = `${invalid.stdout}${invalid.stderr}`
+      const fieldPath = /config\.port/.test(invalidText)
+      add('J3.invalid-field-path', invalid.status !== 0 && fieldPath ? 'PASS' : 'FAIL', `invalid config exit=${invalid.status}; fieldPath=${fieldPath}`)
+
+      write(8080)
+      const valid = boot()
+      const validText = `${valid.stdout}${valid.stderr}`
+      add('J3.valid-config', valid.status !== 0 && /started \(port=8080\)/.test(validText) ? 'PASS' : 'FAIL', `valid config exit=${valid.status}`)
+      add('J7.start-line', /flow-config@1\.0\.0 started/.test(validText) ? 'PASS' : 'FAIL', 'start line names package@version')
+      add('J7.diagnosable', /MISSING_CREDENTIAL|no API key|AUTH|credential/i.test(validText) ? 'PASS' : 'FAIL', 'keyless failure reaches a diagnosable credential boundary')
+
+      write(undefined)
+      const defaults = boot()
+      add('J3.defaults', /started \(port=default\)/.test(`${defaults.stdout}${defaults.stderr}`) ? 'PASS' : 'FAIL', 'missing config uses the default')
+    }
+  } finally {
+    try { fs.rmSync(home, { recursive: true, force: true }) } catch { /* ignore */ }
+  }
+  const result = {
+    schema: 'dsh-flow-config-observe/1',
+    generatedAt: new Date().toISOString(),
+    package: manifest.name,
+    version: manifest.version,
+    environment: { dsh: dshVersion, node: process.version, platform: process.platform },
+    checks,
+    summary: {
+      pass: checks.filter((c) => c.result === 'PASS').length,
+      fail: checks.filter((c) => c.result === 'FAIL').length,
+      blocked: checks.filter((c) => c.result === 'BLOCKED').length,
+    },
+    limitations: ['fixture-level only; not every plugin validates config or logs a start line'],
+  }
+  if (options.json || !process.stdout.isTTY) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  process.exitCode = result.summary.fail > 0 ? 1 : 0
+}
+try { main() } catch (error) { console.error(`journey-config-observe: ${error.message}`); process.exitCode = 3 }

package/40-checker/scripts/journey-disclosure-shape.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * J5/J8 static preflight.
+ *
+ * J5: are capabilities/labels/commitments declared and does the README avoid
+ *     forbidden claims? The final permissions judgement is still human.
+ * J8: is the client/server shape declared (exports["./client"], server entry)?
+ *     This is a shape preflight, not a browser render probe (see web-probe.mjs).
+ *
+ * Usage: node 40-checker/scripts/journey-disclosure-shape.mjs --package <dir> [--json]
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const CHECKER = path.resolve(HERE, '..', 'bin', 'dsh-plugin-verify.mjs')
+const FORBIDDEN = /\b(official|certified|secure|recommended)\b|官方认证|安全审计|推荐标准/i
+
+function parse(argv) {
+  const out = { package: null, json: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--package') out.package = argv[++i]
+    else if (argv[i] === '--json') out.json = true
+    else if (argv[i] === '--help' || argv[i] === '-h') { console.log('usage: journey-disclosure-shape.mjs --package <dir> [--json]'); process.exit(0) }
+    else throw new Error(`unknown option: ${argv[i]}`)
+  }
+  if (!out.package) throw new Error('--package is required')
+  return out
+}
+
+function main() {
+  const options = parse(process.argv.slice(2))
+  const dir = path.resolve(options.package)
+  const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
+  const readme = ['README.md', 'readme.md', 'Readme.md'].map((n) => path.join(dir, n)).find((p) => fs.existsSync(p))
+  const text = readme ? fs.readFileSync(readme, 'utf8') : ''
+  const declared = {
+    capabilities: Array.isArray(manifest.dsh?.capabilities),
+    labels: Array.isArray(manifest.dsh?.labels),
+    commitments: Array.isArray(manifest.dsh?.commitments),
+  }
+  const forbidden = FORBIDDEN.test(text)
+  const run = spawnSync(process.execPath, [CHECKER, dir, '--scope', 'entry', '--entry-claim', 'static', '--format', 'json'], { encoding: 'utf8', timeout: 120_000, maxBuffer: 8 * 1024 * 1024 })
+  let checker = null
+  try { checker = JSON.parse(run.stdout) } catch { /* leave null */ }
+  const byId = new Map((checker?.checks ?? []).map((c) => [c.id, c]))
+  const declaration = ['DSC-11', 'DSC-12', 'DSC-13'].map((id) => ({ id, result: byId.get(id)?.result ?? 'NOT-RUN' }))
+  const j5 = forbidden ? 'FAIL' : declaration.some((d) => d.result === 'FAIL') ? 'FAIL' : declaration.some((d) => d.result === 'WARN') ? 'WARN' : 'PASS'
+  const hasClient = manifest.dsh?.client !== undefined
+  const clientExport = Boolean(manifest.exports?.['./client'])
+  const serverEntry = Boolean(manifest.exports?.['.'] || manifest.main)
+  const j8 = hasClient && !clientExport ? 'FAIL' : hasClient && clientExport && serverEntry ? 'PASS' : 'WARN'
+  const result = {
+    schema: 'dsh-flow-disclosure-shape/1',
+    generatedAt: new Date().toISOString(),
+    package: manifest.name,
+    version: manifest.version,
+    checks: {
+      J5: {
+        machine: j5,
+        humanReview: 'required',
+        declared,
+        forbiddenWords: forbidden,
+        declaration,
+        reason: forbidden ? 'README contains a forbidden claim' : 'permissions/disclosure judgement is still human',
+      },
+      J8: {
+        machine: j8,
+        humanReview: 'required for UI/render',
+        hasClient,
+        clientExport,
+        serverEntry,
+        reason: hasClient ? 'client shape checked statically; render not tested' : 'no dsh.client declaration',
+      },
+    },
+    limitations: ['J5 is a disclosure preflight, not a security review', 'J8 is a shape preflight, not a browser render probe'],
+  }
+  if (options.json || !process.stdout.isTTY) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  process.exitCode = [j5, j8].includes('FAIL') ? 1 : 0
+}
+try { main() } catch (error) { console.error(`journey-disclosure-shape: ${error.message}`); process.exitCode = 3 }