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

package/dist/src/cli/commands/workflow-plan-commands.js

@@ -1,163 +0,0 @@
-import { fail, getErrorMessage } from '../../shared/result.js';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-import { readPlan } from '../../services/workflow/plan-reader.js';
-import { refreshPlan } from '../../services/workflow/plan-refresher.js';
-import { detectTrigger } from '../../services/workflow/plan-trigger-detector.js';
-import { getSessionId } from '../../services/session/session-manager.js';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-const VALID_TYPES = ['security', 'perf'];
-// F-1 (slice 025 security): reject session ids that look like path
-// traversal payloads. Canonical pattern is YYYY-MM-DD-<slug>.
-const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
-// F-1 (slice 025 security): reject rids that contain path separators,
-// null bytes, or traversal sequences.
-const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-function isPlanType(value) {
-    return VALID_TYPES.includes(value);
-}
-function isValidSessionId(value) {
-    return SESSION_ID_PATTERN.test(value);
-}
-function isValidRequestId(value) {
-    return REQUEST_ID_PATTERN.test(value);
-}
-function resolveSessionId(io, command, projectRoot, explicit, asJson) {
-    if (explicit !== undefined && explicit.length > 0) {
-        if (!isValidSessionId(explicit)) {
-            printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: explicit }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
-            process.exitCode = 1;
-            return null;
-        }
-        return explicit;
-    }
-    const sid = getSessionId(projectRoot);
-    if (sid === null || sid === undefined) {
-        printResult(io, fail(command, 'NO_ACTIVE_SESSION', 'No active session — pass --session-id explicitly or run peaks workspace init', { projectRoot }, ['Run peaks workspace init or pass --session-id <YYYY-MM-DD-slug>']), asJson === true);
-        process.exitCode = 1;
-        return null;
-    }
-    // Defensive: even active-session resolution must satisfy the pattern.
-    if (!isValidSessionId(sid)) {
-        printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: sid }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
-        process.exitCode = 1;
-        return null;
-    }
-    return sid;
-}
-function resolveProjectRoot(projectArg) {
-    if (projectArg === undefined || projectArg === '') {
-        return findProjectRoot(process.cwd()) ?? process.cwd();
-    }
-    return projectArg;
-}
-function runPlanRead(io, options) {
-    if (!isPlanType(options.type)) {
-        printResult(io, fail('workflow.plan.read', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
-        process.exitCode = 1;
-        return;
-    }
-    const projectRoot = resolveProjectRoot(options.project);
-    const sessionId = resolveSessionId(io, 'workflow.plan.read', projectRoot, options.sessionId, options.json);
-    if (sessionId === null)
-        return;
-    try {
-        const result = readPlan({ type: options.type, project: projectRoot, sessionId });
-        printResult(io, result, options.json === true);
-    }
-    catch (error) {
-        printResult(io, fail('workflow.plan.read', 'READ_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root with a peaks session']), options.json === true);
-        process.exitCode = 1;
-    }
-}
-function runPlanRefresh(io, options) {
-    if (!isPlanType(options.type)) {
-        printResult(io, fail('workflow.plan.refresh', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
-        process.exitCode = 1;
-        return;
-    }
-    const projectRoot = resolveProjectRoot(options.project);
-    const sessionId = resolveSessionId(io, 'workflow.plan.refresh', projectRoot, options.sessionId, options.json);
-    if (sessionId === null)
-        return;
-    try {
-        const result = refreshPlan({
-            type: options.type,
-            project: projectRoot,
-            sessionId,
-            apply: options.apply === true
-        });
-        printResult(io, result, options.json === true);
-    }
-    catch (error) {
-        printResult(io, fail('workflow.plan.refresh', 'REFRESH_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and the session exists']), options.json === true);
-        process.exitCode = 1;
-    }
-}
-function runPlanDetectTrigger(io, options) {
-    if (options.rid === undefined || options.rid === '') {
-        printResult(io, fail('workflow.plan.detect-trigger', 'MISSING_RID', 'Missing --rid', null, ['Pass --rid <request-id>']), options.json === true);
-        process.exitCode = 1;
-        return;
-    }
-    if (!isValidRequestId(options.rid)) {
-        printResult(io, fail('workflow.plan.detect-trigger', 'INVALID_RID', 'request id must match [A-Za-z0-9][A-Za-z0-9._-]*', { rid: options.rid }, ['Pass --rid <alphanumeric.request-id>']), options.json === true);
-        process.exitCode = 1;
-        return;
-    }
-    const projectRoot = resolveProjectRoot(options.project);
-    const sessionId = resolveSessionId(io, 'workflow.plan.detect-trigger', projectRoot, options.sessionId, options.json);
-    if (sessionId === null)
-        return;
-    try {
-        const result = detectTrigger({
-            project: projectRoot,
-            rid: options.rid,
-            sessionId,
-            ...(options.refresh === true ? { manualOverride: true } : {})
-        });
-        printResult(io, result, options.json === true);
-    }
-    catch (error) {
-        printResult(io, fail('workflow.plan.detect-trigger', 'DETECT_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and --rid is set']), options.json === true);
-        process.exitCode = 1;
-    }
-}
-export function registerWorkflowPlanCommands(program, io) {
-    let workflowCmd = program.commands.find((c) => c.name() === 'workflow');
-    if (workflowCmd === undefined) {
-        workflowCmd = program.command('workflow').description('Plan workflow routing dry-run graphs');
-    }
-    const plan = workflowCmd
-        .command('plan')
-        .description('Read, refresh, or detect-trigger for security / perf plans (slice 025)');
-    addJsonOption(plan
-        .command('read')
-        .description('Read the project-level plan envelope (exists, path, hash, refreshedAt)')
-        .requiredOption('--type <type>', 'plan type: security or perf')
-        .option('--project <path>', 'project root', process.cwd())
-        .option('--session-id <sid>', 'session id (defaults to the active session)')).action((options) => {
-        runPlanRead(io, options);
-    });
-    addJsonOption(plan
-        .command('refresh')
-        .description('Regenerate the plan (deterministic, idempotent; --apply to write)')
-        .requiredOption('--type <type>', 'plan type: security or perf')
-        .option('--project <path>', 'project root', process.cwd())
-        .option('--session-id <sid>', 'session id (defaults to the active session)')
-        .option('--apply', 'write the plan to disk (default is dry-run preview)')).action((options) => {
-        runPlanRefresh(io, options);
-    });
-    addJsonOption(plan
-        .command('detect-trigger')
-        .description('Detect whether a plan refresh is warranted for the slice diff')
-        .requiredOption('--rid <rid>', 'request identifier')
-        .option('--project <path>', 'project root', process.cwd())
-        .option('--session-id <sid>', 'session id (defaults to the active session)')
-        .option('--refresh', 'force triggered=true (manual override)')).action((options) => {
-        runPlanDetectTrigger(io, options);
-    });
-}
-// Re-export for tests that need a programmatic entry point.
-export { runPlanRead as _runPlanRead };
-export { runPlanRefresh as _runPlanRefresh };
-export { runPlanDetectTrigger as _runPlanDetectTrigger };

package/dist/src/cli/commands/workspace/clean-command.d.ts

@@ -1,14 +0,0 @@
-/**
- * `peaks workspace clean` — slice 0.5 Task 9 (runtime-only after
- * slice 2026-06-27-archive-feature-removal).
- *
- * Prunes _runtime/<sid>/ directories older than --older-than hours.
- * Dry-run by default; pass --apply to commit. The previous
- * The legacy sub-agents / bare-sid cleanup axis (which moved bare
- * sids to a forensic dir) was removed when the archive dir was
- * retired; bare sids are now blocked at write time. sids
- * are now blocked at write time by `sid-naming-guard.ts`.
- */
-import type { Command } from 'commander';
-import { type ProgramIO } from '../../cli-helpers.js';
-export declare function registerWorkspaceCleanCommand(workspace: Command, _io: ProgramIO): void;

package/dist/src/cli/commands/workspace/clean-command.js

@@ -1,49 +0,0 @@
-/**
- * `peaks workspace clean` — slice 0.5 Task 9 (runtime-only after
- * slice 2026-06-27-archive-feature-removal).
- *
- * Prunes _runtime/<sid>/ directories older than --older-than hours.
- * Dry-run by default; pass --apply to commit. The previous
- * The legacy sub-agents / bare-sid cleanup axis (which moved bare
- * sids to a forensic dir) was removed when the archive dir was
- * retired; bare sids are now blocked at write time. sids
- * are now blocked at write time by `sid-naming-guard.ts`.
- */
-import { executeRuntimeCleanup } from '../../../services/workspace/workspace-clean-service.js';
-import { resolveCanonicalProjectRoot } from '../../../services/config/config-service.js';
-import { getErrorMessage } from '../../cli-helpers.js';
-export function registerWorkspaceCleanCommand(workspace, _io) {
-    workspace
-        .command('clean')
-        .description('Clean stale workspace artifacts (dry-run by default; pass --apply to commit). ' +
-        'Prunes _runtime/<sid>/ directories older than --older-than hours ' +
-        '(with --grace-hours safety window).')
-        .option('--older-than <hours>', 'age threshold in hours (default 168 = 7d)', '168')
-        .option('--grace-hours <hours>', 'safety grace period in hours added to --older-than (default 24)', '24')
-        .option('--apply', 'actually write changes (default is dry-run)')
-        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
-        .option('--json', 'emit a JSON envelope { ok, data } to stdout')
-        .action((opts) => {
-        try {
-            const projectRoot = resolveCanonicalProjectRoot(opts.project);
-            const apply = opts.apply === true;
-            const result = executeRuntimeCleanup(projectRoot, {
-                olderThanHours: Number.parseInt(opts.olderThan, 10),
-                graceHours: Number.parseInt(opts.graceHours, 10),
-                apply
-            });
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: true, data: { dryRun: !apply, deleted: result.deleted, skipped: result.skipped } }) + '\n');
-            }
-        }
-        catch (error) {
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
-            }
-            else {
-                process.stderr.write(getErrorMessage(error) + '\n');
-            }
-            process.exitCode = 1;
-        }
-    });
-}

