peaks-cli 1.3.8 → 1.4.0

package/dist/src/services/workflow/plan-reader.js

@@ -0,0 +1,158 @@
+/**
+ * `peaks workflow plan read` — slice 025 (Security + Perf Plan/Result split).
+ *
+ * Returns the envelope `{ exists, path, hash, refreshedAt }` for the
+ * session-scoped security-test-plan or perf-baseline plan. The hash is
+ * computed on the **normalized** body (sections sorted, blank lines
+ * collapsed) so it is independent of cosmetic re-ordering; mtime is
+ * surfaced as ISO-8601.
+ *
+ * Back-compat: when the BACK_COMPAT_FLAG env var is "1" and the
+ * legacy path (`.peaks/<planFile>` at the project root) exists but
+ * the canonical session path does not, the reader falls back to the
+ * legacy path and reports `source: "legacy"`.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { fail, ok } from '../../shared/result.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+/** Back-compat env-var. When set to "1", fall back to legacy paths. */
+export const BACK_COMPAT_FLAG = 'PEAKS_PLAN_LEGACY_FALLBACK';
+/** F-1 (slice 025 security): canonical session-id shape. */
+export const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+const PLAN_FILE = {
+    security: 'security-test-plan.md',
+    perf: 'perf-baseline.md'
+};
+/**
+ * Normalize a markdown body for hashing. Sections sorted, blank lines
+ * collapsed, leading/trailing whitespace stripped. Hash is sha256[0:12].
+ */
+export function normalizePlanBody(body) {
+    const lines = body
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    return lines.sort().join('\n');
+}
+/** Compute the deterministic plan hash on a normalized body. */
+export function hashNormalizedBody(body) {
+    const normalized = normalizePlanBody(body);
+    return createHash('sha256').update(normalized, 'utf8').digest('hex').slice(0, 12);
+}
+function canonicalPath(args) {
+    return join(getSessionDir(args.projectRoot, args.sessionId), 'qa', PLAN_FILE[args.type]);
+}
+function legacyPath(args) {
+    return join(args.projectRoot, '.peaks', PLAN_FILE[args.type]);
+}
+/** Build the data envelope for a path that exists. */
+function buildData(args) {
+    const stats = statSync(args.path);
+    return {
+        type: args.type,
+        exists: true,
+        path: args.path,
+        hash: hashNormalizedBody(readFileSync(args.path, 'utf8')),
+        refreshedAt: stats.mtime.toISOString(),
+        source: args.source
+    };
+}
+/**
+ * F-2 (slice 025 security): resolve symlinks and confirm the real path
+ * still lives under the expected base directory. A canonical path
+ * may itself be a symlink (or a directory in the path chain may be),
+ * which would let a malicious or accidental symlink escape the
+ * `.peaks/_runtime/<sessionId>/` containment. We reject anything
+ * whose real path falls outside the expected base.
+ *
+ * The caller passes the expected base:
+ *   - session dir for canonical reads (`.peaks/_runtime/<sid>/qa/...`)
+ *   - project root for legacy back-compat reads (`.peaks/<planFile>`)
+ */
+function assertContained(args) {
+    let real;
+    try {
+        real = realpathSync(args.path);
+    }
+    catch {
+        // If realpath fails (e.g. broken symlink), treat as escape — never
+        // return "ok" without a verified real path.
+        return {
+            ok: false,
+            code: 'SYMLINK_ESCAPE',
+            message: `resolved path escapes base directory: cannot resolve ${args.path}`
+        };
+    }
+    const expectedPrefix = join(args.expectedBase, sep);
+    if (!real.startsWith(expectedPrefix)) {
+        return {
+            ok: false,
+            code: 'SYMLINK_ESCAPE',
+            message: `resolved path escapes base directory: ${real} is not under ${expectedPrefix}`
+        };
+    }
+    return { ok: true, real };
+}
+export function readPlan(args) {
+    // F-1 (slice 025 security): reject path-traversal payloads before any
+    // filesystem call. The CLI also validates, but the service is the
+    // authoritative gate — every caller (CLI, skill, integration test)
+    // benefits from the same rejection shape.
+    if (!SESSION_ID_PATTERN.test(args.sessionId)) {
+        return fail('workflow.plan.read', 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', {
+            type: args.type,
+            exists: false,
+            path: '',
+            hash: null,
+            refreshedAt: null,
+            source: 'missing'
+        });
+    }
+    const canonical = canonicalPath({ projectRoot: args.project, sessionId: args.sessionId, type: args.type });
+    if (existsSync(canonical)) {
+        const guard = assertContained({
+            expectedBase: getSessionDir(args.project, args.sessionId),
+            path: canonical
+        });
+        if (!guard.ok) {
+            return fail('workflow.plan.read', guard.code, guard.message, {
+                type: args.type,
+                exists: false,
+                path: canonical,
+                hash: null,
+                refreshedAt: null,
+                source: 'missing'
+            });
+        }
+        return ok('workflow.plan.read', buildData({ type: args.type, path: canonical, source: 'canonical' }));
+    }
+    const legacy = legacyPath({ projectRoot: args.project, type: args.type });
+    const backCompatEnabled = process.env[BACK_COMPAT_FLAG] === '1';
+    if (backCompatEnabled && existsSync(legacy)) {
+        const guard = assertContained({
+            expectedBase: args.project,
+            path: legacy
+        });
+        if (!guard.ok) {
+            return fail('workflow.plan.read', guard.code, guard.message, {
+                type: args.type,
+                exists: false,
+                path: legacy,
+                hash: null,
+                refreshedAt: null,
+                source: 'missing'
+            });
+        }
+        return ok('workflow.plan.read', buildData({ type: args.type, path: legacy, source: 'legacy' }));
+    }
+    return ok('workflow.plan.read', {
+        type: args.type,
+        exists: false,
+        path: canonical,
+        hash: null,
+        refreshedAt: null,
+        source: 'missing'
+    });
+}

