@engramx/client 0.1.0

package/dist/cli.js

@@ -0,0 +1,1078 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import * as readline from 'readline';
+import * as fs from 'fs';
+import { pair, PairError } from './pair';
+import { execFileSync } from 'node:child_process';
+import * as path from 'path';
+import { setupOpenClaw, setupGitVersioning, OpenClawNotFoundError, getOpenClawDir, getMemoryDir, isGitRepo, } from './openclaw-setup';
+import { generateMcpConfig, claudeConfigPaths, installMcpConfig } from './claude-setup';
+import { migrateOpenClawMemory, recoverOpenClaw, rollbackCheckpoint, listCheckpoints, hasValidPairing, findIncompleteCheckpoint, resumeMigration, } from './migrate';
+import { EngramClient } from './EngramClient';
+import { Principal } from '@icp-sdk/core/principal';
+// Simple colored output helpers
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+function ok(msg) {
+    console.log(`${green('\u2713')} ${msg}`);
+}
+function fail(msg) {
+    console.error(`${red('\u2717')} ${msg}`);
+}
+function warn(msg) {
+    console.log(`${yellow('\u26A0')} ${msg}`);
+}
+function info(msg) {
+    console.log(`  ${dim(msg)}`);
+}
+function step(msg) {
+    console.log(`\n${bold('\u25B6')} ${msg}`);
+}
+let autoConfirm = false;
+/** Detect which agent frameworks are installed on this machine. */
+function detectTargets() {
+    const detected = [];
+    const openclawDir = process.env['OPENCLAW_CONFIG_DIR'] || path.join(process.env['HOME'] || '', '.openclaw');
+    if (fs.existsSync(openclawDir)) {
+        detected.push('openclaw');
+    }
+    const claudeDir = path.join(process.env['HOME'] || '', '.claude');
+    if (fs.existsSync(claudeDir)) {
+        detected.push('claude');
+    }
+    return detected;
+}
+/** Prompt user to choose a target when multiple are detected. */
+async function promptTarget(detected) {
+    if (detected.length === 0) {
+        // Nothing detected — ask
+        console.log(`\n${bold('No agent framework detected.')}`);
+        info('Which framework are you pairing with?');
+    }
+    else {
+        console.log(`\n${bold('Multiple agent frameworks detected:')}`);
+    }
+    for (let i = 0; i < detected.length; i++) {
+        console.log(`  ${bold(`[${i + 1}]`)} ${detected[i]}`);
+    }
+    if (detected.length === 0) {
+        console.log(`  ${bold('[1]')} openclaw`);
+        console.log(`  ${bold('[2]')} claude`);
+    }
+    const choices = detected.length > 0 ? detected : ['openclaw', 'claude'];
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`\n  Select ${dim(`[1]`)}: `, (answer) => {
+            rl.close();
+            const trimmed = answer.trim();
+            if (trimmed === '') {
+                resolve(choices[0]);
+                return;
+            }
+            const num = parseInt(trimmed, 10);
+            if (isNaN(num) || num < 1 || num > choices.length) {
+                fail(`Invalid selection: ${trimmed}`);
+                process.exit(1);
+            }
+            resolve(choices[num - 1]);
+        });
+    });
+}
+/** Resolve the target: from --target flag, auto-detection, or prompt. */
+async function resolveTarget(explicitTarget) {
+    if (explicitTarget) {
+        if (explicitTarget !== 'openclaw' && explicitTarget !== 'claude') {
+            fail(`Invalid --target: ${explicitTarget}. Must be 'openclaw' or 'claude'.`);
+            process.exit(1);
+        }
+        return explicitTarget;
+    }
+    const detected = detectTargets();
+    if (detected.length === 1) {
+        const t = detected[0];
+        if (autoConfirm) {
+            info(`Auto-detected: ${t}`);
+            return t;
+        }
+        const confirmed = await confirm(`  Detected ${bold(t)}. Use it?`);
+        if (confirmed)
+            return t;
+        // User said no — prompt for choice
+        return promptTarget([]);
+    }
+    if (detected.length > 1) {
+        if (autoConfirm) {
+            fail('Multiple agent frameworks detected. Use --target to specify one.');
+            process.exit(1);
+        }
+        return promptTarget(detected);
+    }
+    // Nothing detected
+    if (autoConfirm) {
+        fail('No agent framework detected. Use --target to specify one.');
+        process.exit(1);
+    }
+    return promptTarget([]);
+}
+async function confirm(message) {
+    if (autoConfirm) {
+        console.log(`${message} ${dim('[y/N]')} y ${dim('(--yes)')}`);
+        return true;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${message} ${dim('[y/N]')} `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
+async function promptGitRemote() {
+    if (autoConfirm) {
+        console.log(`\nEnable git versioning for memory? ${dim('[y/N]')} n ${dim('(--yes: skipped, use --git-remote to set)')}`);
+        return null;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`\nEnable git versioning for memory? ${dim('[y/N]')} `, (answer) => {
+            rl.close();
+            if (answer.trim().toLowerCase() !== 'y') {
+                resolve(null);
+                return;
+            }
+            const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+            rl2.question(`Git remote URL (e.g. git@github.com:user/memory.git): `, (url) => {
+                rl2.close();
+                const trimmed = url.trim();
+                resolve(trimmed || null);
+            });
+        });
+    });
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+function formatTimestamp(iso) {
+    const d = new Date(iso);
+    return d.toLocaleString();
+}
+function promptCheckpointSelection(checkpoints) {
+    return new Promise((resolve) => {
+        console.log(`\n${bold('Available checkpoints:')}`);
+        for (let i = 0; i < checkpoints.length; i++) {
+            const c = checkpoints[i];
+            const label = i === 0 ? ' (latest)' : '';
+            console.log(`  ${bold(`[${i + 1}]`)} ${formatTimestamp(c.timestamp)} \u2014 ${c.mode}${label}`);
+        }
+        console.log();
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(`Select checkpoint to roll back ${dim(`[1]`)}: `, (answer) => {
+            rl.close();
+            const trimmed = answer.trim();
+            if (trimmed === '') {
+                resolve(checkpoints[0].id);
+                return;
+            }
+            const num = parseInt(trimmed, 10);
+            if (isNaN(num) || num < 1 || num > checkpoints.length) {
+                fail(`Invalid selection: ${trimmed}`);
+                process.exit(1);
+            }
+            resolve(checkpoints[num - 1].id);
+        });
+    });
+}
+// ── Migration progress display helpers ──────────────────────────
+let fileCounter = 0;
+let totalFileCount = 0;
+function displayFileEvent(event) {
+    if (event.type === 'scan') {
+        totalFileCount = event.totalFiles ?? 0;
+        fileCounter = 0;
+        return;
+    }
+    if (event.type === 'retry') {
+        console.log(`    ${yellow('\u21BB')} Retry ${event.attempt}/${event.maxAttempts}...`);
+        return;
+    }
+    fileCounter++;
+    console.log(`  [${fileCounter}/${totalFileCount}] ${event.relativePath}`);
+    if (event.type === 'migrated') {
+        ok('    Uploaded \u2192 checkpointed \u2192 removed from disk');
+    }
+    else if (event.type === 'skipped') {
+        const reason = event.reason ?? 'empty';
+        info(`    Skipped (${reason})`);
+    }
+    else if (event.type === 'error') {
+        fail(`    Upload failed: ${event.error}`);
+    }
+}
+function displayMigrateSummary(result) {
+    const totalFiles = result.migrated + result.skipped + result.errors.length;
+    if (result.errors.length > 0) {
+        fail(`Migrated ${result.migrated} of ${totalFiles} file${totalFiles === 1 ? '' : 's'} (${result.errors.length} failed)`);
+    }
+    else if (result.migrated > 0) {
+        ok(`Migrated ${result.migrated} file${result.migrated === 1 ? '' : 's'} to engram`);
+    }
+    else {
+        info('No local memory files found to migrate');
+    }
+    if (result.skipped > 0) {
+        info(`Skipped ${result.skipped} file${result.skipped === 1 ? '' : 's'}`);
+    }
+    if (result.checkpointDir) {
+        info(`Checkpoint: ${result.checkpointDir}`);
+    }
+}
+async function runResumeMigration(clientOptions) {
+    step('Resuming incomplete migration...');
+    try {
+        const result = await resumeMigration(clientOptions, displayFileEvent);
+        console.log();
+        displayMigrateSummary(result);
+    }
+    catch (err) {
+        fail(`Resume failed: ${err.message}`);
+        process.exit(1);
+    }
+    console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+}
+// ── Help text ───────────────────────────────────────────────────
+function printUsage() {
+    console.log(`
+${bold('Usage:')}
+  npx @engramx/client pair <code> --engram <id> [options]
+  npx @engramx/client migrate --engram <id> [options]
+  npx @engramx/client rollback [checkpoint-id]
+  npx @engramx/client git-setup <remote-url>
+  npx @engramx/client git-log [file]
+  npx @engramx/client git-diff [ref] [--file <path>]
+  npx @engramx/client git-revert <ref> --engram <id> [--file <path>]
+  npx @engramx/client config <push|pull> --engram <id>
+  npx @engramx/client read <path> --engram <id> [--raw]
+
+${bold('Commands:')}
+  pair        Generate session key and register as operator
+  migrate     Migrate local memory to engram (or recover with --recover)
+  rollback    Restore files from a checkpoint
+  git-setup   Initialize git versioning for the memory directory
+  git-log     Show commit history for the memory repo
+  git-diff    Show changes since a commit (or working tree diff)
+  git-revert  Revert memory to a previous commit and sync to canister
+  config      Push/pull OpenClaw config to/from engram
+  read        Read a memory file (use --raw to see raw stored bytes)
+
+${bold('Options (pair):')}
+  --engram <id>          Engram canister ID (required)
+  --target <openclaw|claude>  Agent framework (auto-detected if omitted)
+  --install              Write Claude MCP config to settings file
+  --host <url>           ICP host (default: https://ic0.app)
+  --key-path <path>      Session key path (default: ~/.engramx/session.key)
+  --git-remote <url>     Enable git versioning and set remote
+  --force                Overwrite existing session key
+  --yes, -y              Auto-confirm all prompts (non-interactive mode)
+
+${bold('Options (migrate):')}
+  --engram <id>      Engram canister ID (required)
+  --recover          Recovery mode: download memory from engram to local
+  --resume           Resume an incomplete migration
+  --dry-run          Show what would be migrated without uploading
+  --host <url>       ICP host (default: https://ic0.app)
+  --key-path <path>  Session key path (default: ~/.engramx/session.key)
+
+${bold('Options (git-revert):')}
+  --engram <id>      Engram canister ID (required)
+  --file <path>      Revert a single file instead of the entire memory dir
+  --host <url>       ICP host (default: https://ic0.app)
+  --key-path <path>  Session key path (default: ~/.engramx/session.key)
+
+${bold('Options (read):')}
+  --raw              Show raw stored bytes as hex instead of decoded text
+
+  --help             Show this help message
+`);
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            engram: { type: 'string' },
+            target: { type: 'string' },
+            install: { type: 'boolean', default: false },
+            recover: { type: 'boolean', default: false },
+            resume: { type: 'boolean', default: false },
+            'dry-run': { type: 'boolean', default: false },
+            host: { type: 'string' },
+            'key-path': { type: 'string' },
+            'git-remote': { type: 'string' },
+            force: { type: 'boolean', default: false },
+            yes: { type: 'boolean', short: 'y', default: false },
+            file: { type: 'string' },
+            raw: { type: 'boolean', default: false },
+            help: { type: 'boolean', default: false },
+        },
+    });
+    if (values.help || positionals.length === 0) {
+        printUsage();
+        process.exit(values.help ? 0 : 1);
+    }
+    const command = positionals[0];
+    autoConfirm = values.yes;
+    if (values.engram) {
+        try {
+            Principal.fromText(values.engram);
+        }
+        catch {
+            fail(`Invalid canister ID: ${values.engram}`);
+            process.exit(1);
+        }
+    }
+    // ── config command ──────────────────────────────────────────
+    if (command === 'config') {
+        const subcommand = positionals[1];
+        if (!subcommand || (subcommand !== 'push' && subcommand !== 'pull')) {
+            fail('Usage: npx @engramx/client config <push|pull> --engram <id>');
+            process.exit(1);
+        }
+        if (!values.engram) {
+            fail('Missing --engram <canister-id>');
+            process.exit(1);
+        }
+        const keyPath = values['key-path'] || '~/.engramx/session.key';
+        const host = values.host || 'https://ic0.app';
+        const client = new EngramClient({ canisterId: values.engram, sessionKeyPath: keyPath, host });
+        if (subcommand === 'push') {
+            const configPath = positionals[2] || '~/.openclaw/openclaw.json';
+            const resolvedPath = configPath.replace(/^~/, process.env['HOME'] || '');
+            if (!fs.existsSync(resolvedPath)) {
+                fail(`Config file not found: ${resolvedPath}`);
+                process.exit(1);
+            }
+            const content = fs.readFileSync(resolvedPath, 'utf-8');
+            step(`Pushing config to engram...`);
+            try {
+                // Owner-only: writeMemory + config/* path require owner credentials.
+                // Use raw actor since the SDK doesn't expose writeMemory.
+                const ciphertext = new TextEncoder().encode(content);
+                const result = await client.actor.writeMemory('config/openclaw.json', ciphertext);
+                if ('Err' in result)
+                    throw new Error(result.Err);
+                ok(`Config pushed (version ${result.Ok})`);
+            }
+            catch (err) {
+                fail(`Push failed: ${err.message}`);
+                process.exit(1);
+            }
+        }
+        else {
+            step('Pulling config from engram...');
+            try {
+                const file = await client.readMemory('config/openclaw.json');
+                console.log(file.content);
+            }
+            catch (err) {
+                fail(`Pull failed: ${err.message}`);
+                process.exit(1);
+            }
+        }
+        return;
+    }
+    // ── read command (debug) ─────────────────────────────────────
+    if (command === 'read') {
+        const filePath = positionals[1];
+        if (!filePath) {
+            fail('Usage: npx @engramx/client read <path> --engram <id> [--raw]');
+            process.exit(1);
+        }
+        if (!values.engram) {
+            fail('Missing --engram <canister-id>');
+            process.exit(1);
+        }
+        const keyPath = values['key-path'] || '~/.engramx/session.key';
+        const host = values.host || 'https://ic0.app';
+        const client = new EngramClient({ canisterId: values.engram, sessionKeyPath: keyPath, host });
+        try {
+            if (values.raw) {
+                console.warn('WARNING: --raw shows the raw stored bytes (content is stored as plaintext).');
+                // Show raw stored bytes as hex (no decode)
+                const result = await client.actor.readMemory(filePath);
+                if ('Err' in result) {
+                    fail(result.Err);
+                    process.exit(1);
+                }
+                const raw = result.Ok;
+                const bytes = new Uint8Array(raw.content);
+                console.log(`Path: ${raw.path}`);
+                console.log(`Version: ${raw.version}`);
+                console.log(`Size: ${bytes.length} bytes (raw stored, plaintext)`);
+                console.log(`Hex: ${Buffer.from(bytes).toString('hex').slice(0, 200)}...`);
+            }
+            else {
+                const file = await client.readMemory(filePath);
+                console.log(file.content);
+            }
+        }
+        catch (err) {
+            fail(`Read failed: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // ── rollback command ──────────────────────────────────────────
+    if (command === 'rollback') {
+        const checkpoints = listCheckpoints();
+        if (checkpoints.length === 0) {
+            fail('No checkpoints to roll back. Run "npx @engramx/client pair" first to create a checkpoint.');
+            process.exit(1);
+        }
+        let targetId;
+        const explicitId = positionals[1];
+        if (explicitId) {
+            // Direct checkpoint ID passed as argument
+            if (!checkpoints.find((c) => c.id === explicitId)) {
+                fail(`Checkpoint not found: ${explicitId}`);
+                process.exit(1);
+            }
+            targetId = explicitId;
+        }
+        else if (checkpoints.length === 1) {
+            targetId = checkpoints[0].id;
+        }
+        else {
+            // Interactive selector
+            targetId = await promptCheckpointSelection(checkpoints);
+        }
+        try {
+            const result = rollbackCheckpoint(targetId);
+            // Show per-file restore results
+            for (const file of result.restoredFiles) {
+                const basename = file.path.split('/').pop() || file.path;
+                if (file.status === 'restored') {
+                    ok(`Restored ${basename} ${dim(`\u2192 ${file.path}`)}`);
+                }
+                else if (file.status === 'skipped') {
+                    info(`Skipped ${basename} (not found in checkpoint)`);
+                }
+                else {
+                    fail(`Failed to restore ${basename}: ${file.error}`);
+                }
+            }
+            const restoredCount = result.restoredFiles.filter((f) => f.status === 'restored').length;
+            if (result.partial) {
+                const failedCount = result.restoredFiles.filter((f) => f.status !== 'restored').length;
+                fail(`Partial rollback: ${failedCount} file${failedCount === 1 ? '' : 's'} could not be restored (see errors above)`);
+                info('Checkpoint preserved for retry.');
+            }
+            else {
+                const dbList = result.restoredDatabases.length > 0
+                    ? ` + databases: ${result.restoredDatabases.join(', ')}`
+                    : '';
+                ok(`Rolled back ${restoredCount} file${restoredCount === 1 ? '' : 's'}${dbList}`);
+                info(`(from checkpoint ${formatTimestamp(result.checkpointTimestamp)})`);
+            }
+            const remaining = listCheckpoints();
+            if (remaining.length > 0) {
+                console.log(dim(`${remaining.length} older checkpoint${remaining.length === 1 ? '' : 's'} still available.`));
+            }
+        }
+        catch (err) {
+            fail(err.message);
+            process.exit(1);
+        }
+        return;
+    }
+    // ── git-log command ──────────────────────────────────────────
+    if (command === 'git-log') {
+        const memoryDir = getMemoryDir();
+        if (!isGitRepo(memoryDir)) {
+            fail('Git versioning not set up. Run: npx @engramx/client git-setup <url>');
+            process.exit(1);
+        }
+        const filePath = positionals[1] || values.file;
+        const args = ['log', '--oneline', '--no-decorate', '-30'];
+        if (filePath)
+            args.push('--', filePath);
+        try {
+            const output = execFileSync('git', args, { cwd: memoryDir, stdio: 'pipe' }).toString().trim();
+            if (output) {
+                console.log(output);
+            }
+            else {
+                info('No commits yet.');
+            }
+        }
+        catch {
+            info('No commits yet.');
+        }
+        return;
+    }
+    // ── git-diff command ────────────────────────────────────────
+    if (command === 'git-diff') {
+        const memoryDir = getMemoryDir();
+        if (!isGitRepo(memoryDir)) {
+            fail('Git versioning not set up. Run: npx @engramx/client git-setup <url>');
+            process.exit(1);
+        }
+        const ref = positionals[1];
+        const filePath = values.file;
+        const args = ['diff'];
+        if (ref)
+            args.push(ref);
+        if (filePath)
+            args.push('--', filePath);
+        try {
+            const output = execFileSync('git', args, { cwd: memoryDir, stdio: 'pipe' }).toString().trim();
+            if (output) {
+                console.log(output);
+            }
+            else {
+                info('No changes.');
+            }
+        }
+        catch (err) {
+            fail(`git diff failed: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // ── git-revert command ──────────────────────────────────────
+    if (command === 'git-revert') {
+        const ref = positionals[1];
+        if (!ref) {
+            fail('Usage: npx @engramx/client git-revert <commit-or-ref> --engram <id> [--file <path>]');
+            process.exit(1);
+        }
+        if (!values.engram) {
+            fail('Missing --engram <canister-id> (needed to sync reverted files to canister)');
+            process.exit(1);
+        }
+        const memoryDir = getMemoryDir();
+        if (!isGitRepo(memoryDir)) {
+            fail('Git versioning not set up. Run: npx @engramx/client git-setup <url>');
+            process.exit(1);
+        }
+        const filePath = values.file;
+        const keyPath = values['key-path'] || '~/.engramx/session.key';
+        const host = values.host || 'https://ic0.app';
+        // 1. Git checkout to revert files
+        step(`Reverting to ${ref}${filePath ? ` (file: ${filePath})` : ''}...`);
+        try {
+            const checkoutArgs = ['checkout', ref, '--'];
+            if (filePath) {
+                checkoutArgs.push(filePath);
+            }
+            else {
+                checkoutArgs.push('.');
+            }
+            execFileSync('git', checkoutArgs, { cwd: memoryDir, stdio: 'pipe' });
+        }
+        catch (err) {
+            fail(`git checkout failed: ${err.message}`);
+            process.exit(1);
+        }
+        // 2. Commit the revert
+        try {
+            execFileSync('git', ['add', '-A'], { cwd: memoryDir, stdio: 'pipe' });
+            const status = execFileSync('git', ['diff', '--cached', '--stat'], {
+                cwd: memoryDir,
+                stdio: 'pipe',
+            })
+                .toString()
+                .trim();
+            if (status) {
+                const msg = filePath
+                    ? `engramx: revert ${filePath} to ${ref}`
+                    : `engramx: revert to ${ref}`;
+                execFileSync('git', ['commit', '-m', msg], { cwd: memoryDir, stdio: 'pipe' });
+                ok('Committed revert to git');
+            }
+            else {
+                info('No changes to commit (already at target state)');
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes('nothing to commit')) {
+                warn(`Git commit failed: ${msg}`);
+            }
+        }
+        // 3. Sync reverted files to canister
+        step('Syncing reverted files to engram canister...');
+        const client = new EngramClient({ canisterId: values.engram, sessionKeyPath: keyPath, host });
+        let syncCount = 0;
+        let syncErrors = 0;
+        async function syncDir(dir) {
+            if (!fs.existsSync(dir))
+                return;
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = `${dir}/${entry.name}`;
+                if (entry.isDirectory()) {
+                    if (entry.name === '.git')
+                        continue;
+                    await syncDir(fullPath);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    const relativePath = path.relative(memoryDir, fullPath);
+                    if (relativePath.startsWith('..'))
+                        continue; // skip files outside memoryDir
+                    const content = fs.readFileSync(fullPath, 'utf-8');
+                    try {
+                        // Operators can append (creates files on first sync, accumulates
+                        // content on subsequent runs — preserves the append-only invariant).
+                        await client.appendMemory(relativePath, content);
+                        ok(`  ${relativePath}`);
+                        syncCount++;
+                    }
+                    catch (err) {
+                        fail(`  ${relativePath}: ${err.message}`);
+                        syncErrors++;
+                    }
+                }
+            }
+        }
+        await syncDir(memoryDir);
+        if (syncErrors > 0) {
+            fail(`Synced ${syncCount} file(s), ${syncErrors} failed`);
+        }
+        else if (syncCount > 0) {
+            ok(`Synced ${syncCount} file${syncCount === 1 ? '' : 's'} to engram`);
+        }
+        else {
+            info('No .md files to sync');
+        }
+        // 4. Push to remote if configured
+        try {
+            execFileSync('git', ['push'], { cwd: memoryDir, stdio: 'pipe' });
+            ok('Pushed to remote');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warn(`Git push skipped: ${msg.split('\n')[0]}`);
+        }
+        return;
+    }
+    // ── git-setup command ────────────────────────────────────────
+    if (command === 'git-setup') {
+        const remoteUrl = positionals[1];
+        if (!remoteUrl) {
+            fail('Missing remote URL. Usage: npx @engramx/client git-setup <remote-url>');
+            process.exit(1);
+        }
+        step('Setting up git versioning...');
+        try {
+            const gitResult = setupGitVersioning(remoteUrl);
+            ok(`Git repo initialized ${dim(`→ ${gitResult.memoryDir}`)}`);
+            ok(`Remote "origin" set to ${dim(remoteUrl)}`);
+            if (gitResult.existingRepo) {
+                info('Using existing git repo');
+            }
+        }
+        catch (err) {
+            fail(`Git setup failed: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // ── migrate command ─────────────────────────────────────────
+    if (command === 'migrate') {
+        if (!values.engram) {
+            fail('Missing --engram <canister-id>');
+            process.exit(1);
+        }
+        const keyPath = values['key-path'] || '~/.engramx/session.key';
+        const host = values.host || 'https://ic0.app';
+        // Pre-flight: require valid pairing
+        const clientOptions = {
+            canisterId: values.engram,
+            sessionKeyPath: keyPath,
+            host,
+            dryRun: values['dry-run'],
+        };
+        if (!values['dry-run']) {
+            const paired = await hasValidPairing(clientOptions);
+            if (!paired) {
+                fail("No valid pairing found. Run 'npx @engramx/client pair' first.");
+                process.exit(1);
+            }
+        }
+        // Flag validation
+        if (values.resume && values['dry-run']) {
+            fail('Cannot combine --resume with --dry-run');
+            process.exit(1);
+        }
+        if (values.recover) {
+            // ── Recovery mode ───────────────────────────────────────
+            step('Recovering from engram...');
+            info('This will checkpoint local state and download memory from engram.');
+            if (!(await confirm('  Continue?'))) {
+                info('Recovery cancelled.');
+                process.exit(0);
+            }
+            info('Checkpointing local state before recovery...');
+            try {
+                const result = await recoverOpenClaw(clientOptions);
+                ok(`Checkpointed local state ${dim(`\u2192 ${result.checkpointDir}`)}`);
+                if (result.restoredBackups.length === 0) {
+                    info('No database backups found on engram');
+                }
+                for (const backup of result.restoredBackups) {
+                    ok(`Restored database: ${backup.dbType} ${dim(`(${backup.backupId}, ${formatBytes(backup.size)})`)}`);
+                }
+                for (const error of result.errors) {
+                    fail(`Recovery: ${error}`);
+                }
+            }
+            catch (err) {
+                fail(`Recovery failed: ${err.message}`);
+                process.exit(1);
+            }
+            console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+            console.log(`Restart OpenClaw \u2014 memory files will sync automatically.`);
+            return;
+        }
+        if (values.resume) {
+            // ── Resume mode ─────────────────────────────────────────
+            await runResumeMigration(clientOptions);
+            return;
+        }
+        // ── Default: check for incomplete checkpoint ────────────
+        const incomplete = findIncompleteCheckpoint();
+        if (incomplete && !values['dry-run']) {
+            info(`Found incomplete migration: ${incomplete.migratedCount} migrated, ${incomplete.remainingCount} remaining.`);
+            info(`Checkpoint: ${incomplete.checkpoint.id}`);
+            const shouldResume = await confirm('  Resume incomplete migration?');
+            if (shouldResume) {
+                await runResumeMigration(clientOptions);
+                return;
+            }
+            // User chose not to resume — start fresh
+        }
+        // ── Migration (fresh or dry-run) ────────────────────────
+        if (values['dry-run']) {
+            step('Dry run: scanning files that would be migrated...');
+        }
+        else {
+            step('Migrating local memory to engram...');
+            info('This will checkpoint local state, upload each file, and remove migrated originals.');
+            if (!(await confirm('  Continue?'))) {
+                info('Migration cancelled.');
+                process.exit(0);
+            }
+        }
+        try {
+            const result = await migrateOpenClawMemory(clientOptions, displayFileEvent);
+            console.log();
+            displayMigrateSummary(result);
+        }
+        catch (err) {
+            fail(`Migration failed: ${err.message}`);
+            process.exit(1);
+        }
+        if (!values['dry-run']) {
+            console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+        }
+        return;
+    }
+    // ── pair command ──────────────────────────────────────────────
+    if (command !== 'pair') {
+        fail(`Unknown command: ${command}`);
+        printUsage();
+        process.exit(1);
+    }
+    // Error if --recover is passed to pair (moved to migrate)
+    if (values.recover) {
+        fail('The --recover flag has moved to the migrate command. Use: npx @engramx/client migrate --engram <id> --recover');
+        process.exit(1);
+    }
+    const inviteCode = positionals[1];
+    if (!inviteCode) {
+        fail('Missing invite code. Usage: npx @engramx/client pair <code> --engram <id>');
+        process.exit(1);
+    }
+    if (!values.engram) {
+        fail('Missing --engram <canister-id>');
+        process.exit(1);
+    }
+    const keyPath = values['key-path'] || '~/.engramx/session.key';
+    const host = values.host || 'https://ic0.app';
+    // Resolve target framework
+    const target = await resolveTarget(values.target);
+    console.log(`\n${bold('EngramX Pairing')}`);
+    info(`Engram:   ${values.engram}`);
+    info(`Host:     ${host}`);
+    info(`Key path: ${keyPath}`);
+    info(`Target:   ${target}`);
+    // Step 1: Pair (generate key + register operator)
+    step('Generating session key and registering operator...');
+    info(`This will write: ${keyPath}`);
+    if (!(await confirm('  Continue?'))) {
+        console.log('\nPairing cancelled.');
+        process.exit(0);
+    }
+    let pairResult;
+    try {
+        pairResult = await pair({
+            inviteCode,
+            canisterId: values.engram,
+            host: values.host,
+            keyPath,
+            force: values.force,
+        });
+        ok(`Generated session key ${dim(`\u2192 ${pairResult.keyPath}`)}`);
+        ok(`Registered as operator ${dim(`(principal: ${pairResult.principal})`)}`);
+    }
+    catch (err) {
+        if (err instanceof PairError) {
+            fail(err.message);
+        }
+        else {
+            fail(`Unexpected error: ${err.message}`);
+        }
+        process.exit(1);
+    }
+    // Step 2: OpenClaw setup
+    if (target === 'openclaw') {
+        step('Installing OpenClaw plugin...');
+        info('This will modify: ~/.openclaw/openclaw.json');
+        let skipOpenClaw = false;
+        if (!(await confirm('  Continue?'))) {
+            info('Skipping OpenClaw plugin setup.');
+            skipOpenClaw = true;
+        }
+        if (!skipOpenClaw)
+            try {
+                const setupResult = await setupOpenClaw({
+                    canisterId: values.engram,
+                    sessionKeyPath: keyPath,
+                    host: values.host,
+                });
+                ok(`Installed EngramX plugin for OpenClaw`);
+                ok(`Updated ${dim(setupResult.configPath)}`);
+            }
+            catch (err) {
+                if (err instanceof OpenClawNotFoundError) {
+                    fail(err.message);
+                    console.log(`\n${dim('Manual setup:')}`);
+                    console.log(dim('  1. npm install @engramx/openclaw'));
+                    console.log(dim('  2. Add to openclaw.json: { "plugins": { "slots": { "memory": "memory-engramx" } } }'));
+                }
+                else {
+                    fail(`OpenClaw setup failed: ${err.message}`);
+                }
+                process.exit(1);
+            }
+    }
+    // Step 2b: Claude setup
+    if (target === 'claude') {
+        step('Configuring Claude MCP integration...');
+        const mcpConfig = generateMcpConfig({
+            canisterId: values.engram,
+            sessionKeyPath: keyPath,
+            host: values.host,
+        });
+        if (values.install) {
+            const paths = claudeConfigPaths();
+            // Install to Claude Code settings
+            try {
+                installMcpConfig(paths.claudeCode, {
+                    canisterId: values.engram,
+                    sessionKeyPath: keyPath,
+                    host: values.host,
+                });
+                ok(`Updated ${dim(paths.claudeCode)}`);
+            }
+            catch (err) {
+                warn(`Could not write to ${paths.claudeCode}: ${err.message}`);
+            }
+            // Install to Claude Desktop settings
+            try {
+                installMcpConfig(paths.claudeDesktop, {
+                    canisterId: values.engram,
+                    sessionKeyPath: keyPath,
+                    host: values.host,
+                });
+                ok(`Updated ${dim(paths.claudeDesktop)}`);
+            }
+            catch (err) {
+                warn(`Could not write to ${paths.claudeDesktop}: ${err.message}`);
+            }
+            info('Restart Claude Code / Cowork for the changes to take effect.');
+        }
+        else {
+            ok('MCP config generated. Add this to your Claude config:\n');
+            const paths = claudeConfigPaths();
+            info(`Claude Code:  ${paths.claudeCode}`);
+            info(`Claude Cowork: ${paths.claudeDesktop}`);
+            console.log();
+            console.log(JSON.stringify(mcpConfig, null, 2));
+            console.log();
+            info('Or re-run with --install to write it automatically.');
+        }
+    }
+    // Step 3: Git versioning
+    let gitRemoteUrl = values['git-remote'] || null;
+    if (gitRemoteUrl) {
+        step('Setting up git versioning...');
+        info(`Remote: ${gitRemoteUrl}`);
+        if (!(await confirm('  Continue?'))) {
+            info('Skipping git versioning setup.');
+            gitRemoteUrl = null;
+        }
+    }
+    else {
+        gitRemoteUrl = await promptGitRemote();
+    }
+    if (gitRemoteUrl) {
+        if (!values['git-remote'])
+            step('Setting up git versioning...');
+        try {
+            const gitResult = setupGitVersioning(gitRemoteUrl);
+            ok(`Git repo initialized ${dim(`→ ${gitResult.memoryDir}`)}`);
+            ok(`Remote "origin" set to ${dim(gitRemoteUrl)}`);
+            if (gitResult.existingRepo) {
+                info('Using existing git repo');
+            }
+            // Stage local memory files into the git-tracked memory dir so the
+            // baseline commit captures actual content (not just .gitignore).
+            try {
+                if (target === 'openclaw') {
+                    const openclawDir = getOpenClawDir();
+                    const ocConfig = (() => {
+                        const p = path.join(openclawDir, 'openclaw.json');
+                        try {
+                            return JSON.parse(fs.readFileSync(p, 'utf-8'));
+                        }
+                        catch {
+                            return {};
+                        }
+                    })();
+                    const agentsCfg = ocConfig['agents'];
+                    const defaultsCfg = agentsCfg?.['defaults'];
+                    const workspaceCfg = defaultsCfg?.['workspace'];
+                    const workspace = workspaceCfg
+                        ? path.isAbsolute(workspaceCfg)
+                            ? workspaceCfg
+                            : path.join(openclawDir, workspaceCfg)
+                        : path.join(openclawDir, 'workspace');
+                    // Copy workspace .md files into memoryDir (matching canister paths)
+                    if (fs.existsSync(workspace)) {
+                        for (const entry of fs.readdirSync(workspace, { withFileTypes: true })) {
+                            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                                continue;
+                            if (entry.name === 'BOOTSTRAP.md')
+                                continue;
+                            const src = path.join(workspace, entry.name);
+                            const dest = path.join(gitResult.memoryDir, entry.name);
+                            fs.copyFileSync(src, dest);
+                        }
+                    }
+                    // Also copy top-level MEMORY.md if it exists
+                    const topMemory = path.join(openclawDir, 'MEMORY.md');
+                    if (fs.existsSync(topMemory)) {
+                        fs.copyFileSync(topMemory, path.join(gitResult.memoryDir, 'MEMORY.md'));
+                    }
+                }
+                execFileSync('git', ['add', '-A'], { cwd: gitResult.memoryDir, stdio: 'pipe' });
+                const status = execFileSync('git', ['diff', '--cached', '--stat'], {
+                    cwd: gitResult.memoryDir,
+                    stdio: 'pipe',
+                })
+                    .toString()
+                    .trim();
+                if (status) {
+                    execFileSync('git', ['commit', '-m', 'engramx: pre-migration baseline'], {
+                        cwd: gitResult.memoryDir,
+                        stdio: 'pipe',
+                    });
+                    ok('Committed pre-migration baseline to git');
+                    try {
+                        const branch = execFileSync('git', ['branch', '--show-current'], {
+                            cwd: gitResult.memoryDir,
+                            stdio: 'pipe',
+                        })
+                            .toString()
+                            .trim() || 'main';
+                        try {
+                            execFileSync('git', ['pull', '--rebase', 'origin', branch], {
+                                cwd: gitResult.memoryDir,
+                                stdio: 'pipe',
+                            });
+                        }
+                        catch {
+                            // pull may fail if remote branch doesn't exist yet — that's fine
+                        }
+                        execFileSync('git', ['push', '-u', 'origin', branch], {
+                            cwd: gitResult.memoryDir,
+                            stdio: 'pipe',
+                        });
+                        ok('Pushed baseline to remote');
+                    }
+                    catch (pushErr) {
+                        const stderr = pushErr?.stderr?.toString() ?? '';
+                        const reason = (stderr
+                            .split('\n')
+                            .find((l) => l.includes('[rejected]') || l.includes('error:')) ??
+                            stderr.split('\n').slice(0, 3).join(' ').trim()) ||
+                            pushErr?.message ||
+                            'unknown error';
+                        warn(`Git push failed (will retry on next sync): ${reason}`);
+                    }
+                }
+            }
+            catch (gitErr) {
+                // git commit is best-effort — don't block pairing
+                warn(`Git baseline commit skipped: ${gitErr?.message || gitErr}`);
+            }
+        }
+        catch (err) {
+            fail(`Git setup failed: ${err.message}`);
+            info('You can set this up manually later. See: npx @engramx/client git-setup <url>');
+        }
+    }
+    // Step 4: Migration
+    {
+        const clientOptions = {
+            canisterId: values.engram,
+            sessionKeyPath: keyPath,
+            host: values.host,
+        };
+        step('Migrating local memory to engram...');
+        info('This will checkpoint local state, upload each file, and remove migrated originals.');
+        if (await confirm('  Continue?')) {
+            try {
+                const migrateResult = await migrateOpenClawMemory(clientOptions, displayFileEvent);
+                console.log();
+                displayMigrateSummary(migrateResult);
+            }
+            catch (err) {
+                fail(`Migration failed: ${err.message}`);
+                process.exit(1);
+            }
+            console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+            if (gitRemoteUrl) {
+                console.log(`Memory changes will be auto-committed and pushed to GitHub.`);
+            }
+            else {
+                info('Tip: Add git versioning with npx @engramx/client git-setup <url>');
+            }
+        }
+        else {
+            info(`Run 'npx @engramx/client migrate --engram ${values.engram}' to migrate later.`);
+        }
+    }
+}
+main().catch((err) => {
+    fail(`Fatal: ${err.message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map