shieldcortex 4.31.2 → 4.32.1

package/dist/cli/remember.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `shieldcortex remember "<title>" --content "<text>" [options]` (Phase 15c)
+ *
+ * A real, non-hanging CLI write command. The historical gotcha — "remember CLI
+ * hangs, avoid until fixed" — was that no such subcommand existed; any lookalike
+ * path blocked on a stdio/TTY transport. This command writes a memory directly
+ * through the SAME store path the MCP `remember` tool uses (executeRemember), so
+ * the defence pipeline + project scoping + dedupe all apply, then EXITS cleanly.
+ *
+ * Anti-hang contract: content comes from `--content`, else from PIPED stdin.
+ * If neither is present (an interactive TTY with no flag), we print usage and
+ * exit non-zero rather than blocking on a read that would never resolve.
+ *
+ * Layering:
+ *   - `runRemember` is the pure core: takes resolved options, returns a
+ *     structured result. No argv, no process.exit, no stdin — fully testable.
+ *   - `resolveRememberContent` isolates the stdin/TTY decision so the anti-hang
+ *     behaviour can be asserted without a real terminal.
+ *   - `handleRememberCommand` is the thin CLI wrapper: parse argv, resolve
+ *     content, run, print, drain cloud sync, close DB, exit.
+ */
+import { type RememberInput } from '../tools/remember.js';
+type Importance = 'low' | 'medium' | 'high';
+export interface RememberOptions {
+    title: string;
+    content: string;
+    category?: string;
+    importance?: Importance;
+    tags?: string[];
+    project?: string;
+    /** Flat source type — defaults to a `cli` source so interactive writes stay uncapped. */
+    sourceType?: RememberInput['sourceType'];
+    sourceIdentifier?: string;
+}
+export interface RememberResult {
+    success: boolean;
+    memory?: {
+        id: number;
+        title: string;
+        salience: number;
+        type: string;
+        category: string;
+    };
+    error?: string;
+}
+/**
+ * Pure write core. Delegates entirely to executeRemember so the defence
+ * pipeline, project auto-scoping, dedupe and salience handling are reused
+ * verbatim — there is no second implementation to drift.
+ */
+export declare function runRemember(opts: RememberOptions): Promise<RememberResult>;
+/**
+ * Resolve the memory content from the flag or piped stdin WITHOUT ever blocking
+ * on a TTY. `readStdin` is injected so this is unit-testable.
+ *
+ * Precedence: explicit --content > piped stdin > usage error.
+ */
+export declare function resolveRememberContent(args: {
+    contentFlag: string | undefined;
+    isTTY: boolean;
+    readStdin: () => Promise<string>;
+}): Promise<{
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    usage: boolean;
+}>;
+/**
+ * CLI entry point. Parses argv, resolves content (flag or piped stdin, never a
+ * TTY block), runs the write, prints a concise human or --json result, drains
+ * any in-flight cloud sync, closes the DB to release handles, and exits.
+ */
+export declare function handleRememberCommand(args: string[]): Promise<void>;
+export {};

package/dist/cli/remember.js

