@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

package/dist/runtime/commands/memory.js

@@ -0,0 +1,582 @@
+/**
+ * `pugi memory` — operator surface for the persona-memory layer
+ * .
+ *
+ * Subcommands:
+ *
+ *  pugi memory list [--persona <slug>] [--kind <kind>] [--limit <n>]
+ *    List memories for the current tenant — recency-first. Renders a
+ *    table with TTL countdown.
+ *
+ *  pugi memory recall <query> [--persona <slug>] [--top-k <n>]
+ *    Hybrid recall (vector + BM25 + recency) for one persona.
+ *
+ *  pugi memory write <kind> <content> [--persona <slug>] [--forget-after <iso>]
+ *    Persist a new memory. Queues locally + retries on next sync when
+ *    the admin-api is unreachable.
+ *
+ *  pugi memory forget <id>
+ *    Hard-delete one memory by id.
+ *
+ *  pugi memory sync
+ *    Push the local pending-write queue to the admin-api. Idempotent:
+ *    successful ops are dropped from the queue, failed ops stay queued.
+ *
+ * Auth surface: the same `resolveActiveCredential` flow every other
+ * pugi command uses — bearer token + apiUrl from `~/.pugi/credentials.json`.
+ * The admin-api enforces the tenant boundary via `BridgeOrJwtGuard` +
+ * `prisma.withTenant`.
+ *
+ * Feature flag: the admin-api side honours `PERSONA_MEMORY_ENABLED` and
+ * returns HTTP 503 `{error: feature_disabled}` until the flag is
+ * flipped. The CLI surfaces that response verbatim so the operator
+ * sees the actual gate.
+ */
+import { request } from 'undici';
+import { resolveActiveCredential } from '../../core/credentials.js';
+import { isScanDisabled, redactSecrets, scanForSecrets, } from '../../core/memory/secret-scanner.js';
+import { PERSONA_MEMORY_KINDS, countPending, defaultQueuePath, enqueueMemoryOp, readMemoryQueue, rewriteMemoryQueue, } from '../../core/memory-sync/queue.js';
+const SUB_USAGE = [
+    'pugi memory list  [--persona <slug>] [--kind <k>] [--limit <n>]',
+    'pugi memory recall <query> [--persona <slug>] [--top-k <n>]',
+    'pugi memory write <kind> <content> [--persona <slug>] [--forget-after <iso>]',
+    'pugi memory forget <id>',
+    'pugi memory sync',
+].join('\n ');
+const DEFAULT_PERSONA = 'mira';
+/** Single CLI entry — top-level `pugi memory` AND the in-REPL `/memory` slash both call this. */
+export async function runMemoryCommand(args, ctx) {
+    const sub = (args[0] ?? '').toLowerCase();
+    const tail = args.slice(1);
+    switch (sub) {
+        case '':
+        case '-h':
+        case '--help':
+            return printUsage(ctx);
+        case 'list':
+            return runList(tail, ctx);
+        case 'recall':
+            return runRecall(tail, ctx);
+        case 'write':
+        case 'remember':
+            return runWrite(tail, ctx);
+        case 'forget':
+        case 'delete':
+            return runForget(tail, ctx);
+        case 'sync':
+            return runSync(ctx);
+        default:
+            ctx.writeOutput({ command: 'memory', sub, status: 'unknown_sub' }, `Unknown sub-command "${sub}".\nUsage:\n ${SUB_USAGE}`);
+            return { command: 'memory', sub, status: 'unknown_sub' };
+    }
+}
+function printUsage(ctx) {
+    ctx.writeOutput({ command: 'memory', sub: 'help', usage: SUB_USAGE }, `pugi memory — persona-memory operator surface .\nUsage:\n ${SUB_USAGE}`);
+    return { command: 'memory', sub: 'help', status: 'listed' };
+}
+// ===========================================================================
+// list
+// ===========================================================================
+async function runList(args, ctx) {
+    const flags = parseFlags(args);
+    const cred = resolveActiveCredential();
+    if (!cred)
+        return emitUnauth('list', ctx);
+    const url = new URL(`${stripTrailing(cred.apiUrl)}/api/persona-memory`);
+    if (flags.persona)
+        url.searchParams.set('personaSlug', flags.persona);
+    if (flags.kind)
+        url.searchParams.set('kind', flags.kind);
+    if (flags.limit)
+        url.searchParams.set('limit', String(flags.limit));
+    const res = await safeGet(url.toString(), cred.apiKey);
+    if (res.status === 503)
+        return emitFeatureDisabled('list', ctx);
+    if (!res.ok) {
+        ctx.writeOutput({ command: 'memory', sub: 'list', status: 'invalid_args', reason: res.detail }, `pugi memory list: HTTP ${res.statusCode} — ${res.detail}`);
+        return { command: 'memory', sub: 'list', status: 'invalid_args', reason: res.detail };
+    }
+    const items = (res.body ?? []);
+    const now = (ctx.now ?? (() => new Date()))();
+    const lines = items.map((item) => formatMemoryRow(item, now));
+    const text = items.length === 0
+        ? 'No memories for the active tenant + filters.'
+        : ['kind        strength age     ttl        id                                   content', ...lines].join('\n');
+    ctx.writeOutput({ command: 'memory', sub: 'list', count: items.length, items }, text);
+    return { command: 'memory', sub: 'list', status: 'listed', count: items.length };
+}
+// ===========================================================================
+// recall
+// ===========================================================================
+async function runRecall(args, ctx) {
+    const { positional, flags } = splitPositionalFlags(args);
+    if (positional.length === 0) {
+        ctx.writeOutput({ command: 'memory', sub: 'recall', status: 'invalid_args' }, 'pugi memory recall <query> — query is required.');
+        return { command: 'memory', sub: 'recall', status: 'invalid_args' };
+    }
+    const query = positional.join(' ').trim();
+    const persona = flags.persona ?? DEFAULT_PERSONA;
+    const topK = flags.topK ?? 5;
+    const cred = resolveActiveCredential();
+    if (!cred)
+        return emitUnauth('recall', ctx);
+    const url = new URL(`${stripTrailing(cred.apiUrl)}/api/persona-memory/recall`);
+    url.searchParams.set('personaSlug', persona);
+    url.searchParams.set('query', query);
+    url.searchParams.set('topK', String(topK));
+    const res = await safeGet(url.toString(), cred.apiKey);
+    if (res.status === 503)
+        return emitFeatureDisabled('recall', ctx);
+    if (!res.ok) {
+        ctx.writeOutput({ command: 'memory', sub: 'recall', status: 'invalid_args', reason: res.detail }, `pugi memory recall: HTTP ${res.statusCode} — ${res.detail}`);
+        return { command: 'memory', sub: 'recall', status: 'invalid_args', reason: res.detail };
+    }
+    const results = (res.body ?? []);
+    const text = results.length === 0
+        ? `No matches for "${query.slice(0, 64)}" on persona "${persona}".`
+        : results
+            .map((r, idx) => `${(idx + 1).toString().padStart(2, ' ')}. [${r.item.kind}] score=${r.score.toFixed(3)} ${r.item.content}`)
+            .join('\n');
+    ctx.writeOutput({ command: 'memory', sub: 'recall', count: results.length, results }, text);
+    return { command: 'memory', sub: 'recall', status: 'recalled', count: results.length };
+}
+// ===========================================================================
+// write
+// ===========================================================================
+async function runWrite(args, ctx) {
+    // Backlog : `--curate` opts into the proposal-first
+    // mode powered by `pugi remember`. Default behaviour (silent enqueue)
+    // is preserved for back-compat per the bundled-skills spec — the
+    // operator has to explicitly opt in.
+    const curateRequested = args.includes('--curate');
+    // Backlog : `--allow-redacted` opts into the
+    // auto-scrub flow. Default behaviour is HARD reject; this flag tells
+    // the secret scanner to replace each secret with `[SECRET:<pattern>]`
+    // and persist the scrubbed payload, surfacing a warning so the
+    // operator notices.
+    const allowRedacted = args.includes('--allow-redacted');
+    const argsWithoutCurate = args
+        .filter((a) => a !== '--curate')
+        .filter((a) => a !== '--allow-redacted');
+    const { positional, flags } = splitPositionalFlags(argsWithoutCurate);
+    if (positional.length < 2) {
+        ctx.writeOutput({ command: 'memory', sub: 'write', status: 'invalid_args' }, 'pugi memory write <kind> <content> — kind + content required.');
+        return { command: 'memory', sub: 'write', status: 'invalid_args' };
+    }
+    if (curateRequested) {
+        // Hand off to the bundled remember skill. We surface a single line
+        // hint and a structured payload so scripted callers can detect the
+        // delegation without grepping prose.
+        const hint = 'Use `pugi remember "<content>"` for proposal-first curation. ' +
+            '`pugi memory write --curate` will route there once the interactive ' +
+            'bundle wiring lands; meanwhile the silent enqueue is preserved.';
+        ctx.writeOutput({
+            command: 'memory',
+            sub: 'write',
+            status: 'curate_hint',
+            hint,
+        }, hint);
+    }
+    const kind = positional[0]?.toLowerCase() ?? '';
+    // `content` is `let` (not `const`) so the secret-scanner branch
+    // below can swap in a redacted version when --allow-redacted fires.
+    let content = positional.slice(1).join(' ').trim();
+    if (!PERSONA_MEMORY_KINDS.includes(kind)) {
+        ctx.writeOutput({
+            command: 'memory',
+            sub: 'write',
+            status: 'invalid_args',
+            reason: 'unknown_kind',
+        }, `pugi memory write: unknown kind "${kind}". Expected one of ${PERSONA_MEMORY_KINDS.join(' | ')}.`);
+        return { command: 'memory', sub: 'write', status: 'invalid_args', reason: 'unknown_kind' };
+    }
+    if (content.length === 0) {
+        ctx.writeOutput({ command: 'memory', sub: 'write', status: 'invalid_args' }, 'pugi memory write: content is empty.');
+        return { command: 'memory', sub: 'write', status: 'invalid_args' };
+    }
+    // Backlog — secret-scanner middleware. Runs BEFORE network +
+    // BEFORE offline enqueue so both code paths share the gate.
+    //  - default: HARD reject (status: 'secret_blocked'), no write.
+    //  - PUGI_MEMORY_SECRET_SCAN_DISABLE=1: skipped entirely.
+    //  - --allow-redacted: matches replaced with `[SECRET:<pattern>]`
+    //                      placeholders, write proceeds + warning.
+    // The post-scan content is what gets enqueued / POSTed. We mutate
+    // `content` to keep the rest of the function untouched.
+    if (!isScanDisabled()) {
+        const matches = scanForSecrets(content);
+        if (matches.length > 0) {
+            if (allowRedacted) {
+                const scrubbed = redactSecrets(content);
+                content = scrubbed.redacted;
+                const names = Array.from(new Set(scrubbed.matches.map((m) => m.pattern))).join(', ');
+                ctx.writeOutput({
+                    command: 'memory',
+                    sub: 'write',
+                    status: 'redacted',
+                    patterns: names,
+                    count: scrubbed.matches.length,
+                }, `pugi memory write: --allow-redacted scrubbed ${scrubbed.matches.length} secret(s) — pattern(s): ${names}. Persisting redacted content.`);
+            }
+            else {
+                const names = Array.from(new Set(matches.map((m) => m.pattern))).join(', ');
+                ctx.writeOutput({
+                    command: 'memory',
+                    sub: 'write',
+                    status: 'secret_blocked',
+                    patterns: names,
+                    count: matches.length,
+                    hint: 'pass --allow-redacted to auto-scrub, or PUGI_MEMORY_SECRET_SCAN_DISABLE=1 to bypass',
+                }, `pugi memory write: refused — content contains secret(s): ${names}. ` +
+                    `Re-run with --allow-redacted to auto-scrub, or set PUGI_MEMORY_SECRET_SCAN_DISABLE=1 to bypass.`);
+                return {
+                    command: 'memory',
+                    sub: 'write',
+                    status: 'secret_blocked',
+                    reason: names,
+                };
+            }
+        }
+    }
+    const persona = flags.persona ?? DEFAULT_PERSONA;
+    const cred = resolveActiveCredential();
+    if (!cred) {
+        // Queue offline. Operator can run `pugi memory sync` once auth is up.
+        const pending = enqueueMemoryOp({
+            op: 'write',
+            personaSlug: persona,
+            kind: kind,
+            content,
+            forgetAfter: flags.forgetAfter ?? null,
+        });
+        ctx.writeOutput({
+            command: 'memory',
+            sub: 'write',
+            status: 'queued_offline',
+            pending,
+        }, `Queued offline (no active credential). ${pending} pending — run \`pugi memory sync\` after \`pugi login\`.`);
+        return { command: 'memory', sub: 'write', status: 'queued_offline', pending };
+    }
+    const url = `${stripTrailing(cred.apiUrl)}/api/persona-memory`;
+    const body = {
+        personaSlug: persona,
+        kind,
+        content,
+        forgetAfter: flags.forgetAfter ?? null,
+    };
+    const res = await safePost(url, cred.apiKey, body);
+    if (res.status === 503)
+        return emitFeatureDisabled('write', ctx);
+    if (!res.ok) {
+        // Server unreachable / 5xx → queue for retry. 4xx → surface error,
+        // don't queue (a malformed write would just loop on sync).
+        if (res.statusCode >= 500 || res.statusCode === 0) {
+            const pending = enqueueMemoryOp({
+                op: 'write',
+                personaSlug: persona,
+                kind: kind,
+                content,
+                forgetAfter: flags.forgetAfter ?? null,
+            });
+            ctx.writeOutput({
+                command: 'memory',
+                sub: 'write',
+                status: 'queued_offline',
+                pending,
+                reason: res.detail,
+            }, `Server unreachable (${res.detail}). Queued — ${pending} pending. Run \`pugi memory sync\` later.`);
+            return {
+                command: 'memory',
+                sub: 'write',
+                status: 'queued_offline',
+                pending,
+                reason: res.detail,
+            };
+        }
+        ctx.writeOutput({ command: 'memory', sub: 'write', status: 'invalid_args', reason: res.detail }, `pugi memory write: HTTP ${res.statusCode} — ${res.detail}`);
+        return {
+            command: 'memory',
+            sub: 'write',
+            status: 'invalid_args',
+            reason: res.detail,
+        };
+    }
+    const created = (res.body ?? {});
+    ctx.writeOutput({ command: 'memory', sub: 'write', status: 'written', item: created }, `Persisted [${kind}] on persona "${persona}": ${created.id}`);
+    return { command: 'memory', sub: 'write', status: 'written' };
+}
+// ===========================================================================
+// forget
+// ===========================================================================
+async function runForget(args, ctx) {
+    const id = (args[0] ?? '').trim();
+    if (!id) {
+        ctx.writeOutput({ command: 'memory', sub: 'forget', status: 'invalid_args' }, 'pugi memory forget <id> — memory id is required.');
+        return { command: 'memory', sub: 'forget', status: 'invalid_args' };
+    }
+    const cred = resolveActiveCredential();
+    if (!cred) {
+        const pending = enqueueMemoryOp({ op: 'forget', id });
+        ctx.writeOutput({ command: 'memory', sub: 'forget', status: 'queued_offline', pending }, `Queued offline (no active credential). ${pending} pending — run \`pugi memory sync\` after \`pugi login\`.`);
+        return { command: 'memory', sub: 'forget', status: 'queued_offline', pending };
+    }
+    const url = `${stripTrailing(cred.apiUrl)}/api/persona-memory/${encodeURIComponent(id)}`;
+    const res = await safeDelete(url, cred.apiKey);
+    if (res.status === 503)
+        return emitFeatureDisabled('forget', ctx);
+    if (res.statusCode === 404) {
+        ctx.writeOutput({ command: 'memory', sub: 'forget', status: 'forget_not_found', id }, `No memory with id "${id}" in this tenant.`);
+        return { command: 'memory', sub: 'forget', status: 'forget_not_found' };
+    }
+    if (!res.ok) {
+        if (res.statusCode >= 500 || res.statusCode === 0) {
+            const pending = enqueueMemoryOp({ op: 'forget', id });
+            ctx.writeOutput({
+                command: 'memory',
+                sub: 'forget',
+                status: 'queued_offline',
+                pending,
+                reason: res.detail,
+            }, `Server unreachable. Queued — ${pending} pending.`);
+            return {
+                command: 'memory',
+                sub: 'forget',
+                status: 'queued_offline',
+                pending,
+                reason: res.detail,
+            };
+        }
+        ctx.writeOutput({ command: 'memory', sub: 'forget', status: 'invalid_args', reason: res.detail }, `pugi memory forget: HTTP ${res.statusCode} — ${res.detail}`);
+        return {
+            command: 'memory',
+            sub: 'forget',
+            status: 'invalid_args',
+            reason: res.detail,
+        };
+    }
+    ctx.writeOutput({ command: 'memory', sub: 'forget', status: 'forgot', id }, `Forgot "${id}".`);
+    return { command: 'memory', sub: 'forget', status: 'forgot' };
+}
+// ===========================================================================
+// sync
+// ===========================================================================
+async function runSync(ctx) {
+    const cred = resolveActiveCredential();
+    if (!cred)
+        return emitUnauth('sync', ctx);
+    const pendingBefore = countPending();
+    if (pendingBefore === 0) {
+        ctx.writeOutput({ command: 'memory', sub: 'sync', status: 'sync_noop', pending: 0 }, 'No pending operations to sync.');
+        return { command: 'memory', sub: 'sync', status: 'sync_noop', pending: 0 };
+    }
+    const ops = readMemoryQueue();
+    const remaining = [];
+    let synced = 0;
+    for (const op of ops) {
+        const ok = await flushOne(cred.apiUrl, cred.apiKey, op);
+        if (ok) {
+            synced++;
+        }
+        else {
+            remaining.push(op);
+        }
+    }
+    rewriteMemoryQueue(remaining);
+    if (remaining.length === 0) {
+        ctx.writeOutput({
+            command: 'memory',
+            sub: 'sync',
+            status: 'synced',
+            pending: 0,
+            count: synced,
+        }, `Synced ${synced} pending operation(s). Queue is empty.`);
+        return { command: 'memory', sub: 'sync', status: 'synced', pending: 0, count: synced };
+    }
+    ctx.writeOutput({
+        command: 'memory',
+        sub: 'sync',
+        status: 'sync_partial',
+        pending: remaining.length,
+        count: synced,
+    }, `Synced ${synced} — ${remaining.length} still pending (server unreachable / 4xx).`);
+    return {
+        command: 'memory',
+        sub: 'sync',
+        status: 'sync_partial',
+        pending: remaining.length,
+        count: synced,
+    };
+}
+async function flushOne(apiUrl, apiKey, op) {
+    if (op.op === 'write') {
+        const res = await safePost(`${stripTrailing(apiUrl)}/api/persona-memory`, apiKey, {
+            personaSlug: op.personaSlug,
+            kind: op.kind,
+            content: op.content,
+            forgetAfter: op.forgetAfter ?? null,
+        });
+        if (res.ok)
+            return true;
+        // 4xx → drop from queue (would loop forever otherwise).
+        if (res.statusCode >= 400 && res.statusCode < 500)
+            return true;
+        return false;
+    }
+    // op.op === 'forget'
+    const res = await safeDelete(`${stripTrailing(apiUrl)}/api/persona-memory/${encodeURIComponent(op.id)}`, apiKey);
+    if (res.ok)
+        return true;
+    // 404 → drop (already gone); other 4xx → drop too.
+    if (res.statusCode >= 400 && res.statusCode < 500)
+        return true;
+    return false;
+}
+function parseFlags(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] ?? '';
+        if (a === '--persona' && args[i + 1]) {
+            out.persona = args[i + 1];
+            i++;
+        }
+        else if (a === '--kind' && args[i + 1]) {
+            out.kind = args[i + 1];
+            i++;
+        }
+        else if (a === '--limit' && args[i + 1]) {
+            const n = Number.parseInt(args[i + 1] ?? '', 10);
+            if (Number.isFinite(n))
+                out.limit = n;
+            i++;
+        }
+        else if (a === '--top-k' && args[i + 1]) {
+            const n = Number.parseInt(args[i + 1] ?? '', 10);
+            if (Number.isFinite(n))
+                out.topK = n;
+            i++;
+        }
+        else if (a === '--forget-after' && args[i + 1]) {
+            out.forgetAfter = args[i + 1];
+            i++;
+        }
+    }
+    return out;
+}
+function splitPositionalFlags(args) {
+    const positional = [];
+    const consumed = new Set();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] ?? '';
+        if (a.startsWith('--')) {
+            consumed.add(i);
+            if (i + 1 < args.length && !(args[i + 1] ?? '').startsWith('--')) {
+                consumed.add(i + 1);
+            }
+        }
+        else if (!consumed.has(i)) {
+            positional.push(a);
+        }
+    }
+    const flagArgs = [];
+    for (let i = 0; i < args.length; i++) {
+        if (consumed.has(i))
+            flagArgs.push(args[i] ?? '');
+    }
+    return { positional, flags: parseFlags(flagArgs) };
+}
+function stripTrailing(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+function formatMemoryRow(item, now) {
+    const age = ageHuman(item.lastUsedAt, now);
+    const ttl = item.forgetAfter ? ttlHuman(item.forgetAfter, now) : 'none';
+    const content = item.content.replace(/[\r\n\t]+/g, ' ').slice(0, 60);
+    return `${item.kind.padEnd(12)} ${item.strength.toFixed(2).padEnd(8)} ${age.padEnd(8)} ${ttl.padEnd(11)} ${item.id.padEnd(36)} ${content}`;
+}
+function ageHuman(iso, now) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return '?';
+    const days = Math.floor((now.getTime() - t) / (1000 * 60 * 60 * 24));
+    if (days <= 0)
+        return '<1d';
+    if (days < 30)
+        return `${days}d`;
+    return `${Math.floor(days / 30)}mo`;
+}
+function ttlHuman(iso, now) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return '?';
+    const ms = t - now.getTime();
+    if (ms <= 0)
+        return 'expired';
+    const days = Math.floor(ms / (1000 * 60 * 60 * 24));
+    if (days >= 1)
+        return `${days}d`;
+    const hours = Math.floor(ms / (1000 * 60 * 60));
+    return `${hours}h`;
+}
+async function safeGet(url, apiKey) {
+    return safeRequest(url, apiKey, 'GET');
+}
+async function safeDelete(url, apiKey) {
+    return safeRequest(url, apiKey, 'DELETE');
+}
+async function safePost(url, apiKey, body) {
+    return safeRequest(url, apiKey, 'POST', body);
+}
+async function safeRequest(url, apiKey, method, body) {
+    try {
+        const headers = {
+            authorization: `Bearer ${apiKey}`,
+            accept: 'application/json',
+        };
+        let bodyText;
+        if (body !== undefined) {
+            bodyText = JSON.stringify(body);
+            headers['content-type'] = 'application/json';
+        }
+        const res = await request(url, { method, headers, body: bodyText });
+        const sc = res.statusCode;
+        if (sc < 200 || sc >= 300) {
+            const detail = await res.body.text().catch(() => '');
+            return {
+                ok: false,
+                status: sc,
+                statusCode: sc,
+                detail: detail.slice(0, 300),
+            };
+        }
+        const parsed = await res.body.json().catch(() => undefined);
+        return { ok: true, status: sc, statusCode: sc, body: parsed, detail: '' };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 0,
+            statusCode: 0,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function emitUnauth(sub, ctx) {
+    ctx.writeOutput({
+        command: 'memory',
+        sub,
+        status: 'unauthenticated',
+        hint: 'pugi login',
+    }, 'pugi memory: no active credential. Run `pugi login` first.');
+    return { command: 'memory', sub, status: 'unauthenticated' };
+}
+function emitFeatureDisabled(sub, ctx) {
+    ctx.writeOutput({
+        command: 'memory',
+        sub,
+        status: 'feature_disabled',
+        hint: 'set PERSONA_MEMORY_ENABLED=true on the admin-api host',
+    }, 'persona-memory feature is disabled on the admin-api host (HTTP 503).');
+    return { command: 'memory', sub, status: 'feature_disabled' };
+}
+/** Re-export for the `pugi doctor` queue-pending probe + the spec. */
+export { defaultQueuePath };
+//# sourceMappingURL=memory.js.map