peaks-loop 4.1.18 → 4.1.19

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 (168) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +126 -0
  3. package/README-en.md +6 -0
  4. package/README.md +5 -0
  5. package/contracts/test-style-contract.md +14 -5
  6. package/dist/cli/commands/audit-red-lines-runners.js +6 -1
  7. package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
  8. package/dist/cli/commands/best-practice-scan-collision.js +115 -0
  9. package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
  10. package/dist/cli/commands/best-practice-scan-command.js +9 -18
  11. package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
  12. package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
  13. package/dist/cli/commands/code-auto-compact-command.js +26 -18
  14. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  15. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  16. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  17. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  18. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  19. package/dist/cli/commands/core/standards-init-command.js +44 -8
  20. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  21. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  22. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  23. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  24. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  25. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  26. package/dist/cli/commands/mut-commands.d.ts +9 -1
  27. package/dist/cli/commands/mut-commands.js +82 -154
  28. package/dist/cli/commands/preferences-commands.js +27 -2
  29. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  30. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  31. package/dist/services/24h-mode/auto-engage.js +14 -6
  32. package/dist/services/artifacts/artifact-templates.js +10 -0
  33. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  34. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  35. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  36. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  37. package/dist/services/artifacts/request-artifact-service.js +6 -6
  38. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  39. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  40. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  41. package/dist/services/audit/static-service.js +4 -4
  42. package/dist/services/code/auto-compact-history.d.ts +6 -1
  43. package/dist/services/code/auto-compact-history.js +6 -1
  44. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  45. package/dist/services/code/auto-compact-modes.js +75 -20
  46. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  47. package/dist/services/code/auto-compact-profile.js +51 -0
  48. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  49. package/dist/services/compact-history/compact-history-service.js +5 -1
  50. package/dist/services/context/auto-compact-types.d.ts +7 -5
  51. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  52. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  53. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  54. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  55. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  56. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  57. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  58. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  59. package/dist/services/hooks/presence-marker-detector.js +21 -19
  60. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  61. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  62. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  63. package/dist/services/mode/mode-status-service.d.ts +26 -27
  64. package/dist/services/mode/mode-status-service.js +36 -60
  65. package/dist/services/preferences/preferences-types.d.ts +30 -0
  66. package/dist/services/preferences/preferences-types.js +13 -0
  67. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  68. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  69. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  70. package/dist/services/scan/rid-change-claims.js +116 -0
  71. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  72. package/dist/services/skills/presence-caller-id.js +43 -0
  73. package/dist/services/skills/presence-gate.d.ts +65 -0
  74. package/dist/services/skills/presence-gate.js +113 -0
  75. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  76. package/dist/services/skills/presence-lease-resolver.js +114 -0
  77. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  78. package/dist/services/skills/presence-lease-selection.js +135 -0
  79. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  80. package/dist/services/skills/presence-lease-service.js +34 -87
  81. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  82. package/dist/services/skills/presence-lease-store.js +94 -0
  83. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  84. package/dist/services/skills/presence-lease-types.js +27 -0
  85. package/dist/services/skills/presence-role.d.ts +35 -0
  86. package/dist/services/skills/presence-role.js +72 -0
  87. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  88. package/dist/services/skills/skill-presence-service.js +143 -174
  89. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  90. package/dist/services/skills/skill-presence-write.js +74 -0
  91. package/dist/services/skills/skill-statusline-service.js +7 -7
  92. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  93. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  94. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  95. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  96. package/dist/services/standards/migrate-service.d.ts +1 -1
  97. package/dist/services/standards/migrate-service.js +27 -7
  98. package/dist/services/standards/project-scripts.d.ts +25 -0
  99. package/dist/services/standards/project-scripts.js +116 -0
  100. package/dist/services/standards/project-standards-service.d.ts +23 -15
  101. package/dist/services/standards/project-standards-service.js +176 -243
  102. package/dist/services/standards/standards-constitution.d.ts +89 -0
  103. package/dist/services/standards/standards-constitution.js +199 -0
  104. package/dist/services/standards/standards-files.d.ts +37 -0
  105. package/dist/services/standards/standards-files.js +138 -0
  106. package/dist/services/standards/standards-pointer.d.ts +73 -0
  107. package/dist/services/standards/standards-pointer.js +98 -0
  108. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  109. package/dist/services/standards/standards-render-agents.js +149 -0
  110. package/dist/services/standards/standards-render-common.d.ts +38 -1
  111. package/dist/services/standards/standards-render-common.js +44 -7
  112. package/dist/services/standards/standards-render.d.ts +1 -3
  113. package/dist/services/standards/standards-render.js +6 -87
  114. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  115. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  116. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  117. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  118. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  119. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  120. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  121. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  122. package/dist/services/workspace/runtime-layout.js +62 -0
  123. package/output-styles/peaks-skill-swarm.md +18 -2
  124. package/package.json +8 -9
  125. package/schemas/doctor-report.schema.json +1 -1
  126. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  127. package/skills/bee/peaks-prd/SKILL.md +5 -3
  128. package/skills/bee/peaks-qa/SKILL.md +4 -2
  129. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  130. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  131. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  132. package/skills/bee/peaks-rd/SKILL.md +4 -2
  133. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  134. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  135. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  136. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
  137. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  138. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  139. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  140. package/skills/bee/peaks-sc/SKILL.md +4 -2
  141. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  142. package/skills/bee/peaks-txt/SKILL.md +5 -3
  143. package/skills/bee/peaks-ui/SKILL.md +6 -4
  144. package/skills/peaks-audit/SKILL.md +3 -1
  145. package/skills/peaks-code/SKILL.md +3 -1
  146. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  147. package/skills/peaks-code/references/completion-handoff.md +1 -1
  148. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  149. package/skills/peaks-code/references/micro-cycle.md +2 -2
  150. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  151. package/skills/peaks-code/references/runbook.md +4 -4
  152. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  153. package/skills/peaks-code/references/standards-preflight.md +7 -6
  154. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  155. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  156. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  157. package/skills/peaks-content/SKILL.md +3 -1
  158. package/skills/peaks-doctor/SKILL.md +3 -1
  159. package/skills/peaks-final-review/SKILL.md +3 -1
  160. package/skills/peaks-ide/SKILL.md +3 -1
  161. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  162. package/skills/peaks-race-code/SKILL.md +3 -1
  163. package/skills/peaks-resume/SKILL.md +3 -1
  164. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  165. package/skills/peaks-solo/SKILL.md +3 -1
  166. package/skills/peaks-sop/SKILL.md +4 -2
  167. package/skills/peaks-status/SKILL.md +3 -1
  168. package/skills/peaks-test/SKILL.md +3 -1
