peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/memory-rotate-command.js

@@ -0,0 +1,55 @@
+// src/cli/commands/memory-rotate-command.ts
+//
+// `peaks memory rotate` — tier-driven retention for `.peaks/memory/`
+// (sediment pruning policy, tier 1: archive, never delete). Dry-run by default;
+// `--apply` moves tier-C candidates into `archived/`. Extracted from
+// `memory-commands.ts`; the envelope, the flags and the exported symbol name
+// are unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { executeMemoryRotate } from '../../services/memory/memory-rotate-service.js';
+import { printResult } from '../cli-helpers.js';
+import { memoryFailure, resolveMemoryProjectRoot } from './memory-command-shared.js';
+export async function runMemoryRotate(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('memory.rotate', 'INVALID_MEMORY_ROTATE_FLAGS', 'Use either --dry-run or --apply, not both', {}, [
+            'Run without --apply to preview the rotation plan, or pass --apply to archive tier-C candidates'
+        ]), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const report = executeMemoryRotate({ projectRoot, apply: options.apply === true });
+        printResult(io, ok('memory.rotate', report, report.warnings, rotateNextActions(report, options)), options.json);
+        if (report.refused)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        printResult(io, memoryFailure({
+            command: 'memory.rotate',
+            fallbackCode: 'MEMORY_ROTATE_FAILED',
+            error,
+            projectRoot,
+            suggestions: ['Check that the project has a readable .peaks/memory directory']
+        }), options.json);
+        process.exitCode = 1;
+    }
+}
+/** The refusal / preview / exclusion / tier-D notices the plan earns, in order. */
+function rotateNextActions(report, options) {
+    const nextActions = [];
+    if (report.refused) {
+        nextActions.push(`Refused to apply: ${report.refusalReasons.join('; ')}`);
+    }
+    else if (options.apply !== true) {
+        nextActions.push('Preview only — re-run with --apply to move the tier-C candidates into archived/.');
+    }
+    if (report.excluded.length > 0) {
+        nextActions.push(`${report.excluded.length} candidate(s) excluded by a safety gate (see \`excluded\`).`);
+    }
+    const deleteCandidates = report.candidates.filter((candidate) => candidate.action === 'delete-candidate');
+    if (deleteCandidates.length > 0) {
+        nextActions.push(`${deleteCandidates.length} tier-D file(s) are delete-candidates only; peaks never deletes them — remove by hand if you are sure.`);
+    }
+    return nextActions;
+}

package/dist/cli/commands/memory-search-command.d.ts

@@ -0,0 +1,7 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type MemorySearchCommandOptions } from './memory-command-shared.js';
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export declare function runMemorySearch(io: ProgramIO, options: MemorySearchCommandOptions): Promise<void>;

package/dist/cli/commands/memory-search-command.js

@@ -0,0 +1,46 @@
+// src/cli/commands/memory-search-command.ts
+//
+// `peaks memory search` — deterministic, local, zero-token fuzzy search over
+// the memory index. Extracted from `memory-commands.ts`; the envelope, the
+// flags and the exported symbol name are unchanged.
+import { ok } from 'peaks-loop-shared/result';
+import { searchMemory } from '../../services/memory/memory-search-service.js';
+import { printResult } from '../cli-helpers.js';
+import { memoryFailure, resolveKindFilter, resolveMemoryProjectRoot } from './memory-command-shared.js';
+/** The one action each named failure earns. */
+const SEARCH_HINTS = {
+    INDEX_MISSING: 'Run `peaks memory extract --apply` to build the index from memory/*.md files',
+    EMPTY_QUERY: 'Use `peaks memory index` to list all entries'
+};
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export async function runMemorySearch(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    const kindFilter = resolveKindFilter(options.kind);
+    try {
+        const matches = searchMemory({
+            query: options.query,
+            projectRoot,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(kindFilter !== undefined ? { kind: kindFilter } : {})
+        });
+        printResult(io, ok('memory.search', {
+            query: options.query,
+            total: matches.length,
+            matches,
+            warnings: []
+        }, []), options.json);
+    }
+    catch (error) {
+        printResult(io, memoryFailure({
+            command: 'memory.search',
+            fallbackCode: 'MEMORY_SEARCH_FAILED',
+            error,
+            projectRoot,
+            byCode: SEARCH_HINTS
+        }), options.json);
+        process.exitCode = 1;
+    }
+}

