mandrel 2.94.0 → 2.95.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/.agents/runtime-deps.json +6 -6
  2. package/.agents/scripts/agents-bootstrap-github.js +1 -1
  3. package/.agents/scripts/board-backfill.js +1 -1
  4. package/.agents/scripts/boot-sweep.js +1 -1
  5. package/.agents/scripts/check-arch-cycles.js +69 -41
  6. package/.agents/scripts/check-doc-links.js +5 -7
  7. package/.agents/scripts/check-gherkin-corpus.js +2 -11
  8. package/.agents/scripts/clean-temp.js +1 -1
  9. package/.agents/scripts/cleanup-repo-test-temp.js +1 -1
  10. package/.agents/scripts/diagnose-friction.js +1 -1
  11. package/.agents/scripts/generate-lens-checklists.js +4 -4
  12. package/.agents/scripts/generate-skills-index.js +3 -2
  13. package/.agents/scripts/generate-workflows-doc.js +2 -1
  14. package/.agents/scripts/lib/audit-baselines/read.js +2 -1
  15. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +13 -3
  16. package/.agents/scripts/lib/audit-exceptions/globs.js +12 -1
  17. package/.agents/scripts/lib/audit-exceptions/probe.js +24 -2
  18. package/.agents/scripts/lib/audit-exceptions/read.js +2 -2
  19. package/.agents/scripts/lib/audit-to-stories/group-findings.js +77 -67
  20. package/.agents/scripts/lib/baselines/components.js +21 -19
  21. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -8
  22. package/.agents/scripts/lib/baselines/kinds/maintainability.js +2 -3
  23. package/.agents/scripts/lib/baselines/preview-gates.js +2 -2
  24. package/.agents/scripts/lib/baselines/refresh-service.js +4 -7
  25. package/.agents/scripts/lib/baselines/writer.js +2 -7
  26. package/.agents/scripts/lib/bdd-runner-detect.js +2 -2
  27. package/.agents/scripts/lib/bdd-step-index.js +3 -7
  28. package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js +11 -7
  29. package/.agents/scripts/lib/bootstrap/install-ledger.js +19 -4
  30. package/.agents/scripts/lib/bootstrap/json-io.js +14 -0
  31. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +20 -44
  32. package/.agents/scripts/lib/bootstrap/quality-bootstrap.js +38 -54
  33. package/.agents/scripts/lib/branch-name-guard.js +2 -3
  34. package/.agents/scripts/lib/claude/agents-projection.js +1 -12
  35. package/.agents/scripts/lib/codex/agents-projection.js +2 -5
  36. package/.agents/scripts/lib/codex/skills-projection.js +4 -12
  37. package/.agents/scripts/lib/config/defaults.js +2 -1
  38. package/.agents/scripts/lib/config/qa.js +4 -5
  39. package/.agents/scripts/lib/config-schema.js +1 -8
  40. package/.agents/scripts/lib/config-settings-schema.js +0 -3
  41. package/.agents/scripts/lib/coverage-baseline.js +2 -3
  42. package/.agents/scripts/lib/coverage-utils.js +2 -1
  43. package/.agents/scripts/lib/cpu-pool.js +0 -1
  44. package/.agents/scripts/lib/cyclomatic-scope.js +2 -1
  45. package/.agents/scripts/lib/doc-tiers.js +2 -1
  46. package/.agents/scripts/lib/gh-exec.js +21 -1
  47. package/.agents/scripts/lib/git/sync-from-base.js +1 -1
  48. package/.agents/scripts/lib/import-graph.js +13 -28
  49. package/.agents/scripts/lib/json-utils.js +11 -0
  50. package/.agents/scripts/lib/label-constants.js +7 -1
  51. package/.agents/scripts/lib/maintainability-utils.js +14 -22
  52. package/.agents/scripts/lib/observability/runtime-friction.js +37 -1
  53. package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js +25 -1
  54. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +9 -12
  55. package/.agents/scripts/lib/orchestration/code-review.js +1 -6
  56. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  57. package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js +7 -14
  58. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +2 -21
  59. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +11 -20
  60. package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js +65 -86
  61. package/.agents/scripts/lib/orchestration/git-cleanup/phases/prompts.js +2 -2
  62. package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js +15 -6
  63. package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js +5 -2
  64. package/.agents/scripts/lib/orchestration/merge-block-class.js +47 -48
  65. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +20 -1
  66. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -3
  67. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +4 -2
  68. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -2
  69. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +3 -3
  70. package/.agents/scripts/lib/orchestration/story-handoff.js +18 -5
  71. package/.agents/scripts/lib/orchestration/ticketing/transition.js +17 -21
  72. package/.agents/scripts/lib/runtime-deps/dep-resolution.js +19 -5
  73. package/.agents/scripts/lib/runtime-deps/scan-imports.js +4 -10
  74. package/.agents/scripts/lib/skills/parse-skill.js +2 -2
  75. package/.agents/scripts/lib/skills/walk-skill-files.js +7 -23
  76. package/.agents/scripts/lib/story-body/story-body.js +4 -14
  77. package/.agents/scripts/lib/util/atomic-write.js +14 -3
  78. package/.agents/scripts/lib/util/regex.js +4 -0
  79. package/.agents/scripts/notify.js +1 -1
  80. package/.agents/scripts/plan-context.js +1 -1
  81. package/.agents/scripts/plan-critics.js +3 -11
  82. package/.agents/scripts/providers/github/auth.js +0 -4
  83. package/.agents/scripts/providers/github/project-board.js +0 -1
  84. package/.agents/scripts/providers/github/tickets.js +0 -2
  85. package/.agents/scripts/resync-status-column.js +1 -1
  86. package/.agents/scripts/run-tests.js +1 -1
  87. package/.agents/scripts/test-wrapper.js +1 -1
  88. package/.agents/scripts/update-ticket-state.js +4 -3
  89. package/.agents/scripts/validate-skills.js +2 -1
  90. package/.agents/skills/core/gates-and-baselines/reference.md +1 -0
  91. package/.agents/workflows/audit-baselines.md +21 -9
  92. package/.agents/workflows/clean-git.md +1 -1
  93. package/.agents/workflows/helpers/audit-lens-core.md +1 -1
  94. package/.agents/workflows/helpers/code-quality-guardrails.md +3 -3
  95. package/README.md +1 -1
  96. package/docs/CHANGELOG.md +34 -0
  97. package/lib/cli/claude-code-version.js +13 -7
  98. package/lib/cli/doctor-checks/llm-review.js +12 -5
  99. package/lib/cli/doctor-checks/merge-driver.js +10 -6
  100. package/lib/cli/doctor-checks/project-access.js +21 -8
  101. package/lib/cli/doctor-checks/read-json.js +2 -15
  102. package/lib/cli/doctor-checks/spawn.js +29 -9
  103. package/lib/cli/doctor-checks/test-credit-path.js +2 -1
  104. package/lib/cli/doctor-checks/toolchain.js +16 -12
  105. package/lib/cli/doctor.js +31 -8
  106. package/lib/cli/registry.js +7 -10
  107. package/lib/cli/sync.js +46 -10
  108. package/lib/cli/uninstall.js +259 -175
  109. package/lib/cli/update.js +3 -3
  110. package/package.json +23 -20