package/dist/src/services/workflow/plan-refresher.d.ts

@@ -0,0 +1,32 @@
+import { type ResultEnvelope } from '../../shared/result.js';
+import { normalizePlanBody, type PlanType } from './plan-reader.js';
+export interface RefreshPlanArgs {
+    readonly type: PlanType;
+    readonly project: string;
+    readonly sessionId: string;
+    /** When true, write the plan to disk. When false, return the would-be body + hash only. */
+    readonly apply: boolean;
+}
+export interface RefreshPlanData {
+    readonly type: PlanType;
+    readonly writtenFiles: string[];
+    /** When `apply=false`, the would-be write targets. */
+    readonly wouldWrite: string[];
+    readonly hash: string;
+    readonly refreshedAt: string;
+    readonly dryRun: boolean;
+    /** The deterministic body (post-normalization). Always surfaced so tests
+     * can assert byte-equality across runs. */
+    readonly bodyPreview: string;
+}
+/** Build the security-test-plan body deterministically. */
+export declare function buildSecurityPlanBody(projectRoot: string): string;
+/** Build the perf-baseline body deterministically. */
+export declare function buildPerfPlanBody(projectRoot: string): string;
+export declare function refreshPlan(args: RefreshPlanArgs): ResultEnvelope<RefreshPlanData>;
+export { normalizePlanBody };
+export declare function renderPlanBody(args: {
+    type: PlanType;
+    project: string;
+}): string;
+export declare function hashBody(body: string): string;

package/dist/src/services/workflow/plan-refresher.js

