hippo-memory 1.60.0 → 1.61.0

package/dist/cli/card.js

@@ -0,0 +1,333 @@
+// The `hippo card` verb (the agent work board); main() loads it lazily from the command table.
+import { createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from '../store-cards.js';
+import { isHandoffOutcome } from '../handoff.js';
+import { isCardStatus } from '../card.js';
+import { loadCardDetail } from '../card-detail.js';
+import { resolveTenantId } from '../tenant.js';
+import { printError } from './output.js';
+import { requireInit, cardStringFlag } from './shared.js';
+// Mirrors ARCHIVE_REASON_REQUIRED so the block message can't drift from its usage line.
+const CARD_BLOCK_REASON_REQUIRED = 'hippo card block <id> requires --reason "<why>" (recorded as a comment).';
+function printCard(detail) {
+    const { card, deps, runs, comments, handoff } = detail;
+    console.log(`## Card ${card.id}\n`);
+    console.log(`- Title: ${card.title}`);
+    console.log(`- Status: ${card.status}`);
+    if (card.assigneeRuntime)
+        console.log(`- Assignee: ${card.assigneeRuntime}`);
+    if (card.leaseUntil)
+        console.log(`- Lease until: ${card.leaseUntil}`);
+    if (card.heartbeatAt)
+        console.log(`- Heartbeat: ${card.heartbeatAt}`);
+    if (card.repo)
+        console.log(`- Repo: ${card.repo}`);
+    if (card.contract)
+        console.log(`- Contract: ${card.contract}`);
+    if (card.budget !== null)
+        console.log(`- Budget: ${card.budget}`);
+    console.log(`- Updated: ${card.updatedAt}`);
+    if (deps.parents.length > 0)
+        console.log(`- Parents: ${deps.parents.join(', ')}`);
+    if (deps.children.length > 0)
+        console.log(`- Children: ${deps.children.join(', ')}`);
+    if (runs.length > 0) {
+        console.log('\n### Runs');
+        for (const run of runs) {
+            console.log(`- run ${run.id}: ${run.runtime} started ${run.started}${run.ended ? ` ended ${run.ended} (${run.outcome})` : ' (open)'}`);
+        }
+    }
+    if (comments.length > 0) {
+        console.log('\n### Comments');
+        for (const comment of comments) {
+            console.log(`- [${comment.createdAt}] ${comment.author}: ${comment.body}`);
+        }
+    }
+    if (handoff) {
+        console.log('\n### Latest handoff');
+        console.log(`- Session: ${handoff.sessionId}, updated ${handoff.updatedAt}`);
+        console.log(handoff.summary);
+    }
+    console.log('');
+}
+// A too-large --run would silently round to a different id (mirrors parsePositiveIncidentId).
+function cardRunFlag(flags) {
+    const raw = cardStringFlag(flags, 'run');
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isSafeInteger(n) || n <= 0) {
+        printError(`Invalid --run: "${raw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return n;
+}
+// Reads after the store already refused, so this only explains the refusal, never changes it.
+function cardRefusal(hippoRoot, tenantId, id) {
+    const card = loadCard(hippoRoot, tenantId, id);
+    const liveRun = loadCardRuns(hippoRoot, tenantId, id).find((r) => !r.ended);
+    return `status ${card?.status ?? 'unknown'}, live run ${liveRun?.id ?? 'none'}`;
+}
+const CARD_SUBCOMMAND_FLAGS = {
+    create: ['title', 'repo', 'contract', 'budget', 'depends-on'],
+    show: ['json'],
+    list: ['status', 'json'],
+    claim: ['runtime', 'session'],
+    heartbeat: ['run'],
+    block: ['reason', 'run'],
+    review: ['run'],
+    complete: ['outcome', 'run'],
+    reclaim: new Array(),
+    comment: ['body', 'author'],
+};
+/** Runs `hippo card <subcommand>`: rejects flags the subcommand never reads, then hands off to its handler. */
+export function cmdCard(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const tenantId = resolveTenantId({});
+    const subcommand = args[0] ?? '';
+    if (!Object.hasOwn(CARD_SUBCOMMAND_FLAGS, subcommand)) {
+        printError('Usage: hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>');
+        process.exit(1);
+    }
+    // SAFETY: hasOwn, unlike `in`, skips inherited keys such as constructor, so subcommand is a real key.
+    const known = subcommand;
+    const allowedFlags = CARD_SUBCOMMAND_FLAGS[known];
+    for (const key of Object.keys(flags)) {
+        if (!allowedFlags.includes(key)) {
+            const valid = allowedFlags.length > 0 ? allowedFlags.map((f) => `--${f}`).join(', ') : '(none)';
+            printError(`Unknown flag --${key} for hippo card ${subcommand}. Valid flags: ${valid}`);
+            process.exit(1);
+        }
+    }
+    CARD_HANDLERS[known](hippoRoot, tenantId, args, flags);
+}
+function cardCreate(hippoRoot, tenantId, _args, flags) {
+    const title = cardStringFlag(flags, 'title') ?? '';
+    if (!title) {
+        printError('Usage: hippo card create --title "..." [--repo <name>] [--contract <text>] [--budget <n>] [--depends-on <id>...]');
+        process.exit(1);
+    }
+    const repo = cardStringFlag(flags, 'repo') || undefined;
+    const contract = cardStringFlag(flags, 'contract') || undefined;
+    const budgetRaw = cardStringFlag(flags, 'budget');
+    let budget;
+    if (budgetRaw !== undefined) {
+        if (!/^\d+$/.test(budgetRaw)) {
+            printError(`Invalid budget: "${budgetRaw}" (expected a positive integer)`);
+            process.exit(1);
+        }
+        budget = Number(budgetRaw);
+    }
+    const dependsOnFlag = flags['depends-on'];
+    if (dependsOnFlag === true) {
+        printError('--depends-on requires a value');
+        process.exit(1);
+    }
+    const dependsOn = Array.isArray(dependsOnFlag) ? dependsOnFlag : [];
+    let card;
+    try {
+        card = createCard(hippoRoot, tenantId, { title, repo, contract, budget, dependsOn });
+    }
+    catch (error) {
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    console.log(`Created card ${card.id} (status: ${card.status})`);
+}
+function cardShow(hippoRoot, tenantId, args, flags) {
+    const id = args[1];
+    if (!id) {
+        printError('Usage: hippo card show <id> [--json]');
+        process.exit(1);
+    }
+    const detail = loadCardDetail(hippoRoot, tenantId, id);
+    if (!detail) {
+        printError(`No card found with id ${id}.`);
+        process.exit(1);
+    }
+    if (flags['json']) {
+        console.log(JSON.stringify(detail, null, 2));
+        return;
+    }
+    printCard(detail);
+}
+function cardList(hippoRoot, tenantId, _args, flags) {
+    const status = cardStringFlag(flags, 'status');
+    if (status !== undefined && !isCardStatus(status)) {
+        printError(`Invalid status: "${status}".`);
+        process.exit(1);
+    }
+    const cards = listCards(hippoRoot, tenantId, { status });
+    if (flags['json']) {
+        console.log(JSON.stringify({ cards }, null, 2));
+        return;
+    }
+    if (cards.length === 0) {
+        console.log('No cards found.');
+        return;
+    }
+    for (const card of cards) {
+        console.log(`${card.id}\t${card.status}\t${card.title}${card.assigneeRuntime ? `\t(${card.assigneeRuntime})` : ''}`);
+    }
+}
+function cardClaim(hippoRoot, tenantId, args, flags) {
+    const id = args[1];
+    const runtime = cardStringFlag(flags, 'runtime') ?? '';
+    if (!id || !runtime) {
+        printError('Usage: hippo card claim <id> --runtime <name> [--session <id>]');
+        process.exit(1);
+    }
+    const sessionId = cardStringFlag(flags, 'session') || undefined;
+    let card;
+    try {
+        card = claimCard(hippoRoot, tenantId, id, runtime, sessionId);
+    }
+    catch (error) {
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    if (!card) {
+        printError(`Could not claim card ${id} (not ready/blocked, or already claimed).`);
+        process.exit(1);
+    }
+    console.log(`Claimed card ${card.id} for ${runtime} (run ${card.runId}, lease until ${card.leaseUntil})`);
+}
+function cardHeartbeat(hippoRoot, tenantId, args, flags) {
+    const id = args[1];
+    const runId = cardRunFlag(flags);
+    if (!id || runId === undefined) {
+        printError('Usage: hippo card heartbeat <id> --run <n>');
+        process.exit(1);
+    }
+    let card;
+    try {
+        card = heartbeatCard(hippoRoot, tenantId, id, runId);
+    }
+    catch (error) {
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    if (!card) {
+        printError(`Could not heartbeat card ${id} (${cardRefusal(hippoRoot, tenantId, id)}).`);
+        process.exit(1);
+    }
+    console.log(`Heartbeat card ${card.id}: lease until ${card.leaseUntil}`);
+}
+function cardBlock(hippoRoot, tenantId, args, flags) {
+    const id = args[1];
+    const reason = cardStringFlag(flags, 'reason') ?? '';
+    if (!id || !reason) {
+        printError(CARD_BLOCK_REASON_REQUIRED);
+        process.exit(1);
+    }
+    const runId = cardRunFlag(flags);
+    let card;
+    try {
+        card = blockCard(hippoRoot, tenantId, id, reason, runId);
+    }
+    catch (error) {
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    if (!card) {
+        const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
+        printError(`Could not block card ${id} (${why}).`);
+        process.exit(1);
+    }
+    console.log(`Blocked card ${card.id}`);
+}
+function cardReview(hippoRoot, tenantId, args, flags) {
+    const id = args[1];
+    if (!id) {
+        printError('Usage: hippo card review <id> [--run <n>]');
+        process.exit(1);
+    }
+    const runId = cardRunFlag(flags);
+    let card;
+    try {
+        card = reviewCard(hippoRoot, tenantId, id, runId);
+    }
+    catch (error) {
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    if (!card) {
+        const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
+        printError(`Could not move card ${id} to review (${why}).`);
+        process.exit(1);
+    }
+    console.log(`Card ${card.id} moved to review`);
+}
+function cardComplete(hippoRoot, tenantId, args, flags) {
+    const id = args[1];
+    const outcomeRaw = flags['outcome'];
+    if (!id || !isHandoffOutcome(outcomeRaw)) {
+        printError('Usage: hippo card complete <id> --outcome <success|failure|partial> [--run <n>]');
+        process.exit(1);
+    }
+    const runId = cardRunFlag(flags);
+    let result;
+    try {
+        result = completeCard(hippoRoot, tenantId, id, outcomeRaw, runId);
+    }
+    catch (error) {
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    if (!result) {
+        const why = runId === undefined ? 'not in review' : cardRefusal(hippoRoot, tenantId, id);
+        printError(`Could not complete card ${id} (${why}).`);
+        process.exit(1);
+    }
+    console.log(`Completed card ${result.card.id} (status: ${result.card.status})`);
+    if (result.promotedChildren.length > 0) {
+        console.log(`Promoted to ready: ${result.promotedChildren.join(', ')}`);
+    }
+}
+function cardReclaim(hippoRoot, tenantId, args) {
+    if (args.length > 1) {
+        printError('Usage: hippo card reclaim (sweeps every expired lease; use hippo card block <id> for one card)');
+        process.exit(1);
+    }
+    const ids = reclaimExpiredCards(hippoRoot, tenantId);
+    if (ids.length === 0) {
+        console.log('No expired leases.');
+        return;
+    }
+    for (const id of ids) {
+        console.log(`Reclaimed card ${id} (now ready)`);
+    }
+}
+function cardComment(hippoRoot, tenantId, args, flags) {
+    const id = args[1];
+    if (!id) {
+        printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
+        process.exit(1);
+    }
+    // Only show and comment look the card up directly; claim/heartbeat/block/review/complete throw from the store instead.
+    const card = loadCard(hippoRoot, tenantId, id);
+    if (!card) {
+        printError(`No card found with id ${id}.`);
+        process.exit(1);
+    }
+    const body = cardStringFlag(flags, 'body') ?? '';
+    if (!body) {
+        printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
+        process.exit(1);
+    }
+    const author = cardStringFlag(flags, 'author') || 'cli';
+    const comment = addCardComment(hippoRoot, tenantId, id, author, body);
+    console.log(`Added comment ${comment.id} to card ${id}`);
+}
+const CARD_HANDLERS = {
+    create: cardCreate,
+    show: cardShow,
+    list: cardList,
+    claim: cardClaim,
+    heartbeat: cardHeartbeat,
+    block: cardBlock,
+    review: cardReview,
+    complete: cardComplete,
+    reclaim: cardReclaim,
+    comment: cardComment,
+};
+//# sourceMappingURL=card.js.map

package/dist/cli/context.d.ts

@@ -0,0 +1,15 @@
+import { MemoryEntry } from '../memory.js';
+import { type CommandContext } from './shared.js';
+export declare function cmdContext(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>, stdinText?: string): Promise<void>;
+/** @internal Exported for the render snapshot test; not a stable public API. */
+export declare function printContextMarkdown(items: Array<{
+    entry: MemoryEntry;
+    score: number;
+    tokens: number;
+    isGlobal: boolean;
+}>, totalTokens: number, framing?: string, opts?: {
+    showStrength?: boolean;
+    heading?: string;
+}): void;
+export declare function handleContext({ hippoRoot, args, flags }: CommandContext): Promise<void>;
+//# sourceMappingURL=context.d.ts.map