@@ -0,0 +1,195 @@
+/**
+ * `shieldcortex remember "<title>" --content "<text>" [options]` (Phase 15c)
+ *
+ * A real, non-hanging CLI write command. The historical gotcha — "remember CLI
+ * hangs, avoid until fixed" — was that no such subcommand existed; any lookalike
+ * path blocked on a stdio/TTY transport. This command writes a memory directly
+ * through the SAME store path the MCP `remember` tool uses (executeRemember), so
+ * the defence pipeline + project scoping + dedupe all apply, then EXITS cleanly.
+ *
+ * Anti-hang contract: content comes from `--content`, else from PIPED stdin.
+ * If neither is present (an interactive TTY with no flag), we print usage and
+ * exit non-zero rather than blocking on a read that would never resolve.
+ *
+ * Layering:
+ *   - `runRemember` is the pure core: takes resolved options, returns a
+ *     structured result. No argv, no process.exit, no stdin — fully testable.
+ *   - `resolveRememberContent` isolates the stdin/TTY decision so the anti-hang
+ *     behaviour can be asserted without a real terminal.
+ *   - `handleRememberCommand` is the thin CLI wrapper: parse argv, resolve
+ *     content, run, print, drain cloud sync, close DB, exit.
+ */
+import { executeRemember } from '../tools/remember.js';
+import { closeDatabase, initDatabase } from '../database/init.js';
+// CLI importance vocabulary → the MCP tool's importance scale. The CLI exposes
+// the friendlier low/medium/high; the tool maps low:0.3, normal:0.5, high:0.8.
+const IMPORTANCE_TO_TOOL = {
+    low: 'low',
+    medium: 'normal',
+    high: 'high',
+};
+/**
+ * Pure write core. Delegates entirely to executeRemember so the defence
+ * pipeline, project auto-scoping, dedupe and salience handling are reused
+ * verbatim — there is no second implementation to drift.
+ */
+export async function runRemember(opts) {
+    const input = {
+        title: opts.title,
+        content: opts.content,
+        category: opts.category,
+        importance: opts.importance ? IMPORTANCE_TO_TOOL[opts.importance] : undefined,
+        tags: opts.tags,
+        project: opts.project,
+        // Default to a `cli` source. addMemory only runs the trust/defence pipeline
+        // when a source is present, so passing one ensures malicious content is
+        // actually scanned (and a `cli` source stays uncapped, unlike `hook`).
+        sourceType: opts.sourceType ?? 'cli',
+        sourceIdentifier: opts.sourceIdentifier ?? 'shieldcortex-remember-cli',
+    };
+    const result = await executeRemember(input);
+    if (!result.success) {
+        return { success: false, error: result.error };
+    }
+    const m = result.memory;
+    return {
+        success: true,
+        memory: { id: m.id, title: m.title, salience: m.salience, type: m.type, category: m.category },
+    };
+}
+/**
+ * Resolve the memory content from the flag or piped stdin WITHOUT ever blocking
+ * on a TTY. `readStdin` is injected so this is unit-testable.
+ *
+ * Precedence: explicit --content > piped stdin > usage error.
+ */
+export async function resolveRememberContent(args) {
+    if (args.contentFlag !== undefined) {
+        return { ok: true, content: args.contentFlag };
+    }
+    // No --content. Only read stdin if it is actually piped — never on a TTY,
+    // which would hang waiting for input that never comes. THIS is the anti-hang.
+    if (!args.isTTY) {
+        const piped = await args.readStdin();
+        return { ok: true, content: piped };
+    }
+    return { ok: false, usage: true };
+}
+/** Read all of process.stdin to EOF. Only called when stdin is piped. */
+function readPipedStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+function parseFlag(args, name) {
+    const idx = args.indexOf(name);
+    if (idx === -1 || idx === args.length - 1)
+        return undefined;
+    return args[idx + 1];
+}
+function printUsage() {
+    console.error('Usage: shieldcortex remember "<title>" --content "<text>" [options]');
+    console.error('       echo "<text>" | shieldcortex remember "<title>"');
+    console.error('');
+    console.error('Options:');
+    console.error('  --content <text>          Memory content (or pipe it via stdin)');
+    console.error('  --category <category>     architecture|pattern|preference|error|context|');
+    console.error('                            learning|todo|note|relationship|custom');
+    console.error('  --importance <level>      low | medium | high');
+    console.error('  --tags <a,b,c>            Comma-separated tags');
+    console.error('  --project <name>          Project scope (auto-detected if omitted)');
+    console.error('  --json                    Emit a structured JSON result');
+}
+/**
+ * CLI entry point. Parses argv, resolves content (flag or piped stdin, never a
+ * TTY block), runs the write, prints a concise human or --json result, drains
+ * any in-flight cloud sync, closes the DB to release handles, and exits.
+ */
+export async function handleRememberCommand(args) {
+    const json = args.includes('--json');
+    // First positional (not a flag, not a flag value) is the title.
+    let title;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            // Skip the value of value-taking flags so it can't be misread as the title.
+            if (['--content', '--category', '--importance', '--tags', '--project'].includes(a))
+                i++;
+            continue;
+        }
+        title = a;
+        break;
+    }
+    if (!title) {
+        printUsage();
+        process.exit(2);
+    }
+    const importanceRaw = parseFlag(args, '--importance');
+    let importance;
+    if (importanceRaw !== undefined) {
+        if (importanceRaw === 'low' || importanceRaw === 'medium' || importanceRaw === 'high') {
+            importance = importanceRaw;
+        }
+        else {
+            console.error(`Invalid --importance "${importanceRaw}". Use: low | medium | high.`);
+            process.exit(2);
+        }
+    }
+    const resolved = await resolveRememberContent({
+        contentFlag: parseFlag(args, '--content'),
+        isTTY: Boolean(process.stdin.isTTY),
+        readStdin: readPipedStdin,
+    });
+    if (!resolved.ok) {
+        console.error('No content provided. Pass --content "<text>" or pipe text via stdin.');
+        console.error('');
+        printUsage();
+        process.exit(2);
+    }
+    const tagsRaw = parseFlag(args, '--tags');
+    const tags = tagsRaw
+        ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean)
+        : undefined;
+    // Initialise the DB explicitly — executeRemember assumes an initialised store.
+    initDatabase();
+    let exitCode = 0;
+    try {
+        const result = await runRemember({
+            title,
+            content: resolved.content,
+            category: parseFlag(args, '--category'),
+            importance,
+            tags,
+            project: parseFlag(args, '--project'),
+        });
+        if (json) {
+            console.log(JSON.stringify(result));
+        }
+        else if (result.success && result.memory) {
+            const m = result.memory;
+            console.log(`Remembered "${m.title}" (id ${m.id}, ${m.category}, salience ${(m.salience * 100).toFixed(0)}%).`);
+        }
+        else {
+            console.error(`Not remembered: ${result.error ?? 'unknown error'}`);
+        }
+        exitCode = result.success ? 0 : 1;
+    }
+    finally {
+        // Clean exit — release any open handles so the process does not linger.
+        try {
+            const { flushPendingCloudSync } = await import('../cloud/sync.js');
+            await flushPendingCloudSync(8000);
+        }
+        catch {
+            // Cloud sync drain is best-effort; never block exit on it.
+        }
+        closeDatabase();
+    }
+    process.exit(exitCode);
+}

