peaks-loop 4.1.7 → 4.1.9

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 (85) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +72 -0
  3. package/config/eslint/tsconfig.lint.json +1 -0
  4. package/dist/cli/commands/code-gate-step-08-command.js +21 -11
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +17 -0
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +76 -0
  7. package/dist/cli/commands/code-job-shape-commands.js +21 -5
  8. package/dist/cli/commands/dispatch-from-dag.js +17 -0
  9. package/dist/cli/commands/job-commands.js +15 -5
  10. package/dist/cli/commands/job-init-status-commands.js +45 -5
  11. package/dist/cli/commands/lint-baseline-command.d.ts +15 -0
  12. package/dist/cli/commands/lint-baseline-command.js +64 -0
  13. package/dist/cli/commands/lint-commands.js +27 -51
  14. package/dist/cli/commands/request-command-options.d.ts +6 -0
  15. package/dist/cli/commands/request-commands.js +2 -0
  16. package/dist/cli/commands/request-mark-qa-initiated-command.d.ts +3 -0
  17. package/dist/cli/commands/request-mark-qa-initiated-command.js +80 -0
  18. package/dist/cli/commands/request-transition-failures.js +1 -0
  19. package/dist/cli/commands/reviewer-commands.d.ts +6 -6
  20. package/dist/cli/commands/reviewer-commands.js +154 -56
  21. package/dist/cli/commands/reviewer-config-commands.d.ts +9 -0
  22. package/dist/cli/commands/reviewer-config-commands.js +133 -0
  23. package/dist/services/artifacts/artifact-lint-service.js +102 -27
  24. package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
  25. package/dist/services/artifacts/artifact-prerequisites.js +13 -13
  26. package/dist/services/artifacts/artifact-template-bodies.d.ts +7 -1
  27. package/dist/services/artifacts/artifact-template-bodies.js +14 -3
  28. package/dist/services/artifacts/artifact-templates.d.ts +6 -1
  29. package/dist/services/artifacts/artifact-templates.js +8 -5
  30. package/dist/services/artifacts/backcompat-acceptance.js +7 -5
  31. package/dist/services/artifacts/prerequisite-checks.d.ts +34 -9
  32. package/dist/services/artifacts/prerequisite-checks.js +28 -9
  33. package/dist/services/artifacts/qa-initiated-marker.d.ts +24 -0
  34. package/dist/services/artifacts/qa-initiated-marker.js +36 -0
  35. package/dist/services/artifacts/request-artifact-metadata.d.ts +9 -0
  36. package/dist/services/artifacts/request-artifact-metadata.js +9 -0
  37. package/dist/services/artifacts/request-artifact-service.js +6 -10
  38. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +2 -1
  39. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -3
  40. package/dist/services/code/job-shape-provisional.d.ts +51 -0
  41. package/dist/services/code/job-shape-provisional.js +80 -0
  42. package/dist/services/code/step-08-gate.d.ts +24 -12
  43. package/dist/services/code/step-08-gate.js +54 -97
  44. package/dist/services/code/step-08-session-readers.d.ts +27 -0
  45. package/dist/services/code/step-08-session-readers.js +105 -0
  46. package/dist/services/dispatch/isolation-lease.d.ts +3 -2
  47. package/dist/services/dispatch/isolation-lease.js +15 -6
  48. package/dist/services/job/subagent-job-wrapper.d.ts +20 -7
  49. package/dist/services/job/subagent-job-wrapper.js +53 -5
  50. package/dist/services/lint/eslint-report.d.ts +19 -0
  51. package/dist/services/lint/eslint-report.js +60 -0
  52. package/dist/services/lint/eslint-runner-support.d.ts +18 -1
  53. package/dist/services/lint/eslint-runner-support.js +35 -2
  54. package/dist/services/lint/eslint-runner-types.d.ts +21 -1
  55. package/dist/services/lint/eslint-runner.js +43 -33
  56. package/dist/services/prd/gate-evidence-derivation.d.ts +2 -4
  57. package/dist/services/prd/gate-evidence-derivation.js +3 -1
  58. package/dist/services/qa/bdd-test-style-contract.d.ts +17 -0
  59. package/dist/services/qa/bdd-test-style-contract.js +41 -0
  60. package/dist/services/qa/bdd-test-style-verifier.d.ts +9 -6
  61. package/dist/services/qa/bdd-test-style-verifier.js +24 -37
  62. package/dist/services/rd/reviewer-dispatch-policy.d.ts +18 -14
  63. package/dist/services/rd/reviewer-dispatch-policy.js +14 -11
  64. package/dist/services/release/release-state.js +20 -5
  65. package/dist/services/reviewer/model-family.js +1 -1
  66. package/dist/services/reviewer/reviewer-artifacts.d.ts +12 -0
  67. package/dist/services/reviewer/reviewer-artifacts.js +67 -0
  68. package/dist/services/reviewer/reviewer-config-write.d.ts +18 -0
  69. package/dist/services/reviewer/reviewer-config-write.js +71 -0
  70. package/dist/services/reviewer/reviewer-config.d.ts +33 -5
  71. package/dist/services/reviewer/reviewer-config.js +102 -46
  72. package/dist/services/reviewer/reviewer-envelopes.d.ts +8 -0
  73. package/dist/services/reviewer/reviewer-envelopes.js +53 -0
  74. package/dist/services/reviewer/reviewer-service.d.ts +7 -4
  75. package/dist/services/reviewer/reviewer-service.js +46 -52
  76. package/dist/services/reviewer/reviewer-types.d.ts +9 -1
  77. package/dist/services/session/getSessionDir.js +16 -7
  78. package/dist/services/web/daemon-registry.d.ts +6 -4
  79. package/dist/services/web/daemon-registry.js +92 -17
  80. package/package.json +5 -5
  81. package/schemas/reviewer-envelope.schema.json +1 -1
  82. package/skills/bee/peaks-reviewer/SKILL.md +20 -4
  83. package/skills/bee/peaks-reviewer/references/reviewer-schema.md +12 -7
  84. package/skills/bee/peaks-security-audit/SKILL.md +20 -0
  85. package/skills/peaks-code/references/step-0-8-gate.md +2 -1
