peaks-loop 4.1.2 → 4.1.3

package/dist/cli/commands/request-transition-preflight.js

@@ -0,0 +1,107 @@
+// Split out of `request-commands.ts`: the
+// pre-transition refusals `peaks request transition` runs before it touches an
+// artifact — session-id resolution, the `--allow-incomplete` reason rule, and
+// the assisted/strict-mode bypass gate.
+import { join } from 'node:path';
+import { fail } from 'peaks-loop-shared/result';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { printResult } from '../cli-helpers.js';
+import { isBypassLimitReached, recordBypass, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
+import { showRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+function refuseInvalidSession(io, options, resolvedSessionId) {
+    printResult(io, fail('request.transition', 'INVALID_SESSION_ID', `Invalid session id: ${resolvedSessionId} (must be a single path segment)`, { provided: resolvedSessionId }, ['Pass a session id that is a single path segment']), options.json);
+    process.exitCode = 1;
+}
+/**
+ * Resolve the artifact's real session up front. Falling back to a literal
+ * 'default' (the previous behavior) points the bypass counter at a
+ * non-existent .peaks/default/ dir and crashes with ENOENT, so when
+ * --session-id is omitted we look the artifact up to find its session.
+ * Returns `null` when a refusal was printed.
+ */
+async function resolveTransitionSessionId(io, requestId, role, options) {
+    let resolvedSessionId = options.sessionId;
+    // Sid axis: either arm of `resolvedSessionId` can be a caller-supplied
+    // `--session-id`, and it is joined into the bypass-counter root below.
+    if (resolvedSessionId !== undefined && isUnsafePathInput(resolvedSessionId)) {
+        refuseInvalidSession(io, options, resolvedSessionId);
+        return null;
+    }
+    if (resolvedSessionId === undefined) {
+        const located = await showRequestArtifact({ projectRoot: options.project, role, requestId });
+        if (located !== null) {
+            resolvedSessionId = located.sessionId;
+        }
+    }
+    return resolvedSessionId;
+}
+function refuseBypassReasonRequired(io, ctx) {
+    printResult(io, fail('request.transition', 'BYPASS_REASON_REQUIRED', '--allow-incomplete requires --reason explaining why prerequisites are skipped', { role: ctx.role, requestId: ctx.requestId }, [
+        'Add --reason "<short justification>" or remove --allow-incomplete and produce the missing artifacts'
+    ]), ctx.options.json);
+    process.exitCode = 1;
+}
+function refuseAllowIncompleteRestricted(io, ctx, mode) {
+    printResult(io, fail('request.transition', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${mode} mode`, { role: ctx.role, requestId: ctx.requestId, mode }, [
+        'Ask the user via AskUserQuestion whether to proceed, then re-run with --confirm if they approve.'
+    ]), ctx.options.json);
+    process.exitCode = 1;
+}
+function refuseBypassLimitReached(io, ctx) {
+    printResult(io, fail('request.transition', 'BYPASS_LIMIT_REACHED', `--allow-incomplete limit reached (${MAX_BYPASSES_PER_SESSION} per session)`, { role: ctx.role, requestId: ctx.requestId, limit: MAX_BYPASSES_PER_SESSION }, ['Produce the missing artifacts instead of bypassing.']), ctx.options.json);
+    process.exitCode = 1;
+}
+/**
+ * Restrict --allow-incomplete in assisted/strict modes: require --confirm,
+ * then count the bypass under the canonical session home
+ * `.peaks/_runtime/<sid>/`, NOT `.peaks/_runtime/<sid>/`. The legacy path
+ * landed `.bypass-count.json` at the project root and was ignored only by
+ * `.gitignore`, not by the runtime — a back-compat reader on the root would
+ * never see it. The canonical home is the same one `peaks session info
+ * --active` resolves from `_runtime/session.json`, so all session-scoped state
+ * (artifacts + bypass counter) now lives in one tree.
+ */
+async function applyRestrictedBypassGate(io, ctx) {
+    const { options, resolvedSessionId } = ctx;
+    const { getSkillPresence } = await import('../../services/skills/skill-presence-service.js');
+    const presence = getSkillPresence(options.project);
+    if (!(presence?.mode === 'assisted' || presence?.mode === 'strict'))
+        return true;
+    if (options.confirm !== true) {
+        refuseAllowIncompleteRestricted(io, ctx, presence.mode);
+        return false;
+    }
+    const sessionRoot = join(options.project, '.peaks', '_runtime', resolvedSessionId ?? 'default');
+    if (isBypassLimitReached(sessionRoot)) {
+        refuseBypassLimitReached(io, ctx);
+        return false;
+    }
+    recordBypass(sessionRoot);
+    return true;
+}
+async function checkBypassPreconditions(io, ctx) {
+    const { options } = ctx;
+    if (options.allowIncomplete === true &&
+        (options.reason === undefined || options.reason.trim().length === 0)) {
+        refuseBypassReasonRequired(io, ctx);
+        return false;
+    }
+    if (options.allowIncomplete === true && options.forceConfirm !== true) {
+        return applyRestrictedBypassGate(io, ctx);
+    }
+    return true;
+}
+export async function runTransitionPreflight(io, requestId, role, options) {
+    const resolvedSessionId = await resolveTransitionSessionId(io, requestId, role, options);
+    if (resolvedSessionId === null)
+        return { proceed: false };
+    const allowed = await checkBypassPreconditions(io, {
+        requestId,
+        role,
+        options,
+        resolvedSessionId
+    });
+    if (!allowed)
+        return { proceed: false };
+    return { proceed: true, resolvedSessionId };
+}

package/dist/cli/commands/scan-command-shared.d.ts

@@ -0,0 +1,96 @@
+import { type RequestType } from '../../services/artifacts/artifact-prerequisites.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ArchetypeOptions = {
+    project: string;
+    json?: boolean;
+};
+export type ExistingSystemOptions = {
+    project: string;
+    maxTokens?: string;
+    maxSamples?: string;
+    json?: boolean;
+};
+export type RequestTypeSanityOptions = {
+    project: string;
+    type: RequestType;
+    baseRef?: string;
+    json?: boolean;
+};
+export type FileSizeScanOptions = {
+    project: string;
+    baseRef?: string;
+    threshold?: string;
+    json?: boolean;
+};
+export type ScanLibrariesOptions = {
+    project: string;
+    json?: boolean;
+};
+export type AcceptanceCoverageOptions = {
+    rid: string;
+    project: string;
+    sessionId?: string;
+    json?: boolean;
+};
+export type DiffVsScopeOptions = {
+    rid: string;
+    project: string;
+    sessionId?: string;
+    baseRef?: string;
+    json?: boolean;
+};
+/** `--format` accepts exactly these two values across the report subcommands. */
+export type ScanOutputFormat = 'md' | 'json';
+export type ApiSurfaceOptions = {
+    project: string;
+    format?: ScanOutputFormat;
+    includeDirs?: string;
+    maxPerKind?: number;
+    json?: boolean;
+};
+export type OrphanScope = 'working-tree' | 'git-diff' | 'all';
+export type OrphanOptions = {
+    project: string;
+    format?: ScanOutputFormat;
+    scope?: OrphanScope;
+    strict?: boolean;
+    json?: boolean;
+};
+export type KarpathyScope = 'working-tree' | 'all';
+export type KarpathyOptions = {
+    project: string;
+    format?: ScanOutputFormat;
+    scope?: KarpathyScope;
+    json?: boolean;
+};
+export declare function parsePositiveInt(value: string | undefined, fallback: number): number;
+export declare function parseOptionalNonNegativeInt(value: string | undefined): number | undefined;
+export declare function parseRequestType(value: string): RequestType;
+export declare function parseScanOutputFormat(value: string): ScanOutputFormat;
+export declare function parseNonNegativeIntOption(value: string): number;
+export declare function parseOrphanScope(value: string): OrphanScope;
+export declare function parseKarpathyScope(value: string): KarpathyScope;
+/**
+ * Everything `emitScanReport` needs. `renderMarkdown` is a thunk because the
+ * original callbacks built the markdown at this exact point in the flow — after
+ * the `--format json` branches have returned — and it must stay lazy so a
+ * `--format json` run never renders markdown it would throw away.
+ */
+export type ScanReportOutput = {
+    command: string;
+    format?: ScanOutputFormat | undefined;
+    json?: boolean | undefined;
+    report: unknown;
+    nextActions: string[];
+    renderMarkdown: () => string;
+};
+/**
+ * The output contract shared by `scan api-surface`, `scan orphan` and
+ * `scan karpathy`:
+ *   - `--format json` without `--json` writes the bare report (no envelope);
+ *   - `--format json` with `--json` writes the ok/data/code envelope;
+ *   - otherwise markdown goes to stdout, and `--json` wraps it as
+ *     `{ markdown, report }` while the human path prints "Next actions:" to
+ *     stderr only when there is at least one.
+ */
+export declare function emitScanReport(io: ProgramIO, output: ScanReportOutput): void;

package/dist/cli/commands/scan-command-shared.js

@@ -0,0 +1,83 @@
+// Shared plumbing for the `peaks scan` subcommands, extracted from
+// scan-commands.ts so that no single file (or function) has to carry ten
+// subcommands at once. Everything here is parameter-in / value-out: the option
+// shapes each runner receives, the parsers the command definitions hand to
+// Commander as option-processing callbacks, and the two output shapes the
+// report commands share (the format-aware envelope / markdown / raw-JSON
+// writer and its "Next actions:" tail).
+//
+// Dependency direction is one-way: this module never imports scan-commands.ts.
+import { InvalidArgumentError } from 'commander';
+import { ok } from 'peaks-loop-shared/result';
+import { isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
+import { printResult } from '../cli-helpers.js';
+export function parsePositiveInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d+$/.test(value))
+        return fallback;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function parseOptionalNonNegativeInt(value) {
+    return value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined;
+}
+export function parseRequestType(value) {
+    if (!isRequestType(value)) {
+        throw new InvalidArgumentError(`must be one of ${VALID_REQUEST_TYPES.join(', ')}`);
+    }
+    return value;
+}
+export function parseScanOutputFormat(value) {
+    if (value !== 'md' && value !== 'json') {
+        throw new InvalidArgumentError('must be md or json');
+    }
+    return value;
+}
+export function parseNonNegativeIntOption(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('must be a non-negative integer');
+    }
+    return Number(value);
+}
+export function parseOrphanScope(value) {
+    if (value !== 'working-tree' && value !== 'git-diff' && value !== 'all') {
+        throw new InvalidArgumentError('must be working-tree, git-diff, or all');
+    }
+    return value;
+}
+export function parseKarpathyScope(value) {
+    if (value !== 'working-tree' && value !== 'all') {
+        throw new InvalidArgumentError('must be working-tree or all');
+    }
+    return value;
+}
+/**
+ * The output contract shared by `scan api-surface`, `scan orphan` and
+ * `scan karpathy`:
+ *   - `--format json` without `--json` writes the bare report (no envelope);
+ *   - `--format json` with `--json` writes the ok/data/code envelope;
+ *   - otherwise markdown goes to stdout, and `--json` wraps it as
+ *     `{ markdown, report }` while the human path prints "Next actions:" to
+ *     stderr only when there is at least one.
+ */
+export function emitScanReport(io, output) {
+    if (output.format === 'json' && !output.json) {
+        // Raw JSON without the ok/data/code envelope.
+        process.stdout.write(JSON.stringify(output.report, null, 2) + '\n');
+        return;
+    }
+    if (output.format === 'json') {
+        printResult(io, ok(output.command, output.report, [], output.nextActions), output.json);
+        return;
+    }
+    const md = output.renderMarkdown();
+    if (output.json) {
+        printResult(io, ok(output.command, { markdown: md, report: output.report }, [], output.nextActions), output.json);
+        return;
+    }
+    process.stdout.write(md + '\n');
+    if (output.nextActions.length > 0) {
+        process.stderr.write('\nNext actions:\n' + output.nextActions.map((a) => '  - ' + a).join('\n') + '\n');
+    }
+}

package/dist/cli/commands/scan-commands.d.ts

@@ -1,3 +1,4 @@
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export type { AcceptanceCoverageOptions, ApiSurfaceOptions, ArchetypeOptions, DiffVsScopeOptions, ExistingSystemOptions, FileSizeScanOptions, KarpathyOptions, KarpathyScope, OrphanOptions, OrphanScope, RequestTypeSanityOptions, ScanLibrariesOptions, ScanOutputFormat, ScanReportOutput } from './scan-command-shared.js';
 export declare function registerScanCommands(program: Command, io: ProgramIO): void;