package/README.md CHANGED
@@ -90,7 +90,7 @@ separate, planned pass.
90
90
 
91
91
  | Area | Lenses |
92
92
  | ---- | ------ |
93
- | Code & design | `architecture`, `clean-code`, `adrs`, `data-model`, `documentation`, `exceptions` |
93
+ | Code & design | `architecture`, `clean-code`, `adrs`, `data-model`, `documentation`, `exceptions`, `lean` |
94
94
  | Quality & ops | `quality`, `baselines`, `performance`, `devops`, `sre`, `dependencies` |
95
95
  | Security & privacy | `security`, `privacy` |
96
96
  | Product & UX | `ux-ui`, `accessibility`, `mobile`, `navigability`, `seo` |
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,40 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.95.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.94.0...mandrel-v2.95.0) (2026-10-21)
19
+
20
+
21
+ ### Added
22
+
23
+ * observe invalid agent:: state transitions instead of leaving the transition table unwired ([#5805](https://github.com/dsj1984/mandrel/issues/5805)) ([#5821](https://github.com/dsj1984/mandrel/issues/5821)) ([68bb4c1](https://github.com/dsj1984/mandrel/commit/68bb4c122c99f96bcb70b0b10a1d40ca1f72885f))
24
+ * tighten the quality floors after the burn-down, refresh stale baselines, and stop check-baselines ignoring unknown gate kinds ([#5817](https://github.com/dsj1984/mandrel/issues/5817)) ([#5833](https://github.com/dsj1984/mandrel/issues/5833)) ([37705a7](https://github.com/dsj1984/mandrel/commit/37705a7ac6a44a1d1df080273c708b958d532246))
25
+
26
+
27
+ ### Fixed
28
+
29
+ * address the post-v2.94.0 review: accept js-yaml 4 at consumer roots, observe every agent:: transition, and close error-path regressions ([#5836](https://github.com/dsj1984/mandrel/issues/5836)) ([5e0c216](https://github.com/dsj1984/mandrel/commit/5e0c216e7b79b084427b20f565db59eada73ec12))
30
+ * clear the dev-only npm advisories and refresh dependencies: markdownlint-cli2 0.24 with js-yaml 5, jscpd 4.3, minor batch, c8 12, chokidar 6 ([#5815](https://github.com/dsj1984/mandrel/issues/5815)) ([#5831](https://github.com/dsj1984/mandrel/issues/5831)) ([aba9345](https://github.com/dsj1984/mandrel/commit/aba93456869d150f256bbb1694de1fc9db1d326e))
31
+ * **deps:** clear the markdown-it GHSA-gfr2-rv44-r23c advisory (refs [#5799](https://github.com/dsj1984/mandrel/issues/5799)) ([#5800](https://github.com/dsj1984/mandrel/issues/5800)) ([9f5ccd1](https://github.com/dsj1984/mandrel/commit/9f5ccd1d31977fcb19bc630ff8d769d37e7f2baa))
32
+ * fix [#5804](https://github.com/dsj1984/mandrel/issues/5804): gh-exec.js ends child.stdin with no 'error' listener, so a g… ([#5819](https://github.com/dsj1984/mandrel/issues/5819)) ([#5820](https://github.com/dsj1984/mandrel/issues/5820)) ([86a1ffb](https://github.com/dsj1984/mandrel/commit/86a1ffb9f9a95775ae1e7b25ad00fdd006871ed0))
33
+ * justify or remove the dead and unexplained exceptions: GitHub auth coverage ignores, knip/biome/prettier exemptions, eslint comments ([#5812](https://github.com/dsj1984/mandrel/issues/5812)) ([#5828](https://github.com/dsj1984/mandrel/issues/5828)) ([66213b9](https://github.com/dsj1984/mandrel/commit/66213b98f6e4ae8a79978926cc5a3691c8c779de))
34
+ * plan-persist --dry-run prints 'Rewrote #&lt;id&gt; in place; it is agent::rea… ([#5802](https://github.com/dsj1984/mandrel/issues/5802)) ([#5803](https://github.com/dsj1984/mandrel/issues/5803)) ([d39f797](https://github.com/dsj1984/mandrel/commit/d39f7970198f7a6487c53d53638ba58487e7a085))
35
+ * stop interactive /clean-git from dropping every stash: await the stash decision and drop only on an explicit 'drop' ([#5834](https://github.com/dsj1984/mandrel/issues/5834)) ([#5835](https://github.com/dsj1984/mandrel/issues/5835)) ([9c8c890](https://github.com/dsj1984/mandrel/commit/9c8c8909d31feb9ea684e9378969c5c67fc568d6))
36
+ * write sync output and orchestration state files atomically, and make mandrel sync skip unchanged files ([#5813](https://github.com/dsj1984/mandrel/issues/5813)) ([#5829](https://github.com/dsj1984/mandrel/issues/5829)) ([9760a2f](https://github.com/dsj1984/mandrel/commit/9760a2f056351a9c078a98d15e2d822160b8acd8))
37
+
38
+
39
+ ### Performance
40
+
41
+ * run mandrel doctor checks concurrently, dedupe claude --version, and probe the user rung first for user-owned boards ([#5814](https://github.com/dsj1984/mandrel/issues/5814)) ([#5830](https://github.com/dsj1984/mandrel/issues/5830)) ([a699bc0](https://github.com/dsj1984/mandrel/commit/a699bc001c10067deef5ee5ae275a5113688daaf))
42
+
43
+
44
+ ### Changed
45
+
46
+ * adopt the shared helpers the tree re-implements: toPosix, walkFiles, isObject, parseGateArgv, escapeRegExp ([#5816](https://github.com/dsj1984/mandrel/issues/5816)) ([#5832](https://github.com/dsj1984/mandrel/issues/5832)) ([ae332d3](https://github.com/dsj1984/mandrel/commit/ae332d364f2c53c46be7b4037a7e57beb3e8747b))
47
+ * burn down the bootstrap hotspots and collapse their duplicated JSON readers ([#5807](https://github.com/dsj1984/mandrel/issues/5807)) ([#5825](https://github.com/dsj1984/mandrel/issues/5825)) ([f07f470](https://github.com/dsj1984/mandrel/commit/f07f470862aaf131b5f5e0b8e924418225f12074))
48
+ * burn down the lib/cli/uninstall.js CRAP and cyclomatic hotspot ([#5808](https://github.com/dsj1984/mandrel/issues/5808)) ([#5822](https://github.com/dsj1984/mandrel/issues/5822)) ([883d16a](https://github.com/dsj1984/mandrel/commit/883d16a6aaafedeca3fc81fc93f52db44c6be589))
49
+ * burn down the remaining single-file hotspots: baselines/components, merge-block-class, group-findings, config-schema ([#5810](https://github.com/dsj1984/mandrel/issues/5810)) ([#5826](https://github.com/dsj1984/mandrel/issues/5826)) ([39136ff](https://github.com/dsj1984/mandrel/commit/39136ffeafc94c78b219ebcb40c5b116daa4f820))
50
+ * test the git-cleanup phase drivers and probes, and remove their pass-through forwarders ([#5809](https://github.com/dsj1984/mandrel/issues/5809)) ([#5824](https://github.com/dsj1984/mandrel/issues/5824)) ([b97880b](https://github.com/dsj1984/mandrel/commit/b97880b212bf942a52b77e0ecfebb6d2c442d945))
51
+
18
52
  ## [2.94.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.93.0...mandrel-v2.94.0) (2026-10-20)
19
53
 
20
54
 
@@ -5,8 +5,8 @@
5
5
  * framework never hydrates, so the check fails. A missing `claude` binary,
6
6
  * unparseable output, or a project still carrying CLAUDE.md skips with
7
7
  * `ok: true` so headless/CI hosts are never blocked. The `claude --version`
8
- * spawn is injected by the registry (fixed argv, never user input); with no
9
- * runner the check skips.
8
+ * spawn goes through the injected `runner` (fixed argv, never user input);
9
+ * with neither `runner` nor `runClaude` the check skips.
10
10
  *
11
11
  * @module cli/claude-code-version
12
12
  */
@@ -33,15 +33,21 @@ export function parseClaudeVersion(text) {
33
33
  * projectRoot?: string,
34
34
  * cwd?: () => string,
35
35
  * existsSync?: (p: string) => boolean,
36
- * runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException },
36
+ * runner?: (cmd: string, args: string[], opts?: object) => unknown,
37
+ * runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException } | Promise<{ status: number|null, stdout: string, error?: NodeJS.ErrnoException }>,
37
38
  * }} [opts]
38
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
39
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
39
40
  */
40
- export function runClaudeCodeVersion({
41
+ export async function runClaudeCodeVersion({
41
42
  projectRoot,
42
43
  cwd = () => process.cwd(),
43
44
  existsSync = fs.existsSync,
44
- runClaude = () => ({ status: null, stdout: '', error: new Error('none') }),
45
+ runner = () => ({ status: null, stdout: '', error: new Error('none') }),
46
+ runClaude = () =>
47
+ runner('claude', ['--version'], {
48
+ shell: process.platform === 'win32',
49
+ timeout: 10_000,
50
+ }),
45
51
  } = {}) {
46
52
  const root = projectRoot ?? cwd();
47
53
  if (existsSync(path.join(root, 'CLAUDE.md'))) {
@@ -50,7 +56,7 @@ export function runClaudeCodeVersion({
50
56
  if (!existsSync(path.join(root, 'AGENTS.md'))) {
51
57
  return { ok: true, detail: 'skipped: no AGENTS.md' };
52
58
  }
53
- const r = runClaude();
59
+ const r = await runClaude();
54
60
  if (r.error || r.status !== 0) {
55
61
  return { ok: true, detail: 'skipped: claude not found on PATH' };
56
62
  }
@@ -34,6 +34,13 @@ function readReviewChain(projectRoot, fsImpl) {
34
34
  : { entries: DEFAULT_REVIEW_PROVIDERS, pinned: false };
35
35
  }
36
36
 
37
+ async function firstOnPath(clis, onPath) {
38
+ for (const cli of clis) {
39
+ if (await onPath(cli)) return cli;
40
+ }
41
+ return undefined;
42
+ }
43
+
37
44
  /**
38
45
  * Which CLI will serve each LLM provider in the effective review chain.
39
46
  * Fails only for a pinned non-optional provider whose CLI is missing — the
@@ -46,9 +53,9 @@ function readReviewChain(projectRoot, fsImpl) {
46
53
  * fsImpl?: { readFileSync: Function, existsSync: Function },
47
54
  * platform?: string,
48
55
  * }} [opts]
49
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
56
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
50
57
  */
51
- export function runLlmReviewProvider({
58
+ export async function runLlmReviewProvider({
52
59
  projectRoot,
53
60
  cwd,
54
61
  runner = spawn,
@@ -58,9 +65,9 @@ export function runLlmReviewProvider({
58
65
  const root = projectRoot ?? (cwd ?? (() => process.cwd()))();
59
66
  const { entries, pinned } = readReviewChain(root, fsImpl);
60
67
  const seen = new Map();
61
- const onPath = (cli) => {
68
+ const onPath = async (cli) => {
62
69
  if (!seen.has(cli)) {
63
- const r = runner(cli, ['--version'], {
70
+ const r = await runner(cli, ['--version'], {
64
71
  shell: platform === 'win32',
65
72
  timeout: 5000,
66
73
  });
@@ -74,7 +81,7 @@ export function runLlmReviewProvider({
74
81
  for (const entry of entries) {
75
82
  const clis = entry?.manualPrompt ? null : REVIEW_PROVIDER_CLIS[entry?.name];
76
83
  if (!clis) continue;
77
- const cli = clis.find(onPath);
84
+ const cli = await firstOnPath(clis, onPath);
78
85
  if (cli) served.push(`${entry.name} via ${cli}`);
79
86
  else if (entry.optional !== true) missing.push(entry.name);
80
87
  }
@@ -18,12 +18,16 @@ import { spawn } from './spawn.js';
18
18
  * `.gitattributes` does not declare the driver.
19
19
  *
20
20
  * @param {{cwd?: () => string, fsImpl?: typeof fs, runner?: typeof spawn}} [opts]
21
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
21
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
22
22
  */
23
- export function runMergeDriver({ cwd, fsImpl = fs, runner = spawn } = {}) {
23
+ export async function runMergeDriver({
24
+ cwd,
25
+ fsImpl = fs,
26
+ runner = spawn,
27
+ } = {}) {
24
28
  const projectRoot = (cwd ?? (() => process.cwd()))();
25
29
  // Git runs from projectRoot: the config key is per-clone.
26
- const { declared, command } = probeBaselineMergeDriver({
30
+ const { declared, command } = await probeBaselineMergeDriver({
27
31
  projectRoot,
28
32
  fsImpl,
29
33
  runGit: (args) => runner('git', args, { cwd: projectRoot }),
@@ -55,9 +59,9 @@ export function runMergeDriver({ cwd, fsImpl = fs, runner = spawn } = {}) {
55
59
  * @param {string} command
56
60
  * @param {typeof spawn} runner
57
61
  * @param {string} projectRoot
58
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
62
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
59
63
  */
60
- function probeConfiguredDriver(command, runner, projectRoot) {
64
+ async function probeConfiguredDriver(command, runner, projectRoot) {
61
65
  const parsed = parseBaselineMergeDriverCommand(command);
62
66
  if (!parsed) {
63
67
  return {
@@ -66,7 +70,7 @@ function probeConfiguredDriver(command, runner, projectRoot) {
66
70
  remedy: BASELINE_MERGE_DRIVER_REMEDY,
67
71
  };
68
72
  }
69
- const probe = runner(parsed.file, [...parsed.args, '--help'], {
73
+ const probe = await runner(parsed.file, [...parsed.args, '--help'], {
70
74
  cwd: projectRoot,
71
75
  });
72
76
  if (probe.status === 0) return { ok: true, detail: command };
@@ -54,13 +54,21 @@ function rungArgs(root, owner, projectNumber) {
54
54
  return args;
55
55
  }
56
56
 
57
+ /** An owner equal to the authenticated `login` is a user: probe that rung first. */
58
+ function rungOrder(owner, login) {
59
+ if (!owner) return ['viewer'];
60
+ return owner.toLowerCase() === login?.toLowerCase()
61
+ ? ['user', 'organization']
62
+ : ['organization', 'user'];
63
+ }
64
+
57
65
  /**
58
66
  * Probe one rung.
59
67
  *
60
68
  * @returns {'found'|'miss'|'scope'|'defer'}
61
69
  */
62
- function probeRung(runner, root, owner, projectNumber) {
63
- const r = runGh(
70
+ async function probeRung(runner, root, owner, projectNumber) {
71
+ const r = await runGh(
64
72
  rungArgs(root, owner, projectNumber),
65
73
  { timeout: 20_000 },
66
74
  runner,
@@ -82,12 +90,17 @@ function probeRung(runner, root, owner, projectNumber) {
82
90
 
83
91
  /**
84
92
  * Can the active token read the configured Projects v2 board? No board →
85
- * skipped; a gh that cannot run defers to `gh-auth`.
93
+ * skipped; a gh that cannot run defers to `gh-auth`, whose result is `prior`.
86
94
  *
87
- * @param {{ cwd?: () => string, fsImpl?: typeof fs, runner?: typeof spawn }} [opts]
88
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
95
+ * @param {{ cwd?: () => string, fsImpl?: typeof fs, runner?: typeof spawn, prior?: { login?: string } }} [opts]
96
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
89
97
  */
90
- export function runProjectAccess({ cwd, fsImpl = fs, runner = spawn } = {}) {
98
+ export async function runProjectAccess({
99
+ cwd,
100
+ fsImpl = fs,
101
+ runner = spawn,
102
+ prior,
103
+ } = {}) {
91
104
  const projectRoot = (cwd ?? (() => process.cwd()))();
92
105
  const { projectNumber, owner } = readBoardConfig(projectRoot, fsImpl);
93
106
  if (!projectNumber) {
@@ -96,10 +109,10 @@ export function runProjectAccess({ cwd, fsImpl = fs, runner = spawn } = {}) {
96
109
  detail: 'skipped — no github.projectNumber configured',
97
110
  };
98
111
  }
99
- const roots = owner ? ['organization', 'user'] : ['viewer'];
112
+ const roots = rungOrder(owner, prior?.login);
100
113
  const target = `project #${projectNumber}${owner ? ` for ${owner}` : ''}`;
101
114
  for (const root of roots) {
102
- const outcome = probeRung(runner, root, owner, projectNumber);
115
+ const outcome = await probeRung(runner, root, owner, projectNumber);
103
116
  if (outcome === 'found') return { ok: true, detail: `${target} readable` };
104
117
  if (outcome === 'defer') {
105
118
  return {
@@ -1,16 +1,3 @@
1
- // lib/cli/doctor-checks/read-json.js — shared JSON read for the doctor checks.
1
+ // Shared doctor-check JSON read: any failure degrades to `null`.
2
2
 
3
- /**
4
- * Raw JSON read; any failure degrades to `null`.
5
- *
6
- * @param {string} absPath
7
- * @param {{ readFileSync: Function }} fsImpl
8
- * @returns {object | null}
9
- */
10
- export function readJsonSafe(absPath, fsImpl) {
11
- try {
12
- return JSON.parse(fsImpl.readFileSync(absPath, 'utf8'));
13
- } catch {
14
- return null;
15
- }
16
- }
3
+ export { readJsonOrNull as readJsonSafe } from '../../../.agents/scripts/lib/json-utils.js';
@@ -1,18 +1,38 @@
1
- // lib/cli/doctor-checks/spawn.js — Shared `spawnSync` wrapper for the doctor checks.
1
+ // lib/cli/doctor-checks/spawn.js — Shared async spawn wrapper for the doctor checks.
2
2
 
3
- import { spawnSync } from 'node:child_process';
3
+ import { execFile } from 'node:child_process';
4
4
 
5
5
  /**
6
6
  * @param {string} cmd
7
7
  * @param {string[]} args
8
- * @returns {{ status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException }}
8
+ * @returns {Promise<{ status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException }>}
9
9
  */
10
10
  export function spawn(cmd, args, opts = {}) {
11
- const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
12
- return {
13
- status: r.status,
14
- stdout: typeof r.stdout === 'string' ? r.stdout : '',
15
- stderr: typeof r.stderr === 'string' ? r.stderr : '',
16
- error: r.error,
11
+ return new Promise((resolve) => {
12
+ const settle = (err, stdout, stderr) => {
13
+ const status = err ? (Number.isInteger(err.code) ? err.code : null) : 0;
14
+ resolve({
15
+ status,
16
+ stdout: stdout ?? '',
17
+ stderr: stderr ?? '',
18
+ error: status === null ? err : undefined,
19
+ });
20
+ };
21
+ try {
22
+ execFile(cmd, args, { encoding: 'utf8', ...opts }, settle);
23
+ } catch (err) {
24
+ // Node throws some spawn errors (ENOTDIR, EINVAL, bad args) synchronously.
25
+ settle(err);
26
+ }
27
+ });
28
+ }
29
+
30
+ /** One doctor run's runner: identical `cmd + args` probes share one spawn. */
31
+ export function createRunner(run = spawn) {
32
+ const spawned = new Map();
33
+ return (cmd, args, opts) => {
34
+ const key = JSON.stringify([cmd, args]);
35
+ if (!spawned.has(key)) spawned.set(key, run(cmd, args, opts));
36
+ return spawned.get(key);
17
37
  };
18
38
  }
@@ -5,6 +5,7 @@ import path from 'node:path';
5
5
  import { COMMANDS_DEFAULTS } from '../../../.agents/scripts/lib/config/commands.js';
6
6
  import { COVERAGE_CAPTURE_DEFAULTS } from '../../../.agents/scripts/lib/config/gates/coverage.schema.js';
7
7
  import { packageScriptArgv } from '../../../.agents/scripts/lib/detect-package-manager.js';
8
+ import { toPosix } from '../../../.agents/scripts/lib/util/paths.js';
8
9
  import { readJsonSafe } from './read-json.js';
9
10
 
10
11
  // check: test-credit-path
@@ -250,7 +251,7 @@ function describePrePushHook(projectRoot, readFileImpl) {
250
251
  ]) {
251
252
  try {
252
253
  hook = readFileImpl(path.join(projectRoot, rel), 'utf8');
253
- hookPath = rel.split(path.sep).join('/');
254
+ hookPath = toPosix(rel);
254
255
  break;
255
256
  } catch {
256
257
  // Absent here — try the next hooks location.
@@ -32,8 +32,8 @@ export function runNodeVersion({ nodeVersion = process.versions.node } = {}) {
32
32
  * @param {{ runner?: (cmd: string, args: string[]) => { status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException } }} [opts]
33
33
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
34
34
  */
35
- export function runGitAvailable({ runner = spawn } = {}) {
36
- const r = runner('git', ['--version']);
35
+ export async function runGitAvailable({ runner = spawn } = {}) {
36
+ const r = await runner('git', ['--version']);
37
37
  if (r.error?.code === 'ENOENT' || r.status !== 0) {
38
38
  const snippet = (r.stderr || r.stdout || '').trim().slice(0, 120);
39
39
  return {
@@ -51,8 +51,8 @@ export function runGitAvailable({ runner = spawn } = {}) {
51
51
  * @param {{ runner?: (cmd: string, args: string[]) => { status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException } }} [opts]
52
52
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
53
53
  */
54
- export function runGhAvailable({ runner = spawn } = {}) {
55
- const r = runGh(['--version'], {}, runner);
54
+ export async function runGhAvailable({ runner = spawn } = {}) {
55
+ const r = await runGh(['--version'], {}, runner);
56
56
  if (r.error?.code === 'ENOENT' || r.status !== 0) {
57
57
  const snippet = (r.stderr || r.stdout || '').trim().slice(0, 120);
58
58
  return {
@@ -77,12 +77,15 @@ export function runGhAvailable({ runner = spawn } = {}) {
77
77
  * error?: NodeJS.ErrnoException } }} [opts]
78
78
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
79
79
  */
80
- export function runGithubToken({ env = process.env, runner = spawn } = {}) {
80
+ export async function runGithubToken({
81
+ env = process.env,
82
+ runner = spawn,
83
+ } = {}) {
81
84
  const envToken = env.GITHUB_TOKEN || env.GH_TOKEN;
82
85
  if (envToken && envToken.length > 0) {
83
86
  return { ok: true, detail: 'GITHUB_TOKEN set' };
84
87
  }
85
- const r = runGh(['auth', 'token'], {}, runner);
88
+ const r = await runGh(['auth', 'token'], {}, runner);
86
89
  const ghToken = !r.error && r.status === 0 ? (r.stdout || '').trim() : '';
87
90
  if (ghToken.length > 0) {
88
91
  return { ok: true, detail: 'token resolved via `gh auth token`' };
@@ -105,10 +108,10 @@ export function runGithubToken({ env = process.env, runner = spawn } = {}) {
105
108
  * logged in" fails.
106
109
  *
107
110
  * @param {{ runner?: (cmd: string, args: string[]) => { status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException }, env?: Record<string,string|undefined> }} [opts]
108
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
111
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string, login?: string }>}
109
112
  */
110
- export function runGhAuth({ runner = spawn, env = process.env } = {}) {
111
- const r = runGh(['auth', 'status'], {}, runner);
113
+ export async function runGhAuth({ runner = spawn, env = process.env } = {}) {
114
+ const r = await runGh(['auth', 'status'], {}, runner);
112
115
  if (r.error?.code === 'ENOENT') {
113
116
  return {
114
117
  ok: false,
@@ -133,7 +136,8 @@ export function runGhAuth({ runner = spawn, env = process.env } = {}) {
133
136
  };
134
137
  }
135
138
  const output = (r.stdout + r.stderr).trim();
136
- const match = /Logged in to \S+ as (\S+)/i.exec(output);
137
- const detail = match ? `logged in as ${match[1]}` : 'logged in';
138
- return { ok: true, detail };
139
+ const login = /Logged in to \S+ (?:as|account) (\S+)/i.exec(output)?.[1];
140
+ return login
141
+ ? { ok: true, detail: `logged in as ${login}`, login }
142
+ : { ok: true, detail: 'logged in' };
139
143
  }
package/lib/cli/doctor.js CHANGED
@@ -1,8 +1,9 @@
1
1
  // lib/cli/doctor.js
2
2
  /**
3
- * `mandrel doctor`: run the registry checks in order, print a ✔/✘ line per
4
- * check (with the remedy under a failure) and a summary; exit 1 on any
5
- * failure.
3
+ * `mandrel doctor`: run the registry checks concurrently (a check with a
4
+ * prerequisite starts once it settles), print a ✔/✘ line per check in
5
+ * registry order (with the remedy under a failure) and a summary; exit 1 on
6
+ * any failure.
6
7
  */
7
8
 
8
9
  import nodeFs from 'node:fs';
@@ -12,6 +13,7 @@ import {
12
13
  resolveAlwaysLoadedClosure,
13
14
  tierTotalBytes,
14
15
  } from '../../.agents/scripts/lib/doc-tiers.js';
16
+ import { createRunner } from './doctor-checks/spawn.js';
15
17
  import { registry } from './registry.js';
16
18
 
17
19
  /**
@@ -23,6 +25,12 @@ function padName(name, width) {
23
25
  return name.length >= width ? name : name + ' '.repeat(width - name.length);
24
26
  }
25
27
 
28
+ /** Check name → the check it presupposes, whose result it gets as `prior`. */
29
+ const PREREQUISITES = {
30
+ 'gh-auth': 'gh-available',
31
+ 'github-project-access': 'gh-auth',
32
+ };
33
+
26
34
  // Longest check name is 19 chars.
27
35
  const NAME_COL = 21;
28
36
 
@@ -104,8 +112,12 @@ export function writeDoctorResultCache(
104
112
  }
105
113
 
106
114
  /**
115
+ * Every check gets the one per-run `runner`; a check that throws reports as
116
+ * a failure instead of aborting the run.
117
+ *
107
118
  * @param {{
108
- * checks?: Array<{ name: string, run(opts?: unknown): { ok: boolean, detail: string, remedy?: string } }>,
119
+ * checks?: Array<{ name: string, run(opts?: unknown): { ok: boolean, detail: string, remedy?: string } | Promise<{ ok: boolean, detail: string, remedy?: string }> }>,
120
+ * runner?: ReturnType<typeof createRunner>,
109
121
  * write?: (s: string) => void,
110
122
  * exit?: (code: number) => void,
111
123
  * writeResultCache?: (verdict: 'ready'|'unready') => void,
@@ -115,17 +127,28 @@ export function writeDoctorResultCache(
115
127
  */
116
128
  export async function runDoctor({
117
129
  checks = registry,
130
+ runner = createRunner(),
118
131
  write = (s) => process.stdout.write(s),
119
132
  exit = (code) => process.exit(code),
120
133
  writeResultCache = writeDoctorResultCache,
121
134
  closureReport = () => formatClosureReport(),
122
135
  } = {}) {
123
- let passed = 0;
136
+ const started = new Map();
137
+ const runs = checks.map((check) => {
138
+ const run = Promise.resolve(started.get(PREREQUISITES[check.name]))
139
+ .then((prior) => check.run({ runner, prior }))
140
+ .catch((err) => ({
141
+ ok: false,
142
+ detail: `check threw: ${err instanceof Error ? err : typeof err}`,
143
+ }));
144
+ started.set(check.name, run);
145
+ return run;
146
+ });
124
147
 
125
- for (const check of checks) {
126
- const result = await check.run();
148
+ let passed = 0;
149
+ for (const [i, result] of (await Promise.all(runs)).entries()) {
127
150
  if (result.ok) passed++;
128
- write(formatResult({ name: check.name, ...result }));
151
+ write(formatResult({ name: checks[i].name, ...result }));
129
152
  }
130
153
 
131
154
  // Report-only: not counted toward passed/total.
@@ -1,10 +1,10 @@
1
1
  // lib/cli/registry.js
2
2
  /**
3
3
  * Ordered `mandrel doctor` check registry: each entry is `{ name, run() }`,
4
- * `run()` returning `{ ok, detail, remedy? }` (`remedy` present whenever
5
- * `ok` is false). Checks run sequentially because some presuppose an earlier
6
- * one (`gh-auth` needs `gh-available`). Each check lives under
7
- * `doctor-checks/`; this array is the order. Node built-ins only (here and in
4
+ * `run()` resolving to `{ ok, detail, remedy? }` (`remedy` present whenever
5
+ * `ok` is false). Checks run concurrently except where one presupposes an
6
+ * earlier one (`PREREQUISITES` in `doctor.js`). Each check lives under
7
+ * `doctor-checks/`; this array is the report order. Node built-ins only (here and in
8
8
  * every check module), so it loads inside the preflight guard before
9
9
  * third-party packages exist; no check ever echoes a token value.
10
10
  */
@@ -74,7 +74,8 @@ export const registry = [
74
74
  name: 'gh-auth',
75
75
  run: (opts) => runGhAuth(opts),
76
76
  },
77
- // Presupposes gh-auth: an unauthenticated gh defers there.
77
+ // Presupposes gh-auth: an unauthenticated gh defers there; its login
78
+ // orders the rungs.
78
79
  {
79
80
  name: 'github-project-access',
80
81
  run: (opts) => runProjectAccess(opts),
@@ -113,11 +114,7 @@ export const registry = [
113
114
  },
114
115
  {
115
116
  name: 'claude-code-version',
116
- run: (opts) =>
117
- runClaudeCodeVersion({
118
- runClaude: () => spawn('claude', ['--version'], { timeout: 10_000 }),
119
- ...opts,
120
- }),
117
+ run: (opts) => runClaudeCodeVersion({ runner: spawn, ...opts }),
121
118
  },
122
119
  {
123
120
  name: 'llm-review-provider',
package/lib/cli/sync.js CHANGED
@@ -20,11 +20,19 @@ import path from 'node:path';
20
20
  import { ensureBaselineMergeDriver } from '../../.agents/scripts/lib/bootstrap/baseline-merge-driver.js';
21
21
  import { LEDGER_RELATIVE_PATH } from '../../.agents/scripts/lib/bootstrap/install-ledger.js';
22
22
  import { CODEX_SKILLS_DIR } from '../../.agents/scripts/lib/codex/skills-projection.js';
23
+ import {
24
+ copyFileAtomic,
25
+ writeFileAtomic,
26
+ } from '../../.agents/scripts/lib/util/atomic-write.js';
27
+ import { toPosix } from '../../.agents/scripts/lib/util/paths.js';
23
28
 
24
29
  export const PACKAGE_NAME = 'mandrel';
25
30
 
26
31
  const AGENTS_DIR = '.agents';
27
32
 
33
+ /** Windows stat modes carry only the readonly flag, so only POSIX compares. */
34
+ const COMPARES_MODE = process.platform !== 'win32';
35
+
28
36
  /** Top-level `.agents/` subdirectory reserved for consumer additions. */
29
37
  export const LOCAL_ZONE_DIR = 'local';
30
38
 
@@ -186,6 +194,41 @@ export function listFiles(dir, fsImpl, prefix = '') {
186
194
  return out;
187
195
  }
188
196
 
197
+ function installFile(src, dest, fsImpl) {
198
+ if (!isSameFile(src, dest, fsImpl)) copyFileAtomic(src, dest, { fsImpl });
199
+ }
200
+
201
+ function writeVersionMarker(projectRoot, version, fsImpl) {
202
+ if (readVersionMarker(projectRoot, fsImpl) === version) return;
203
+ const marker = path.join(
204
+ projectRoot,
205
+ AGENTS_DIR,
206
+ VERSION_MARKER_RELATIVE_PATH,
207
+ );
208
+ writeFileAtomic(marker, `${version}\n`, { fsImpl });
209
+ }
210
+
211
+ /**
212
+ * Size and permission bits first, then bytes: an unchanged payload file is
213
+ * never rewritten, and a mode-only change re-lands with the source's mode.
214
+ */
215
+ function isSameFile(src, dest, fsImpl) {
216
+ let destStat;
217
+ try {
218
+ destStat = fsImpl.statSync(dest);
219
+ } catch {
220
+ return false;
221
+ }
222
+ const srcStat = fsImpl.statSync(src);
223
+ if (destStat.size !== srcStat.size || !samePermissions(srcStat, destStat))
224
+ return false;
225
+ return fsImpl.readFileSync(src).equals(fsImpl.readFileSync(dest));
226
+ }
227
+
228
+ function samePermissions(a, b) {
229
+ return !COMPARES_MODE || (a.mode & 0o777) === (b.mode & 0o777);
230
+ }
231
+
189
232
  /**
190
233
  * Destination-tree enumeration for pruning. Skips the top-level local zone,
191
234
  * `*.local.*` overrides, {@link GENERATED_FILES} and {@link GENERATED_DIRS}.
@@ -290,10 +333,7 @@ export function runSync({
290
333
  }
291
334
 
292
335
  for (const rel of payloadFiles) {
293
- const src = path.join(sourceRoot, rel);
294
- const dest = path.join(destRoot, rel);
295
- fs.mkdirSync(path.dirname(dest), { recursive: true });
296
- fs.copyFileSync(src, dest);
336
+ installFile(path.join(sourceRoot, rel), path.join(destRoot, rel), fs);
297
337
  }
298
338
 
299
339
  const payloadSet = new Set(payloadFiles);
@@ -305,11 +345,7 @@ export function runSync({
305
345
  }
306
346
 
307
347
  // Written after the prune as a second safeguard beside GENERATED_FILES.
308
- const packageVersion = resolvePackageVersion(packageRoot, fs);
309
- fs.writeFileSync(
310
- path.join(destRoot, VERSION_MARKER_RELATIVE_PATH),
311
- `${packageVersion}\n`,
312
- );
348
+ writeVersionMarker(projectRoot, resolvePackageVersion(packageRoot, fs), fs);
313
349
 
314
350
  // Config half only; never allowed to fail the sync (no git, read-only config).
315
351
  const driver = ensureMergeDriver({
@@ -362,7 +398,7 @@ export function listRunbooks(payloadFiles, readText) {
362
398
  }
363
399
  return {
364
400
  title: title || path.basename(rel, '.md'),
365
- path: path.join(AGENTS_DIR, rel).split(path.sep).join('/'),
401
+ path: toPosix(path.join(AGENTS_DIR, rel)),
366
402
  };
367
403
  });
368
404
  }