peaks-loop 4.1.2 → 4.1.4

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

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

@@ -1,309 +1,19 @@
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { loadMemoryIndex, searchMemory } from '../../services/memory/memory-search-service.js';
-import { executeMemoryReindex, VALID_PROJECT_MEMORY_KINDS } from '../../services/memory/project-memory-service.js';
-import { boundedNames, fitSummaryToBytes } from '../../services/context/summary-view.js';
-import { executeMemoryIngest } from '../../services/memory/memory-ingest-service.js';
-import { executeMemoryRotate } from '../../services/memory/memory-rotate-service.js';
-import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { getErrorMessage, printResult } from '../cli-helpers.js';
-import { join } from 'node:path';
-const VALID_KINDS = VALID_PROJECT_MEMORY_KINDS;
-/**
- * `memory reindex`. The full report's arrays stay on disk / in the default
- * envelope; this replaces them with `{count, names}` views (≤ 2 KB).
- */
-export function buildMemoryReindexSummary(report) {
-    const view = {
-        view: 'summary',
-        apply: report.apply,
-        projectRoot: report.projectRoot,
-        memoryDir: report.memoryDir,
-        indexPath: report.indexPath,
-        memoryMdPath: report.memoryMdPath,
-        scannedFiles: report.scannedFiles,
-        indexed: report.indexed,
-        indexedByKind: report.indexedByKind,
-        unclassified: boundedNames(report.unclassified.map((u) => `${u.name}${u.rawKind === null ? '' : ` (${u.rawKind})`}`)),
-        nameConflicts: boundedNames(report.nameConflicts.map((c) => c.name)),
-        orphanIndex: boundedNames(report.orphanIndex.map((o) => o.name)),
-        orphanDisk: boundedNames(report.orphanDisk.map((p) => p.split(/[\\/]/).pop() ?? p)),
-        memoryMd: report.memoryMd,
-        writtenFiles: boundedNames(report.writtenFiles.map((p) => p.split(/[\\/]/).pop() ?? p))
-    };
-    return fitSummaryToBytes(view);
-}
-/**
- * Slice B: bounded view of `memory list`. `count` is the true total; `names`
- * carries `name (kind)` labels for the first N entries.
- */
-export function buildMemoryListSummary(data) {
-    const label = (e) => `${e.name} (${e.kind})`;
-    const view = {
-        view: 'summary',
-        indexPath: data.snapshot.indexPath,
-        version: data.snapshot.version,
-        updatedAt: data.snapshot.updatedAt,
-        total: data.entries.length,
-        kindFilter: data.kindFilter ?? null,
-        entries: boundedNames(data.entries.map(label))
-    };
-    if (data.pickedOutputPath !== null) {
-        view.picked = boundedNames(data.pickedEntries.map(label));
-        view.pickedOutputPath = data.pickedOutputPath;
-        view.fzfVersion = data.fzfVersion;
-    }
-    return fitSummaryToBytes(view);
-}
-function resolveMemoryProjectRoot(project) {
-    return project !== undefined
-        ? resolveCanonicalProjectRoot(project)
-        : (findProjectRoot(process.cwd()) ?? process.cwd());
-}
-export async function runMemoryList(io, options) {
-    const projectRoot = options.project !== undefined
-        ? resolveCanonicalProjectRoot(options.project)
-        : (findProjectRoot(process.cwd()) ?? process.cwd());
-    try {
-        const snapshot = loadMemoryIndex(projectRoot);
-        const kindFilter = options.kind !== undefined && VALID_KINDS.includes(options.kind)
-            ? options.kind
-            : undefined;
-        const entries = kindFilter === undefined
-            ? snapshot.entries
-            : snapshot.entries.filter((e) => e.kind === kindFilter);
-        const warnings = [];
-        let pickedEntries = entries;
-        let pickedOutputPath = null;
-        let fzfVersion = null;
-        if (options.pick === true) {
-            const outputPath = join(projectRoot, '.peaks', 'memory', 'picked.json');
-            const byName = new Map(entries.map((e) => [e.name, e]));
-            const result = await pickFromList({
-                items: entries,
-                formatLine: (entry) => `${entry.name} | ${entry.kind} | ${entry.description.slice(0, 60)}`,
-                parseLine: (line) => {
-                    const parts = line.split('|').map((p) => p.trim());
-                    if (parts.length < 1)
-                        return null;
-                    const name = parts[0];
-                    if (name === undefined || name.length === 0)
-                        return null;
-                    return byName.get(name) ?? null;
-                },
-                outputPath,
-                meta: { kindFilter: kindFilter ?? null, totalCandidates: entries.length },
-                ...(options.fzfBin !== undefined ? { fzfBin: options.fzfBin } : {}),
-                projectRoot,
-                multi: true,
-                prompt: 'memory> '
-            });
-            pickedEntries = [...result.picked];
-            pickedOutputPath = result.outputPath;
-            fzfVersion = result.fzfVersion;
-        }
-        const nextActions = [];
-        if (pickedOutputPath !== null) {
-            nextActions.push(`Picked ${pickedEntries.length} entr(ies); written to ${pickedOutputPath}`);
-        }
-        if (entries.length === 0) {
-            nextActions.push('No entries match; run `peaks memory extract` to build the index from memory/*.md files.');
-        }
-        // Slice B: `--summary` swaps the full entry array for a bounded
-        // `{count, names}` view. The default (no flag) envelope is byte-identical
-        // to before — the flag is strictly opt-in.
-        const data = options.summary === true
-            ? buildMemoryListSummary({
-                snapshot,
-                entries,
-                kindFilter,
-                pickedEntries,
-                pickedOutputPath,
-                fzfVersion
-            })
-            : {
-                indexPath: snapshot.indexPath,
-                version: snapshot.version,
-                updatedAt: snapshot.updatedAt,
-                total: entries.length,
-                kindFilter: kindFilter ?? null,
-                entries,
-                ...(options.pick === true
-                    ? { picked: pickedEntries, pickedOutputPath, fzfVersion }
-                    : {})
-            };
-        printResult(io, ok('memory.list', data, warnings, nextActions), options.json);
-    }
-    catch (error) {
-        const message = getErrorMessage(error);
-        const code = error.code ?? 'MEMORY_LIST_FAILED';
-        const suggestions = [];
-        if (code === 'INDEX_MISSING') {
-            suggestions.push('Run `peaks memory extract` to build the index from memory/*.md files');
-        }
-        printResult(io, fail('memory.list', code, message, { projectRoot }, suggestions), options.json);
-        process.exitCode = 1;
-    }
-}
-/**
- * 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 = options.project !== undefined
-        ? resolveCanonicalProjectRoot(options.project)
-        : (findProjectRoot(process.cwd()) ?? process.cwd());
-    const kindFilter = options.kind !== undefined && VALID_KINDS.includes(options.kind)
-        ? options.kind
-        : undefined;
-    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) {
-        const message = getErrorMessage(error);
-        const code = error.code ?? 'MEMORY_SEARCH_FAILED';
-        const suggestions = [];
-        if (code === 'INDEX_MISSING') {
-            suggestions.push('Run `peaks memory extract --apply` to build the index from memory/*.md files');
-        }
-        if (code === 'EMPTY_QUERY') {
-            suggestions.push('Use `peaks memory index` to list all entries');
-        }
-        printResult(io, fail('memory.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
-        process.exitCode = 1;
-    }
-}
-/**
- * `peaks memory reindex` — rebuild `.peaks/memory/index.json` from disk and
- * regenerate `MEMORY.md`. Dry-run by default; `--apply` writes.
- */
-export async function runMemoryReindex(io, options) {
-    const projectRoot = resolveMemoryProjectRoot(options.project);
-    if (options.dryRun === true && options.apply === true) {
-        printResult(io, fail('memory.reindex', 'INVALID_MEMORY_REINDEX_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview the drift report, or pass --apply to rebuild']), options.json);
-        process.exitCode = 1;
-        return;
-    }
-    try {
-        const report = executeMemoryReindex({ projectRoot, apply: options.apply === true });
-        const nextActions = [];
-        if (options.apply !== true) {
-            nextActions.push('Preview only — re-run with --apply to rebuild index.json and regenerate MEMORY.md.');
-        }
-        if (report.unclassified.length > 0) {
-            nextActions.push(`${report.unclassified.length} file(s) have no resolvable kind; add \`metadata.type\` (or \`kind:\`) to index them.`);
-        }
-        if (report.orphanIndex.length > 0) {
-            nextActions.push(`${report.orphanIndex.length} previous index entry(ies) point at missing files; they are dropped from the rebuilt index.`);
-        }
-        if (report.nameConflicts.length > 0) {
-            nextActions.push(`${report.nameConflicts.length} name collision(s) across files; both entries are kept — rename one file to disambiguate.`);
-        }
-        // Slice B: `--summary` keeps the scalar drift counts + names-of-first-N;
-        // the full report (with every unclassified/orphan path) stays available
-        // by omitting the flag. Default shape is unchanged.
-        const data = options.summary === true ? buildMemoryReindexSummary(report) : report;
-        printResult(io, ok('memory.reindex', data, [], nextActions), options.json);
-    }
-    catch (error) {
-        const message = getErrorMessage(error);
-        const code = error.code ?? 'MEMORY_REINDEX_FAILED';
-        printResult(io, fail('memory.reindex', code, message, { projectRoot }, [
-            'Check that the project has a readable .peaks/memory directory'
-        ]), options.json);
-        process.exitCode = 1;
-    }
-}
-/**
- * `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 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 });
-        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.`);
-        }
-        printResult(io, ok('memory.rotate', report, report.warnings, nextActions), options.json);
-        if (report.refused)
-            process.exitCode = 1;
-    }
-    catch (error) {
-        const message = getErrorMessage(error);
-        const code = error.code ?? 'MEMORY_ROTATE_FAILED';
-        printResult(io, fail('memory.rotate', code, message, { projectRoot }, [
-            'Check that the project has a readable .peaks/memory directory'
-        ]), options.json);
-        process.exitCode = 1;
-    }
-}
-/**
- * `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 async function runMemoryIngest(io, options) {
-    const projectRoot = resolveMemoryProjectRoot(options.project);
-    if (options.dryRun === true && options.apply === true) {
-        printResult(io, fail('memory.ingest', 'INVALID_MEMORY_INGEST_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview imports, or pass --apply to write them into .peaks/memory']), options.json);
-        process.exitCode = 1;
-        return;
-    }
-    try {
-        const report = executeMemoryIngest({
-            projectRoot,
-            ...(options.sourceDir !== undefined ? { sourceDir: options.sourceDir } : {}),
-            apply: options.apply === true
-        });
-        const nextActions = [];
-        if (options.apply !== true && report.imported.length > 0) {
-            nextActions.push('Preview only — re-run with --apply to write these memories into .peaks/memory.');
-        }
-        if (report.conflicts.length > 0) {
-            nextActions.push(`${report.conflicts.length} conflict(s) left both copies in place; resolve them by hand.`);
-        }
-        if (report.needsClassification.length > 0) {
-            nextActions.push(`${report.needsClassification.length} file(s) could not be classified; add \`metadata.type\` to the source before re-running.`);
-        }
-        printResult(io, ok('memory.ingest', report, report.warnings, nextActions), options.json);
-    }
-    catch (error) {
-        const message = getErrorMessage(error);
-        const code = error.code ?? 'MEMORY_INGEST_FAILED';
-        printResult(io, fail('memory.ingest', code, message, { projectRoot }, [
-            'Check the --source-dir path and that .peaks/memory is writable'
-        ]), options.json);
-        process.exitCode = 1;
-    }
-}
+// src/cli/commands/memory-commands.ts
+//
+// The `peaks memory` run functions, one module per verb:
+//
+//   read  : `memory-list-command.ts`, `memory-search-command.ts`
+//   write : `memory-reindex-command.ts`, `memory-rotate-command.ts`,
+//           `memory-ingest-command.ts`
+//   shared: `memory-command-shared.ts` (option types, project root, failures)
+//
+// The Commander wiring lives in `core/memory-command.ts`, which reaches these
+// functions by dynamic `import('../memory-commands.js')`; this module is the
+// path it names and keeps re-exporting every symbol it used to define, so
+// `tests/unit/cli/commands/summary-flag.test.ts` and
+// `tests/unit/services/context/summary-view.test.ts` need no edit.
+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';

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

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type MemoryIngestCommandOptions } from './memory-command-shared.js';
+export declare function runMemoryIngest(io: ProgramIO, options: MemoryIngestCommandOptions): Promise<void>;

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

@@ -0,0 +1,50 @@
+// src/cli/commands/memory-ingest-command.ts
+//
+// `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.
+// 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 { executeMemoryIngest } from '../../services/memory/memory-ingest-service.js';
+import { printResult } from '../cli-helpers.js';
+import { memoryFailure, resolveMemoryProjectRoot } from './memory-command-shared.js';
+export async function runMemoryIngest(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('memory.ingest', 'INVALID_MEMORY_INGEST_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview imports, or pass --apply to write them into .peaks/memory']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const report = executeMemoryIngest({
+            projectRoot,
+            ...(options.sourceDir !== undefined ? { sourceDir: options.sourceDir } : {}),
+            apply: options.apply === true
+        });
+        printResult(io, ok('memory.ingest', report, report.warnings, ingestNextActions(report, options)), options.json);
+    }
+    catch (error) {
+        printResult(io, memoryFailure({
+            command: 'memory.ingest',
+            fallbackCode: 'MEMORY_INGEST_FAILED',
+            error,
+            projectRoot,
+            suggestions: ['Check the --source-dir path and that .peaks/memory is writable']
+        }), options.json);
+        process.exitCode = 1;
+    }
+}
+/** The preview / conflict / unclassified notices the report earns, in order. */
+function ingestNextActions(report, options) {
+    const nextActions = [];
+    if (options.apply !== true && report.imported.length > 0) {
+        nextActions.push('Preview only — re-run with --apply to write these memories into .peaks/memory.');
+    }
+    if (report.conflicts.length > 0) {
+        nextActions.push(`${report.conflicts.length} conflict(s) left both copies in place; resolve them by hand.`);
+    }
+    if (report.needsClassification.length > 0) {
+        nextActions.push(`${report.needsClassification.length} file(s) could not be classified; add \`metadata.type\` to the source before re-running.`);
+    }
+    return nextActions;
+}

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

@@ -0,0 +1,16 @@
+import { type MemoryIndexEntry, type MemoryIndexSnapshot, type ProjectMemoryKind } from '../../services/memory/memory-search-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type MemoryListCommandOptions } from './memory-command-shared.js';
+/**
+ * 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 declare function runMemoryList(io: ProgramIO, options: MemoryListCommandOptions): Promise<void>;