peaks-loop 4.0.0-beta.2 → 4.0.0-beta.21

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

@@ -0,0 +1,163 @@
+import { fail, getErrorMessage } from 'peaks-loop-shared/result';
+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/cli/commands/workspace/init-command.d.ts

@@ -0,0 +1,139 @@
+/**
+ * `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;
+    /**
+     * Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC9 / AC10):
+     * commander-style `--no-project-scan-bootstrap` opt-out. Default
+     * (no flag) leaves this `undefined` (treated as `true`). Pass the
+     * flag to set `options.projectScanBootstrap === false`, which the
+     * caller reads as `=== false` to skip the bootstrap call.
+     */
+    projectScanBootstrap?: boolean;
+    /**
+     * Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC10):
+     * `--force-project-scan-templates` flag. Default (no flag)
+     * leaves this `undefined`. Pass the flag to set
+     * `options.forceProjectScanTemplates === true`, which forces the
+     * bootstrap service to overwrite the 4 bundled audit/business
+     * templates even when they already exist (sediment is preserved
+     * otherwise).
+     */
+    forceProjectScanTemplates?: 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>;