peaks-loop 3.0.0

package/dist/src/services/log/logger.js

@@ -0,0 +1,224 @@
+/**
+ * JSONL file logger for peaks-cli.
+ *
+ * Slice 2026-06-16-cli-logging (G1, G2, G5, G6, G7).
+ *
+ * Default-on file logging: every peaks-cli invocation writes a
+ * structured log entry to `<homedir>/.peaks/logs/peaks-cli-YYYY-MM-DD.log`
+ * (UTC date stamp). One JSON object per line.
+ *
+ * Hard contracts enforced here:
+ *  - stdout is NEVER touched by the logger (G7). Use the returned
+ *    `LogLine` string and pipe it to the file only.
+ *  - The log dir is created lazily on first write (G1).
+ *  - File mode is 0o600 on POSIX (R3). Windows uses ACLs and the
+ *    0o600 bit is a no-op there; the call is best-effort.
+ *  - All write paths go through `redact` so a leaked secret can
+ *    never reach disk (G6).
+ *  - The log level can be overridden via `PEAKS_LOG_LEVEL` (G3) and
+ *    `PEAKS_LOG_DATE_OVERRIDE` (AC2) for deterministic tests.
+ *
+ * No third-party deps (R1): `fs.appendFileSync` + `JSON.stringify`
+ * is enough; pino/winston are NOT pulled in.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { isSecretKey, redactLine, redactValue } from './redact.js';
+const LEVEL_PRIORITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40
+};
+/**
+ * Returns the canonical log directory. On Windows, `homedir()` is
+ * `%USERPROFILE%`; on macOS / Linux, `$HOME`. The path is the
+ * user-global `~/.peaks/logs/` — never inside a project tree (NG6).
+ */
+export function resolveLogDir() {
+    return join(homedir(), '.peaks', 'logs');
+}
+/**
+ * Returns the UTC date-stamped file name. `date` is injectable so
+ * tests can pin the date without monkey-patching `Date`.
+ */
+export function buildLogFileName(date) {
+    const yyyy = date.getUTCFullYear().toString().padStart(4, '0');
+    const mm = (date.getUTCMonth() + 1).toString().padStart(2, '0');
+    const dd = date.getUTCDate().toString().padStart(2, '0');
+    return `peaks-loop-${yyyy}-${mm}-${dd}.log`;
+}
+/**
+ * Walk a structured payload and redact any field whose key matches
+ * the secret pattern. Returns a NEW object (immutable). Used by
+ * `writeLogEntry` so a `data` payload containing `apiKey` is never
+ * serialized verbatim.
+ */
+function redactPayload(payload) {
+    if (payload === null || payload === undefined)
+        return payload;
+    if (Array.isArray(payload)) {
+        return payload.map((item) => redactPayload(item));
+    }
+    if (typeof payload === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(payload)) {
+            if (isSecretKey(k)) {
+                out[k] = '<redacted>';
+            }
+            else if (typeof v === 'string') {
+                out[k] = redactValue(v);
+            }
+            else {
+                out[k] = redactPayload(v);
+            }
+        }
+        return out;
+    }
+    if (typeof payload === 'string')
+        return redactValue(payload);
+    return payload;
+}
+function resolveLogLevel() {
+    const env = process.env.PEAKS_LOG_LEVEL?.toLowerCase();
+    if (env === 'debug' || env === 'info' || env === 'warn' || env === 'error') {
+        return env;
+    }
+    return 'info';
+}
+function shouldEmit(level) {
+    const threshold = resolveLogLevel();
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[threshold];
+}
+/**
+ * Write a single JSONL log entry. Returns the absolute file path
+ * the entry was written to, or `null` when the entry was filtered
+ * out by the current log level.
+ *
+ * Failures inside the logger (mkdir, appendFile, chmod) are caught
+ * and swallowed: a logger that takes down the CLI is worse than a
+ * logger that drops a line. The swallow is intentional per the PRD
+ * non-goals (NG1: no remote ship; the user only ever sees a file
+ * they read directly).
+ */
+export function writeLogEntry(entry, opts = {}) {
+    if (!shouldEmit(entry.level))
+        return null;
+    const now = opts.now ? opts.now() : new Date();
+    const dateForFile = opts.dateOverride !== undefined
+        ? new Date(`${opts.dateOverride}T00:00:00.000Z`)
+        : now;
+    const logDir = opts.dirOverride ?? resolveLogDir();
+    const fileName = buildLogFileName(dateForFile);
+    const fullPath = join(logDir, fileName);
+    try {
+        if (!existsSync(logDir)) {
+            mkdirSync(logDir, { recursive: true });
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    // Build a redacted copy of the entry. We never mutate the caller's
+    // object (immutability rule from coding-style.md).
+    const redactedEntry = {
+        ...entry,
+        ts: entry.ts ?? now.toISOString(),
+        msg: redactLine(entry.msg),
+        ...(entry.sessionId !== undefined ? { sessionId: entry.sessionId } : {}),
+        ...(entry.version !== undefined ? { version: entry.version } : {}),
+        ...(entry.batchId !== undefined ? { batchId: entry.batchId } : {}),
+        ...(entry.data !== undefined ? { data: redactPayload(entry.data) } : {})
+    };
+    let line;
+    try {
+        line = JSON.stringify(redactedEntry);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    try {
+        appendFileSync(fullPath, line + '\n', { mode: 0o600 });
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    // `appendFileSync({mode})` only sets the mode when the file is
+    // created. On subsequent writes the mode would not be re-applied
+    // (Node's documented behavior). chmod is a no-op when the mode
+    // is already correct; safe to call.
+    if (process.platform !== 'win32') {
+        try {
+            const stat = statSync(fullPath);
+            if ((stat.mode & 0o777) !== 0o600) {
+                chmodSync(fullPath, 0o600);
+            }
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            /* best-effort */
+        }
+    }
+    return fullPath;
+}
+/**
+ * Read the current day's log file and return all parseable JSON
+ * entries. Malformed lines are skipped (the on-disk file is JSONL,
+ * but a crash mid-write can leave a partial line; we don't want
+ * that to break `peaks log tail`).
+ */
+export function readLogEntries(opts = {}) {
+    const now = opts.now ? opts.now() : new Date();
+    const dateForFile = opts.dateOverride !== undefined
+        ? new Date(`${opts.dateOverride}T00:00:00.000Z`)
+        : now;
+    const logDir = opts.dirOverride ?? resolveLogDir();
+    const fileName = buildLogFileName(dateForFile);
+    const fullPath = join(logDir, fileName);
+    if (!existsSync(fullPath))
+        return [];
+    let body;
+    try {
+        body = readFileSync(fullPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of body.split('\n')) {
+        if (line.length === 0)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // skip malformed
+        }
+    }
+    return out;
+}
+/**
+ * Print a log line to stderr IF the current process is in verbose
+ * mode (`--verbose` / `-v` / `PEAKS_LOG_LEVEL=debug`). This is the
+ * G3 opt-in channel: by default, stderr stays clean so the CLI's
+ * `--json` envelope is not contaminated.
+ *
+ * Returns `true` when the line was written; `false` otherwise. The
+ * caller can use the boolean to detect silent-failure patterns (a
+ * `peaks log tail` that prints nothing when the user expected a
+ * verbose stream).
+ */
+export function maybeWriteStderr(entry, opts) {
+    if (!opts.verbose)
+        return false;
+    if (entry.level !== 'debug' && entry.level !== 'info')
+        return false;
+    try {
+        process.stderr.write(JSON.stringify(entry) + '\n');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { dirname };

package/dist/src/services/log/redact.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Secret redaction for peaks-cli JSONL log lines.
+ *
+ * Slice 2026-06-16-cli-logging (G6). The logger must NEVER write
+ * a raw secret to disk. We redact at two levels:
+ *  1. Field level — when a structured payload contains a key whose
+ *     name matches a secret pattern (`api_key`, `password`, `token`,
+ *     `Authorization`, etc.), the value is replaced with `<redacted>`.
+ *  2. Line level — when a free-form string contains patterns like
+ *     `Authorization: Bearer <token>`, `api_key=<value>`, or
+ *     `password="<value>"`, the token-shaped value is replaced.
+ *
+ * Redaction is intentionally conservative: false positives are
+ * acceptable (a user can read a redacted line); false negatives are
+ * NOT (a leaked token may be pasted into a GitHub issue).
+ *
+ * The PRD lists the redaction triggers; this module is the only
+ * place the regex table lives, so any future addition (e.g. a new
+ * `client_secret` key) is a one-line change.
+ */
+/**
+ * Returns true when the given key name should be treated as a
+ * secret regardless of the value's shape. Case-insensitive.
+ */
+export declare function isSecretKey(key: unknown): boolean;
+/**
+ * Redact a single string value. Returns the original string when
+ * it does not look like a credential; returns `<redacted>` when it
+ * does. Empty / non-strings return as-is.
+ */
+export declare function redactValue(value: unknown): unknown;
+export declare function redactLine(line: string): string;

package/dist/src/services/log/redact.js

@@ -0,0 +1,89 @@
+/**
+ * Secret redaction for peaks-cli JSONL log lines.
+ *
+ * Slice 2026-06-16-cli-logging (G6). The logger must NEVER write
+ * a raw secret to disk. We redact at two levels:
+ *  1. Field level — when a structured payload contains a key whose
+ *     name matches a secret pattern (`api_key`, `password`, `token`,
+ *     `Authorization`, etc.), the value is replaced with `<redacted>`.
+ *  2. Line level — when a free-form string contains patterns like
+ *     `Authorization: Bearer <token>`, `api_key=<value>`, or
+ *     `password="<value>"`, the token-shaped value is replaced.
+ *
+ * Redaction is intentionally conservative: false positives are
+ * acceptable (a user can read a redacted line); false negatives are
+ * NOT (a leaked token may be pasted into a GitHub issue).
+ *
+ * The PRD lists the redaction triggers; this module is the only
+ * place the regex table lives, so any future addition (e.g. a new
+ * `client_secret` key) is a one-line change.
+ */
+const SECRET_KEY_PATTERN = /^(?:.*[\._-])?(api[_-]?key|apikey|api[_-]?secret|secret|password|passwd|token|authorization|access[_-]?token|refresh[_-]?token|cookie|set[_-]?cookie|client[_-]?secret)$/i;
+/**
+ * Returns true when the given key name should be treated as a
+ * secret regardless of the value's shape. Case-insensitive.
+ */
+export function isSecretKey(key) {
+    if (typeof key !== 'string' || key.length === 0)
+        return false;
+    return SECRET_KEY_PATTERN.test(key);
+}
+/**
+ * Heuristic: a string value that looks like a credential-shaped
+ * token (Bearer, github_pat_, ghp_, sk_, long opaque base64) is
+ * redacted. Short, human-readable strings (a name, a command name)
+ * are left alone.
+ */
+const TOKEN_VALUE_PATTERN = /^(?:Bearer\s+[A-Za-z0-9._\-+/=]{8,}|ghp_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{16,}|sk-[A-Za-z0-9]{16,}|[A-Za-z0-9_\-]{32,})$/;
+const REDACTED = '<redacted>';
+/**
+ * Redact a single string value. Returns the original string when
+ * it does not look like a credential; returns `<redacted>` when it
+ * does. Empty / non-strings return as-is.
+ */
+export function redactValue(value) {
+    if (typeof value !== 'string')
+        return value;
+    if (value.length === 0)
+        return value;
+    if (TOKEN_VALUE_PATTERN.test(value))
+        return REDACTED;
+    return value;
+}
+/**
+ * Line-level redaction. Replaces `key=value`, `key="value"`, and
+ * `key: value` substrings whose key matches the secret pattern.
+ * Preserves non-secret lines verbatim.
+ */
+const LINE_KEY_VALUE_PATTERN = new RegExp(String.raw `((?:api[_-]?key|apikey|secret|password|passwd|token|access[_-]?token|refresh[_-]?token|client[_-]?secret))` +
+    String.raw `\s*[=:]\s*` +
+    String.raw `(?:"([^"]*)"|'([^']*)'|([^\s,;"'` +
+    String.raw `` +
+    String.raw `]+))`, 'gi');
+const AUTH_HEADER_PATTERN = /Authorization\s*:\s*Bearer\s+[A-Za-z0-9._\-+/=]+/gi;
+export function redactLine(line) {
+    if (typeof line !== 'string' || line.length === 0)
+        return line;
+    let out = line;
+    out = out.replace(AUTH_HEADER_PATTERN, (match) => {
+        return match.replace(/Bearer\s+[A-Za-z0-9._\-+/=]+/, `Bearer ${REDACTED}`);
+    });
+    out = out.replace(LINE_KEY_VALUE_PATTERN, (_match, key, q1, q2, bare) => {
+        if (q1 !== undefined)
+            return `${key}=${REDACTED}`;
+        if (q2 !== undefined)
+            return `${key}=${REDACTED}`;
+        if (bare !== undefined) {
+            // For bare (unquoted) key=value pairs, any value longer than 4
+            // chars is treated as a secret — these are config dumps where
+            // the value is always opaque (the test fixture
+            // `api_key=supersecret12345` is 19 chars; production secrets
+            // are usually ≥ 16). This is conservative on purpose.
+            if (bare.length >= 4)
+                return `${key}=${REDACTED}`;
+            return `${key}=${bare}`;
+        }
+        return _match;
+    });
+    return out;
+}

package/dist/src/services/log/retention.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 7-day log rotation for peaks-loop.
+ *
+ * Slice 2026-06-16-cli-logging (G2). Cheapest possible rotation:
+ * daily files are named by UTC date, so a "new day" automatically
+ * means a new file. The retention sweep runs at the start of every
+ * peaks-loop invocation and removes any `peaks-loop-*.log` whose
+ * UTC date is more than `retentionDays` days behind today.
+ *
+ * No external dep — `fs.readdirSync` + `statSync.mtimeMs` (or, for
+ * the name-derived path, parse the YYYY-MM-DD from the file name).
+ * We prefer the file NAME (not mtime) so a user who copies an old
+ * log back into the directory does not have it re-deleted on the
+ * next sweep.
+ */
+export type ApplyRetentionOptions = {
+    /** Number of days to keep. Defaults to 7. */
+    retentionDays?: number;
+    /** Wall-clock for tests. Defaults to `Date.now()`. */
+    nowMs?: number;
+    /** Override log dir (used by tests). */
+    dirOverride?: string;
+};
+/**
+ * Delete any `peaks-loop-YYYY-MM-DD.log` file in the log dir whose
+ * UTC date is more than `retentionDays` days older than today.
+ * Returns the absolute paths of the deleted files (for tests +
+ * observability).
+ *
+ * The function is best-effort: a per-file unlink failure is
+ * silently swallowed (the file may have been removed by another
+ * process between the `readdir` and the `unlink`).
+ */
+export declare function applyRetention(opts?: ApplyRetentionOptions): string[];

package/dist/src/services/log/retention.js

@@ -0,0 +1,78 @@
+/**
+ * 7-day log rotation for peaks-loop.
+ *
+ * Slice 2026-06-16-cli-logging (G2). Cheapest possible rotation:
+ * daily files are named by UTC date, so a "new day" automatically
+ * means a new file. The retention sweep runs at the start of every
+ * peaks-loop invocation and removes any `peaks-loop-*.log` whose
+ * UTC date is more than `retentionDays` days behind today.
+ *
+ * No external dep — `fs.readdirSync` + `statSync.mtimeMs` (or, for
+ * the name-derived path, parse the YYYY-MM-DD from the file name).
+ * We prefer the file NAME (not mtime) so a user who copies an old
+ * log back into the directory does not have it re-deleted on the
+ * next sweep.
+ */
+import { readdirSync, statSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveLogDir } from './logger.js';
+const LOG_FILE_NAME_PATTERN = /^peaks-loop-(\d{4}-\d{2}-\d{2})\.log$/;
+function dayDiffUtc(nowUtcMidnightMs, fileDateUtcMs) {
+    const dayMs = 24 * 60 * 60 * 1000;
+    return Math.floor((nowUtcMidnightMs - fileDateUtcMs) / dayMs);
+}
+function utcMidnightMs(date) {
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+/**
+ * Delete any `peaks-loop-YYYY-MM-DD.log` file in the log dir whose
+ * UTC date is more than `retentionDays` days older than today.
+ * Returns the absolute paths of the deleted files (for tests +
+ * observability).
+ *
+ * The function is best-effort: a per-file unlink failure is
+ * silently swallowed (the file may have been removed by another
+ * process between the `readdir` and the `unlink`).
+ */
+export function applyRetention(opts = {}) {
+    const retentionDays = opts.retentionDays ?? 7;
+    const now = opts.nowMs ?? Date.now();
+    const logDir = opts.dirOverride ?? resolveLogDir();
+    if (!existsSync(logDir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(logDir);
+    }
+    catch {
+        return [];
+    }
+    const nowUtcMidnight = utcMidnightMs(new Date(now));
+    const removed = [];
+    for (const name of names) {
+        const match = LOG_FILE_NAME_PATTERN.exec(name);
+        if (match === null)
+            continue;
+        const dateStr = match[1];
+        if (dateStr === undefined)
+            continue;
+        const fileDateUtcMs = Date.parse(`${dateStr}T00:00:00.000Z`);
+        if (Number.isNaN(fileDateUtcMs))
+            continue;
+        const diff = dayDiffUtc(nowUtcMidnight, fileDateUtcMs);
+        if (diff > retentionDays) {
+            const fullPath = join(logDir, name);
+            try {
+                const stat = statSync(fullPath);
+                if (!stat.isFile())
+                    continue;
+                unlinkSync(fullPath);
+                removed.push(fullPath);
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                /* best-effort: file removed by another process or perms denied */
+            }
+        }
+    }
+    return removed;
+}

package/dist/src/services/loop/evaluator-dispatcher.d.ts

@@ -0,0 +1,50 @@
+import type { EvaluatorKind } from '../workflow/workflow-spec.js';
+/** Standard evaluator verdict envelope — matches the union members
+ *  consumed by `envelopesToAggregatorInput`. */
+export interface EvaluatorVerdictEnvelope {
+    readonly kind: EvaluatorKind;
+    readonly passed: boolean;
+    readonly gateAction: 'pass' | 'warn' | 'block';
+    /** Severity-graded violations (file + line + hint). */
+    readonly violations: ReadonlyArray<{
+        readonly severity: 'CRITICAL' | 'HIGH' | 'MED' | 'LOW';
+        readonly file: string;
+        readonly line: number;
+        readonly hint: string;
+        readonly dimension?: string;
+    }>;
+    /** Summary line; surfaced in the nextActions list. */
+    readonly summary: string;
+    /** Wall-time the evaluator took (seconds). */
+    readonly wallSeconds: number;
+    /** When true, the evaluator fell back to a stub because the binary was
+     *  unavailable in this environment. Surfaces in the verdict envelope so
+     *  the user can rerun on a real peaks-cli install. */
+    readonly degraded: boolean;
+}
+export interface DispatchOptions {
+    readonly projectRoot: string;
+    readonly rid: string;
+    /** Session id — required by `monotonic-improvement` so the guard
+     *  can read the prior cycle from the slice dir. Other evaluators
+     *  ignore it. */
+    readonly sessionId?: string;
+    readonly scope?: string;
+    readonly threshold?: string;
+    /** Override the peaks binary path (default: `node bin/peaks.js` from cwd). */
+    readonly peaksBin?: string;
+}
+/** Dispatch a single evaluator against the given rid and project. */
+export declare function dispatchEvaluator(kind: EvaluatorKind, options: DispatchOptions): EvaluatorVerdictEnvelope;
+export declare function envelopeAs(envelope: EvaluatorVerdictEnvelope, kind: EvaluatorKind): EvaluatorVerdictEnvelope;
+/**
+ * Best-effort markdown parse for karpathy-review.md / security.md / perf.md.
+ * Mirrors the shape accepted by `parseKarpathyEnvelope` /
+ * `parseSecurityEnvelope` / `parsePerfEnvelope` in `services/verdict/envelopes.ts`,
+ * keeping verdict-aggregator backward-compat intact.
+ */
+export declare function parseAuditMarkdownEnvelope(md: string, kind: 'security-review' | 'perf-baseline'): EvaluatorVerdictEnvelope | null;
+/** Load an on-disk audit file (e.g. `.peaks/_runtime/<sid>/audit/security.md`)
+ *  and project it to an `EvaluatorVerdictEnvelope`. Used by workflow yaml
+ *  evaluators that point at on-disk artifacts. */
+export declare function loadEnvelopeFromDisk(projectRoot: string, sid: string, rel: string, kind: 'security-review' | 'perf-baseline'): EvaluatorVerdictEnvelope | null;