peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/loop-goal-compose-command.js

@@ -0,0 +1,36 @@
+// src/cli/commands/loop-goal-compose-command.ts
+//
+// `peaks goal compose` — registered as a TOP-LEVEL command (not under
+// `peaks loop`) because IDE adapters expose it as `goalCommand` and the
+// sub-agent dispatch path consumes it. Extracted from `loop-commands.ts`; the
+// registered name, description, options and envelope are unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const GOAL_COMPOSE_SUMMARY = 'goal.compose is a thin facade; the LLM-side UX layer decomposes the goal into sub-agent tasks.';
+export function registerLoopGoalComposeCommand(program, io) {
+    addJsonOption(program
+        .command('goal')
+        .description('14.5: compose an autonomous goal (returns the goal envelope that the LLM-side UX layer feeds to peaks sub-agent dispatch)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--goal <text>', 'the high-level goal to compose')).action((options) => {
+        try {
+            printResult(io, ok('goal.compose', goalComposePayload(options), [], [GOAL_COMPOSE_SUMMARY]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('goal.compose', 'GOAL_COMPOSE_FAILED', getErrorMessage(error), { project: options.project, goal: options.goal }, ['Verify the project path and --goal value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+/** The placeholder body; the LLM-side UX layer decomposes `goal` into tasks. */
+function goalComposePayload(options) {
+    return {
+        project: options.project,
+        goal: options.goal,
+        status: 'placeholder',
+        nextSteps: [
+            'The composed goal is consumed by peaks sub-agent dispatch.',
+            'The hermes + openclaw IDE adapters (Slice #0.7) surface this as a goalCommand.'
+        ]
+    };
+}

package/dist/cli/commands/loop-import-command.d.ts

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

package/dist/cli/commands/loop-import-command.js

@@ -0,0 +1,86 @@
+// src/cli/commands/loop-import-command.ts
+//
+// `peaks loop import` (M7, spec §7A.2) — extract a `peaks.bundle/1` tarball and
+// land it as `candidate` only; promotion needs an evolution_evaluation row.
+// Extracted from `loop-commands.ts`; the registered name, description, options,
+// refusal codes and envelope are unchanged.
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { BundleImportToStableForbiddenError, BundleMajorVersionMismatchError, BundleMalformedError, BundleSchemaVersionsMismatchError, readBundle } from '../../services/share/bundle-reader.js';
+import { printResult } from '../cli-helpers.js';
+import { LOOP_EXPORT_IMPORT_OPTS, resolveLoopProjectRoot } from './loop-command-shared.js';
+export function registerLoopImportCommand(loop, io) {
+    LOOP_EXPORT_IMPORT_OPTS(loop
+        .command('import')
+        .description('M7: import a peaks.bundle/1 tarball. Lands as candidate only — promotion requires an evolution_evaluation row (spec §7A.2 / §10 RL-9 / AC-25 / AC-26).')
+        .requiredOption('--in <path>', 'input .tar.gz path')
+        .option('--as <id>', 'optional rename for the loop id when landing')).action((options) => {
+        const asJson = options.json === true;
+        try {
+            const result = importLoopBundle(options);
+            printResult(io, ok('loop.import', {
+                assetId: result.assetId,
+                kind: result.kind,
+                importedAs: result.importedAs,
+                warnings: result.warnings,
+                evidenceBriefCount: result.evidenceBriefCount
+            }, result.warnings, [
+                'Run an independent evaluation against this release before promoting; peaks loop promote refuses without an evolution_evaluation row.'
+            ]), asJson);
+        }
+        catch (error) {
+            const refusal = importRefusal(error, options.in) ??
+                fail('loop.import', 'LOOP_IMPORT_FAILED', getErrorMessage(error), { ok: false, inPath: options.in }, ['Verify the bundle path and integrity.']);
+            printResult(io, refusal, asJson);
+            process.exitCode = 1;
+        }
+    });
+}
+/** Open `<projectRoot>/.peaks/state.db` (creating `.peaks/`) and read the bundle in. */
+function importLoopBundle(options) {
+    const projectRoot = resolveLoopProjectRoot(options.project);
+    if (!existsSync(join(projectRoot, '.peaks'))) {
+        mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+    }
+    const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
+    try {
+        return readBundle({
+            db,
+            blobsDir: join(projectRoot, '.peaks', 'blobs'),
+            inPath: options.in,
+            ...(options.as !== undefined ? { asName: options.as } : {})
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * The four named bundle refusals, each with the action its reader earned, or
+ * `null` for anything else. The `data` each carries differs (`receivedMajor` on
+ * a version mismatch, `inPath` on a malformed bundle), so the branches are a
+ * flat guard chain rather than a table with a `data` callback.
+ */
+function importRefusal(error, inPath) {
+    if (error instanceof BundleMajorVersionMismatchError) {
+        return fail('loop.import', error.code, error.message, { ok: false, receivedMajor: error.receivedMajor }, ['Use the matching peaks.bundle/<major> reader; this peaks build only supports major=1.']);
+    }
+    if (error instanceof BundleSchemaVersionsMismatchError) {
+        return fail('loop.import', error.code, error.message, { ok: false }, [
+            'Source bundle did not declare the canonical schema versions; refuse the bundle.'
+        ]);
+    }
+    if (error instanceof BundleImportToStableForbiddenError) {
+        return fail('loop.import', error.code, error.message, { ok: false }, [
+            'Bundles always land as candidate; promotion to stable requires an evolution_evaluation row (AC-26).'
+        ]);
+    }
+    if (error instanceof BundleMalformedError) {
+        return fail('loop.import', error.code, error.message, { ok: false, inPath }, [
+            'Re-export from the source via `peaks loop export`.'
+        ]);
+    }
+    return null;
+}

package/dist/cli/commands/loop-placeholder-commands.d.ts

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

package/dist/cli/commands/loop-placeholder-commands.js

@@ -0,0 +1,52 @@
+// src/cli/commands/loop-placeholder-commands.ts
+//
+// `peaks loop preflight|detect-pattern|check-consistency` — the three 14.x
+// placeholder facades. They differ only in their verb, the list of things the
+// LLM-side UX layer should run instead, and the one-line note on the envelope;
+// three copies of the same builder is what pushed `registerLoopCommands` past
+// the per-function line cap. Extracted from `loop-commands.ts` as one table;
+// every registered name, description, option and envelope is unchanged.
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const PLACEHOLDERS = [
+    {
+        verb: 'preflight',
+        command: 'loop.preflight',
+        description: '14.2: pre-run sanity checks (placeholder; future slice runs peaks doctor + peaks audit before each loop iter)',
+        nextSteps: [
+            'For each L4 loop iteration, call peaks doctor + peaks audit to surface regressions.',
+            'A future slice will inline the preflight checks (not just placeholder).'
+        ],
+        summary: 'loop.preflight is a thin facade; the LLM-side UX layer composes peaks doctor + peaks audit.'
+    },
+    {
+        verb: 'detect-pattern',
+        command: 'loop.detect-pattern',
+        description: '14.3: detect repeating patterns across past sessions (placeholder; future slice uses peaks retrospective search)',
+        nextSteps: [
+            'Run peaks retrospective search --limit 50 to surface high-frequency patterns.',
+            'A future slice will rank by frequency + LLM confidence.'
+        ],
+        summary: 'loop.detect-pattern is a thin facade; the LLM-side UX layer composes peaks retrospective search.'
+    },
+    {
+        verb: 'check-consistency',
+        command: 'loop.check-consistency',
+        description: '14.4: verify state consistency (placeholder; future slice compares .peaks/_runtime across sessions)',
+        nextSteps: [
+            'Compare .peaks/_runtime/<sid>/session.json across recent sessions for drift.',
+            'A future slice will report drift with severity (warn / fail).'
+        ],
+        summary: 'loop.check-consistency is a thin facade; the LLM-side UX layer composes the drift scan.'
+    }
+];
+export function registerLoopPlaceholderCommands(loop, io) {
+    for (const spec of PLACEHOLDERS) {
+        addJsonOption(loop
+            .command(spec.verb)
+            .description(spec.description)
+            .requiredOption('--project <path>', 'target project root')).action((options) => {
+            printResult(io, ok(spec.command, { project: options.project, status: 'placeholder', nextSteps: [...spec.nextSteps] }, [], [spec.summary]), options.json);
+        });
+    }
+}

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

@@ -0,0 +1,59 @@
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+import type { ProjectMemoryKind } from '../../services/memory/memory-search-service.js';
+export interface MemorySearchCommandOptions {
+    query: string;
+    kind?: string;
+    limit?: number;
+    project?: string;
+    json?: boolean;
+}
+export interface MemoryListCommandOptions {
+    kind?: string;
+    pick?: boolean;
+    fzfBin?: string;
+    project?: string;
+    json?: boolean;
+    /** Slice B: emit counts + names-of-first-N instead of the full entry array. */
+    summary?: boolean;
+}
+export interface MemoryReindexCommandOptions {
+    project?: string;
+    dryRun?: boolean;
+    apply?: boolean;
+    json?: boolean;
+    /** Slice B: emit counts + names-of-first-N instead of the full arrays. */
+    summary?: boolean;
+}
+export interface MemoryIngestCommandOptions {
+    project?: string;
+    sourceDir?: string;
+    dryRun?: boolean;
+    apply?: boolean;
+    json?: boolean;
+}
+export interface MemoryRotateCommandOptions {
+    project?: string;
+    dryRun?: boolean;
+    apply?: boolean;
+    json?: boolean;
+}
+/** `--project` canonicalised, else the nearest project root above cwd, else cwd. */
+export declare function resolveMemoryProjectRoot(project?: string): string;
+/** The CLI kind flag, narrowed to the canonical vocabulary; unknown ⇒ no filter. */
+export declare function resolveKindFilter(kind: string | undefined): ProjectMemoryKind | undefined;
+/**
+ * The failed envelope for a memory verb: the error's own `code` when it carries
+ * one, the verb's `<VERB>_FAILED` otherwise. `byCode` names the one action worth
+ * recommending for a specific failure; anything else falls back to
+ * `suggestions`, so a caller that has no code-specific advice omits it.
+ */
+export declare function memoryFailure(input: {
+    readonly command: string;
+    readonly fallbackCode: string;
+    readonly error: unknown;
+    readonly projectRoot: string;
+    readonly suggestions?: readonly string[];
+    readonly byCode?: Readonly<Record<string, string>>;
+}): ResultEnvelope<{
+    projectRoot: string;
+}>;

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

@@ -0,0 +1,39 @@
+// src/cli/commands/memory-command-shared.ts
+//
+// What every `peaks memory` run function shares: the option types the Commander
+// wiring in `core/memory-command.ts` feeds them, the project-root resolution,
+// the kind filter, and the one place a refused run becomes an envelope. Split
+// out of `memory-commands.ts` so each verb can live in its own module.
+//
+// The five run functions used to repeat the same twelve-line catch block, each
+// with its own `(error as { code?: string }).code ?? '<VERB>_FAILED'` and its
+// own suggestion list. `memoryFailure` is that block once; the per-verb
+// fallback code, the code-keyed hints and the default suggestion are the only
+// things that ever differed.
+import { fail, getErrorMessage } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { VALID_PROJECT_MEMORY_KINDS } from '../../services/memory/project-memory-service.js';
+/** `--project` canonicalised, else the nearest project root above cwd, else cwd. */
+export function resolveMemoryProjectRoot(project) {
+    return project !== undefined
+        ? resolveCanonicalProjectRoot(project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+}
+/** The CLI kind flag, narrowed to the canonical vocabulary; unknown ⇒ no filter. */
+export function resolveKindFilter(kind) {
+    return kind !== undefined && VALID_PROJECT_MEMORY_KINDS.includes(kind)
+        ? kind
+        : undefined;
+}
+/**
+ * The failed envelope for a memory verb: the error's own `code` when it carries
+ * one, the verb's `<VERB>_FAILED` otherwise. `byCode` names the one action worth
+ * recommending for a specific failure; anything else falls back to
+ * `suggestions`, so a caller that has no code-specific advice omits it.
+ */
+export function memoryFailure(input) {
+    const code = input.error.code ?? input.fallbackCode;
+    const hint = input.byCode?.[code];
+    return fail(input.command, code, getErrorMessage(input.error), { projectRoot: input.projectRoot }, hint === undefined ? [...(input.suggestions ?? [])] : [hint]);
+}

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

@@ -1,79 +1,6 @@
-import { type MemoryIndexEntry, type MemoryIndexSnapshot, type ProjectMemoryKind } from '../../services/memory/memory-search-service.js';
-import { type MemoryReindexReport } from '../../services/memory/project-memory-service.js';
-import { type ProgramIO } from '../cli-helpers.js';
-export interface MemorySearchCommandOptions {
-    query: string;
-    kind?: string;
-    limit?: number;
-    project?: string;
-    json?: boolean;
-}
-export interface MemoryListCommandOptions {
-    kind?: string;
-    pick?: boolean;
-    fzfBin?: string;
-    project?: string;
-    json?: boolean;
-    /** Slice B: emit counts + names-of-first-N instead of the full entry array. */
-    summary?: boolean;
-}
-export interface MemoryReindexCommandOptions {
-    project?: string;
-    dryRun?: boolean;
-    apply?: boolean;
-    json?: boolean;
-    /** Slice B: emit counts + names-of-first-N instead of the full arrays. */
-    summary?: boolean;
-}
-/**
- * `memory reindex`. The full report's arrays stay on disk / in the default
- * envelope; this replaces them with `{count, names}` views (≤ 2 KB).
- */
-export declare function buildMemoryReindexSummary(report: MemoryReindexReport): Record<string, unknown>;
-/**
- * Slice B: bounded view of `memory list`. `count` is the true total; `names`
- * carries `name (kind)` labels for the first N entries.
- */
-export declare function buildMemoryListSummary(data: {
-    snapshot: MemoryIndexSnapshot;
-    entries: readonly MemoryIndexEntry[];
-    kindFilter: ProjectMemoryKind | undefined;
-    pickedEntries: readonly MemoryIndexEntry[];
-    pickedOutputPath: string | null;
-    fzfVersion: string | null;
-}): Record<string, unknown>;
-export interface MemoryIngestCommandOptions {
-    project?: string;
-    sourceDir?: string;
-    dryRun?: boolean;
-    apply?: boolean;
-    json?: boolean;
-}
-export interface MemoryRotateCommandOptions {
-    project?: string;
-    dryRun?: boolean;
-    apply?: boolean;
-    json?: boolean;
-}
-export declare function runMemoryList(io: ProgramIO, options: MemoryListCommandOptions): Promise<void>;
-/**
- * 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>;
-/**
- * `peaks memory reindex` — rebuild `.peaks/memory/index.json` from disk and
- * regenerate `MEMORY.md`. Dry-run by default; `--apply` writes.
- */
-export declare function runMemoryReindex(io: ProgramIO, options: MemoryReindexCommandOptions): Promise<void>;
-/**
- * `peaks memory rotate` — tier-driven retention for `.peaks/memory/`.
- * Implements the sediment pruning policy (tier 1: archive, never delete).
- * Dry-run by default; `--apply` moves tier-C candidates into `archived/`.
- */
-export declare function runMemoryRotate(io: ProgramIO, options: MemoryRotateCommandOptions): Promise<void>;
-/**
- * `peaks memory ingest` — import memories written by the IDE-side agent into
- * `.peaks/memory/`. The IDE-side source is read-only; dry-run by default.
- */
-export declare function runMemoryIngest(io: ProgramIO, options: MemoryIngestCommandOptions): Promise<void>;
+export type { MemoryIngestCommandOptions, MemoryListCommandOptions, MemoryReindexCommandOptions, MemoryRotateCommandOptions, MemorySearchCommandOptions } from './memory-command-shared.js';
+export { buildMemoryListSummary, runMemoryList } from './memory-list-command.js';
+export { buildMemoryReindexSummary, runMemoryReindex } from './memory-reindex-command.js';
+export { runMemoryIngest } from './memory-ingest-command.js';
+export { runMemoryRotate } from './memory-rotate-command.js';
+export { runMemorySearch } from './memory-search-command.js';