package/dist/cli/commands/openspec-archive-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerOpenSpecArchiveCommand(openspec: Command, io: ProgramIO): void;

package/dist/cli/commands/openspec-archive-command.js

@@ -0,0 +1,55 @@
+// src/cli/commands/openspec-archive-command.ts
+//
+// `peaks openspec archive <changeId>`. Extracted from `openspec-commands.ts`;
+// the registered name, description, options and envelopes are unchanged.
+import { archiveOpenSpecChange, OpenSpecArchiveError } from '../../services/openspec/openspec-archive-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec, OPENSPEC_PATH_HINT, printArchiveError, printChangeNotFound, toArchiveOptions } from './openspec-command-shared.js';
+/** The `--force` bypasses an archived run reports, in a fixed order. */
+function archiveWarnings(result) {
+    const warnings = [];
+    if (result.coverageGateBypassed === true) {
+        warnings.push('Coverage gate bypassed via --force; archived with at least one uncovered requirement.');
+    }
+    if (result.coverageMismatchBypassed === true) {
+        warnings.push('Coverage summary mismatch bypassed via --force; archived with at least one capability below 100%.');
+    }
+    return warnings;
+}
+const ARCHIVE_DESCRIPTION = 'Move an OpenSpec change under openspec/changes/<archiveDir>/<id>/ (dry-run by default)';
+const FORCE_DESCRIPTION = 'bypass the Pre-cond 2 Coverage Evidence gate (use only after confirming the gap is acceptable for this archive)';
+const COVERAGE_SUMMARY_DESCRIPTION = 'override coverage-summary.json discovery (Fix-6B). Default: <projectRoot>/coverage/coverage-summary.json, then <projectRoot>/openspec/coverage-summary.json';
+export function registerOpenSpecArchiveCommand(openspec, io) {
+    addJsonOption(openspec
+        .command('archive')
+        .description(ARCHIVE_DESCRIPTION)
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--apply', 'actually move the change directory')
+        .option('--force', FORCE_DESCRIPTION)
+        .option('--coverage-summary <path>', COVERAGE_SUMMARY_DESCRIPTION)
+        .option('--archive-dir <name>', 'archive subdirectory name (default: archive)')).action(async (changeId, options) => {
+        try {
+            const result = await archiveOpenSpecChange(changeId, toArchiveOptions(options.project, options));
+            if (result === null) {
+                printChangeNotFound(io, 'openspec.archive', changeId, options.json);
+                return;
+            }
+            printResult(io, ok('openspec.archive', result, archiveWarnings(result), result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
+        }
+        catch (error) {
+            if (error instanceof OpenSpecArchiveError) {
+                printArchiveError(io, error, options.json);
+                return;
+            }
+            failOpenSpec(io, 'openspec.archive', {
+                code: 'OPENSPEC_ARCHIVE_FAILED',
+                error,
+                data: { changeId },
+                nextActions: OPENSPEC_PATH_HINT,
+                json: options.json
+            });
+        }
+    });
+}

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

@@ -0,0 +1,62 @@
+import type { OpenSpecScanOptions } from '../../services/openspec/openspec-scan-service.js';
+import type { OpenSpecArchiveError, OpenSpecArchiveOptions } from '../../services/openspec/openspec-archive-service.js';
+import type { OpenSpecRenderOptions, OpenSpecRenderRequest } from '../../services/openspec/openspec-render-service.js';
+import type { OpenSpecValidateOptions } from '../../services/openspec/openspec-validate-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type OpenSpecListOptions = {
+    project?: string;
+    json?: boolean;
+};
+export type OpenSpecShowOptions = OpenSpecListOptions;
+export type OpenSpecToRdOptions = OpenSpecListOptions;
+export type OpenSpecRenderCommandOptions = OpenSpecListOptions & {
+    request: string;
+    apply?: boolean;
+    overwrite?: boolean;
+};
+export type OpenSpecValidateCommandOptions = OpenSpecListOptions & {
+    preferExternal?: boolean;
+};
+export type OpenSpecArchiveCommandOptions = OpenSpecListOptions & {
+    apply?: boolean;
+    force?: boolean;
+    coverageSummary?: string;
+    archiveDir?: string;
+};
+export type OpenSpecInitCommandOptions = {
+    project: string;
+    apply?: boolean;
+    json?: boolean;
+};
+/** The next action every path/layout failure carries. */
+export declare const OPENSPEC_PATH_HINT: string[];
+/** Everything a verb-specific catch needs to build its failure envelope. */
+export type OpenSpecFailure = {
+    readonly code: string;
+    readonly error: unknown;
+    readonly nextActions: string[];
+    readonly json: boolean | undefined;
+    readonly data?: Record<string, unknown>;
+};
+export declare function resolveScanOptions(project: string | undefined): OpenSpecScanOptions;
+export declare function loadRenderRequest(requestPath: string): Promise<OpenSpecRenderRequest>;
+/** Print a verb failure and mark the run failed. One call site per catch. */
+export declare function failOpenSpec(io: ProgramIO, command: string, failure: OpenSpecFailure): void;
+/** The `<changeId>` resolution every change-scoped verb shares. */
+export declare function printChangeNotFound(io: ProgramIO, command: string, changeId: string, json: boolean | undefined): void;
+/**
+ * Translate `--project` into the service option shape, carrying only the flags
+ * the caller actually set (a `false`/`undefined` flag must stay absent, not be
+ * written as `false`).
+ */
+export declare function toRenderOptions(project: string | undefined, options: OpenSpecRenderCommandOptions): OpenSpecRenderOptions;
+export declare function toValidateOptions(project: string | undefined, options: OpenSpecValidateCommandOptions): OpenSpecValidateOptions;
+export declare function toArchiveOptions(project: string | undefined, options: OpenSpecArchiveCommandOptions): OpenSpecArchiveOptions;
+/**
+ * Per-error-code remediation hints for the archive gate.
+ * Centralized here so the catch block stays readable and the next-actions
+ * can be reviewed in isolation.
+ */
+export declare function nextActionsForArchiveError(code: OpenSpecArchiveError['code']): string[];
+/** The `openspec.archive` failure envelope for the gate's own error class. */
+export declare function printArchiveError(io: ProgramIO, error: OpenSpecArchiveError, json: boolean | undefined): void;

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

@@ -0,0 +1,135 @@
+// src/cli/commands/openspec-command-shared.ts
+//
+// The option shapes, flag translation and envelope printers shared by every
+// `peaks openspec <verb>` subcommand module. Split out of
+// `openspec-commands.ts` so each verb can live in its own file without
+// repeating the `fail(...)` boilerplate eight times.
+import { readFile } from 'node:fs/promises';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { normalizePath } from '../../shared/path-utils.js';
+import { fail } from 'peaks-loop-shared/result';
+/** The next action every path/layout failure carries. */
+export const OPENSPEC_PATH_HINT = [
+    'Check the project path and openspec/ layout before retrying'
+];
+export function resolveScanOptions(project) {
+    if (project === undefined) {
+        return {};
+    }
+    return { openspecRoot: `${normalizePath(project).replace(/\/$/, '')}/openspec` };
+}
+export async function loadRenderRequest(requestPath) {
+    const raw = await readFile(requestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Render request file must contain a JSON object');
+    }
+    return parsed;
+}
+/** Print a verb failure and mark the run failed. One call site per catch. */
+export function failOpenSpec(io, command, failure) {
+    printResult(io, fail(command, failure.code, getErrorMessage(failure.error), failure.data ?? {}, failure.nextActions), failure.json);
+    process.exitCode = 1;
+}
+/** The `<changeId>` resolution every change-scoped verb shares. */
+export function printChangeNotFound(io, command, changeId, json) {
+    printResult(io, fail(command, 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), json);
+    process.exitCode = 1;
+}
+const ROOT_KEY = 'openspecRoot';
+/**
+ * Translate `--project` into the service option shape, carrying only the flags
+ * the caller actually set (a `false`/`undefined` flag must stay absent, not be
+ * written as `false`).
+ */
+export function toRenderOptions(project, options) {
+    const renderOptions = {};
+    const scan = resolveScanOptions(project);
+    if (scan.openspecRoot !== undefined) {
+        renderOptions[ROOT_KEY] = scan.openspecRoot;
+    }
+    if (options.apply === true) {
+        renderOptions.apply = true;
+    }
+    if (options.overwrite === true) {
+        renderOptions.overwrite = true;
+    }
+    return renderOptions;
+}
+export function toValidateOptions(project, options) {
+    const validateOptions = {};
+    const scan = resolveScanOptions(project);
+    if (scan.openspecRoot !== undefined) {
+        validateOptions[ROOT_KEY] = scan.openspecRoot;
+    }
+    if (options.preferExternal === true) {
+        validateOptions.preferExternal = true;
+    }
+    return validateOptions;
+}
+export function toArchiveOptions(project, options) {
+    const archiveOptions = {};
+    const scan = resolveScanOptions(project);
+    if (scan.openspecRoot !== undefined) {
+        archiveOptions[ROOT_KEY] = scan.openspecRoot;
+    }
+    if (options.apply === true) {
+        archiveOptions.apply = true;
+    }
+    if (options.force === true) {
+        archiveOptions.force = true;
+    }
+    if (options.coverageSummary !== undefined) {
+        archiveOptions.coverageSummaryPath = options.coverageSummary;
+    }
+    if (options.archiveDir !== undefined) {
+        archiveOptions.archiveDirName = options.archiveDir;
+    }
+    return archiveOptions;
+}
+/**
+ * Per-error-code remediation hints for the archive gate.
+ * Centralized here so the catch block stays readable and the next-actions
+ * can be reviewed in isolation.
+ */
+export function nextActionsForArchiveError(code) {
+    switch (code) {
+        case 'OPENSPEC_COVERAGE_GATE_PARTIAL':
+            return [
+                'Update the Coverage Evidence table to mark each failing requirement as covered',
+                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
+            ];
+        case 'OPENSPEC_COVERAGE_GATE_FAILED':
+            return [
+                'Add the missing Coverage Evidence or Capability Mapping block to proposal.md (see error.message)',
+                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED':
+            return [
+                'Fix the proposal.md Coverage Evidence table — the heading exists but no parsable rows were found',
+                'Expected shape: | capability | requirement | status | testAnchor | with status in {covered, partial, uncovered}'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_MISSING':
+            return [
+                'Run `pnpm test:coverage` (which invokes scripts/coverage-c8.mjs) to generate coverage-summary.json',
+                'Or pass --coverage-summary <path> to point at an existing summary',
+                'Or re-run with --force to bypass the gate'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_STALE':
+            return [
+                'Re-run `pnpm test:coverage` to refresh coverage-summary.json',
+                'Or re-run with --force to bypass the gate after confirming the source delta is acceptable'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_MISMATCH':
+            return [
+                'Inspect error.detail.mismatches[] — each entry lists the failing capability, file, and actual pct',
+                'Close the coverage gap (add tests or update the Capability Mapping block in proposal.md)',
+                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
+            ];
+    }
+}
+/** The `openspec.archive` failure envelope for the gate's own error class. */
+export function printArchiveError(io, error, json) {
+    printResult(io, fail('openspec.archive', error.code, getErrorMessage(error), error.detail, nextActionsForArchiveError(error.code)), json);
+    process.exitCode = 1;
+}

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

@@ -1,3 +1,3 @@
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerOpenSpecCommands(program: Command, io: ProgramIO): void;