hippo-memory 1.69.0 → 1.70.0

package/dist/cli/playbooks.js

@@ -1,22 +1,17 @@
 // First-class object verbs for processes, policies and skills.
-import { extractPathTags } from '../path-context.js';
-import * as processesModule from '../processes.js';
-import * as policiesModule from '../policies.js';
-import * as skillsModule from '../skills.js';
-import { resolveTenantId } from '../tenant.js';
+import { extractPathTags } from '../search/path-context.js';
+import * as processesModule from '../objects/processes.js';
+import * as policiesModule from '../objects/policies.js';
+import * as skillsModule from '../objects/skills.js';
+import { resolveTenantId } from '../store/tenant.js';
 import { printError } from './output.js';
+import { nonEmptyStringFlag, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
-// parseInt alone accepts trailing junk ('1abc' -> 1), which would let `process close 1abc`
-// silently hit the wrong row; require the whole arg to be digits.
-function parsePositiveProcessId(idRaw) {
-    const s = String(idRaw ?? '').trim();
-    const id = parseInt(s, 10);
-    if (!/^\d+$/.test(s) || id <= 0) {
-        printError(`Invalid process id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
-    }
-    return id;
-}
+import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail } from './object-verbs.js';
+import { errorMessage } from '../util/log.js';
+const PROCESS = { cmd: 'process', noun: 'Process', idLabel: 'process' };
+const POLICY = { cmd: 'policy', noun: 'Policy', idLabel: 'policy' };
+const SKILL = { cmd: 'skill', noun: 'Skill', idLabel: 'skill' };
 // --step is a repeatable flag (collected into an array by parseArgs). A single
 // --step yields a string; normalize both to string[]. A value-less --step errors.
 function collectProcessSteps(stepRaw) {
@@ -30,57 +25,23 @@ function collectProcessSteps(stepRaw) {
     }
     return [];
 }
-function parseListLimit(flags) {
-    const limitRaw = flags['limit'];
-    const limit = limitRaw !== undefined ? parseInt(String(limitRaw), 10) : 100;
-    if (!Number.isFinite(limit) || limit <= 0) {
-        printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
-        process.exit(1);
-    }
-    return limit;
+function printProcessRow(proc) {
+    console.log(`#${proc.id} [${proc.status}] v${proc.version} steps=${proc.steps.length} memory=${proc.memoryId ?? '-'}`);
+    console.log(`    ${proc.processName}`);
+    if (proc.changeSummary)
+        console.log(`    change: ${proc.changeSummary}`);
 }
 function processList(hippoRoot, tenantId, flags) {
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
-    const limit = parseListLimit(flags);
-    let results;
-    if (status === 'all') {
-        results = processesModule.loadProcesses(hippoRoot, tenantId, { limit });
-    }
-    else {
-        if (!processesModule.VALID_PROCESS_STATES.has(status)) {
-            printError(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
-            process.exit(1);
-        }
-        results = processesModule.loadProcesses(hippoRoot, tenantId, {
-            status: status,
-            limit,
-        });
-    }
-    if (results.length === 0) {
-        console.log('No processes.');
-        return;
-    }
-    console.log(`Found ${results.length} processes:\n`);
-    for (const proc of results) {
-        console.log(`#${proc.id} [${proc.status}] v${proc.version} steps=${proc.steps.length} memory=${proc.memoryId ?? '-'}`);
-        console.log(`    ${proc.processName}`);
-        if (proc.changeSummary)
-            console.log(`    change: ${proc.changeSummary}`);
-    }
+    listObjects(flags, {
+        plural: 'processes',
+        states: processesModule.VALID_PROCESS_STATES,
+        load: (opts) => processesModule.loadProcesses(hippoRoot, tenantId, opts),
+        printRow: printProcessRow,
+    });
 }
 function processGet(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo process get <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveProcessId(idRaw);
-    const proc = processesModule.loadProcessById(hippoRoot, tenantId, id);
-    if (!proc) {
-        printError(`Process ${id} not found.`);
-        process.exit(1);
-    }
+    const id = idArgOrExit(args, 'Usage: hippo process get <id>', PROCESS.idLabel);
+    const proc = foundOrExit(processesModule.loadProcessById(hippoRoot, tenantId, id), PROCESS.noun, id);
     console.log(`Process #${proc.id}`);
     console.log(`  name: ${proc.processName}`);
     console.log(`  status: ${proc.status}`);
@@ -91,25 +52,10 @@ function processGet(hippoRoot, tenantId, args) {
         console.log(`  steps:`);
         proc.steps.forEach((s, i) => console.log(`    ${i + 1}. ${s}`));
     }
-    if (proc.changeSummary)
-        console.log(`  change_summary: ${proc.changeSummary}`);
-    if (proc.supersededBy !== null)
-        console.log(`  superseded_by: #${proc.supersededBy}`);
-    if (proc.supersededAt)
-        console.log(`  superseded_at: ${proc.supersededAt}`);
-    if (proc.closedAt)
-        console.log(`  closed_at: ${proc.closedAt}`);
-    if (proc.memoryId)
-        console.log(`  memory: ${proc.memoryId}`);
-    console.log(`  created: ${proc.createdAt}`);
+    printLifecycleTail(proc);
 }
 function processSupersede(hippoRoot, tenantId, args, flags) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo process supersede <id> --step "<text>" [--step ...] [--change "<summary>"] [--description "<text>"]');
-        process.exit(1);
-    }
-    const id = parsePositiveProcessId(idRaw);
+    const id = idArgOrExit(args, 'Usage: hippo process supersede <id> --step "<text>" [--step ...] [--change "<summary>"] [--description "<text>"]', PROCESS.idLabel);
     const steps = collectProcessSteps(flags['step']);
     if (steps.length === 0) {
         printError('hippo process supersede requires at least one --step "<text>" for the new version.');
@@ -118,15 +64,9 @@ function processSupersede(hippoRoot, tenantId, args, flags) {
     // A supersession is a new version of the SAME process, so the new row reuses the predecessor's name (stable identity
     // across versions). loadProcessById gives an early not-found before the write; saveProcess's in-SAVEPOINT preflight
     // is the authoritative active-state check.
-    const existing = processesModule.loadProcessById(hippoRoot, tenantId, id);
-    if (!existing) {
-        printError(`Process ${id} not found.`);
-        process.exit(1);
-    }
-    const changeRaw = flags['change'];
-    const changeSummary = typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined;
-    const descRaw = flags['description'];
-    const description = typeof descRaw === 'string' && descRaw ? descRaw : undefined;
+    const existing = foundOrExit(processesModule.loadProcessById(hippoRoot, tenantId, id), PROCESS.noun, id);
+    const changeSummary = nonEmptyStringFlag(flags, 'change');
+    const description = nonEmptyStringFlag(flags, 'description');
     const procPathTags = extractPathTags(process.cwd());
     const created = processesModule.saveProcess(hippoRoot, tenantId, {
         processName: existing.processName,
@@ -141,14 +81,7 @@ function processSupersede(hippoRoot, tenantId, args, flags) {
         console.log(`  memory: ${created.memoryId}`);
 }
 function processClose(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo process close <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveProcessId(idRaw);
-    const closed = processesModule.closeProcess(hippoRoot, tenantId, id);
-    console.log(`Process #${closed.id} closed.`);
+    closeObject(args, PROCESS, (id) => processesModule.closeProcess(hippoRoot, tenantId, id));
 }
 export function cmdProcess(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -177,8 +110,7 @@ function processCreate(hippoRoot, tenantId, processName, flags) {
         process.exit(1);
     }
     const steps = collectProcessSteps(flags['step']);
-    const descRaw = flags['description'];
-    const description = typeof descRaw === 'string' && descRaw ? descRaw : undefined;
+    const description = nonEmptyStringFlag(flags, 'description');
     const procPathTags = extractPathTags(process.cwd());
     const created = processesModule.saveProcess(hippoRoot, tenantId, {
         processName,
@@ -190,16 +122,6 @@ function processCreate(hippoRoot, tenantId, processName, flags) {
     if (created.memoryId)
         console.log(`  memory: ${created.memoryId}`);
 }
-// Strict positive-integer id parse for the mutating policy subcommands: parseInt alone accepts '1abc' -> 1.
-function parsePositivePolicyId(idRaw) {
-    const s = String(idRaw ?? '').trim();
-    const id = parseInt(s, 10);
-    if (!/^\d+$/.test(s) || id <= 0) {
-        printError(`Invalid policy id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
-    }
-    return id;
-}
 function printPolicyRow(p) {
     const range = p.validTo ? `${p.validFrom}..${p.validTo}` : `${p.validFrom}..(open)`;
     console.log(`#${p.id} [${p.status}] v${p.version} ${range} memory=${p.memoryId ?? '-'}`);
@@ -208,30 +130,12 @@ function printPolicyRow(p) {
         console.log(`    change: ${p.changeSummary}`);
 }
 function policyList(hippoRoot, tenantId, flags) {
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
-    const limit = parseListLimit(flags);
-    let results;
-    if (status === 'all') {
-        results = policiesModule.loadPolicies(hippoRoot, tenantId, { limit });
-    }
-    else {
-        if (!policiesModule.VALID_POLICY_STATES.has(status)) {
-            printError(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
-            process.exit(1);
-        }
-        results = policiesModule.loadPolicies(hippoRoot, tenantId, {
-            status: status,
-            limit,
-        });
-    }
-    if (results.length === 0) {
-        console.log('No policies.');
-        return;
-    }
-    console.log(`Found ${results.length} policies:\n`);
-    for (const p of results)
-        printPolicyRow(p);
+    listObjects(flags, {
+        plural: 'policies',
+        states: policiesModule.VALID_POLICY_STATES,
+        load: (opts) => policiesModule.loadPolicies(hippoRoot, tenantId, opts),
+        printRow: printPolicyRow,
+    });
 }
 function policyAsOf(hippoRoot, tenantId, args, flags) {
     const dateRaw = args[1];
@@ -239,14 +143,13 @@ function policyAsOf(hippoRoot, tenantId, args, flags) {
         printError('Usage: hippo policy asof <iso-date> [--name "<policy>"]');
         process.exit(1);
     }
-    const nameRaw = flags['name'];
-    const name = typeof nameRaw === 'string' && nameRaw ? nameRaw : undefined;
+    const name = nonEmptyStringFlag(flags, 'name');
     let results;
     try {
         results = policiesModule.loadPoliciesAsOf(hippoRoot, tenantId, dateRaw, { name });
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
     if (results.length === 0) {
@@ -258,17 +161,8 @@ function policyAsOf(hippoRoot, tenantId, args, flags) {
         printPolicyRow(p);
 }
 function policyGet(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo policy get <id>');
-        process.exit(1);
-    }
-    const id = parsePositivePolicyId(idRaw);
-    const p = policiesModule.loadPolicyById(hippoRoot, tenantId, id);
-    if (!p) {
-        printError(`Policy ${id} not found.`);
-        process.exit(1);
-    }
+    const id = idArgOrExit(args, 'Usage: hippo policy get <id>', POLICY.idLabel);
+    const p = foundOrExit(policiesModule.loadPolicyById(hippoRoot, tenantId, id), POLICY.noun, id);
     console.log(`Policy #${p.id}`);
     console.log(`  name: ${p.policyName}`);
     console.log(`  text: ${p.policyText}`);
@@ -276,45 +170,23 @@ function policyGet(hippoRoot, tenantId, args) {
     console.log(`  version: ${p.version}`);
     console.log(`  valid_from: ${p.validFrom}`);
     console.log(`  valid_to: ${p.validTo ?? '(open-ended)'}`);
-    if (p.changeSummary)
-        console.log(`  change_summary: ${p.changeSummary}`);
-    if (p.supersededBy !== null)
-        console.log(`  superseded_by: #${p.supersededBy}`);
-    if (p.supersededAt)
-        console.log(`  superseded_at: ${p.supersededAt}`);
-    if (p.closedAt)
-        console.log(`  closed_at: ${p.closedAt}`);
-    if (p.memoryId)
-        console.log(`  memory: ${p.memoryId}`);
-    console.log(`  created: ${p.createdAt}`);
+    printLifecycleTail(p);
 }
 function policySupersede(hippoRoot, tenantId, args, flags) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo policy supersede <id> --text "<rule>" [--from <iso>] [--to <iso>] [--change "<summary>"]');
-        process.exit(1);
-    }
-    const id = parsePositivePolicyId(idRaw);
-    const textRaw = flags['text'];
-    if (typeof textRaw !== 'string' || !textRaw.trim()) {
+    const id = idArgOrExit(args, 'Usage: hippo policy supersede <id> --text "<rule>" [--from <iso>] [--to <iso>] [--change "<summary>"]', POLICY.idLabel);
+    const textRaw = stringFlag(flags, 'text');
+    if (!textRaw?.trim()) {
         printError('hippo policy supersede requires --text "<rule>" for the new version.');
         process.exit(1);
     }
-    const existing = policiesModule.loadPolicyById(hippoRoot, tenantId, id);
-    if (!existing) {
-        printError(`Policy ${id} not found.`);
-        process.exit(1);
-    }
-    const fromRaw = flags['from'];
-    const toRaw = flags['to'];
-    const changeRaw = flags['change'];
+    const existing = foundOrExit(policiesModule.loadPolicyById(hippoRoot, tenantId, id), POLICY.noun, id);
     try {
         const created = policiesModule.savePolicy(hippoRoot, tenantId, {
             policyName: existing.policyName,
             policyText: textRaw,
-            validFrom: typeof fromRaw === 'string' && fromRaw ? fromRaw : undefined,
-            validTo: typeof toRaw === 'string' && toRaw ? toRaw : undefined,
-            changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+            validFrom: nonEmptyStringFlag(flags, 'from'),
+            validTo: nonEmptyStringFlag(flags, 'to'),
+            changeSummary: nonEmptyStringFlag(flags, 'change'),
             supersedesPolicyId: id,
             extraTags: extractPathTags(process.cwd()),
         });
@@ -323,19 +195,12 @@ function policySupersede(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }
 function policyClose(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo policy close <id>');
-        process.exit(1);
-    }
-    const id = parsePositivePolicyId(idRaw);
-    const closed = policiesModule.closePolicy(hippoRoot, tenantId, id);
-    console.log(`Policy #${closed.id} closed.`);
+    closeObject(args, POLICY, (id) => policiesModule.closePolicy(hippoRoot, tenantId, id));
 }
 export function cmdPolicy(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -358,8 +223,8 @@ function policyCreate(hippoRoot, tenantId, args, flags) {
     // Default subcommand: new (create). Accept both `policy new "<name>"` and the
     // bare `policy "<name>"` form: for the `new` keyword the name is args[1].
     const policyName = subcommand === 'new' ? (args[1] ?? '') : subcommand;
-    const textRaw = flags['text'];
-    if (!policyName || typeof textRaw !== 'string' || !textRaw.trim()) {
+    const textRaw = stringFlag(flags, 'text');
+    if (!policyName || !textRaw?.trim()) {
         printError('Usage: hippo policy new "<name>" --text "<rule>" [--from <iso>] [--to <iso>]');
         printError('       hippo policy list [--status active|superseded|closed|all] [--limit N]');
         printError('       hippo policy get <id>');
@@ -368,14 +233,12 @@ function policyCreate(hippoRoot, tenantId, args, flags) {
         printError('       hippo policy close <id>');
         process.exit(1);
     }
-    const fromRaw = flags['from'];
-    const toRaw = flags['to'];
     try {
         const created = policiesModule.savePolicy(hippoRoot, tenantId, {
             policyName,
             policyText: textRaw,
-            validFrom: typeof fromRaw === 'string' && fromRaw ? fromRaw : undefined,
-            validTo: typeof toRaw === 'string' && toRaw ? toRaw : undefined,
+            validFrom: nonEmptyStringFlag(flags, 'from'),
+            validTo: nonEmptyStringFlag(flags, 'to'),
             extraTags: extractPathTags(process.cwd()),
         });
         const range = created.validTo ? `${created.validFrom}..${created.validTo}` : `${created.validFrom}..(open)`;
@@ -384,20 +247,10 @@ function policyCreate(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }
-// Strict positive-integer id parse for the mutating skill subcommands: parseInt accepts '1abc' -> 1.
-function parsePositiveSkillId(idRaw) {
-    const s = String(idRaw ?? '').trim();
-    const id = parseInt(s, 10);
-    if (!/^\d+$/.test(s) || id <= 0) {
-        printError(`Invalid skill id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
-    }
-    return id;
-}
 function printSkillRow(s) {
     const trig = s.trigger ? ` when="${s.trigger}"` : '';
     console.log(`#${s.id} [${s.status}] v${s.version}${trig} memory=${s.memoryId ?? '-'}`);
@@ -406,30 +259,12 @@ function printSkillRow(s) {
         console.log(`    change: ${s.changeSummary}`);
 }
 function skillList(hippoRoot, tenantId, flags) {
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
-    const limit = parseListLimit(flags);
-    let results;
-    if (status === 'all') {
-        results = skillsModule.loadSkills(hippoRoot, tenantId, { limit });
-    }
-    else {
-        if (!skillsModule.VALID_SKILL_STATES.has(status)) {
-            printError(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
-            process.exit(1);
-        }
-        results = skillsModule.loadSkills(hippoRoot, tenantId, {
-            status: status,
-            limit,
-        });
-    }
-    if (results.length === 0) {
-        console.log('No skills.');
-        return;
-    }
-    console.log(`Found ${results.length} skills:\n`);
-    for (const s of results)
-        printSkillRow(s);
+    listObjects(flags, {
+        plural: 'skills',
+        states: skillsModule.VALID_SKILL_STATES,
+        load: (opts) => skillsModule.loadSkills(hippoRoot, tenantId, opts),
+        printRow: printSkillRow,
+    });
 }
 function skillExport(hippoRoot, tenantId) {
     const md = skillsModule.exportSkills(hippoRoot, tenantId);
@@ -440,17 +275,8 @@ function skillExport(hippoRoot, tenantId) {
     console.log(md);
 }
 function skillGet(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo skill get <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveSkillId(idRaw);
-    const s = skillsModule.loadSkillById(hippoRoot, tenantId, id);
-    if (!s) {
-        printError(`Skill ${id} not found.`);
-        process.exit(1);
-    }
+    const id = idArgOrExit(args, 'Usage: hippo skill get <id>', SKILL.idLabel);
+    const s = foundOrExit(skillsModule.loadSkillById(hippoRoot, tenantId, id), SKILL.noun, id);
     console.log(`Skill #${s.id}`);
     console.log(`  name: ${s.skillName}`);
     console.log(`  status: ${s.status}`);
@@ -458,43 +284,22 @@ function skillGet(hippoRoot, tenantId, args) {
     if (s.trigger)
         console.log(`  when: ${s.trigger}`);
     console.log(`  instructions: ${s.instructions}`);
-    if (s.changeSummary)
-        console.log(`  change_summary: ${s.changeSummary}`);
-    if (s.supersededBy !== null)
-        console.log(`  superseded_by: #${s.supersededBy}`);
-    if (s.supersededAt)
-        console.log(`  superseded_at: ${s.supersededAt}`);
-    if (s.closedAt)
-        console.log(`  closed_at: ${s.closedAt}`);
-    if (s.memoryId)
-        console.log(`  memory: ${s.memoryId}`);
-    console.log(`  created: ${s.createdAt}`);
+    printLifecycleTail(s);
 }
 function skillSupersede(hippoRoot, tenantId, args, flags) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo skill supersede <id> --instructions "<text>" [--trigger "<when>"] [--change "<summary>"]');
-        process.exit(1);
-    }
-    const id = parsePositiveSkillId(idRaw);
-    const instrRaw = flags['instructions'];
-    if (typeof instrRaw !== 'string' || !instrRaw.trim()) {
+    const id = idArgOrExit(args, 'Usage: hippo skill supersede <id> --instructions "<text>" [--trigger "<when>"] [--change "<summary>"]', SKILL.idLabel);
+    const instrRaw = stringFlag(flags, 'instructions');
+    if (!instrRaw?.trim()) {
         printError('hippo skill supersede requires --instructions "<text>" for the new version.');
         process.exit(1);
     }
-    const existing = skillsModule.loadSkillById(hippoRoot, tenantId, id);
-    if (!existing) {
-        printError(`Skill ${id} not found.`);
-        process.exit(1);
-    }
-    const trigRaw = flags['trigger'];
-    const changeRaw = flags['change'];
+    const existing = foundOrExit(skillsModule.loadSkillById(hippoRoot, tenantId, id), SKILL.noun, id);
     try {
         const created = skillsModule.saveSkill(hippoRoot, tenantId, {
             skillName: existing.skillName,
             instructions: instrRaw,
-            trigger: typeof trigRaw === 'string' && trigRaw ? trigRaw : undefined,
-            changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+            trigger: nonEmptyStringFlag(flags, 'trigger'),
+            changeSummary: nonEmptyStringFlag(flags, 'change'),
             supersedesSkillId: id,
             extraTags: extractPathTags(process.cwd()),
         });
@@ -503,19 +308,12 @@ function skillSupersede(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }
 function skillClose(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo skill close <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveSkillId(idRaw);
-    const closed = skillsModule.closeSkill(hippoRoot, tenantId, id);
-    console.log(`Skill #${closed.id} closed.`);
+    closeObject(args, SKILL, (id) => skillsModule.closeSkill(hippoRoot, tenantId, id));
 }
 export function cmdSkill(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -538,8 +336,8 @@ function skillCreate(hippoRoot, tenantId, args, flags) {
     // Default subcommand: new (create). Accept both `skill new "<name>"` and the
     // bare `skill "<name>"` form: for the `new` keyword the name is args[1].
     const skillName = subcommand === 'new' ? (args[1] ?? '') : subcommand;
-    const instrRaw = flags['instructions'];
-    if (!skillName || typeof instrRaw !== 'string' || !instrRaw.trim()) {
+    const instrRaw = stringFlag(flags, 'instructions');
+    if (!skillName || !instrRaw?.trim()) {
         printError('Usage: hippo skill new "<name>" --instructions "<text>" [--trigger "<when>"]');
         printError('       hippo skill list [--status active|superseded|closed|all] [--limit N]');
         printError('       hippo skill get <id>');
@@ -548,12 +346,11 @@ function skillCreate(hippoRoot, tenantId, args, flags) {
         printError('       hippo skill close <id>');
         process.exit(1);
     }
-    const trigRaw = flags['trigger'];
     try {
         const created = skillsModule.saveSkill(hippoRoot, tenantId, {
             skillName,
             instructions: instrRaw,
-            trigger: typeof trigRaw === 'string' && trigRaw ? trigRaw : undefined,
+            trigger: nonEmptyStringFlag(flags, 'trigger'),
             extraTags: extractPathTags(process.cwd()),
         });
         console.log(`Skill recorded: #${created.id} (v${created.version})`);
@@ -561,7 +358,7 @@ function skillCreate(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }

package/dist/cli/print.d.ts

@@ -0,0 +1,18 @@
+import { TaskSnapshot, SessionEvent } from '../store/rows.js';
+import type { SessionHandoff } from '../core/handoff.js';
+import type { SearchResult } from '../core/search-types.js';
+import { type ImportReport } from '../agent-memories/report.js';
+export declare function fmt(n: number, digits?: number): string;
+export declare function recallEntryText(r: SearchResult, query: string, showWhy: boolean, isGlobal: boolean): string;
+export declare function recallHeading(entries: number, tokens: number, query: string): string;
+/** One line when an agent memory import moved anything; its warnings go to stderr. */
+export declare function printAgentImport(report: ImportReport, indent?: string): void;
+export declare function printActiveTaskSnapshot(snapshot: TaskSnapshot): void;
+export declare function printSessionEvents(events: SessionEvent[]): void;
+export declare function printHandoff(handoff: SessionHandoff): void;
+/**
+ * Run `fn` with console.log captured; returns the captured lines joined by
+ * newlines (what the same calls would have printed, minus the final newline).
+ */
+export declare function captureConsole(fn: () => void): string;
+//# sourceMappingURL=print.d.ts.map

package/dist/cli/print.js

@@ -0,0 +1,85 @@
+// Text printers for recall results, agent imports, task snapshots, session trails and handoffs.
+import { confidenceLabel } from '../core/memory.js';
+import { explainMatch } from '../search/explain.js';
+import { summaryLine } from '../agent-memories/report.js';
+import { snapshotText, sessionTrailText, handoffText } from '../api/context-render.js';
+import { printError } from './output.js';
+export function fmt(n, digits = 2) {
+    return n.toFixed(digits);
+}
+// What `hippo recall` prints for one result; the budget prices this same text.
+export function recallEntryText(r, query, showWhy, isGlobal) {
+    const e = r.entry;
+    const label = confidenceLabel(e);
+    const confLabel = label.warn ? `[${label.text}] ⚠️` : `[${label.text}]`;
+    const bars = Math.round(e.strength * 10);
+    const graphMark = r.graphVia ? ` [graph: ${r.graphVia.hops}hop ${r.graphVia.relType}]` : '';
+    const lines = [
+        `--- ${e.id} [${e.layer}] ${confLabel}${isGlobal ? ' [global]' : ''}${e.superseded_by ? ' [superseded]' : ''}${graphMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`,
+        `    [${'█'.repeat(bars)}${'░'.repeat(10 - bars)}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ${e.retrieval_count}x`,
+    ];
+    if (showWhy) {
+        const explanation = explainMatch(query, r);
+        lines.push(`    source:${isGlobal ? ' [global]' : ' [local]'} | layer: [${e.layer}] | confidence: [${label.text}]`, `    reason: ${explanation.reason}`);
+        const env = explanation.envelope;
+        if (env) {
+            lines.push(`    kind: ${env.kind}`);
+            if (env.scope)
+                lines.push(`    scope: ${env.scope}`);
+            if (env.owner)
+                lines.push(`    owner: ${env.owner}`);
+            if (env.artifact_ref)
+                lines.push(`    artifact_ref: ${env.artifact_ref}`);
+            if (env.session_id)
+                lines.push(`    session_id: ${env.session_id}`);
+            lines.push(`    confidence: ${env.confidence}`);
+        }
+        // The recall trace, e.g. "ranking: base 0.420 -> interference x0.30 -> 0.126 -> goal-boost x1.50 -> 0.189".
+        if (r.rerankTrace && r.rerankTrace.length > 0) {
+            const parts = [`base ${fmt(r.rerankTrace[0].scoreBefore, 3)}`];
+            for (const step of r.rerankTrace) {
+                parts.push(`${step.stage}${step.multiplier !== undefined ? ` x${fmt(step.multiplier, 2)}` : ''}`, fmt(step.scoreAfter, 3));
+            }
+            lines.push(`    ranking: ${parts.join(' -> ')}`);
+        }
+    }
+    lines.push('', e.content, '');
+    return lines.join('\n');
+}
+export function recallHeading(entries, tokens, query) {
+    return `Found ${entries} memories (${tokens} tokens) for: "${query}"\n`;
+}
+/** One line when an agent memory import moved anything; its warnings go to stderr. */
+export function printAgentImport(report, indent = '   ') {
+    const line = summaryLine(report);
+    if (line !== null)
+        console.log(`${indent}${line}`);
+    for (const warning of report.warnings)
+        printError(`hippo: agent memories: ${warning}`);
+}
+export function printActiveTaskSnapshot(snapshot) {
+    console.log(snapshotText(snapshot));
+}
+export function printSessionEvents(events) {
+    console.log(events.length === 0 ? 'No session events found.' : sessionTrailText(events));
+}
+export function printHandoff(handoff) {
+    console.log(handoffText(handoff));
+}
+/**
+ * Run `fn` with console.log captured; returns the captured lines joined by
+ * newlines (what the same calls would have printed, minus the final newline).
+ */
+export function captureConsole(fn) {
+    const lines = [];
+    const realLog = console.log;
+    console.log = (...parts) => { lines.push(parts.map(String).join(' ')); };
+    try {
+        fn();
+    }
+    finally {
+        console.log = realLog;
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=print.js.map

package/dist/cli/projects.d.ts

@@ -1,4 +1,3 @@
-type Flags = Record<string, string | boolean | string[]>;
-export declare function cmdProjects(hippoRoot: string, args: string[], flags: Flags): void;
-export {};
+import { type CliFlags } from './flag-values.js';
+export declare function cmdProjects(hippoRoot: string, args: string[], flags: CliFlags): void;
 //# sourceMappingURL=projects.d.ts.map