package/dist/src/cli/commands/workspace/helpers.d.ts

@@ -1,28 +0,0 @@
-/**
- * Shared helpers for `peaks workspace <sub-command>` implementations.
- *
- * Extracted from `src/cli/commands/workspace-commands.ts` (slice
- * 2026-06-16-workspace-commands-split) so multiple sub-command files can
- * reuse the same hooks-decision marker + prompt logic. Pure helpers
- * only — no commander / no service calls. Keeping these here means the
- * per-subcommand files stay focused on their command wiring and option
- * parsing.
- */
-/** Sticky decision marker for the first-time "install hooks" prompt. */
-export declare const HOOKS_DECISION_REL_PATH = ".peaks/.peaks-init-hooks-decision.json";
-export type HooksDecision = 'installed' | 'skipped';
-export type HooksDecisionMarker = {
-    version: 1;
-    decision: HooksDecision;
-    decidedAt: string;
-    scope: 'project' | 'global';
-};
-export declare function readDecisionMarker(projectRoot: string): HooksDecisionMarker | null;
-export declare function writeDecisionMarker(projectRoot: string, decision: HooksDecision): void;
-/**
- * Read a yes/no answer from stdin. Returns `true` for empty / Y / y,
- * `false` for N / n, or `null` when stdin is not a TTY (the caller falls
- * back to the no-prompt path). Times out after 30s so a piped-but-blocked
- * stdin never hangs the CLI.
- */
-export declare function promptYesNo(question: string): Promise<boolean | null>;