package/dist/cli/repair.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `shieldcortex repair` — fix a broken install in place.
+ *
+ * Today it heals the better-sqlite3 native binding (the #1 post-update breakage
+ * on arm64 / newer-than-prebuilt Node): verify → rebuild in the install dir →
+ * re-verify, then print the exact remediation if it still can't load.
+ */
+export declare function runRepair(): Promise<void>;

package/dist/cli/repair.js

@@ -0,0 +1,34 @@
+/**
+ * `shieldcortex repair` — fix a broken install in place.
+ *
+ * Today it heals the better-sqlite3 native binding (the #1 post-update breakage
+ * on arm64 / newer-than-prebuilt Node): verify → rebuild in the install dir →
+ * re-verify, then print the exact remediation if it still can't load.
+ */
+import { ensureNativeBinding } from '../setup/native-binding.js';
+const isTTY = Boolean(process.stdout.isTTY);
+const c = (code, s) => (isTTY ? `\x1b[${code}m${s}\x1b[0m` : s);
+export async function runRepair() {
+    process.stdout.write(`\n  ${c('35', '◆')} ${c('1', 'ShieldCortex repair')}\n\n`);
+    process.stdout.write(`  ${c('90', 'Checking the native database engine (better-sqlite3)…')}\n`);
+    const r = await ensureNativeBinding();
+    if (r.status === 'ok') {
+        process.stdout.write(`  ${c('32', '✓')}  Database engine: healthy (no rebuild needed)\n\n`);
+        return;
+    }
+    if (r.status === 'healed') {
+        process.stdout.write(`  ${c('32', '✓')}  Database engine: rebuilt and verified\n`);
+        process.stdout.write(`  ${c('90', 'Restart Claude Code / the OpenClaw gateway so running processes reload it.')}\n\n`);
+        return;
+    }
+    // failed
+    process.stdout.write(`  ${c('31', '✗')}  Database engine: still cannot load after a rebuild\n`);
+    if (r.error)
+        process.stdout.write(`     ${c('90', r.error.split('\n')[0])}\n`);
+    process.stdout.write(`\n  ${c('1', 'Fix it manually:')}\n`);
+    for (const line of (r.remediation ?? '').split('\n')) {
+        process.stdout.write(`     ${c('33', line)}\n`);
+    }
+    process.stdout.write('\n');
+    process.exitCode = 1;
+}

