hippo-memory 2.0.0 → 2.1.0

package/dist/cli/transfer.js

@@ -4,7 +4,7 @@ import * as fs from 'fs';
 import { isInitialized } from '../core/project-identity.js';
 import { RejectedValueError } from '../core/api-errors.js';
 import { embedCoverage, embedMissingMemories } from '../api/embeddings.js';
-import { captureError, runWatched } from '../learn/autolearn.js';
+import { captureError, runWatched, runWatchedLine } from '../learn/autolearn.js';
 import { currentMachine, importAtSessionEnd, importForStore } from '../agent-memories/sync.js';
 import { detailLines } from '../agent-memories/report.js';
 import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
@@ -14,16 +14,16 @@ import { importChatGPT, importClaude, importCursor, importGenericFile, } from '.
 import { importMarkdown } from '../importers/markdown.js';
 import { importVault } from '../importers/vault.js';
 import * as api from '../api/index.js';
-import { getMemory, listMemories } from '../api/memories.js';
+import { getMemory, listMemories } from '../api/memories/memories.js';
 import * as client from './client.js';
 import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
 import { errorMessage, log } from '../util/log.js';
 import { requireInit, runViaServerIfAvailable, learnFromRepo } from './shared.js';
 import { fmt } from './print.js';
-import { boolFlag, flagIsTrue, isStringFlag, nonEmptyStringFlag, numberFlag } from './flag-values.js';
+import { boolFlag, flagIsTrue, isStringFlag, nonEmptyStringFlag, numberFlag, stringFlagOrExit, stringListFlag, } from './flag-values.js';
 import { CONTENT_PREVIEW_CHARS, DATE_PREFIX_CHARS } from '../util/token-text.js';
-import { CliExit } from './exit.js';
+import { CliExit, fail } from './exit.js';
 const STDERR_PREVIEW_CHARS = 80;
 const MAX_ENTRIES_SHOWN = 10;
 // Watch command