package/dist/src/cli/commands/workspace/helpers.js

@@ -1,87 +0,0 @@
-/**
- * Shared helpers for `peaks workspace <sub-command>` implementations.
- *
- * Extracted from `src/cli/commands/workspace-commands.ts` (slice
- * 2026-06-16-workspace-commands-split) so multiple sub-command files can
- * reuse the same hooks-decision marker + prompt logic. Pure helpers
- * only — no commander / no service calls. Keeping these here means the
- * per-subcommand files stay focused on their command wiring and option
- * parsing.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { createInterface } from 'node:readline';
-/** Sticky decision marker for the first-time "install hooks" prompt. */
-export const HOOKS_DECISION_REL_PATH = '.peaks/.peaks-init-hooks-decision.json';
-export function readDecisionMarker(projectRoot) {
-    const path = join(projectRoot, HOOKS_DECISION_REL_PATH);
-    if (!existsSync(path))
-        return null;
-    try {
-        const data = JSON.parse(readFileSync(path, 'utf8'));
-        if (data.version !== 1)
-            return null;
-        if (data.decision !== 'installed' && data.decision !== 'skipped')
-            return null;
-        if (typeof data.decidedAt !== 'string')
-            return null;
-        if (data.scope !== 'project' && data.scope !== 'global')
-            return null;
-        return {
-            version: 1,
-            decision: data.decision,
-            decidedAt: data.decidedAt,
-            scope: data.scope
-        };
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
-    }
-}
-export function writeDecisionMarker(projectRoot, decision) {
-    const path = join(projectRoot, HOOKS_DECISION_REL_PATH);
-    const dir = join(projectRoot, '.peaks');
-    mkdirSync(dir, { recursive: true });
-    const marker = {
-        version: 1,
-        decision,
-        decidedAt: new Date().toISOString(),
-        scope: 'project'
-    };
-    writeFileSync(path, JSON.stringify(marker, null, 2) + '\n', 'utf8');
-}
-/**
- * Read a yes/no answer from stdin. Returns `true` for empty / Y / y,
- * `false` for N / n, or `null` when stdin is not a TTY (the caller falls
- * back to the no-prompt path). Times out after 30s so a piped-but-blocked
- * stdin never hangs the CLI.
- */
-export function promptYesNo(question) {
-    return new Promise((resolve) => {
-        if (process.stdin.isTTY !== true) {
-            resolve(null);
-            return;
-        }
-        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
-        const timer = setTimeout(() => {
-            rl.close();
-            resolve(null);
-        }, 30_000);
-        rl.question(question, (answer) => {
-            clearTimeout(timer);
-            rl.close();
-            const trimmed = answer.trim().toLowerCase();
-            if (trimmed === '' || trimmed === 'y' || trimmed === 'yes') {
-                resolve(true);
-                return;
-            }
-            if (trimmed === 'n' || trimmed === 'no') {
-                resolve(false);
-                return;
-            }
-            // Treat anything else as "no" — the user can re-run with --install-hooks
-            // if they want a different answer. We never throw from this prompt.
-            resolve(false);
-        });
-    });
-}

