hippo-memory 1.69.0 → 1.71.0

package/dist/cli/playbooks.js

@@ -1,86 +1,47 @@
 // 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 { printError } from './output.js';
+import { isStringFlag, 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';
+import { CliExit } from './exit.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) {
     if (Array.isArray(stepRaw))
         return stepRaw;
-    if (typeof stepRaw === 'string')
+    if (isStringFlag(stepRaw))
         return [stepRaw];
     if (stepRaw === true) {
         printError('--step requires a value, e.g. hippo process new "<name>" --step "do X".');
-        process.exit(1);
+        throw new CliExit(1);
     }
     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,42 +52,20 @@ 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.');
-        process.exit(1);
-    }
-    // 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);
+        throw new CliExit(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;
+    // A supersession is a new version of the SAME process, so the new row reuses the predecessor's name; loadProcessById gives an early not-found,
+    // and saveProcess's in-SAVEPOINT preflight is the authoritative active-state check.
+    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,18 +80,10 @@ 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) {
+export function handleProcess({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
     if (subcommand === 'list')
         return processList(hippoRoot, tenantId, flags);
@@ -162,9 +93,8 @@ export function cmdProcess(hippoRoot, args, flags) {
         return processSupersede(hippoRoot, tenantId, args, flags);
     if (subcommand === 'close')
         return processClose(hippoRoot, tenantId, args);
-    // Default subcommand: new (create). Accept both the documented
-    // `process new "<name>"` form and the bare `process "<name>"` form: for the
-    // `new` keyword the name is args[1], otherwise args[0] IS the name.
+    // Default subcommand is new (create): accept both `process new "<name>"` and bare `process "<name>"`;
+    // for the `new` keyword the name is args[1], otherwise args[0] is the name.
     processCreate(hippoRoot, tenantId, subcommand === 'new' ? (args[1] ?? '') : subcommand, flags);
 }
 function processCreate(hippoRoot, tenantId, processName, flags) {
@@ -174,11 +104,10 @@ function processCreate(hippoRoot, tenantId, processName, flags) {
         printError('       hippo process get <id>');
         printError('       hippo process supersede <id> --step "<text>" [--change "<summary>"]');
         printError('       hippo process close <id>');
-        process.exit(1);
+        throw new CliExit(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 +119,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,46 +127,27 @@ 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];
     if (!dateRaw) {
         printError('Usage: hippo policy asof <iso-date> [--name "<policy>"]');
-        process.exit(1);
+        throw new CliExit(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);
-        process.exit(1);
+        printError(errorMessage(e));
+        throw new CliExit(1);
     }
     if (results.length === 0) {
         console.log(`No active policies in force at ${dateRaw}${name ? ` for "${name}"` : ''}.`);
@@ -258,17 +158,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 +167,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);
+        throw new CliExit(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,23 +192,15 @@ function policySupersede(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
-        process.exit(1);
+        printError(errorMessage(e));
+        throw new CliExit(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) {
+export function handlePolicy({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
     if (subcommand === 'list')
         return policyList(hippoRoot, tenantId, flags);
@@ -358,24 +219,22 @@ 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>');
         printError('       hippo policy asof <iso-date> [--name "<policy>"]');
         printError('       hippo policy supersede <id> --text "<rule>" [--from] [--to] [--change "<summary>"]');
         printError('       hippo policy close <id>');
-        process.exit(1);
+        throw new CliExit(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 +243,10 @@ function policyCreate(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
-        process.exit(1);
+        printError(errorMessage(e));
+        throw new CliExit(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 +255,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 +271,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 +280,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);
+        throw new CliExit(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,23 +304,15 @@ function skillSupersede(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
-        process.exit(1);
+        printError(errorMessage(e));
+        throw new CliExit(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) {
+export function handleSkill({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
     if (subcommand === 'list')
         return skillList(hippoRoot, tenantId, flags);
@@ -538,22 +331,21 @@ 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>');
         printError('       hippo skill export   (render active skills as an AGENTS.md/CLAUDE.md block)');
         printError('       hippo skill supersede <id> --instructions "<text>" [--trigger] [--change "<summary>"]');
         printError('       hippo skill close <id>');
-        process.exit(1);
+        throw new CliExit(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,8 +353,8 @@ function skillCreate(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
-        process.exit(1);
+        printError(errorMessage(e));
+        throw new CliExit(1);
     }
 }
 //# sourceMappingURL=playbooks.js.map

package/dist/cli/print.d.ts

@@ -0,0 +1,15 @@
+import type { 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 (no final newline). */
+export declare function captureConsole(fn: () => void): string;
+//# sourceMappingURL=print.d.ts.map