@@ -0,0 +1,353 @@
+/**
+ * `peaks workflow plan refresh` — slice 025 (Security + Perf Plan/Result split).
+ *
+ * Deterministically regenerates a security-test-plan or perf-baseline
+ * plan body. Without `--apply`, computes the would-be body + hash but
+ * does not write. With `--apply`, atomically writes the file.
+ *
+ * Determinism: inputs (file list, dependency list) are sorted before
+ * being rendered; the body is then `normalizePlanBody`-ed before hashing
+ * so re-running with no input change returns the same hash.
+ */
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { fail, ok } from '../../shared/result.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { hashNormalizedBody, normalizePlanBody } from './plan-reader.js';
+const PLAN_FILE = {
+    security: 'security-test-plan.md',
+    perf: 'perf-baseline.md'
+};
+const SENSITIVE_SERVICE_DIRS = ['auth', 'security', 'secrets', 'payments', 'filesystem'];
+function readPackageJson(projectRoot) {
+    const path = join(projectRoot, 'package.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function listAuthTsFiles(projectRoot) {
+    const out = [];
+    const roots = [join(projectRoot, 'src')];
+    for (const root of roots) {
+        if (!existsSync(root))
+            continue;
+        const stack = [root];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (dir === undefined)
+                continue;
+            let entries;
+            try {
+                entries = readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist')
+                    continue;
+                const full = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (entry.isFile() && /auth.*\.ts$|\.ts$/i.test(entry.name) && /auth/i.test(entry.name)) {
+                    out.push(full);
+                }
+            }
+        }
+    }
+    return [...new Set(out)].sort();
+}
+function listSensitiveServiceFiles(projectRoot) {
+    const result = {};
+    for (const dir of SENSITIVE_SERVICE_DIRS) {
+        const root = join(projectRoot, 'src', 'services', dir);
+        if (!existsSync(root)) {
+            result[dir] = [];
+            continue;
+        }
+        const files = [];
+        const stack = [root];
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            if (cur === undefined)
+                continue;
+            let entries;
+            try {
+                entries = readdirSync(cur, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const full = join(cur, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.ts')) {
+                    files.push(full);
+                }
+            }
+        }
+        result[dir] = files.sort();
+    }
+    return result;
+}
+function listCliCommands(projectRoot) {
+    const root = join(projectRoot, 'src', 'cli', 'commands');
+    if (!existsSync(root))
+        return [];
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith('-commands.ts'))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Build the security-test-plan body deterministically. */
+export function buildSecurityPlanBody(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    const deps = pkg?.dependencies ? Object.keys(pkg.dependencies).sort() : [];
+    const optDeps = pkg?.optionalDependencies ? Object.keys(pkg.optionalDependencies).sort() : [];
+    const sensitive = listSensitiveServiceFiles(projectRoot);
+    const authFiles = listAuthTsFiles(projectRoot);
+    const sections = [];
+    sections.push(`# Security Test Plan (project-level)`);
+    sections.push(`Generated: ${new Date('2026-01-01T00:00:00Z').toISOString()}`);
+    sections.push(`## Threat Model`);
+    sections.push(`Asset inventory: auth boundary, secret storage, external API surface, file system writes.`);
+    sections.push(`## Sensitive Service Files`);
+    for (const dir of [...SENSITIVE_SERVICE_DIRS].sort()) {
+        const files = sensitive[dir] ?? [];
+        sections.push(`### ${dir}`);
+        if (files.length === 0) {
+            sections.push('- (none)');
+        }
+        else {
+            for (const f of files)
+                sections.push(`- ${f}`);
+        }
+    }
+    sections.push(`## Auth Surface (*auth*.ts files repo-wide)`);
+    if (authFiles.length === 0) {
+        sections.push('- (none)');
+    }
+    else {
+        for (const f of authFiles)
+            sections.push(`- ${f}`);
+    }
+    sections.push(`## Runtime Dependencies`);
+    sections.push(`### dependencies`);
+    if (deps.length === 0) {
+        sections.push('- (none)');
+    }
+    else {
+        for (const d of deps)
+            sections.push(`- ${d}`);
+    }
+    sections.push(`### optionalDependencies`);
+    if (optDeps.length === 0) {
+        sections.push('- (none)');
+    }
+    else {
+        for (const d of optDeps)
+            sections.push(`- ${d}`);
+    }
+    sections.push(`## Test Matrix`);
+    sections.push(`- Auth boundary: covered by peaks-qa per-slice diff scan.`);
+    sections.push(`- Secret storage: covered by peaks-qa per-slice diff scan.`);
+    sections.push(`- External API surface: covered by peaks-qa per-slice diff scan.`);
+    sections.push(`- File system writes: covered by peaks-qa per-slice diff scan.`);
+    return sections.join('\n');
+}
+/** Build the perf-baseline body deterministically. */
+export function buildPerfPlanBody(projectRoot) {
+    const commands = listCliCommands(projectRoot);
+    const sections = [];
+    sections.push(`# Performance Baseline (project-level)`);
+    sections.push(`Generated: ${new Date('2026-01-01T00:00:00Z').toISOString()}`);
+    sections.push(`## CLI Command Inventory`);
+    if (commands.length === 0) {
+        sections.push('- (none)');
+    }
+    else {
+        for (const c of commands)
+            sections.push(`- ${c}`);
+    }
+    sections.push(`## Routes / Hooks`);
+    sections.push(`- All routes are CLI subcommands; no HTTP listeners.`);
+    sections.push(`## Baseline Measurements`);
+    sections.push(`- TBD: lighthouse / k6 / autocannon — project-local measurement.`);
+    sections.push(`## Thresholds`);
+    sections.push(`- TBD: per-route threshold (p95 latency / throughput).`);
+    return sections.join('\n');
+}
+function planPath(args) {
+    return join(getSessionDir(args.projectRoot, args.sessionId), 'qa', PLAN_FILE[args.type]);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+export function refreshPlan(args) {
+    const target = planPath({ projectRoot: args.project, sessionId: args.sessionId, type: args.type });
+    // The body is a *function* of the project (sorted inputs + normalized
+    // output). To make the hash independent of the current wall clock, we
+    // always emit the same `Generated:` timestamp; the real `refreshedAt`
+    // is reported separately as the envelope field.
+    const rawBody = args.type === 'security' ? buildSecurityPlanBody(args.project) : buildPerfPlanBody(args.project);
+    const hash = hashNormalizedBody(rawBody);
+    const wouldWrite = [target];
+    const refreshedAt = nowIso();
+    if (!args.apply) {
+        return ok('workflow.plan.refresh', {
+            type: args.type,
+            writtenFiles: [],
+            wouldWrite,
+            hash,
+            refreshedAt,
+            dryRun: true,
+            bodyPreview: rawBody
+        });
+    }
+    // F-2 (slice 025 security): if the parent dir chain has a symlink
+    // that escapes the session dir, refuse to write. We resolve the
+    // parent (the dir we are about to mkdir/write into) and confirm its
+    // real path stays under the expected base.
+    //
+    // Two cases:
+    //   (a) Some ancestor of the parent already exists on disk. We
+    //       resolve the deepest existing ancestor to its real path and
+    //       require that real path to be under `<projectRoot>` (a
+    //       symlink within the project is fine; an escape to outside the
+    //       project is not). The new dirs we are about to mkdir are
+    //       created by us, so once the deepest-existing ancestor is
+    //       verified, the new sub-dirs inherit containment.
+    //   (b) No ancestor inside the project exists (a fully fresh write).
+    //       The mkdir chain starts from the project root, which we
+    //       already resolved. We require the project root's real path
+    //       to be under itself (trivially true) and trust the mkdir
+    //       chain. This avoids the "walked up to /" false positive
+    //       when the test fixture is a fresh temp dir.
+    const projectRoot = args.project;
+    let projectRootReal;
+    try {
+        projectRootReal = realpathSync(projectRoot);
+    }
+    catch {
+        return fail('workflow.plan.refresh', 'SYMLINK_ESCAPE', `cannot resolve project root ${projectRoot}`, {
+            type: args.type,
+            writtenFiles: [],
+            wouldWrite,
+            hash,
+            refreshedAt,
+            dryRun: true,
+            bodyPreview: rawBody
+        }, ['Inspect the project root for symlinks that escape the filesystem']);
+    }
+    const parent = join(target, '..');
+    // Find the deepest existing ancestor of `parent` that is still
+    // inside the project root. We start at the parent itself and walk
+    // up, but never past the project root.
+    let existingParent = null;
+    let cursor = parent;
+    // Bound the walk: stop at the project root (inclusive). If the
+    // project root itself does not exist, that's an error.
+    while (cursor !== projectRoot && cursor !== join(projectRoot, '..') && cursor !== '' && cursor !== sep) {
+        if (existsSync(cursor)) {
+            existingParent = cursor;
+            break;
+        }
+        const next = join(cursor, '..');
+        if (next === cursor)
+            break;
+        cursor = next;
+    }
+    if (existingParent === null) {
+        // No ancestor inside the project root exists. Verify the project
+        // root itself resolves, and trust the mkdir chain. The project
+        // root's real path IS the deepest verifiable ancestor; if it's
+        // a symlink, realpathSync has already collapsed it.
+        if (!existsSync(projectRoot)) {
+            return fail('workflow.plan.refresh', 'SYMLINK_ESCAPE', `project root does not exist: ${projectRoot}`, {
+                type: args.type,
+                writtenFiles: [],
+                wouldWrite,
+                hash,
+                refreshedAt,
+                dryRun: true,
+                bodyPreview: rawBody
+            }, ['Inspect the project root — it must exist and be a directory']);
+        }
+        // Sanity: ensure the project root's real path stays inside its
+        // own prefix (always true after realpath). No further check needed.
+    }
+    else {
+        let resolvedParent;
+        try {
+            resolvedParent = realpathSync(existingParent);
+        }
+        catch {
+            return fail('workflow.plan.refresh', 'SYMLINK_ESCAPE', `cannot resolve parent directory ${existingParent}`, {
+                type: args.type,
+                writtenFiles: [],
+                wouldWrite,
+                hash,
+                refreshedAt,
+                dryRun: true,
+                bodyPreview: rawBody
+            }, ['Inspect the parent directory chain for symlinks that escape the session dir']);
+        }
+        // Resolved parent must stay under the project root. This catches
+        // both: (i) a symlink within the project that points outside the
+        // project, (ii) a symlink that points inside the project but
+        // outside the session dir. The session dir is the eventual
+        // destination, so the resolved parent chain must end up there.
+        const projectRootPrefix = projectRootReal + sep;
+        if (!resolvedParent.startsWith(projectRootPrefix) && resolvedParent !== projectRootReal) {
+            return fail('workflow.plan.refresh', 'SYMLINK_ESCAPE', `resolved path escapes project root: ${resolvedParent} is not under ${projectRootReal}`, {
+                type: args.type,
+                writtenFiles: [],
+                wouldWrite,
+                hash,
+                refreshedAt,
+                dryRun: true,
+                bodyPreview: rawBody
+            }, ['Inspect the parent directory chain for symlinks that escape the project root']);
+        }
+    }
+    // Apply: ensure parent dir exists, then write.
+    if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+    }
+    // If a file already exists, capture its mtime to report `refreshedAt` of
+    // the new state. If it doesn't, this is a fresh write.
+    writeFileSync(target, rawBody, 'utf8');
+    const stats = statSync(target);
+    return ok('workflow.plan.refresh', {
+        type: args.type,
+        writtenFiles: [target],
+        wouldWrite: [],
+        hash,
+        refreshedAt: stats.mtime.toISOString(),
+        dryRun: false,
+        bodyPreview: rawBody
+    });
+}
+// Re-export for callers that import the normalizer from this module.
+export { normalizePlanBody };
+// Helper for the CLI to use the same body builder.
+export function renderPlanBody(args) {
+    return args.type === 'security' ? buildSecurityPlanBody(args.project) : buildPerfPlanBody(args.project);
+}
+// hash helper for tests that want to assert a body against a fixture.
+export function hashBody(body) {
+    return hashNormalizedBody(body);
+}