@@ -2,10 +2,9 @@ import { mkdirSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
4
4
  import { fail, ok } from 'peaks-loop-shared/result';
5
- import { CLI_VERSION } from 'peaks-loop-shared/version';
6
- import { repoRelativeKey } from '../../shared/path-utils.js';
7
5
  import { detectEslint } from '../../services/lint/detect-eslint.js';
8
- import { resolveProjectRoot, runEslint } from '../../services/lint/eslint-runner.js';
6
+ import { runEslint } from '../../services/lint/eslint-runner.js';
7
+ import { emitBaseline } from './lint-baseline-command.js';
9
8
  function parseTimeoutMs(value) {
10
9
  if (value === undefined)
11
10
  return undefined;
@@ -15,28 +14,6 @@ function parseTimeoutMs(value) {
15
14
  }
16
15
  return parsed;
17
16
  }
18
- function writeBaselineJson(projectRoot, baselineFile, result) {
19
- const fullPath = join(projectRoot, baselineFile);
20
- mkdirSync(dirname(fullPath), { recursive: true });
21
- // Write the SAME key the reader matches on. Writing ESLint's absolute
22
- // `filePath` here is what re-rooted the file on whichever machine ran
23
- // the command, so the next checkout inherited keys it could not match.
24
- const violations = result.findings.map((f) => ({
25
- ruleId: f.ruleId,
26
- file: repoRelativeKey(f.filePath, projectRoot),
27
- line: f.line,
28
- severity: f.severity,
29
- message: f.message
30
- }));
31
- const payload = {
32
- version: 1,
33
- generatedAt: new Date().toISOString(),
34
- toolVersion: `peaks-loop-${CLI_VERSION}`,
35
- violations
36
- };
37
- writeFileSync(fullPath, JSON.stringify(payload, null, 2), 'utf8');
38
- return { path: fullPath, violations: violations.length };
39
- }
40
17
  function writeRedLineSummary(cwd, result) {
41
18
  const fullPath = join(cwd, '.peaks/memory/lint-redline-summary.md');
42
19
  mkdirSync(dirname(fullPath), { recursive: true });
@@ -69,6 +46,24 @@ function writeRedLineSummary(cwd, result) {
69
46
  writeFileSync(fullPath, lines.join('\n'), 'utf8');
70
47
  return { path: fullPath, ruleIds: result.redLine.map((r) => r.ruleId) };
71
48
  }
49
+ function checkRunOptions(options, cwd, timeoutMs) {
50
+ return {
51
+ cwd,
52
+ ...(options.scope !== undefined ? { scope: options.scope } : {}),
53
+ ...(options.config !== undefined ? { configPath: options.config } : {}),
54
+ ...(options.baselineFile !== undefined ? { baselineFile: options.baselineFile } : {}),
55
+ ...(options.allowEmpty === true ? { allowEmpty: true } : {}),
56
+ ...(timeoutMs !== undefined ? { timeoutMs } : {})
57
+ };
58
+ }
59
+ /** §2.41: an opted-in empty population still warns instead of reading green. */
60
+ function populationWarnings(result) {
61
+ if (result.checkedFiles !== 0)
62
+ return [];
63
+ return [
64
+ 'checkedFiles=0 — the requested scope examined no files, so its finding count says nothing (--allow-empty opted in).'
65
+ ];
66
+ }
72
67
  export function registerLintCommands(program, io) {
73
68
  const lint = program
74
69
  .command('lint')
@@ -92,7 +87,8 @@ export function registerLintCommands(program, io) {
92
87
  .option('--config <path>', 'explicit ESLint config path')
93
88
  .option('--timeout-ms <ms>', 'subprocess timeout in milliseconds (default 60000)')
94
89
  .option('--baseline-file <path>', 'baseline JSON path (default .peaks/lint/baseline.json)')
95
- .option('--red-line', 'also write .peaks/memory/lint-redline-summary.md')).action((options) => {
90
+ .option('--red-line', 'also write .peaks/memory/lint-redline-summary.md')
91
+ .option('--allow-empty', 'accept a scope that examined 0 files instead of refusing it')).action((options) => {
96
92
  let timeoutMs;
97
93
  try {
98
94
  timeoutMs = parseTimeoutMs(options.timeoutMs);
@@ -102,20 +98,13 @@ export function registerLintCommands(program, io) {
102
98
  return;
103
99
  }
104
100
  const cwd = process.cwd();
105
- const runOptions = {
106
- cwd,
107
- ...(options.scope !== undefined ? { scope: options.scope } : {}),
108
- ...(options.configPath !== undefined ? { configPath: options.configPath } : {}),
109
- ...(options.baselineFile !== undefined ? { baselineFile: options.baselineFile } : {}),
110
- ...(timeoutMs !== undefined ? { timeoutMs } : {})
111
- };
112
- const result = runEslint(runOptions);
101
+ const result = runEslint(checkRunOptions(options, cwd, timeoutMs));
113
102
  const extras = {};
114
103
  if (options.redLine === true) {
115
104
  extras.redLineSummary = writeRedLineSummary(cwd, result);
116
105
  }
117
106
  const envelope = result.state === 'ok' || result.state === 'baseline-missing'
118
- ? ok('code.lint', { ...result, ...extras }, [], [])
107
+ ? ok('code.lint', { ...result, ...extras }, populationWarnings(result), [])
119
108
  : fail('code.lint', result.state.toUpperCase().replace(/-/g, '_'), `peaks code lint state: ${result.state}${result.reason === undefined ? '' : ` — ${result.reason}`}`, { ...result, ...extras }, [
120
109
  'The reason above names which condition fired; a spawn timeout wants a larger --timeout-ms.'
121
110
  ]);
@@ -127,7 +116,8 @@ export function registerLintCommands(program, io) {
127
116
  .option('--scope <path>', 'lint scope (default: project root)')
128
117
  .option('--config <path>', 'explicit ESLint config path')
129
118
  .option('--timeout-ms <ms>', 'subprocess timeout in milliseconds (default 60000)')
130
- .option('--baseline-file <path>', 'baseline JSON output path (default .peaks/lint/baseline.json)')).action((options) => {
119
+ .option('--baseline-file <path>', 'baseline JSON path, read for existing waivers and written with the scan (default .peaks/lint/baseline.json)')
120
+ .option('--allow-empty', 'accept a scope that examined 0 files instead of refusing it')).action((options) => {
131
121
  let timeoutMs;
132
122
  try {
133
123
  timeoutMs = parseTimeoutMs(options.timeoutMs);
@@ -136,20 +126,6 @@ export function registerLintCommands(program, io) {
136
126
  printResult(io, fail('code.lint.baseline', 'INVALID_TIMEOUT', getErrorMessage(error), { state: 'execution-failed' }, ['Re-run with --timeout-ms <positive integer>.']), options.json);
137
127
  return;
138
128
  }
139
- const cwd = process.cwd();
140
- const runOptions = {
141
- cwd,
142
- diffOnly: false,
143
- ...(options.scope !== undefined ? { scope: options.scope } : {}),
144
- ...(options.configPath !== undefined ? { configPath: options.configPath } : {}),
145
- ...(timeoutMs !== undefined ? { timeoutMs } : {})
146
- };
147
- const result = runEslint(runOptions);
148
- const baselineFile = options.baselineFile ?? '.peaks/lint/baseline.json';
149
- const written = writeBaselineJson(resolveProjectRoot(cwd), baselineFile, result);
150
- const envelope = ok('code.lint.baseline', { state: result.state, findings: result.findings.length, ...written }, [], [
151
- 'Commit baseline.json (or .gitignore it). Peak-loop ships its own baseline as a reference fixture.'
152
- ]);
153
- printResult(io, envelope, options.json);
129
+ emitBaseline(io, options, timeoutMs);
154
130
  });
155
131
  }
@@ -49,6 +49,12 @@ export type RequestLintOptions = {
49
49
  sessionId?: string;
50
50
  json?: boolean;
51
51
  };
52
+ export type RequestMarkQaInitiatedOptions = {
53
+ project: string;
54
+ /** Restrict the artifact lookup to one session; omitted, the artifact's own session is used. */
55
+ sessionId?: string;
56
+ json?: boolean;
57
+ };
52
58
  export type RequestRepairStatusOptions = {
53
59
  project: string;
54
60
  sessionId?: string;
@@ -1,4 +1,5 @@
1
1
  import { registerRequestInitCommand } from './request-init-command.js';
2
+ import { registerRequestMarkQaInitiatedCommand } from './request-mark-qa-initiated-command.js';
2
3
  import { registerRequestListCommand } from './request-list-command.js';
3
4
  import { registerRequestShowCommand } from './request-show-command.js';
4
5
  import { registerRequestRetagCommand } from './request-retag-command.js';
@@ -12,6 +13,7 @@ const REQUEST_DESCRIPTION = 'Manage per-request Peaks role artifacts (PRD / UI /
12
13
  export function registerRequestCommands(program, io) {
13
14
  const request = program.command('request').description(REQUEST_DESCRIPTION);
14
15
  registerRequestInitCommand(request, io);
16
+ registerRequestMarkQaInitiatedCommand(request, io);
15
17
  registerRequestListCommand(request, io);
16
18
  registerRequestShowCommand(request, io);
17
19
  registerRequestRetagCommand(request, io);
@@ -0,0 +1,3 @@
1
+ import type { Command } from 'commander';
2
+ import { type ProgramIO } from '../cli-helpers.js';
3
+ export declare function registerRequestMarkQaInitiatedCommand(request: Command, io: ProgramIO): void;
@@ -0,0 +1,80 @@
1
+ import { fail, ok } from 'peaks-loop-shared/result';
2
+ import { markQaInitiated } from '../../services/artifacts/qa-initiated-marker.js';
3
+ import { showRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
4
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
5
+ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
6
+ const MARK_DESCRIPTION = 'Create the qa/.initiated marker for a session whose QA request artifact already exists. Idempotent: a second call changes nothing, and the request artifact is never touched.';
7
+ const MARK_REQUEST_ID_HELP = 'request id of the existing QA artifact';
8
+ const MARK_PROJECT_HELP = 'target project root';
9
+ const MARK_SESSION_HELP = 'restrict the artifact lookup to a specific session id';
10
+ function failMark(io, json, failure) {
11
+ printResult(io, fail('request.mark-qa-initiated', failure.code, failure.message, failure.data, failure.nextActions), json);
12
+ process.exitCode = 1;
13
+ }
14
+ /**
15
+ * The artifact is the anchor: the marker lands in THAT artifact's session, so
16
+ * a caller who omits `--session-id` cannot mark a different session by
17
+ * accident. A missing artifact refuses rather than writing the marker, because
18
+ * then nothing records that QA was ever invoked.
19
+ */
20
+ async function findQaArtifact(requestId, options) {
21
+ const showOptions = {
22
+ projectRoot: options.project,
23
+ role: 'qa',
24
+ requestId
25
+ };
26
+ if (options.sessionId !== undefined)
27
+ showOptions.sessionId = options.sessionId;
28
+ return await showRequestArtifact(showOptions);
29
+ }
30
+ function artifactMissingFailure(requestId, options) {
31
+ return {
32
+ code: 'QA_ARTIFACT_MISSING',
33
+ message: `No QA request artifact found for requestId=${requestId}; the marker records that the artifact already exists`,
34
+ data: { requestId },
35
+ nextActions: [
36
+ `Run \`peaks request init --role qa --id ${requestId} --project ${options.project} --apply\` to create the artifact and the marker together`
37
+ ]
38
+ };
39
+ }
40
+ async function runRequestMarkQaInitiated(requestId, options, io) {
41
+ try {
42
+ if (options.sessionId !== undefined && isUnsafePathInput(options.sessionId)) {
43
+ failMark(io, options.json, {
44
+ code: 'INVALID_SESSION_ID',
45
+ message: `Invalid session id: ${options.sessionId} (must be a single path segment)`,
46
+ data: { provided: options.sessionId },
47
+ nextActions: ['Pass a session id that is a single path segment']
48
+ });
49
+ return;
50
+ }
51
+ const artifact = await findQaArtifact(requestId, options);
52
+ if (artifact === null) {
53
+ failMark(io, options.json, artifactMissingFailure(requestId, options));
54
+ return;
55
+ }
56
+ const result = await markQaInitiated({
57
+ projectRoot: options.project,
58
+ sessionId: artifact.sessionId
59
+ });
60
+ printResult(io, ok('request.mark-qa-initiated', { requestId, sessionId: artifact.sessionId, path: result.path, created: result.created }, [], result.created ? [] : [`qa/.initiated already existed at ${result.path}; nothing changed`]), options.json);
61
+ }
62
+ catch (error) {
63
+ failMark(io, options.json, {
64
+ code: 'REQUEST_MARK_QA_INITIATED_FAILED',
65
+ message: getErrorMessage(error),
66
+ data: { requestId },
67
+ nextActions: [
68
+ 'Verify the project path, session id, and the existing QA artifact before retrying'
69
+ ]
70
+ });
71
+ }
72
+ }
73
+ export function registerRequestMarkQaInitiatedCommand(request, io) {
74
+ addJsonOption(request
75
+ .command('mark-qa-initiated')
76
+ .description(MARK_DESCRIPTION)
77
+ .argument('<request-id>', MARK_REQUEST_ID_HELP)
78
+ .requiredOption('--project <path>', MARK_PROJECT_HELP)
79
+ .option('--session-id <session>', MARK_SESSION_HELP)).action((requestId, options) => runRequestMarkQaInitiated(requestId, options, io));
80
+ }
@@ -56,6 +56,7 @@ function reportLintGateFailure(io, options, error) {
56
56
  printResult(io, fail('request.transition', error.code, error.message, {
57
57
  role: error.role,
58
58
  newState: error.newState,
59
+ path: error.path,
59
60
  errorCount: error.errorCount,
60
61
  findings: error.findings
61
62
  }, [
@@ -1,13 +1,13 @@
1
1
  /**
2
- * `peaks reviewer run` / `peaks reviewer status` — CLI surface for the
3
- * G4 third-party reviewer. v2.14.0.
2
+ * `peaks reviewer run|status` — CLI surface for the G4 third-party reviewer.
3
+ * `peaks reviewer config` lives in reviewer-config-commands.ts (file-size cap).
4
4
  *
5
- * peaks reviewer run --rid <rid> [--json]
6
- * peaks reviewer status [--json]
5
+ * peaks reviewer run --rid <rid> [--write] [--session-id <id>] [--project <path>] [--json]
6
+ * peaks reviewer status [--project <path>] [--json]
7
7
  *
8
8
  * The CLI never silently prompts for API keys. When `~/.peaks/config.json`
9
- * has no `reviewer` section, both commands emit a structured skip envelope
10
- * and exit 0 (consistent with A4.3 fallbackOnError=skip).
9
+ * has no usable `reviewer` section, `run` emits the skip envelope (which is
10
+ * NOT a pass) and exits 0, consistent with fallbackOnError=skip.
11
11
  */
12
12
  import type { Command } from 'commander';
13
13
  import { type ProgramIO } from '../cli-helpers.js';
@@ -1,64 +1,162 @@
1
- import { runReviewer, REVIEWER_ID } from '../../services/reviewer/reviewer-service.js';
2
- import { loadReviewerConfig } from '../../services/reviewer/reviewer-config.js';
1
+ import { runReviewer } from '../../services/reviewer/reviewer-service.js';
2
+ import { defaultReviewerConfigPath, loadReviewerConfig, MIN_REVIEWER_PROVIDERS, resolveReviewerSchema } from '../../services/reviewer/reviewer-config.js';
3
+ import { DISPATCHABLE_PROVIDER_NAMES } from '../../services/reviewer/reviewer-config-write.js';
4
+ import { writeReviewerArtifacts } from '../../services/reviewer/reviewer-artifacts.js';
3
5
  import { deriveModelFamily } from '../../services/reviewer/model-family.js';
4
- import { addJsonOption, printResult } from '../cli-helpers.js';
6
+ import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
7
+ import { readActiveSid } from './code-runtime-session.js';
8
+ import { registerReviewerConfigCommand } from './reviewer-config-commands.js';
9
+ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
5
10
  import { fail, ok } from 'peaks-loop-shared/result';
6
- export function registerReviewerCommands(program, io) {
7
- const reviewer = program
8
- .command('reviewer')
9
- .description('Third-party reviewer (v2.14.0 G4 anti-fake-green) — runs an out-of-band model on the slice and emits a schema-validated ReviewerEnvelope.');
10
- addJsonOption(reviewer
11
- .command('run')
12
- .description('Run the configured third-party reviewer on a slice.')
13
- .option('--rid <rid>', 'request id (slice) to review')).action(async (options) => {
14
- const rid = options.rid ?? '';
15
- if (rid.length === 0) {
16
- printResult(io, fail('reviewer.run', 'MISSING_RID', '--rid is required', null), options.json === true);
17
- process.exitCode = 2;
18
- return;
19
- }
20
- const status = loadReviewerConfig();
21
- if (!status.ok) {
22
- const envelope = {
23
- reviewerId: REVIEWER_ID,
24
- modelId: 'skipped',
25
- modelFamily: 'skipped',
26
- passed: true,
27
- violations: [],
28
- gateAction: 'allow',
29
- reason: 'skipped: no-reviewer-config (fallbackOnError=skip)'
30
- };
31
- printResult(io, ok('reviewer.run', { envelope, reason: status.reason }), options.json === true);
11
+ function isJson(options) {
12
+ return options.json === true;
13
+ }
14
+ function printRunFailure(io, options, code, message, nextActions) {
15
+ printResult(io, fail('reviewer.run', code, message, null, nextActions), isJson(options));
16
+ }
17
+ async function handleRun(options, io) {
18
+ const rid = options.rid ?? '';
19
+ if (rid.length === 0) {
20
+ printRunFailure(io, options, 'MISSING_RID', '--rid is required', []);
21
+ process.exitCode = 2;
22
+ return;
23
+ }
24
+ const projectRoot = resolveCanonicalProjectRoot(options.project ?? process.cwd());
25
+ const result = await runReviewer({
26
+ rid,
27
+ context: `rid=${rid}`,
28
+ projectRoot,
29
+ ...(options.config !== undefined ? { configPath: options.config } : {})
30
+ });
31
+ if (!result.ok) {
32
+ if (result.reason === 'schema-missing') {
33
+ printRunFailure(io, options, 'SCHEMA_MISSING', `Reviewer schema not found; searched: ${(result.schemaCandidates ?? []).join(', ')}`, ['Fix the reviewer config schemaPath or place the schema at one of the searched paths.']);
34
+ process.exitCode = 1;
32
35
  return;
33
36
  }
34
- const result = await runReviewer({ rid, context: `rid=${rid}` });
35
- if (result.ok) {
36
- printResult(io, ok('reviewer.run', { envelope: result.envelope }), options.json === true);
37
- return;
37
+ printConfigSkip(result, options, io);
38
+ return;
39
+ }
40
+ if (options.write !== true) {
41
+ printResult(io, ok('reviewer.run', { envelope: result.envelope }), isJson(options));
42
+ return;
43
+ }
44
+ if (result.skipped) {
45
+ printResult(io, ok('reviewer.run', {
46
+ envelope: result.envelope,
47
+ written: false,
48
+ writeSkippedReason: result.envelope.reason
49
+ }), isJson(options));
50
+ return;
51
+ }
52
+ writeArtifacts(result.envelope, rid, { projectRoot, options }, io);
53
+ }
54
+ function printConfigSkip(result, options, io) {
55
+ const data = options.write === true
56
+ ? {
57
+ envelope: result.envelope,
58
+ reason: result.reason,
59
+ written: false,
60
+ writeSkippedReason: result.envelope.reason
38
61
  }
39
- printResult(io, fail('reviewer.run', 'NO_REVIEWER_CONFIG', result.reason, null), options.json === true);
40
- });
62
+ : { envelope: result.envelope, reason: result.reason };
63
+ printResult(io, ok('reviewer.run', data, [], [
64
+ `Configure the reviewer with: peaks reviewer config --provider <name:model> --provider <name:model>`
65
+ ]), isJson(options));
66
+ }
67
+ function writeArtifacts(envelope, rid, context, io) {
68
+ const { projectRoot, options } = context;
69
+ const sessionId = options.sessionId ?? readActiveSid(projectRoot) ?? '';
70
+ if (sessionId.length === 0) {
71
+ printResult(io, fail('reviewer.run', 'MISSING_SESSION_ID', '--write needs an active session id; pass --session-id <id>', { envelope }, ['Re-run with --session-id <sessionId>']), isJson(options));
72
+ process.exitCode = 1;
73
+ return;
74
+ }
75
+ try {
76
+ printResult(io, ok('reviewer.run', {
77
+ envelope,
78
+ written: true,
79
+ artifacts: writeReviewerArtifacts({ projectRoot, sessionId, rid, envelope })
80
+ }), isJson(options));
81
+ }
82
+ catch (error) {
83
+ printResult(io, fail('reviewer.run', 'ARTIFACT_WRITE_FAILED', getErrorMessage(error), { envelope }), isJson(options));
84
+ process.exitCode = 1;
85
+ }
86
+ }
87
+ function registerRunCommand(reviewer, io) {
88
+ addJsonOption(reviewer
89
+ .command('run')
90
+ .description('Run the configured third-party reviewer on a slice.')
91
+ .option('--rid <rid>', 'request id (slice) to review')
92
+ .option('--write', 'write rd/third-party-review-<rid>.md + .json under the session runtime')
93
+ .option('--session-id <id>', 'session id for --write (defaults to the active session)')
94
+ .option('--project <path>', 'project root for schema resolution and --write (promotes to the git root)')
95
+ .option('--config <path>', 'reviewer config path (defaults to ~/.peaks/config.json)')).action((options) => handleRun(options, io));
96
+ }
97
+ function unconfiguredData(status, path) {
98
+ return {
99
+ configured: false,
100
+ state: status.reason === 'insufficient-providers' ? 'insufficient-providers' : 'no-section',
101
+ reason: status.reason,
102
+ configPath: path,
103
+ providerCount: status.providerCount,
104
+ requiredProviders: status.requiredProviders
105
+ };
106
+ }
107
+ function unconfiguredActions(status, path) {
108
+ const first = status.reason === 'insufficient-providers'
109
+ ? `Only ${String(status.providerCount)} valid provider(s); at least ${String(status.requiredProviders)} are required. Add one with: peaks reviewer config --provider <name:model>`
110
+ : `No reviewer section at ${path}. Write one with: peaks reviewer config --provider <name:model> --provider <name:model>`;
111
+ return [first, `Accepted providers: ${DISPATCHABLE_PROVIDER_NAMES.join(', ')}.`];
112
+ }
113
+ function configuredData(config, path, projectRoot) {
114
+ const families = config.providers.map((p) => ({
115
+ name: p.name,
116
+ model: p.model,
117
+ modelFamily: deriveModelFamily(p.model).modelFamily
118
+ }));
119
+ const schema = resolveReviewerSchema(projectRoot, config.schemaPath);
120
+ return {
121
+ configured: true,
122
+ state: 'configured',
123
+ configPath: path,
124
+ providerCount: families.length,
125
+ requiredProviders: MIN_REVIEWER_PROVIDERS,
126
+ selection: config.selection,
127
+ requireDistinctModelFamily: config.requireDistinctModelFamily,
128
+ fallbackOnError: config.fallbackOnError,
129
+ schemaPath: config.schemaPath,
130
+ schemaPathExists: schema.ok,
131
+ schemaPathSource: schema.ok ? schema.source : null,
132
+ schemaPathResolved: schema.ok ? schema.path : null,
133
+ rdProviderName: config.rdProviderName,
134
+ providers: families
135
+ };
136
+ }
137
+ function handleStatus(options, io) {
138
+ const path = options.config ?? defaultReviewerConfigPath();
139
+ // Same promotion as `run`: the diagnostic must agree with the run decision.
140
+ const projectRoot = resolveCanonicalProjectRoot(options.project ?? process.cwd());
141
+ const status = loadReviewerConfig(options.config !== undefined ? { path } : {});
142
+ if (!status.ok) {
143
+ printResult(io, ok('reviewer.status', unconfiguredData(status, path), [], unconfiguredActions(status, path)), isJson(options));
144
+ return;
145
+ }
146
+ printResult(io, ok('reviewer.status', configuredData(status.config, path, projectRoot)), isJson(options));
147
+ }
148
+ function registerStatusCommand(reviewer, io) {
41
149
  addJsonOption(reviewer
42
150
  .command('status')
43
- .description('Show whether the reviewer is configured and which selection mode + provider families are active.')).action((options) => {
44
- const status = loadReviewerConfig();
45
- if (!status.ok) {
46
- printResult(io, ok('reviewer.status', { configured: false, reason: status.reason }), options.json === true);
47
- return;
48
- }
49
- const families = status.config.providers.map((p) => ({
50
- name: p.name,
51
- model: p.model,
52
- modelFamily: deriveModelFamily(p.model).modelFamily
53
- }));
54
- printResult(io, ok('reviewer.status', {
55
- configured: true,
56
- selection: status.config.selection,
57
- requireDistinctModelFamily: status.config.requireDistinctModelFamily,
58
- fallbackOnError: status.config.fallbackOnError,
59
- schemaPath: status.config.schemaPath,
60
- rdProviderName: status.config.rdProviderName,
61
- providers: families
62
- }), options.json === true);
63
- });
151
+ .description('Show whether the reviewer is configured and which selection mode + provider families are active.')
152
+ .option('--config <path>', 'reviewer config path (defaults to ~/.peaks/config.json)')
153
+ .option('--project <path>', 'project root for schema resolution (promotes to the git root)')).action((options) => handleStatus(options, io));
154
+ }
155
+ export function registerReviewerCommands(program, io) {
156
+ const reviewer = program
157
+ .command('reviewer')
158
+ .description('Third-party reviewer (v2.14.0 G4 anti-fake-green) — runs an out-of-band model on the slice and emits a schema-validated ReviewerEnvelope.');
159
+ registerReviewerConfigCommand(reviewer, io);
160
+ registerRunCommand(reviewer, io);
161
+ registerStatusCommand(reviewer, io);
64
162
  }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * `peaks reviewer config` — write the `reviewer` section on the user's behalf.
3
+ * Split out of reviewer-commands.ts for the 300-line file-size cap.
4
+ *
5
+ * The LLM runs this; the user never hand-authors JSON (backlog §7.10 ①).
6
+ */
7
+ import type { Command } from 'commander';
8
+ import { type ProgramIO } from '../cli-helpers.js';
9
+ export declare function registerReviewerConfigCommand(reviewer: Command, io: ProgramIO): void;
@@ -0,0 +1,133 @@
1
+ import { defaultReviewerConfigPath, loadReviewerConfig, MIN_REVIEWER_PROVIDERS } from '../../services/reviewer/reviewer-config.js';
2
+ import { DISPATCHABLE_PROVIDER_NAMES, parseProviderSpec, validateReviewerSection, writeReviewerConfig } from '../../services/reviewer/reviewer-config-write.js';
3
+ import { addJsonOption, printResult } from '../cli-helpers.js';
4
+ import { fail, ok } from 'peaks-loop-shared/result';
5
+ const SELECTIONS = ['round-robin', 'hash', 'random'];
6
+ const FALLBACKS = ['skip', 'error'];
7
+ function collect(value, previous) {
8
+ return [...previous, value];
9
+ }
10
+ function isSelection(value) {
11
+ return SELECTIONS.includes(value);
12
+ }
13
+ function isFallback(value) {
14
+ return FALLBACKS.includes(value);
15
+ }
16
+ /** `undefined` when the flag was absent; `null` when it is not a boolean. */
17
+ function parseBooleanFlag(value) {
18
+ if (value === undefined)
19
+ return undefined;
20
+ if (value === 'true')
21
+ return true;
22
+ if (value === 'false')
23
+ return false;
24
+ return null;
25
+ }
26
+ function parseProviderFlags(options) {
27
+ const providers = [];
28
+ for (const spec of options.provider ?? []) {
29
+ const parsed = parseProviderSpec(spec);
30
+ if (parsed === null) {
31
+ return {
32
+ code: 'INVALID_PROVIDER_SPEC',
33
+ message: `--provider expects <name:model>; got "${spec}"`,
34
+ nextActions: [`Accepted providers: ${DISPATCHABLE_PROVIDER_NAMES.join(', ')}`]
35
+ };
36
+ }
37
+ providers.push(parsed);
38
+ }
39
+ return { providers };
40
+ }
41
+ function parseModeFlags(options, status) {
42
+ const selection = options.selection ?? (status.ok ? status.config.selection : 'round-robin');
43
+ if (!isSelection(selection)) {
44
+ return {
45
+ code: 'INVALID_SELECTION',
46
+ message: `--selection must be one of ${SELECTIONS.join(', ')}`,
47
+ nextActions: []
48
+ };
49
+ }
50
+ const fallbackOnError = options.fallbackOnError ?? (status.ok ? status.config.fallbackOnError : 'skip');
51
+ if (!isFallback(fallbackOnError)) {
52
+ return {
53
+ code: 'INVALID_FALLBACK',
54
+ message: `--fallback-on-error must be one of ${FALLBACKS.join(', ')}`,
55
+ nextActions: []
56
+ };
57
+ }
58
+ const distinct = parseBooleanFlag(options.requireDistinctModelFamily);
59
+ if (distinct === null) {
60
+ return {
61
+ code: 'INVALID_DISTINCT_FLAG',
62
+ message: '--require-distinct-model-family must be true or false',
63
+ nextActions: []
64
+ };
65
+ }
66
+ return {
67
+ selection,
68
+ fallbackOnError,
69
+ requireDistinctModelFamily: distinct ?? (status.ok ? status.config.requireDistinctModelFamily : true)
70
+ };
71
+ }
72
+ function buildSection(options, status, providers, modes) {
73
+ return {
74
+ providers: providers.length > 0 ? providers : status.ok ? [...status.config.providers] : [],
75
+ selection: modes.selection,
76
+ rdProviderName: options.rdProviderName ?? (status.ok ? status.config.rdProviderName : null),
77
+ requireDistinctModelFamily: modes.requireDistinctModelFamily,
78
+ fallbackOnError: modes.fallbackOnError,
79
+ schemaPath: options.schemaPath ??
80
+ (status.ok ? status.config.schemaPath : 'schemas/reviewer-envelope.schema.json')
81
+ };
82
+ }
83
+ function printConfigFailure(io, options, failure, exitCode) {
84
+ printResult(io, fail('reviewer.config', failure.code, failure.message, null, failure.nextActions), options.json === true);
85
+ process.exitCode = exitCode;
86
+ }
87
+ function invalidSectionFailure(message) {
88
+ return {
89
+ code: 'REVIEWER_CONFIG_INVALID',
90
+ message,
91
+ nextActions: [
92
+ 'Add providers with: peaks reviewer config --provider <name:model> --provider <name:model>'
93
+ ]
94
+ };
95
+ }
96
+ function handleConfigAction(options, io) {
97
+ const path = options.config ?? defaultReviewerConfigPath();
98
+ const status = loadReviewerConfig(options.config !== undefined ? { path } : {});
99
+ const providersResult = parseProviderFlags(options);
100
+ if ('code' in providersResult) {
101
+ printConfigFailure(io, options, providersResult, 2);
102
+ return;
103
+ }
104
+ const modes = parseModeFlags(options, status);
105
+ if ('code' in modes) {
106
+ printConfigFailure(io, options, modes, 2);
107
+ return;
108
+ }
109
+ const section = buildSection(options, status, providersResult.providers, modes);
110
+ const invalid = validateReviewerSection(section);
111
+ if (invalid !== null) {
112
+ printConfigFailure(io, options, invalidSectionFailure(invalid), 2);
113
+ return;
114
+ }
115
+ const written = writeReviewerConfig(section, options.config !== undefined ? { path } : {});
116
+ if (!written.ok) {
117
+ printConfigFailure(io, options, { code: 'REVIEWER_CONFIG_UNREADABLE', message: written.message, nextActions: [] }, 1);
118
+ return;
119
+ }
120
+ printResult(io, ok('reviewer.config', { path: written.path, reviewer: section }, [], ['Run `peaks reviewer status` to confirm the section is active.']), options.json === true);
121
+ }
122
+ export function registerReviewerConfigCommand(reviewer, io) {
123
+ addJsonOption(reviewer
124
+ .command('config')
125
+ .description('Write the `reviewer` section to the user config without hand-authoring JSON (LLM-driven).')
126
+ .option('--provider <name:model>', `provider entry, repeatable; at least ${MIN_REVIEWER_PROVIDERS} required (accepted: ${DISPATCHABLE_PROVIDER_NAMES.join(', ')})`, collect, [])
127
+ .option('--selection <mode>', 'round-robin | hash | random')
128
+ .option('--require-distinct-model-family <true|false>', 'require a family distinct from the RD model')
129
+ .option('--fallback-on-error <mode>', 'skip | error')
130
+ .option('--rd-provider-name <name>', 'name of the RD-side provider, if any')
131
+ .option('--schema-path <path>', 'path to the ReviewerEnvelope schema')
132
+ .option('--config <path>', 'reviewer config path (defaults to ~/.peaks/config.json)')).action((options) => handleConfigAction(options, io));
133
+ }