@@ -33,25 +33,25 @@ function watchedCommand(args, flags) {
     if (flags['shell'] !== undefined) {
         const line = nonEmptyStringFlag(flags, 'shell');
         if (line === undefined) {
-            printError(WATCH_USAGE);
-            throw new CliExit(1);
+            fail(WATCH_USAGE);
         }
+        // The shell is the feature here: the user's own command line, pipes and && included, opted into by name; argv runs
+        // with no shell.
         return { argv: [line], shell: true };
     }
     if (args.length === 0) {
-        printError(WATCH_USAGE);
-        throw new CliExit(1);
+        fail(WATCH_USAGE);
     }
     // A quoted 1.x command line would now run as one program name, so it is refused rather than guessed at.
     if (args.length === 1 && /\s/.test(args[0])) {
-        printError(`hippo watch: "${args[0]}" is one argument with spaces. Use \`hippo watch -- cmd args\` or \`hippo watch --shell "<command line>"\`.`);
-        throw new CliExit(1);
+        fail(`hippo watch: "${args[0]}" is one argument with spaces. Use \`hippo watch -- cmd args\` ` +
+            `or \`hippo watch --shell "<command line>"\`.`);
     }
     return { argv: [...args], shell: false };
 }
 async function cmdWatch(argv, shell, hippoRoot, tenantId) {
     const command = argv.join(' ');
-    const { exitCode, stderr } = await runWatched(argv, undefined, { shell });
+    const { exitCode, stderr } = await (shell ? runWatchedLine(argv[0]) : runWatched(argv));
     if (exitCode === 0) {
         // Success: no noise
         return;
@@ -91,8 +91,7 @@ async function cmdWatch(argv, shell, hippoRoot, tenantId) {
 export async function handleLearn({ hippoRoot, tenantId, flags }) {
     requireInit(hippoRoot);
     if (!flags['git']) {
-        printError('Usage: hippo learn --git [--days <n>] [--repos <paths>]');
-        throw new CliExit(1);
+        fail('Usage: hippo learn --git [--days <n>] [--repos <paths>]');
     }
     const days = numberFlag(flags, 'days') ?? 7;
     console.log(`Scanning git log for the last ${days} days...`);
@@ -107,7 +106,8 @@ export async function handleLearn({ hippoRoot, tenantId, flags }) {
             totalAdded += added;
             totalSkipped += skipped;
         }
-        console.log(`Git learn complete: ${totalAdded} new lessons added, ${totalSkipped} duplicates skipped across ${repos.length} repos.`);
+        console.log(`Git learn complete: ${totalAdded} new lessons added, ` +
+            `${totalSkipped} duplicates skipped across ${repos.length} repos.`);
     }
     else {
         const { added, skipped } = await learnFromRepo(hippoRoot, tenantId, process.cwd(), days);
@@ -115,7 +115,8 @@ export async function handleLearn({ hippoRoot, tenantId, flags }) {
     }
 }
 // Import command
-/** The rows are saved either way; a failed backfill only delays vectors, so it warns with how many wait and the command that finishes them. */
+/** The rows are saved either way; a failed backfill only delays vectors, so it warns with how many wait and the command
+ * that finishes them. */
 function warnBackfillFailed(ctx, embedCommand, err) {
     let waiting;
     try {
@@ -126,25 +127,24 @@ function warnBackfillFailed(ctx, embedCommand, err) {
     catch (countErr) {
         waiting = `an unknown number of (count failed: ${errorMessage(countErr)})`;
     }
-    log.warn(`import: embedding backfill failed (${errorMessage(err)}); ${waiting} rows have no vector; run '${embedCommand}' to backfill`);
+    log.warn(`import: embedding backfill failed (${errorMessage(err)}); ${waiting} rows have no vector; ` +
+        `run '${embedCommand}' to backfill`);
 }
-/** Batch-embed freshly imported rows. The floating promise is deliberate: libuv keeps the process alive until it settles, and awaiting
- *  would block the CLI on model load; `hippo embed` is the backstop if interrupted. */
+/** Batch-embed freshly imported rows. The floating promise is deliberate: libuv keeps the process alive until it
+ * settles, and awaiting would block the CLI on model load; `hippo embed` is the backstop if interrupted. */
 function backfillVectors(ctx, embedCommand) {
     void embedMissingMemories(ctx).catch((err) => warnBackfillFailed(ctx, embedCommand, err));
 }
 function warnRedacted(count) {
-    if (count)
-        printError(`Warning: secret-shaped text was redacted from ${count} imported ${count === 1 ? 'entry' : 'entries'} before storing`);
+    if (count) {
+        const noun = count === 1 ? 'entry' : 'entries';
+        printError(`Warning: secret-shaped text was redacted from ${count} imported ${noun} before storing`);
+    }
 }
 export async function handleImport({ hippoRoot, tenantId, args, flags }) {
     const useGlobal = boolFlag(flags, 'global');
     const dryRun = boolFlag(flags, 'dry-run');
-    const extraTags = Array.isArray(flags['tag'])
-        ? flags['tag']
-        : flags['tag']
-            ? [String(flags['tag'])]
-            : [];
+    const extraTags = stringListFlag(flags, 'tag') ?? [];
     const targetRoot = useGlobal ? getGlobalRoot() : hippoRoot;
     if (flags['agents'])
         return importAgentMemories(hippoRoot, useGlobal, dryRun);
@@ -160,24 +160,31 @@ export async function handleImport({ hippoRoot, tenantId, args, flags }) {
         extraTags,
         hippoRoot,
     };
-    // Vault import is a FOLDER importer that dispatches apart from the single-file slot below; it writes through tenant-scoped api calls,
-    // so the tenant is resolved and passed through. --global is unsupported (the connector raw-archive path is tenant-local).
-    if (flags['vault'])
-        return await importVaultFolder(hippoRoot, tenantId, flags, importOptions, useGlobal, dryRun);
+    // Vault import is a FOLDER importer that dispatches apart from the single-file slot below; it writes through
+    // tenant-scoped api calls, so the tenant is resolved and passed through. --global is unsupported (the connector
+    // raw-archive path is tenant-local).
+    const vault = stringFlagOrExit(flags, 'vault');
+    if (vault)
+        return await importVaultFolder(hippoRoot, tenantId, vault, flags, importOptions, useGlobal, dryRun);
     importFromFile(targetRoot, args, flags, { importOptions, useGlobal, dryRun, tenantId });
 }
 // Determine which importer to use based on flag
 function pickImporter(args, flags) {
-    if (flags['chatgpt'])
-        return { filePath: String(flags['chatgpt']), importer: importChatGPT, importerName: 'ChatGPT' };
-    if (flags['claude'])
-        return { filePath: String(flags['claude']), importer: importClaude, importerName: 'Claude' };
-    if (flags['cursor'])
-        return { filePath: String(flags['cursor']), importer: importCursor, importerName: 'Cursor' };
-    if (flags['file'])
-        return { filePath: String(flags['file']), importer: importGenericFile, importerName: 'File' };
-    if (flags['markdown'])
-        return { filePath: String(flags['markdown']), importer: importMarkdown, importerName: 'Markdown' };
+    if (flags['chatgpt']) {
+        return { filePath: stringFlagOrExit(flags, 'chatgpt'), importer: importChatGPT, importerName: 'ChatGPT' };
+    }
+    if (flags['claude']) {
+        return { filePath: stringFlagOrExit(flags, 'claude'), importer: importClaude, importerName: 'Claude' };
+    }
+    if (flags['cursor']) {
+        return { filePath: stringFlagOrExit(flags, 'cursor'), importer: importCursor, importerName: 'Cursor' };
+    }
+    if (flags['file']) {
+        return { filePath: stringFlagOrExit(flags, 'file'), importer: importGenericFile, importerName: 'File' };
+    }
+    if (flags['markdown']) {
+        return { filePath: stringFlagOrExit(flags, 'markdown'), importer: importMarkdown, importerName: 'Markdown' };
+    }
     // Positional: try to auto-detect from extension
     if (args[0])
         return { filePath: args[0], importer: importGenericFile, importerName: 'File' };
@@ -187,12 +194,11 @@ function importFromFile(targetRoot, args, flags, options) {
     const { importOptions, useGlobal, dryRun, tenantId } = options;
     const { filePath, importer, importerName } = pickImporter(args, flags);
     if (!filePath || !importer) {
-        printError('Usage: hippo import <--chatgpt|--claude|--cursor|--file|--markdown|--vault> <path>, or hippo import --agents [--dry-run]');
-        throw new CliExit(1);
+        fail('Usage: hippo import <--chatgpt|--claude|--cursor|--file|--markdown|--vault> <path>, ' +
+            'or hippo import --agents [--dry-run]');
     }
     if (!fs.existsSync(filePath)) {
-        printError(`File not found: ${filePath}`);
-        throw new CliExit(1);
+        fail(`File not found: ${filePath}`);
     }
     const result = importer(filePath, importOptions);
     // The importers' writeEntry sites don't embed, so the new rows are embedded here in one pass.
@@ -238,38 +244,33 @@ function importAgentMemories(hippoRoot, useGlobal, dryRun) {
     for (const warning of report.warnings)
         printError(`hippo: agent memories: ${warning}`);
 }
-async function importVaultFolder(hippoRoot, tenantId, flags, importOptions, useGlobal, dryRun) {
-    const folderPath = String(flags['vault']);
+async function importVaultFolder(hippoRoot, tenantId, folderPath, flags, importOptions, useGlobal, dryRun) {
     checkVaultArgs(folderPath, flags, useGlobal);
     const vaultOptions = {
         ...importOptions,
         tenantId,
-        name: flags['name'] ? String(flags['name']) : undefined,
-        scope: flags['scope'] ? String(flags['scope']) : undefined,
+        name: nonEmptyStringFlag(flags, 'name'),
+        scope: nonEmptyStringFlag(flags, 'scope'),
     };
     const vaultResult = await importVault(folderPath, vaultOptions);
     printVaultSummary(vaultResult, folderPath, cliApiContext(hippoRoot, tenantId), dryRun);
 }
 function checkVaultArgs(folderPath, flags, useGlobal) {
     if (!fs.existsSync(folderPath) || !fs.statSync(folderPath).isDirectory()) {
-        printError(`Vault folder not found (or not a directory): ${folderPath}`);
-        throw new CliExit(1);
+        fail(`Vault folder not found (or not a directory): ${folderPath}`);
     }
     if (useGlobal) {
-        printError('hippo import --vault does not support --global (raw rows are tenant-local).');
-        throw new CliExit(1);
+        fail('hippo import --vault does not support --global (raw rows are tenant-local).');
     }
     if (!isStringFlag(flags['name']) || !flags['name'].trim()) {
         // --name keys the destructive source-deletion sync; a folder-basename default lets same-basename vaults clobber
         // each other, and a valueless `--name` (boolean true) would silently import under vault:true:*.
-        printError('hippo import --vault requires --name <vault> (a non-empty identity key for source-deletion sync).');
-        throw new CliExit(1);
+        fail('hippo import --vault requires --name <vault> (a non-empty identity key for source-deletion sync).');
     }
     if (flags['scope'] !== undefined && (!isStringFlag(flags['scope']) || !flags['scope'].trim())) {
-        // Same valueless-flag trap: a bare `--scope` must not become scope "true". The example uses the source-prefixed private form,
-        // since a bare `private` scope is not treated as private by recall and importVault rejects it.
-        printError('hippo import --vault: --scope requires a value (e.g. --scope vault:private:notes).');
-        throw new CliExit(1);
+        // Same valueless-flag trap: a bare `--scope` must not become scope "true". The example uses the source-prefixed
+        // private form, since a bare `private` scope is not treated as private by recall and importVault rejects it.
+        fail('hippo import --vault: --scope requires a value (e.g. --scope vault:private:notes).');
     }
 }
 function printVaultSummary(vaultResult, folderPath, ctx, dryRun) {
@@ -291,8 +292,7 @@ function printVaultSummary(vaultResult, folderPath, ctx, dryRun) {
 function cmdPromote(hippoRoot, tenantId, id) {
     requireInit(hippoRoot);
     if (!id) {
-        printError('Usage: hippo promote <id>');
-        throw new CliExit(1);
+        fail('Usage: hippo promote <id>');
     }
     const ctx = cliApiContext(hippoRoot, tenantId);
     try {
@@ -301,8 +301,7 @@ function cmdPromote(hippoRoot, tenantId, id) {
         console.log(`   Global store: ${getGlobalRoot()}`);
     }
     catch (err) {
-        printError(`Failed to promote: ${errorMessage(err)}`);
-        throw new CliExit(1);
+        fail(`Failed to promote: ${errorMessage(err)}`);
     }
 }
 // Sync command
@@ -316,8 +315,8 @@ export function handleSync({ hippoRoot, flags }) {
     // v39: other-project rows are skipped by default; secrets always are.
     const includeCrossProject = flagIsTrue(flags, 'cross-project');
     const count = syncGlobalToLocal(hippoRoot, globalRoot, { includeCrossProject });
-    console.log(`Synced ${count} global memories into local project.${includeCrossProject ? '' : ' (other-project rows skipped; use --cross-project to ' +
-        'include them)'}`);
+    const skipNote = includeCrossProject ? '' : ' (other-project rows skipped; use --cross-project to include them)';
+    console.log(`Synced ${count} global memories into local project.${skipNote}`);
 }
 export async function handleWatch({ hippoRoot, tenantId, args, flags }) {
     const { argv, shell } = watchedCommand(args, flags);
@@ -326,8 +325,7 @@ export async function handleWatch({ hippoRoot, tenantId, args, flags }) {
 export async function handlePromote({ hippoRoot, tenantId, args }) {
     const id = args[0];
     if (!id) {
-        printError('Please provide a memory ID.');
-        throw new CliExit(1);
+        fail('Please provide a memory ID.');
     }
     const promoted = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
         try {
@@ -335,8 +333,7 @@ export async function handlePromote({ hippoRoot, tenantId, args }) {
             console.log(`Promoted ${id} to global store as ${result.globalId}`);
         }
         catch (err) {
-            printError(`Failed to promote: ${errorMessage(err)}`);
-            throw new CliExit(1);
+            fail(`Failed to promote: ${errorMessage(err)}`);
         }
     });
     if (promoted)
@@ -384,14 +381,12 @@ export async function handleShare({ hippoRoot, tenantId, args, flags }) {
                 console.log('Use --force to share anyway.');
             }
             else {
-                printError(`Memory not found: ${shareId}`);
-                throw new CliExit(1);
+                fail(`Memory not found: ${shareId}`);
             }
         }
     }
     else {
-        printError('Usage: hippo share <memory_id> [--force] or hippo share --auto [--dry-run]');
-        throw new CliExit(1);
+        fail('Usage: hippo share <memory_id> [--force] or hippo share --auto [--dry-run]');
     }
 }
 export function handlePeers({ tenantId, flags }) {
@@ -406,15 +401,16 @@ export function handlePeers({ tenantId, flags }) {
         const scopeLabel = allTenants ? 'global store (all tenants)' : `global store (tenant "${tenantScope}")`;
         console.log(`${peers.length} project${peers.length === 1 ? '' : 's'} contributing to ${scopeLabel}:\n`);
         for (const p of peers) {
-            console.log(`  ${p.project.padEnd(25)} ${String(p.count).padStart(4)} memories  (latest: ${p.latest.slice(0, DATE_PREFIX_CHARS)})`);
+            console.log(`  ${p.project.padEnd(25)} ${String(p.count).padStart(4)} memories  ` +
+                `(latest: ${p.latest.slice(0, DATE_PREFIX_CHARS)})`);
         }
     }
 }
-export function handleExport({ hippoRoot, tenantId, args, flags }) {
+export async function handleExport({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const format = String(flags['format'] || 'json');
+    const format = stringFlagOrExit(flags, 'format') || 'json';
     const outputPath = args[0] || null;
-    const entries = listMemories(cliApiContext(hippoRoot, tenantId));
+    const entries = await listMemories(cliApiContext(hippoRoot, tenantId));
     let output;
     if (format === 'markdown' || format === 'md') {
         output = entries.map(e => {

package/dist/cli/verbs/memory.js

@@ -1,11 +1,13 @@
 // Store, recall and maintenance verbs; every verbs/ file keeps its rows in the order `hippo help` lists them.
-import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from '../../core/search-types.js';
-import { DEFAULT_EMBEDDING_WEIGHT, DEFAULT_MMR_LAMBDA } from '../../search/hybrid.js';
+import { CONFLICT_PEER_MULTIPLIER, DEFAULT_LOCAL_BUMP, DEFAULT_MMR_LAMBDA, DEFAULT_RECALL_BUDGET, SALIENCE_MIN_MULTIPLIER, UTILITY_LENGTH_PENALTY_CAP, UTILITY_LENGTH_TOKENS, VALUE_MULT_MAX, VALUE_MULT_MIN, VALUE_MULT_SLOPE, } from '../../core/search-types.js';
+import { DEFAULT_EMBEDDING_WEIGHT } from '../../search/hybrid.js';
 import { DEFAULT_GRAPH_HOPS, DEFAULT_GRAPH_SEED_COUNT } from '../../graph/stream.js';
 import { verb } from '../verb-row.js';
+const VALUE_CLIP = `clip(1 + ${VALUE_MULT_SLOPE}*tanh(pos - neg), ${VALUE_MULT_MIN}, ${VALUE_MULT_MAX})`;
 export const MEMORY_VERBS = {
     init: verb(() => import('../init.js'), 'handleInit', {
         repairsCodexWrapper: true,
+        scoped: true,
         flags: { switches: ['global', 'no-hooks', 'no-learn', 'no-schedule'], values: ['scan'], numbers: ['days'] },
         usage: [`
   init                     Create .hippo/ structure in current directory
@@ -84,17 +86,17 @@ export const MEMORY_VERBS = {
     --evc-adaptive         When the top results overlap heavily (a conflict
                            cluster), widen the pool and re-rank by recency.
                            Default off.
-    --filter-conflicts     Drop superseded entries and down-weight by 0.3x any
+    --filter-conflicts     Drop superseded entries and down-weight by ${CONFLICT_PEER_MULTIPLIER}x any
                            entry in an open conflict with another result.
                            Uses recorded supersession and conflicts only, never
                            lexical inference. Default off.
     --value-aware          Boost memories with positive cumulative outcomes and
                            demote those with negative ones during ranking:
-                           multiplier clip(1 + 0.3*tanh(pos - neg), 0.7, 1.3).
+                           multiplier ${VALUE_CLIP}.
                            Reads outcome_positive and outcome_negative. Default off.
     --rerank-utility       Re-sort results by utility = score * (0.5 + 0.5 * strength)
                            * (1 - cost_factor), where cost_factor =
-                           min(0.3, tokens / 10000). Default off.
+                           min(${UTILITY_LENGTH_PENALTY_CAP}, tokens / ${UTILITY_LENGTH_TOKENS}). Default off.
     --reranker <name>      Apply a reranker pass after retrieval
                            (cross-encoder|jev|clef-flash|clef|llm) to re-order the
                            top-K candidates. Default unset (no reranker).
@@ -119,7 +121,7 @@ export const MEMORY_VERBS = {
                            on top of base BM25 score, capped at 3.0x.
     --salience-threshold <n>
                            Down-weight memories retrieved fewer than n times:
-                           score *= max(0.5, retrieval_count / n) for entries
+                           score *= max(${SALIENCE_MIN_MULTIPLIER}, retrieval_count / n) for entries
                            with count < n; entries at or above n are unchanged.
                            Salience comes from use, not from lexical overlap.
                            Default off.

package/dist/cli/verbs/objects.js

@@ -1,5 +1,5 @@
 // First-class object, server, goal and auth verbs, in `hippo help` order.
-import { DEFAULT_KEY_TTL_DAYS, MAX_TTL_DAYS } from '../../api/auth.js';
+import { DEFAULT_KEY_TTL_DAYS, MAX_TTL_DAYS } from '../../api/auth/auth.js';
 import { DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT } from '../../server/defaults.js';
 import { verb } from '../verb-row.js';
 export const OBJECT_VERBS = {
@@ -228,8 +228,13 @@ export const OBJECT_VERBS = {
     }),
     auth: verb(() => import('../auth.js'), 'handleAuth', {
         scoped: true,
-        flags: { switches: ['all', 'global', 'json', 'no-expiry'], values: ['label', 'role', 'tenant'], numbers: ['ttl-days'] },
-        usage: [`
+        flags: {
+            switches: ['all', 'global', 'json', 'no-expiry'],
+            values: ['label', 'role', 'tenant'],
+            numbers: ['ttl-days'],
+        },
+        usage: [
+            `
   auth <sub>               Manage API keys (A5 stub auth)
     auth create            Mint a new API key (plaintext shown ONCE)
       --label <s>          Optional human label
@@ -251,7 +256,8 @@ export const OBJECT_VERBS = {
       --global             Operate on the global store
     auth ungrant <key_id> <scope>  Remove a scope grant
       --json               Output as JSON
-      --global             Operate on the global store`],
+      --global             Operate on the global store`
+        ],
     }),
 };
 //# sourceMappingURL=objects.js.map

package/dist/cli/versioned-verbs.d.ts

@@ -1,4 +1,5 @@
 import { type CliFlags, type CommandContext } from './flag-values.js';
+import type { Objects } from '../store/port.js';
 import { printLifecycleTail, type ObjectNames } from './object-verbs.js';
 type VersionedRow = Parameters<typeof printLifecycleTail>[0] & {
     readonly id: number;
@@ -23,29 +24,29 @@ export interface VersionedKind<O extends VersionedRow, S extends string, B> {
     readonly body: (flags: CliFlags, verb: 'new' | 'supersede') => B | undefined;
     /** What a new version keeps from the one it supersedes: the repo, customer or name. */
     readonly keyOf: (o: O) => string;
-    readonly save: (key: string, body: B, extraTags: string[], from?: Succession) => O;
+    readonly save: (key: string, body: B, extraTags: string[], from?: Succession) => Promise<O>;
     /** The first line `new` prints. */
     readonly recorded: (o: O) => string;
     readonly list: (opts: {
         status?: S;
         limit: number;
-    }, flags: CliFlags) => readonly O[];
-    readonly loadById: (id: number) => O | null;
-    readonly close: (id: number) => {
+    }, flags: CliFlags) => Promise<readonly O[]>;
+    readonly loadById: (id: number) => Promise<O | null>;
+    readonly close: (id: number) => Promise<{
         id: number;
-    };
+    }>;
     readonly printRow: (o: O) => void;
     /** The `get` lines between the header and the lifecycle tail. */
     readonly printDetail: (o: O) => void;
     /** A subcommand only this kind has. */
     readonly extra?: {
         readonly sub: string;
-        readonly run: (args: string[], flags: CliFlags) => void;
+        readonly run: (args: string[], flags: CliFlags) => Promise<void>;
     };
 }
 /** A flag that must carry text: its raw value, or undefined when absent or blank. */
 export declare function requiredText(flags: CliFlags, name: string): string | undefined;
 /** The `hippo <cmd>` handler for a kind; `kindAt` binds the descriptor to the store the command runs against. */
-export declare function versionedVerbs<O extends VersionedRow, S extends string, B>(kindAt: (hippoRoot: string, tenantId: string) => VersionedKind<O, S, B>): (ctx: CommandContext) => void;
+export declare function versionedVerbs<O extends VersionedRow, S extends string, B>(kindAt: (objects: Objects, hippoRoot: string, tenantId: string) => VersionedKind<O, S, B>): (ctx: CommandContext) => Promise<void>;
 export {};
 //# sourceMappingURL=versioned-verbs.d.ts.map

package/dist/cli/versioned-verbs.js

@@ -1,11 +1,14 @@
-// One handler set for the kinds that evolve by supersession (brief, note, policy, process, skill), each driven by a descriptor.
+// One handler set for the kinds that evolve by supersession (brief, note, policy, process, skill),
+// each driven by a descriptor.
 import { extractPathTags } from '../search/path-context.js';
 import { errorMessage } from '../util/log.js';
 import { printError } from './output.js';
 import { nonEmptyStringFlag, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
-import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail } from './object-verbs.js';
-import { CliExit } from './exit.js';
+import { objectsOf } from '../api/objects/objects.js';
+import { cliApiContext } from './api-context.js';
+import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail, } from './object-verbs.js';
+import { CliExit, fail } from './exit.js';
 /** A flag that must carry text: its raw value, or undefined when absent or blank. */
 export function requiredText(flags, name) {
     const raw = stringFlag(flags, name);
@@ -13,14 +16,19 @@ export function requiredText(flags, name) {
 }
 /** The `hippo <cmd>` handler for a kind; `kindAt` binds the descriptor to the store the command runs against. */
 export function versionedVerbs(kindAt) {
-    return ({ hippoRoot, tenantId, args, flags }) => {
+    return async ({ hippoRoot, tenantId, args, flags }) => {
         requireInit(hippoRoot);
-        const kind = kindAt(hippoRoot, tenantId);
+        const kind = kindAt(objectsOf(cliApiContext(hippoRoot, tenantId)), hippoRoot, tenantId);
         const sub = args[0] ?? '';
         if (sub === kind.extra?.sub)
             return kind.extra.run(args, flags);
         if (sub === 'list') {
-            return listObjects(flags, { plural: kind.plural, states: kind.states, load: (opts) => kind.list(opts, flags), printRow: kind.printRow });
+            return listObjects(flags, {
+                plural: kind.plural,
+                states: kind.states,
+                load: (opts) => kind.list(opts, flags),
+                printRow: kind.printRow,
+            });
         }
         if (sub === 'get')
             return getVersion(kind, args);
@@ -29,46 +37,48 @@ export function versionedVerbs(kindAt) {
         if (sub === 'close')
             return closeObject(args, kind.names, kind.close);
         // Both `<cmd> new "<key>"` and the bare `<cmd> "<key>"` create.
-        createVersion(kind, sub === 'new' ? (args[1] ?? '') : sub, flags);
+        await createVersion(kind, sub === 'new' ? (args[1] ?? '') : sub, flags);
     };
 }
-function getVersion(kind, args) {
+async function getVersion(kind, args) {
     const id = idArgOrExit(args, `Usage: hippo ${kind.names.cmd} get <id>`, kind.names.idLabel);
-    const o = foundOrExit(kind.loadById(id), kind.names.noun, id);
+    const o = foundOrExit(await kind.loadById(id), kind.names.noun, id);
     console.log(`${kind.names.noun} #${o.id}`);
     kind.printDetail(o);
     printLifecycleTail(o);
 }
-function createVersion(kind, key, flags) {
+async function createVersion(kind, key, flags) {
     const body = key ? kind.body(flags, 'new') : undefined;
     if (body === undefined) {
         for (const line of kind.usage)
             printError(line);
         throw new CliExit(1);
     }
-    const created = saveVersion(kind, key, body);
+    const created = await saveVersion(kind, key, body);
     printSaved(kind.recorded(created), created);
 }
-function supersedeVersion(kind, args, flags) {
+async function supersedeVersion(kind, args, flags) {
     const id = idArgOrExit(args, kind.supersedeUsage, kind.names.idLabel);
     const body = kind.body(flags, 'supersede');
     if (body === undefined) {
-        printError(`hippo ${kind.names.cmd} supersede requires ${kind.bodyRequired} for the new version.`);
-        throw new CliExit(1);
+        fail(`hippo ${kind.names.cmd} supersede requires ${kind.bodyRequired} for the new version.`);
     }
-    // The lookup only gives a missing id its not-found line; the save's own preflight is the authoritative active-state check.
-    const existing = foundOrExit(kind.loadById(id), kind.names.noun, id);
-    const created = saveVersion(kind, kind.keyOf(existing), body, { id, changeSummary: nonEmptyStringFlag(flags, 'change') });
+    // The lookup only gives a missing id its not-found line; the save's own preflight is the
+    // authoritative active-state check.
+    const existing = foundOrExit(await kind.loadById(id), kind.names.noun, id);
+    const created = await saveVersion(kind, kind.keyOf(existing), body, {
+        id,
+        changeSummary: nonEmptyStringFlag(flags, 'change'),
+    });
     printSaved(`${kind.names.noun} #${created.id} recorded (v${created.version}), superseding #${id}.`, created);
 }
 /** Every kind's save goes through here, so a refused write always prints the store's message and exits 1. */
-function saveVersion(kind, key, body, from) {
+async function saveVersion(kind, key, body, from) {
     try {
-        return kind.save(key, body, extractPathTags(process.cwd()), from);
+        return await kind.save(key, body, extractPathTags(process.cwd()), from);
     }
     catch (e) {
-        printError(errorMessage(e));
-        throw new CliExit(1);
+        fail(errorMessage(e));
     }
 }
 function printSaved(line, o) {