@@ -2,7 +2,7 @@ import { migrateStandards } from '../../../services/standards/migrate-service.js
2
2
  import { migrateClaudeRules } from '../../../services/standards/migrate-claude-rules-service.js';
3
3
  import { fail, ok } from 'peaks-loop-shared/result';
4
4
  import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
5
- /** `--from-claude-rules`: thin `.claude/rules/` to pointers, scaffold `.peaks/standards/`. */
5
+ /** `--from-claude-rules`: thin `.claude/rules/` to pointers, scaffold `.peaks/standards/` + the constitution. */
6
6
  function runMigrateClaudeRules(io, options, projectRoot) {
7
7
  try {
8
8
  const result = migrateClaudeRules({ projectRoot, apply: options.apply === true });
@@ -13,6 +13,7 @@ function runMigrateClaudeRules(io, options, projectRoot) {
13
13
  backupPath: null,
14
14
  thinnedFiles: [],
15
15
  scaffoldedFiles: [],
16
+ scaffoldedConstitutionFiles: [],
16
17
  preservedFiles: [],
17
18
  wouldChange: false,
18
19
  applied: false,
@@ -21,7 +22,7 @@ function runMigrateClaudeRules(io, options, projectRoot) {
21
22
  process.exitCode = 1;
22
23
  }
23
24
  }
24
- /** Default branch: rewrite the legacy heartbeat block in CLAUDE.md. */
25
+ /** Default branch: rewrite the legacy heartbeat block in the project's constitution file. */
25
26
  function runMigrateLegacy(io, options, projectRoot) {
26
27
  try {
27
28
  const result = migrateStandards({ project: projectRoot, apply: options.apply === true });
@@ -43,10 +44,10 @@ function runMigrateLegacy(io, options, projectRoot) {
43
44
  export function registerStandardsMigrateCommand(standards, io) {
44
45
  addJsonOption(standards
45
46
  .command('migrate')
46
- .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write. With --from-claude-rules, thins the 1.x .claude/rules/ tree to 2-line pointers and scaffolds .peaks/standards/ (slice 2026-06-12-standards-migrate-claude-rules).')
47
+ .description('Rewrite a consumer project constitution file (AGENTS.md, or CLAUDE.md in a 1.x tree) to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write. With --from-claude-rules, thins the 1.x .claude/rules/ tree to 2-line pointers and scaffolds .peaks/standards/ plus the AGENTS.md + CLAUDE.md constitution (slice 2026-06-12-standards-migrate-claude-rules).')
47
48
  .option('--project <path>', 'target project root')
48
49
  .option('--apply', 'rewrite the legacy block in place; default is dry-run')
49
- .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/')).action((options) => {
50
+ .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/ + the constitution files')).action((options) => {
50
51
  const projectRoot = options.project ?? process.cwd();
51
52
  if (options.fromClaudeRules === true) {
52
53
  runMigrateClaudeRules(io, options, projectRoot);
@@ -36,6 +36,7 @@ export declare function makeCliRunner(args: {
36
36
  ids: {
37
37
  readonly rid: string;
38
38
  readonly sid: string;
39
+ readonly projectRoot: string;
39
40
  };
40
41
  emissions: DagEmissions;
41
42
  }): (spec: DispatchSpec) => Promise<SliceOutcome>;
@@ -1,6 +1,7 @@
1
1
  import { detectInstalledIde } from '../../services/ide/ide-detector.js';
2
2
  import { getAdapter } from '../../services/ide/ide-registry.js';
3
3
  import { planFileOverlapWaves } from '../../services/dispatch/file-overlap-wave-planner.js';
4
+ import { buildScratchPathInjection } from './dispatch-scratch-path-block.js';
4
5
  /** Detect the IDE and resolve its sub-agent dispatcher. */
5
6
  export function resolveDagDispatcher(projectRoot) {
6
7
  const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
@@ -32,9 +33,18 @@ export function planFirstLevelWaves(dag, levelArr) {
32
33
  export function makeCliRunner(args) {
33
34
  const { firstLevelIds, dispatcher, ids, emissions } = args;
34
35
  return async (spec) => {
36
+ // The scratch path is pinned HERE, in the brief the leaf receives: the DAG
37
+ // path does not pass through the prompt composer, so without this the leaf
38
+ // would pick its own redirect target, and a cwd-relative one lands at the
39
+ // repository root.
40
+ const scratch = buildScratchPathInjection({
41
+ projectRoot: ids.projectRoot,
42
+ sid: ids.sid,
43
+ role: spec.role
44
+ });
35
45
  const toolCall = dispatcher.buildToolCall({
36
46
  role: spec.role,
37
- prompt: spec.prompt,
47
+ prompt: `${spec.prompt}\n\n${scratch.block}`,
38
48
  requestId: ids.rid,
39
49
  sessionId: ids.sid
40
50
  });
@@ -3,6 +3,7 @@
3
3
  // in-process pipeline runs, so it lives in its own module.
4
4
  import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
5
5
  import { printResult } from '../cli-helpers.js';
6
+ import { buildScratchPathInjection } from './dispatch-scratch-path-block.js';
6
7
  function resolveMaxConcurrent(options) {
7
8
  return typeof options.maxConcurrent === 'string' && options.maxConcurrent.length > 0
8
9
  ? Number.parseInt(options.maxConcurrent, 10)
@@ -32,6 +33,23 @@ function reportDetachedError(io, role, error, asJson) {
32
33
  ]), asJson);
33
34
  process.exitCode = 1;
34
35
  }
36
+ /**
37
+ * The brief the vendor CLI receives: the caller's prompt plus the scratch
38
+ * block.
39
+ *
40
+ * The scratch path is pinned HERE, in the brief itself: the detached path does
41
+ * not pass through the prompt composer, so without this the leaf would pick its
42
+ * own redirect target, and a cwd-relative one lands at the repository root. The
43
+ * session id is resolved the way the detached handler resolves it, so both name
44
+ * one directory.
45
+ */
46
+ function detachedBrief(options, role) {
47
+ const projectRoot = options.project ?? process.cwd();
48
+ const sid = process.env.PEAKS_SESSION_ID ?? 'local';
49
+ const scratch = buildScratchPathInjection({ projectRoot, sid, role });
50
+ const prompt = typeof options.prompt === 'string' ? options.prompt : '';
51
+ return `${prompt}\n\n${scratch.block}`;
52
+ }
35
53
  export async function runDetachedDispatch(io, role, options, asJson) {
36
54
  try {
37
55
  const { dispatch: detachedDispatch } = await import('./sub-agent/detached.js');
@@ -39,7 +57,7 @@ export async function runDetachedDispatch(io, role, options, asJson) {
39
57
  const maxConcurrent = resolveMaxConcurrent(options);
40
58
  const result = await detachedDispatch({
41
59
  role,
42
- prompt: typeof options.prompt === 'string' ? options.prompt : '',
60
+ prompt: detachedBrief(options, role),
43
61
  requestId: options.requestId ?? 'unknown-rid',
44
62
  mode: 'detached',
45
63
  ...(typeof options.vendor === 'string' ? { vendor: options.vendor } : {}),
@@ -1,9 +1,45 @@
1
1
  /**
2
- * `peaks mut` — pure helper module extracted from `mut-commands.ts`
3
- * (file-size cap campaign). Mechanical move only: the stub-report
4
- * factories and the summary emitter keep their original behavior.
2
+ * `peaks mut` — command builders and helper functions.
3
+ *
4
+ * Originally extracted from `mut-commands.ts` (file-size cap campaign).
5
+ * It holds the stub-report factories, the summary emitter, the named-error
6
+ * mapping, and — after the `max-lines-per-function` rule was measured at
7
+ * 209 code lines for `createMutCommands` — the three subcommand builders
8
+ * that drive the mutation pipeline (`run`, `mutants`, `asserts`).
9
+ * The `report` subcommand — a pure reader of an already-written file —
10
+ * lives with the CLI surface in `mut-commands.ts`.
11
+ *
12
+ * The named-error part exists for R7: a missing or unloadable mutation
13
+ * toolchain must surface a MACHINE-READABLE error code (for example
14
+ * `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
15
+ * non-zero exit code — never `UNHANDLED_ERROR` with a bare
16
+ * "Cannot find package".
5
17
  */
6
- import { type AssertionsReport, type MutationReport } from 'peaks-loop-mut';
18
+ import { Command } from 'commander';
19
+ import { type AssertionsReport, type MutationReport, type StrykerInvoker } from 'peaks-loop-mut';
20
+ import { type ProgramIO } from '../cli-helpers.js';
21
+ /**
22
+ * Fallback code for a mutation failure that carries no named code of its
23
+ * own. The production invoker raises the specific codes; anything that
24
+ * escapes it without one still gets a stable, greppable name.
25
+ */
26
+ export declare const MUT_CLI_ERROR_CODE = "MUT_FAILED";
27
+ /**
28
+ * The IO the mut family writes to when the caller injects none. Same
29
+ * shape as `src/cli/program.ts`'s default sinks: one trailing newline
30
+ * per write.
31
+ */
32
+ export declare const DEFAULT_MUT_IO: ProgramIO;
33
+ /** The options every Stryker-backed subcommand receives. */
34
+ export interface MutCommandArgs {
35
+ readonly project: string;
36
+ readonly testFiles: string[];
37
+ readonly mutate?: string[];
38
+ readonly inputSig: string;
39
+ readonly sessionId: string;
40
+ readonly out: string;
41
+ readonly json: boolean;
42
+ }
7
43
  /**
8
44
  * Pure helper: a stub AssertionsReport used when only Stryker ran.
9
45
  * The mutants-only path does NOT touch the AST scanner; we still need
@@ -22,9 +58,40 @@ export declare function emptyMutation(): MutationReport;
22
58
  * both `--json` and the human-readable branches so the `passed` /
23
59
  * `sha256` shape stays consistent regardless of TTY mode.
24
60
  */
25
- export declare function emitSummary(json: boolean, payload: {
61
+ export declare function emitSummary(io: ProgramIO, json: boolean, payload: {
26
62
  ok: true;
27
63
  sha256: string;
28
64
  passed: boolean;
29
65
  path: string;
30
66
  }): void;
67
+ /**
68
+ * Read the machine-readable code off a failure. The production invoker
69
+ * raises named codes (`MUT_TOOLCHAIN_UNAVAILABLE`, `MUT_NO_MUTANTS`,
70
+ * `MUT_MUTATE_PATTERN_REQUIRED`, …) and `runMutation` preserves them
71
+ * while wrapping. Anything without a recognised code falls back to
72
+ * `MUT_FAILED` so the envelope is never anonymous.
73
+ */
74
+ export declare function mutErrorCode(err: unknown): string;
75
+ /** The human-readable half of the envelope. */
76
+ export declare function mutErrorMessage(err: unknown): string;
77
+ /**
78
+ * Emit the failure envelope on stderr and set a non-zero exit code.
79
+ * stdout stays reserved for the `--json` payload (R6), so the envelope
80
+ * goes to stderr exactly like every other peaks CLI error.
81
+ */
82
+ export declare function emitMutError(io: ProgramIO, err: unknown): void;
83
+ /**
84
+ * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
85
+ * report). One-axis: --session-id required.
86
+ */
87
+ export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
88
+ /**
89
+ * `peaks mut mutants` — Stryker only; writes a stub-assertions
90
+ * mut-report.json. One-axis: --session-id required.
91
+ */
92
+ export declare function buildMutMutantsCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
93
+ /**
94
+ * `peaks mut asserts` — the assertion scan only; writes a mut-report.json
95
+ * with an empty mutation block. One-axis: --session-id required.
96
+ */
97
+ export declare function buildMutAssertsCommand(io: ProgramIO): Command;
@@ -1,3 +1,40 @@
1
+ /**
2
+ * `peaks mut` — command builders and helper functions.
3
+ *
4
+ * Originally extracted from `mut-commands.ts` (file-size cap campaign).
5
+ * It holds the stub-report factories, the summary emitter, the named-error
6
+ * mapping, and — after the `max-lines-per-function` rule was measured at
7
+ * 209 code lines for `createMutCommands` — the three subcommand builders
8
+ * that drive the mutation pipeline (`run`, `mutants`, `asserts`).
9
+ * The `report` subcommand — a pure reader of an already-written file —
10
+ * lives with the CLI surface in `mut-commands.ts`.
11
+ *
12
+ * The named-error part exists for R7: a missing or unloadable mutation
13
+ * toolchain must surface a MACHINE-READABLE error code (for example
14
+ * `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
15
+ * non-zero exit code — never `UNHANDLED_ERROR` with a bare
16
+ * "Cannot find package".
17
+ */
18
+ import { Command } from 'commander';
19
+ import { buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
20
+ import { printErrorEnvelope } from '../cli-helpers.js';
21
+ /**
22
+ * Fallback code for a mutation failure that carries no named code of its
23
+ * own. The production invoker raises the specific codes; anything that
24
+ * escapes it without one still gets a stable, greppable name.
25
+ */
26
+ export const MUT_CLI_ERROR_CODE = 'MUT_FAILED';
27
+ /** Named mutation codes are always `MUT_` + upper snake case. */
28
+ const NAMED_CODE_PATTERN = /^MUT_[A-Z0-9_]+$/;
29
+ /**
30
+ * The IO the mut family writes to when the caller injects none. Same
31
+ * shape as `src/cli/program.ts`'s default sinks: one trailing newline
32
+ * per write.
33
+ */
34
+ export const DEFAULT_MUT_IO = {
35
+ stdout: (text) => process.stdout.write(`${text}\n`),
36
+ stderr: (text) => process.stderr.write(`${text}\n`)
37
+ };
1
38
  /**
2
39
  * Pure helper: a stub AssertionsReport used when only Stryker ran.
3
40
  * The mutants-only path does NOT touch the AST scanner; we still need
@@ -33,11 +70,167 @@ export function emptyMutation() {
33
70
  * both `--json` and the human-readable branches so the `passed` /
34
71
  * `sha256` shape stays consistent regardless of TTY mode.
35
72
  */
36
- export function emitSummary(json, payload) {
73
+ export function emitSummary(io, json, payload) {
37
74
  if (json) {
38
- process.stdout.write(JSON.stringify(payload) + '\n');
75
+ io.stdout(JSON.stringify(payload));
76
+ return;
39
77
  }
40
- else {
41
- process.stdout.write(`mut-report.json: ${payload.path}\nsha256: ${payload.sha256}\npassed: ${payload.passed}\n`);
78
+ io.stdout(`mut-report.json: ${payload.path}\nsha256: ${payload.sha256}\npassed: ${payload.passed}`);
79
+ }
80
+ /**
81
+ * Read the machine-readable code off a failure. The production invoker
82
+ * raises named codes (`MUT_TOOLCHAIN_UNAVAILABLE`, `MUT_NO_MUTANTS`,
83
+ * `MUT_MUTATE_PATTERN_REQUIRED`, …) and `runMutation` preserves them
84
+ * while wrapping. Anything without a recognised code falls back to
85
+ * `MUT_FAILED` so the envelope is never anonymous.
86
+ */
87
+ export function mutErrorCode(err) {
88
+ if (err && typeof err === 'object' && 'code' in err) {
89
+ const code = err.code;
90
+ if (typeof code === 'string' && NAMED_CODE_PATTERN.test(code)) {
91
+ return code;
92
+ }
42
93
  }
94
+ return MUT_CLI_ERROR_CODE;
95
+ }
96
+ /** The human-readable half of the envelope. */
97
+ export function mutErrorMessage(err) {
98
+ return err instanceof Error ? err.message : String(err);
99
+ }
100
+ /**
101
+ * Emit the failure envelope on stderr and set a non-zero exit code.
102
+ * stdout stays reserved for the `--json` payload (R6), so the envelope
103
+ * goes to stderr exactly like every other peaks CLI error.
104
+ */
105
+ export function emitMutError(io, err) {
106
+ printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), {}, []);
107
+ }
108
+ /**
109
+ * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
110
+ * report). One-axis: --session-id required.
111
+ */
112
+ export function buildMutRunCommand(invokeStryker, io) {
113
+ return new Command('run')
114
+ .description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
115
+ .requiredOption('--project <path>', 'project root')
116
+ .requiredOption('--test-files <files...>', 'test files to mutate against')
117
+ .option('--mutate <patterns...>', 'source patterns to mutate, relative to --project')
118
+ .requiredOption('--input-sig <hex>', 'TACT.sig (sha256) for chain')
119
+ .requiredOption('--session-id <sid>', 'session id; CLI writes artifacts only under .peaks/_runtime/<sid>/mut/ (one-axis layout)')
120
+ .requiredOption('--out <path>', 'output path for mut-report.json')
121
+ .option('--json', 'machine-readable output', false)
122
+ .action(async (a) => {
123
+ try {
124
+ const { mutation } = await runMutation({
125
+ project: a.project,
126
+ testFiles: a.testFiles,
127
+ mutate: a.mutate ?? [],
128
+ invokeStryker
129
+ });
130
+ const assertions = await scanAssertions({
131
+ project: a.project,
132
+ testFiles: a.testFiles
133
+ });
134
+ const report = await buildMutReport({
135
+ inputSig: a.inputSig,
136
+ out: a.out,
137
+ mutation,
138
+ assertions
139
+ });
140
+ emitSummary(io, a.json, {
141
+ ok: true,
142
+ sha256: report.sha256,
143
+ passed: report.thresholds.passed,
144
+ path: a.out
145
+ });
146
+ if (!report.thresholds.passed) {
147
+ // H6: CLI裁决 — threshold breach is a non-zero exit so callers
148
+ // (peaks-rd, peaks-qa, CI) can block on it without parsing stdout.
149
+ process.exitCode = 1;
150
+ }
151
+ }
152
+ catch (err) {
153
+ // R7: a named code + actionable message + non-zero exit, never an
154
+ // UNHANDLED_ERROR envelope with a bare "Cannot find package".
155
+ emitMutError(io, err);
156
+ }
157
+ });
158
+ }
159
+ /**
160
+ * `peaks mut mutants` — Stryker only; writes a stub-assertions
161
+ * mut-report.json. One-axis: --session-id required.
162
+ */
163
+ export function buildMutMutantsCommand(invokeStryker, io) {
164
+ return new Command('mutants')
165
+ .description('Run Stryker only; write a stub-assertions mut-report.json. One-axis: --session-id required.')
166
+ .requiredOption('--project <path>', 'project root')
167
+ .requiredOption('--test-files <files...>', 'test files to mutate against')
168
+ .option('--mutate <patterns...>', 'source patterns to mutate, relative to --project')
169
+ .requiredOption('--input-sig <hex>', 'TACT.sig')
170
+ .requiredOption('--session-id <sid>', 'session id')
171
+ .requiredOption('--out <path>', 'output path for mut-report.json')
172
+ .option('--json', 'machine-readable output', false)
173
+ .action(async (a) => {
174
+ try {
175
+ const { mutation } = await runMutation({
176
+ project: a.project,
177
+ testFiles: a.testFiles,
178
+ mutate: a.mutate ?? [],
179
+ invokeStryker
180
+ });
181
+ const report = await buildMutReport({
182
+ inputSig: a.inputSig,
183
+ out: a.out,
184
+ mutation,
185
+ assertions: emptyAssertions()
186
+ });
187
+ emitSummary(io, a.json, {
188
+ ok: true,
189
+ sha256: report.sha256,
190
+ passed: report.thresholds.passed,
191
+ path: a.out
192
+ });
193
+ if (!report.thresholds.passed) {
194
+ process.exitCode = 1;
195
+ }
196
+ }
197
+ catch (err) {
198
+ emitMutError(io, err);
199
+ }
200
+ });
201
+ }
202
+ /**
203
+ * `peaks mut asserts` — the assertion scan only; writes a mut-report.json
204
+ * with an empty mutation block. One-axis: --session-id required.
205
+ */
206
+ export function buildMutAssertsCommand(io) {
207
+ return new Command('asserts')
208
+ .description('Run the assertion scan only; write a mut-report.json with empty mutation block. One-axis: --session-id required.')
209
+ .requiredOption('--project <path>', 'project root')
210
+ .requiredOption('--test-files <files...>', 'test files to scan')
211
+ .requiredOption('--input-sig <hex>', 'TACT.sig')
212
+ .requiredOption('--session-id <sid>', 'session id')
213
+ .requiredOption('--out <path>', 'output path for mut-report.json')
214
+ .option('--json', 'machine-readable output', false)
215
+ .action(async (a) => {
216
+ const assertions = await scanAssertions({
217
+ project: a.project,
218
+ testFiles: a.testFiles
219
+ });
220
+ const report = await buildMutReport({
221
+ inputSig: a.inputSig,
222
+ out: a.out,
223
+ mutation: emptyMutation(),
224
+ assertions
225
+ });
226
+ emitSummary(io, a.json, {
227
+ ok: true,
228
+ sha256: report.sha256,
229
+ passed: report.thresholds.passed,
230
+ path: a.out
231
+ });
232
+ if (!report.thresholds.passed) {
233
+ process.exitCode = 1;
234
+ }
235
+ });
43
236
  }
@@ -3,6 +3,8 @@ import { type StrykerInvoker } from 'peaks-loop-mut';
3
3
  import type { ProgramIO } from '../cli-helpers.js';
4
4
  export interface MutCommandsOptions {
5
5
  readonly invokeStryker: StrykerInvoker;
6
+ /** Where the command writes. Defaults to stdout/stderr. */
7
+ readonly io?: ProgramIO;
6
8
  }
7
9
  /**
8
10
  * Construct the `peaks mut` family as a standalone Commander command.
@@ -17,4 +19,10 @@ export declare function createMutCommands(opts: MutCommandsOptions): Command;
17
19
  * `createMutCommands({ invokeStryker })` instead so the heavy
18
20
  * @stryker-mutator/core runtime stays out of the unit-test path.
19
21
  */
20
- export declare function registerMutCommands(program: Command, _io: ProgramIO): void;
22
+ export declare function registerMutCommands(program: Command, io: ProgramIO): void;
23
+ /**
24
+ * `peaks mut report` — re-read a previously-written mut-report.json (no
25
+ * Stryker / scan invocation). One-axis: --session-id required for the
26
+ * audit trail.
27
+ */
28
+ export declare function buildMutReportCommand(io: ProgramIO): Command;