peaks-cli 1.3.9 → 1.4.1

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>;

package/dist/src/services/workflow/plan-trigger-detector.js

@@ -0,0 +1,142 @@
+/**
+ * `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 { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, ok } from '../../shared/result.js';
+/** F-1 (slice 025 security): canonical request-id shape. */
+export const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+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 isAuthFile(path) {
+    return /auth.*\.ts$|\.ts$/i.test(path) && /auth/i.test(path);
+}
+function isHotPathFile(path) {
+    return /router\.ts$|commands\/.*-commands\.ts$/i.test(path);
+}
+function isSensitiveServiceFile(path) {
+    if (!/^src\/services\/(auth|security|secrets|payments|filesystem)\//.test(path))
+        return false;
+    return /\.ts$/.test(path);
+}
+function freshScan(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    const newFiles = [];
+    const root = join(projectRoot, 'src');
+    if (existsSync(root)) {
+        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() && entry.name.endsWith('.ts')) {
+                    // For the purposes of trigger detection, every TS file is a
+                    // candidate; the gate logic decides which class it falls into.
+                    newFiles.push(full);
+                }
+            }
+        }
+    }
+    return {
+        packageJson: {
+            dependencies: { added: Object.keys(pkg?.dependencies ?? {}), removed: [], changed: [] },
+            optionalDependencies: { added: Object.keys(pkg?.optionalDependencies ?? {}), removed: [], changed: [] },
+            devDependencies: { added: Object.keys(pkg?.devDependencies ?? {}), removed: [], changed: [] }
+        },
+        newFiles: newFiles.sort(),
+        changedFiles: []
+    };
+}
+function anyAddedDeps(diff) {
+    const dep = diff.packageJson?.dependencies?.added ?? [];
+    const opt = diff.packageJson?.optionalDependencies?.added ?? [];
+    return dep.length > 0 || opt.length > 0;
+}
+function findNewAuthFile(diff) {
+    for (const f of diff.newFiles ?? []) {
+        if (isAuthFile(f))
+            return f;
+    }
+    return null;
+}
+function findNewSensitiveServiceFile(diff) {
+    for (const f of diff.newFiles ?? []) {
+        if (isSensitiveServiceFile(f))
+            return f;
+    }
+    return null;
+}
+function findNewHotPathFile(diff) {
+    for (const f of diff.newFiles ?? []) {
+        if (isHotPathFile(f))
+            return f;
+    }
+    return null;
+}
+export function detectTrigger(args) {
+    // F-1 (slice 025 security): reject traversal/separator payloads at
+    // the service boundary so every caller (CLI, skill, integration test)
+    // gets the same rejection shape.
+    if (!REQUEST_ID_PATTERN.test(args.rid)) {
+        return fail('workflow.plan.detect-trigger', 'INVALID_RID', 'request id must match [A-Za-z0-9][A-Za-z0-9._-]*', {
+            triggered: false,
+            reason: 'no-triggering-change'
+        });
+    }
+    if (args.manualOverride === true) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'manual-override' });
+    }
+    const diff = args.diff ?? freshScan(args.project);
+    // Rule 1: new top-level dependency in `dependencies` or `optionalDependencies`
+    // (devDependencies explicitly excluded per locked decision 1).
+    if (anyAddedDeps(diff)) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'new-dependency' });
+    }
+    // Rule 2: new file under src/services/{auth,security,secrets,payments,filesystem}/
+    if (findNewSensitiveServiceFile(diff) !== null) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'auth-surface-added' });
+    }
+    // Rule 3: new *auth*.ts file anywhere in src/
+    if (findNewAuthFile(diff) !== null) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'auth-surface-added' });
+    }
+    // Rule 4: new endpoint / route registration
+    if (findNewHotPathFile(diff) !== null) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'hot-path-added' });
+    }
+    return ok('workflow.plan.detect-trigger', { triggered: false, reason: 'no-triggering-change' });
+}

package/dist/src/services/workspace/migrate-1-4-1-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004.
+ *
+ * Cleanup command for projects upgraded from peaks-cli 1.4.1 → 1.4.2.
+ *
+ * Slice 006 (1.4.0) moved the canonical per-session root to
+ * `.peaks/_runtime/<sid>/`. Per-request artifacts (PRD, RD, QA, SC requests)
+ * were written to the new root, but per-session artifacts (tech-doc.md,
+ * code-review.md, test-cases/<rid>.md, etc.) were kept at the legacy
+ * `.peaks/<sid>/<role>/<file>.md` path. The 2-tier fallback in
+ * `resolvePrerequisiteAbsolutePathWithFallback` accepts either location, so
+ * the functional behavior is correct, but the user's filesystem has visible
+ * dual-path duplication ("飘逸" — the user's term for the UX).
+ *
+ * R004 ships this command to physically move the legacy per-session files
+ * into the canonical `_runtime/<sid>/<role>/` location. After this runs,
+ * the project has a single canonical tree; the legacy `<sid>/<role>/`
+ * directories are removed (only if empty after the move).
+ *
+ * Default: dry-run. Pass `--apply` to actually move.
+ */
+export declare const PER_SESSION_ARTIFACT_TYPES: readonly ["rd/tech-doc.md", "rd/code-review.md", "rd/security-review.md", "rd/perf-baseline.md", "rd/bug-analysis.md", "qa/security-findings.md", "qa/performance-findings.md"];
+export declare const PER_REQUEST_ARTIFACT_TYPES: readonly ["qa/test-cases/<rid>.md", "qa/test-reports/<rid>.md"];
+export type MigrationPlanEntry = {
+    readonly sessionId: string;
+    readonly relativePath: string;
+    readonly from: string;
+    readonly to: string;
+    readonly sha256: string;
+    readonly reason: 'legacy-only' | 'identical-content-already-canonical' | 'content-mismatch' | 'no-legacy-file';
+};
+export type MigrationResult = {
+    readonly plan: ReadonlyArray<MigrationPlanEntry>;
+    readonly applied: boolean;
+    readonly movedCount: number;
+    readonly conflictCount: number;
+    readonly deletedEmptyDirs: ReadonlyArray<string>;
+    readonly errors: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+};
+export declare function planMigrate1_4_1(projectRoot: string): MigrationResult;
+export declare function applyMigrate1_4_1(projectRoot: string): MigrationResult;