package/dist/src/services/workflow/plan-trigger-detector.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `peaks workflow plan detect-trigger` — slice 025 (Security + Perf
+ * Plan/Result split).
+ *
+ * Compares the current project state (filesystem + package.json) to the
+ * last-refresh fingerprint and returns whether a plan refresh is
+ * warranted. Five trigger rules, locked decision 1 excludes
+ * devDependencies.
+ *
+ * The slice's "diff" is supplied as a `SliceDiff` object; when not
+ * supplied, the detector scans the project directly (the same scan the
+ * refresh plan performs).
+ */
+import { type ResultEnvelope } from '../../shared/result.js';
+export type TriggerReason = 'new-dependency' | 'auth-surface-added' | 'hot-path-added' | 'manual-override' | 'no-change' | 'no-triggering-change';
+/** F-1 (slice 025 security): canonical request-id shape. */
+export declare const REQUEST_ID_PATTERN: RegExp;
+export interface DetectTriggerArgs {
+    readonly project: string;
+    readonly rid: string;
+    readonly sessionId: string;
+    /** Optional slice diff — when provided, takes precedence over a fresh
+     * filesystem scan. Shape mirrors the `peaks request diff <rid> --json`
+     * output's `packageJson` field. */
+    readonly diff?: SliceDiff | null;
+    /** When true, the caller is the slice workflow with `--refresh` set.
+     * Forces triggered=true. Per PRD trigger table. */
+    readonly manualOverride?: boolean;
+}
+export interface SliceDiff {
+    readonly packageJson?: {
+        readonly dependencies?: {
+            readonly added?: readonly string[];
+            readonly removed?: readonly string[];
+            readonly changed?: readonly string[];
+        };
+        readonly optionalDependencies?: {
+            readonly added?: readonly string[];
+            readonly removed?: readonly string[];
+            readonly changed?: readonly string[];
+        };
+        readonly devDependencies?: {
+            readonly added?: readonly string[];
+            readonly removed?: readonly string[];
+            readonly changed?: readonly string[];
+        };
+    };
+    readonly newFiles?: readonly string[];
+    readonly changedFiles?: readonly string[];
+}
+export interface DetectTriggerData {
+    readonly triggered: boolean;
+    readonly reason: TriggerReason;
+}
+export declare function detectTrigger(args: DetectTriggerArgs): ResultEnvelope<DetectTriggerData>;