package/dist/src/cli/commands/workspace/init-command.d.ts

@@ -1,121 +0,0 @@
-/**
- * `peaks workspace init` — slice 006 + 007 + 014 + 018 + 2026-06-16-peaks-code-auto-scaffold.
- *
- * Extracted from `src/cli/commands/workspace-commands.ts` (slice
- * 2026-06-16-workspace-commands-split) to keep that entry file under the
- * 800-line Karpathy cap. Owns:
- *   - commander option wiring (`--project`, `--session-id`, `--change-id`, etc.)
- *   - canonical project-root resolution
- *   - session id resolution (with slice-018 rotation)
- *   - first-time hooks install prompt + sticky marker
- *   - missing-standards diagnostic surface (AC1-AC7) and `--init-standards` apply
- *
- * Imports the shared hooks-decision marker helpers from `./helpers.ts`.
- */
-import type { Command } from 'commander';
-import { type ProgramIO } from '../../cli-helpers.js';
-import { type HooksDecision } from './helpers.js';
-export type WorkspaceInitOptions = {
-    project: string;
-    sessionId?: string;
-    json?: boolean;
-    allowSessionRebind?: boolean;
-    /**
-     * Slice 018 opt-out, commander-convention form. The user-facing
-     * flag is `--no-rotate-on-outer-mismatch`; commander strips the
-     * `--no-` prefix and assigns the boolean to this property (default
-     * `true`, set to `false` when the flag is passed). The wrapper
-     * reads this as `=== false` to opt out. The presence file still
-     * records `outerSessionMismatch` regardless of the flag's value.
-     */
-    rotateOnOuterMismatch?: boolean;
-    /**
-     * How to handle the first-time "install peaks hooks" prompt.
-     *   - ask  (default in TTY): prompt the user once, sticky-marker the answer
-     *   - auto (default in --json / non-TTY): install silently, sticky-marker installed
-     *   - skip: write sticky-marker skipped, do not install
-     * After the first decision the sticky marker wins, regardless of --install-hooks
-     * (re-runs respect the recorded decision; only re-install when the marker says
-     * installed but the hooks have been removed out from under us).
-     */
-    installHooks?: 'ask' | 'auto' | 'skip';
-    /**
-     * Slice 2.0.1-bug3-fact-forcing-bypass: opt out of writing the
-     * consumer-project `.claude/settings.local.json` file. Default
-     * (commander `--no-` prefix) is `true`; pass `--no-claude-hooks` to
-     * set this to `false`. The wrapper reads this as `=== false` to
-     * skip the materialization. The bypass is documented in
-     * `peaks-code/references/anchoring-and-session-info.md`.
-     */
-    claudeHooks?: boolean;
-    /**
-     * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7): opt-in flag to
-     * auto-scaffold `.claude/rules/{common,<language>}/` when missing.
-     * Default `false` — the diagnostic fires but no write happens.
-     * Set to `true` (via `--init-standards`) to also run
-     * `executeProjectStandardsInit({ projectRoot, apply: true })`.
-     */
-    initStandards?: boolean;
-};
-/**
- * Outcome of the first-time "install peaks hooks" decision attached to
- * `peaks workspace init`. Reported in the response data so the LLM and
- * the human both see what happened.
- */
-export type FirstTimeHooksInstallOutcome = {
-    /** The decision recorded (or already on file) in the sticky marker. */
-    decision: HooksDecision;
-    /**
-     * What the install path actually did this call.
-     *   - first-decision: we recorded a brand-new sticky marker (and may have installed)
-     *   - reinstalled:    the marker said installed but the hooks were missing — we re-applied
-     *   - marker-honored: the marker already existed; we did not touch the hooks
-     *   - already-installed: the hooks were already present and the marker does not exist yet
-     *                          (we write a fresh marker to lock in the answer for next time)
-     */
-    action: 'first-decision' | 'reinstalled' | 'marker-honored' | 'already-installed';
-    scope: 'project' | 'global';
-    /**
-     * Why the action was the way it was (e.g. "stdin-not-tty", "user-answered-no",
-     * "marker-installed-hooks-missing"). Surfaced for forensics.
-     */
-    reason?: string;
-};
-export type ResolveFirstTimeHooksInstallOptions = {
-    projectRoot: string;
-    /**
-     * Explicit mode from the --install-hooks flag. When omitted, the default
-     * is "ask" in TTY mode and "auto" otherwise (see `defaultMode` logic).
-     */
-    explicitMode?: 'ask' | 'auto' | 'skip' | undefined;
-    /**
-     * Whether the caller is in --json mode. In --json mode we never prompt
-     * (the LLM cannot answer an interactive question) — we silently treat
-     * "ask" as "auto" and proceed.
-     */
-    jsonMode: boolean;
-};
-export declare function registerWorkspaceInitCommand(workspace: Command, io: ProgramIO): void;
-/**
- * Resolve the first-time "install peaks hooks" decision for this project.
- * Decision tree:
- *
- *   1. Read the sticky marker.
- *      - Marker present:
- *        - marker.decision === 'installed' AND hooks are present → action: marker-honored, no side effects
- *        - marker.decision === 'installed' AND hooks are MISSING   → re-install, action: reinstalled
- *        - marker.decision === 'skipped'                            → action: marker-honored, no install
- *      - Marker absent:
- *        - hooks already present → write a fresh 'installed' marker, action: already-installed
- *        - otherwise:
- *          - explicit --install-hooks=auto  → install + marker, action: first-decision
- *          - explicit --install-hooks=skip  → marker only, action: first-decision
- *          - explicit --install-hooks=ask OR default in TTY:
- *              - jsonMode → silently auto-install (LLM cannot answer), action: first-decision
- *              - TTY      → prompt; on yes install + marker, on no marker-only
- *          - default in non-TTY → auto-install, action: first-decision
- *
- * Project scope is the only supported scope here; global scope is reserved
- * for explicit `peaks hooks install --global` invocations.
- */
-export declare function resolveFirstTimeHooksInstall(options: ResolveFirstTimeHooksInstallOptions): Promise<FirstTimeHooksInstallOutcome>;