peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/cli/commands/job-commands.js

@@ -0,0 +1,289 @@
+// src/cli/commands/job-commands.ts
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { writeJobProgress, readJobProgress, tryReadJobProgress } from '../../services/job/job-progress-store.js';
+import { JobRotation } from '../../services/job/job-rotation.js';
+import { SubAgentJobWrapper } from '../../services/job/subagent-job-wrapper.js';
+import { emitJobEvent } from '../../services/job/job-event-emitter.js';
+import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } from '../../services/job/job-types.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+function projectRoot(opts) {
+    // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
+    return opts.project ?? process.cwd();
+}
+/**
+ * Resolves the on-disk root for Job state files.
+ *
+ * Per spec §3.3 + §4.5 (2.7.1 single-scope-axis layout), Job state lives at:
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`
+ *
+ * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
+ * compute the canonical root here (per-call) so the store can stay layout-agnostic.
+ *
+ * Resolution order:
+ * 1. `--session-id` flag (explicit override)
+ * 2. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json` per peaks-code
+ * 3. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ */
+function resolveJobStateRoot(opts) {
+    const project = projectRoot(opts);
+    const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+    if (!sessionId) {
+        throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-code session via peaks workspace init');
+    }
+    const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
+    return { rootDir, sessionId, projectRoot: project };
+}
+export function registerJobCommands(program, io = { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) }) {
+    const job = new Command('job').description('Drive long multi-slice work as one Job (peaks-code Step 0.8+)');
+    job
+        .command('init')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-list <list>')
+        .option('--parallelism-hint <serial|llm-decides>', 'llm-decides')
+        .option('--exit-policy <strict|best-effort>', 'strict')
+        .option('--main-loop-strategy <single|rotating>', 'rotating')
+        .option('--rotate-every <n>', 'rotate every N slices (rotating mode)', '3')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json; required to land in the 2.7.1 single-scope-axis layout)')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const project = projectRoot(opts);
+        // Resolve sessionId: explicit flag > canonical session binding > FAIL.
+        // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
+        // a random UUID would scatter state across dirs and break resume/auto-compact.
+        let sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        if (!sessionId) {
+            return printResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-code session via peaks workspace init)', { project }, [
+                'Re-run with --session-id <sid>',
+                'Or run `peaks workspace init` to create a session first'
+            ]), opts);
+        }
+        const parsed = JobInitInputSchema.safeParse({
+            jobId: opts.jobId,
+            sessionId,
+            sliceList: opts.sliceList.split(',').map((s) => s.trim()).filter(Boolean),
+            parallelismHint: opts.parallelismHint,
+            exitPolicy: opts.exitPolicy,
+            mainLoopStrategy: opts.mainLoopStrategy,
+            rotateEvery: Number(opts.rotateEvery),
+            project,
+            json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.rootDir);
+        const orch = new JobOrchestrator(store);
+        const state = orch.init({
+            jobId: parsed.data.jobId,
+            sessionId: parsed.data.sessionId,
+            sliceList: parsed.data.sliceList,
+            parallelismHint: parsed.data.parallelismHint,
+            exitPolicy: parsed.data.exitPolicy,
+            mainLoopStrategy: parsed.data.mainLoopStrategy,
+            rotateEvery: parsed.data.rotateEvery,
+        });
+        try {
+            emitJobEvent({ kind: 'job-started', jobId: state.jobId, total: state.slices.length, strategy: state.mainLoopStrategy });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job init
+            void e;
+        }
+        printResult(io, ok('init', { jobId: state.jobId, sliceCount: state.slices.length, statePath: `${jobRoot.rootDir}/${state.jobId}/state.json` }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'init'));
+    job
+        .command('status')
+        .requiredOption('--job-id <jid>')
+        .option('--watch', 'poll every 3s')
+        .option('--show-cost', 'overlay cost from peaks budget')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        if (opts.watch) {
+            const draw = () => {
+                const bar = `[${'='.repeat(s.done)}${' '.repeat(s.total - s.done)}]`;
+                process.stdout.write(`\rjob ${opts.jobId}: ${bar} ${s.done}/${s.total}${s.currentSlice ? ` next=${s.currentSlice}` : ''}    `);
+            };
+            draw();
+            const iv = setInterval(() => { const u = orch.status(opts.jobId); Object.assign(s, u); draw(); if (u.done + u.failed + u.skipped + u.blocked >= u.total)
+                clearInterval(iv); }, 3000);
+            process.on('SIGINT', () => { clearInterval(iv); process.stdout.write('\n'); process.exit(0); });
+            return;
+        }
+        try {
+            emitJobEvent({ kind: 'job-progress', jobId: opts.jobId, done: s.done, total: s.total, ...(s.currentSlice ? { currentSlice: s.currentSlice } : {}) });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job status
+            void e;
+        }
+        printResult(io, ok('status', s), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'status'));
+    // M4.2: wire rotate-now to JobRotation (session-rotate callbacks are stubs pending M6.5 batch-fix).
+    job.command('rotate-now')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const rotation = new JobRotation(store, async (_jid) => { /* delegate to peaks session rotate — implementation wired in M6.5 batch-fix */ return { rotated: true }; }, async (jid) => ({ jobId: jid, cycle: 0 }));
+        const r = await rotation.rotateNow(opts.jobId);
+        printResult(io, ok('rotate-now', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'rotate-now'));
+    job.command('subagent-cleanup')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--batch-id <bid>')
+        .option('--force')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts).rootDir), async () => ({ batchId: opts.batchId }));
+        const r = await wrapper.cleanup({ jobId: opts.jobId, batchId: opts.batchId, force: !!opts.force });
+        printResult(io, ok('subagent-cleanup', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'subagent-cleanup'));
+    // M3.2: wire the remaining 5 subcommand slots — block, checkpoint, continue, handoff, resume.
+    job
+        .command('checkpoint')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--state <done|failed|skipped>')
+        .option('--commit-sha <sha>')
+        .option('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobCheckpointInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, state: opts.state,
+            commitSha: opts.commitSha, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.rootDir);
+        const orch = new JobOrchestrator(store);
+        if (parsed.data.state === 'done') {
+            await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
+            // v3.1.2: after each --state done, mirror slice progress to
+            // .peaks/_runtime/<sessionId>/job/<jid>/progress.json so the
+            // next LLM turn (or peaks code gate-step-08 hook) can read it.
+            const project = projectRoot(opts);
+            const sessId = jobRoot.sessionId;
+            const state = orch.status(parsed.data.jobId);
+            writeJobProgress(project, sessId, {
+                jobId: parsed.data.jobId,
+                done: state.done,
+                total: state.total,
+                currentSlice: state.currentSlice ?? `slice-${state.done + 1}`,
+                lastCommitSha: parsed.data.commitSha ?? null,
+                updatedAt: new Date().toISOString()
+            });
+        }
+        else if (parsed.data.state === 'skipped') {
+            await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        else {
+            await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
+    job
+        .command('block')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobBlockInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        await orch.blockSlice(parsed.data);
+        printResult(io, ok('block', { blocked: parsed.data.sliceId, reason: parsed.data.reason }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'block'));
+    job
+        .command('continue')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const r = orch.continueNow(opts.jobId);
+        printResult(io, ok('continue', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'continue'));
+    job
+        .command('resume')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'resume'));
+    // v3.1.2: read the on-disk slice progress mirror written by `peaks
+    // job checkpoint --state done`. Used by peaks code gate-step-08 and
+    // by peaks-code Step 0.7 (resume) to surface `Next: slice #N of M
+    // (<currentSlice>)` without re-deriving from state.json.
+    job
+        .command('progress')
+        .description('v3.1.2: read the on-disk slice progress mirror (.peaks/_runtime/<sid>/job/<jid>/progress.json). ' +
+        'Returns { jobId, done, total, currentSlice, lastCommitSha, updatedAt }.')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .option('--allow-missing', 'return done=0/total=0 envelope instead of failing when progress.json is absent')
+        .action(async (opts) => {
+        try {
+            const jobRoot = resolveJobStateRoot(opts);
+            const sessId = jobRoot.sessionId;
+            const project = projectRoot(opts);
+            const progress = opts.allowMissing === true
+                ? tryReadJobProgress(project, sessId, opts.jobId)
+                : readJobProgress(project, sessId, opts.jobId);
+            if (progress === null) {
+                printResult(io, fail('progress', 'NO_PROGRESS', `No progress.json for job ${opts.jobId} at .peaks/_runtime/${sessId}/job/${opts.jobId}/progress.json`, { jobId: opts.jobId, sessionId: sessId }, [
+                    'Run `peaks job checkpoint --state done ...` at least once to seed progress.json.',
+                    'Or pass --allow-missing to return a zero-progress envelope.'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('progress', progress, [], [
+                `Next: slice #${progress.done + 1} of ${progress.total} (${progress.currentSlice})`
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('progress', 'PROGRESS_READ_FAILED', err instanceof Error ? err.message : String(err), { jobId: opts.jobId }, ['Verify the job id and try again']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'progress'));
+    job
+        .command('handoff')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'handoff'));
+    program.addCommand(job);
+}

package/dist/cli/commands/legacy-commands.d.ts

@@ -0,0 +1,11 @@
+/**
+ * v2.15.0 follow-up — G8: peaks legacy detect CLI.
+ *
+ *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
+ *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
+ *     Useful as a "where to start" inventory when peaks-loop is applied
+ *     to a 存量老项目.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLegacyCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/legacy-commands.js

@@ -0,0 +1,32 @@
+/**
+ * v2.15.0 follow-up — G8: peaks legacy detect CLI.
+ *
+ *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
+ *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
+ *     Useful as a "where to start" inventory when peaks-loop is applied
+ *     to a 存量老项目.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { detectLegacy } from '../../services/legacy/legacy-detector.js';
+import { ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerLegacyCommands(program, io) {
+    addJsonOption(program
+        .command('legacy-detect')
+        .description('v2.15.0 follow-up G8: scan a directory for legacy smells (TODO/FIXME/HACK, ' +
+        'console.log, any-type, large files, ts-ignore). Returns a smell grade ' +
+        '(low / medium / high) and per-kind counts. Lightweight heuristics — ' +
+        'NOT a replacement for a real linter. Useful as a "where to start" ' +
+        'inventory when peaks-loop is applied to a legacy codebase.')
+        .option('--dir <path>', 'directory to scan (default: src)', 'src')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const report = detectLegacy(projectRoot, opts.dir);
+        printResult(io, ok('legacy-detect', { projectRoot, dir: opts.dir, report }, [], [
+            `Scanned ${report.scannedFiles} file(s). Smells: ${report.smells}.`,
+            report.smells === 'high'
+                ? 'Consider refactoring high-smell areas first.'
+                : 'Manageable technical debt.'
+        ]), opts.json ?? false);
+    });
+}

package/dist/cli/commands/log-commands.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `peaks log *` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Two subcommands:
+ *   - `peaks log tail [--lines N]` — print the last N lines of
+ *     today's JSONL log to stdout. With `--json`, prints as a
+ *     JSON envelope (matching the project's response shape).
+ *   - `peaks log ls` — list the available log files (newest first).
+ *
+ * The CLI layer is intentionally thin: it formats the output and
+ * delegates the actual filesystem reads to
+ * `src/services/log/log-commands-service.ts`. That service is
+ * already covered by `tests/unit/log/log-commands.test.ts`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLogCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/log-commands.js

@@ -0,0 +1,64 @@
+/**
+ * `peaks log *` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Two subcommands:
+ *   - `peaks log tail [--lines N]` — print the last N lines of
+ *     today's JSONL log to stdout. With `--json`, prints as a
+ *     JSON envelope (matching the project's response shape).
+ *   - `peaks log ls` — list the available log files (newest first).
+ *
+ * The CLI layer is intentionally thin: it formats the output and
+ * delegates the actual filesystem reads to
+ * `src/services/log/log-commands-service.ts`. That service is
+ * already covered by `tests/unit/log/log-commands.test.ts`.
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { tailLog, listLogFiles } from '../../services/log/log-commands-service.js';
+import { getErrorMessage, printResult, addJsonOption } from '../cli-helpers.js';
+import { ok, fail } from '../../shared/result.js';
+export function registerLogCommands(program, io) {
+    const log = program
+        .command('log')
+        .description('Inspect the peaks-loop JSONL log directory (default: ~/.peaks/logs/)');
+    addJsonOption(log
+        .command('tail')
+        .description('Print the last 50 lines of today\'s peaks-loop log (JSONL). Pass --lines N to change the count, --date YYYY-MM-DD to read a different day, --batch <id> to filter by batchId, --json to print a JSON envelope.')
+        .option('--lines <n>', 'number of lines to show (default 50)', (value) => Number(value))
+        .option('--date <YYYY-MM-DD>', 'read the log for this UTC date instead of today (PRD AC2: PEAKS_LOG_DATE_OVERRIDE)')
+        // Slice 2026-06-23-audit-4th #B2: --batch filter for cross-run
+        // correlation. Without this, a user post-hoc cannot group the
+        // log lines for one batch (they interleave in the JSONL file).
+        .option('--batch <id>', 'filter entries by batchId (sub-agent dispatch / heartbeat / share)')).action((options) => {
+        try {
+            const requestedLines = options.lines ?? 50;
+            const safeLines = Number.isFinite(requestedLines) && requestedLines > 0 ? Math.floor(requestedLines) : 50;
+            const result = tailLog({
+                lines: safeLines,
+                ...(options.date !== undefined ? { dateOverride: options.date } : {}),
+                ...(options.batch !== undefined ? { batchId: options.batch } : {})
+            });
+            printResult(io, ok('log.tail', {
+                file: result.file,
+                total: result.total,
+                lines: safeLines,
+                ...(options.batch !== undefined ? { batch: options.batch, batchMatches: result.batchMatches ?? 0 } : {}),
+                entries: result.entries
+            }, []), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('log.tail', 'LOG_TAIL_FAILED', getErrorMessage(error), {}, ['Check `peaks log ls` to see available log files']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(log
+        .command('ls')
+        .description('List peaks-loop-*.log files in ~/.peaks/logs/ (newest first).')).action((options) => {
+        const files = listLogFiles();
+        printResult(io, ok('log.ls', {
+            logDir: join(homedir(), '.peaks', 'logs'),
+            total: files.length,
+            files
+        }, []), options.json);
+    });
+}

package/dist/cli/commands/loop-commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * peaks loop * CLI (Slice #14 + M7 add).
+ *
+ * Slices:
+ *   #14 sub-features (L4 Agent Loop integration): distill / preflight /
+ *     detect-pattern / check-consistency / peaks goal compose.
+ *
+ *   M7 (2026-07-07 spec §7A.2):
+ *     peaks loop export --loop <id> --out <path.tar.gz>
+ *     peaks loop import --in <path.tar.gz> [--as <loop-id>]
+ *
+ * `peaks loop export` reads the source loop_release + relations +
+ * related bees + evidence briefs and emits a `peaks.bundle/1`
+ * tar.gz. Hard-blocks when the source has `shareable=false`.
+ *
+ * `peaks loop import` extracts a bundle, validates
+ * format_version_major=1, and lands the release as `candidate`
+ * (mandatory landing status per spec §7A.2). The receiver must run
+ * an independent evaluation before promoting to `stable`.
+ *
+ * The existing 14.x commands are kept under the same `loop` parent;
+ * M7 only ADDs export / import — it does not modify the existing
+ * surface.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopCommands(program: Command, io: ProgramIO): void;