package/dist/cli/update.js

@@ -210,6 +210,29 @@ async function stepNpmPackage(currentVersion, latestVersion, force) {
     });
     return { updated: true, result };
 }
+/**
+ * Verify the better-sqlite3 native binding loads and self-heal it if not.
+ *
+ * `npm install -g` reports success on its exit code even when the native
+ * binding never built for this platform/ABI (common on arm64 / a Node newer
+ * than the prebuilds) — leaving the package installed-but-broken. This step
+ * runs AFTER the install completes (not nested inside it), rebuilds the binding
+ * in the correct install dir if it's missing, and reports honestly.
+ */
+async function stepVerifyEngine() {
+    let remediation = null;
+    await step('Database engine', async () => {
+        const { ensureNativeBinding } = await import('../setup/native-binding.js');
+        const r = await ensureNativeBinding();
+        if (r.status === 'ok')
+            return 'native binding OK';
+        if (r.status === 'healed')
+            return 'rebuilt native binding';
+        remediation = r.remediation ?? null;
+        return { status: 'warn', summary: 'binding failed — run `shieldcortex repair`' };
+    });
+    return { remediation };
+}
 /**
  * Is the realtime plugin registered with OpenClaw's plugin registry?
  *
@@ -395,10 +418,21 @@ export async function runUpdate() {
     catch {
         // npm failure already surfaced by step(); continue with reconcile.
     }
+    // Verify (and self-heal) the native DB binding after the install completes.
+    // Runs unconditionally: a pre-existing broken binding heals on any update.
+    const engineResult = await stepVerifyEngine();
     await stepOpenClawPlugin(home);
     await stepOpenClawSkill(home);
     await stepClaudeHooks();
     footer(Date.now() - flowStart, mainUpdated);
+    // If the binding couldn't be auto-healed, print the exact copy-paste fix.
+    if (engineResult.remediation) {
+        process.stdout.write(`\n  ${paint('yellow', '⚠')}  ${paint('bold', 'Database engine could not be rebuilt automatically.')}\n`);
+        for (const line of engineResult.remediation.split('\n')) {
+            process.stdout.write(`     ${paint('gray', line)}\n`);
+        }
+        process.stdout.write('\n');
+    }
     maybePrint411Notice(currentVersion, mainUpdated);
     await maybePrintDashboardHint();
 }

package/dist/cloud/config.d.ts

@@ -41,9 +41,31 @@ export declare function setCloudIronDomeCache(data: Record<string, unknown>): vo
  */
 export declare function getCloudIronDomeCache(): Record<string, unknown> | null;
 /**
- * Write lastSyncAt timestamp to config.json on successful cloud sync.
+ * Record a successful cloud sync. Always updates the in-memory timestamp;
+ * persists to config.json at most once per 60s (time-debounced). Callers
+ * (sync.ts / sync-queue.ts / memory-sync.ts) are unchanged — the debounce is
+ * internal.
  */
 export declare function updateLastSyncAt(): void;
+/**
+ * Force-persist the latest in-memory lastSyncAt regardless of the debounce
+ * window, so the final sync timestamp isn't lost if the process exits inside
+ * the debounce window. Safe no-op if nothing is pending.
+ *
+ * Available for a shutdown path (not currently wired): the existing
+ * SIGINT/SIGTERM/exit handlers (src/index.ts, src/api/visualization-server.ts)
+ * are MCP-server / dashboard lifecycle concerns and don't obviously own the
+ * cloud-sync clock, so wiring is left to whichever shutdown owner adopts it
+ * rather than bolted onto an unrelated handler. Losing at most one debounced
+ * timestamp on abrupt exit is non-critical (the next sync re-stamps it).
+ */
+export declare function flushLastSyncAt(): void;
+/**
+ * Returns the most recent sync timestamp, preferring the in-memory value (which
+ * may be ahead of disk inside the debounce window) and falling back to the
+ * persisted config value.
+ */
+export declare function getLastSyncAt(): string | null;
 export type DefenceMode = 'strict' | 'balanced' | 'permissive';
 /**
  * Returns the persisted defence mode, defaulting to 'balanced'.