@tpsdev-ai/flair 0.52.0 → 0.54.1

package/dist/commands/backup.js

@@ -0,0 +1,115 @@
+import { resolveAdminUser } from "../lib/auth-resolve.js";
+import * as render from "../render.js";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+let cli;
+/** Bind the cli-locals this module depends on. */
+export function bindCli(fns) {
+    cli = fns;
+}
+function addSharedCredentialOptions(...args) {
+    return cli.addSharedCredentialOptions(...args);
+}
+function applyAdminPassFile(...args) {
+    return cli.applyAdminPassFile(...args);
+}
+function resolveHttpPort(...args) {
+    return cli.resolveHttpPort(...args);
+}
+export function register(program) {
+    // ─── flair backup ────────────────────────────────────────────────────────────
+    addSharedCredentialOptions(program
+        .command("backup")
+        .description("Export agents, memories, and souls to a JSON archive")
+        .option("--output <path>", "Output file path (default: ~/.flair/backups/flair-backup-<timestamp>.json)")
+        .option("--agents <ids>", "Comma-separated agent IDs to include (default: all)")
+        .option("--port <port>", "Harper HTTP port")
+        .option("--url <url>", "Flair base URL (overrides --port)")).action(async (opts) => {
+        const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
+        applyAdminPassFile(opts);
+        // Env is a second-class fallback after the explicit flags (same order
+        // backup used before the shared helper). FLAIR_ADMIN_PASS is still
+        // accepted so existing scripts keep working.
+        const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+        const adminUser = resolveAdminUser(opts.adminUser);
+        if (!adminPass) {
+            console.error("Error: --admin-pass, --admin-pass-file, or FLAIR_ADMIN_PASS required for backup");
+            process.exit(1);
+        }
+        // flair#968: `flair backup > file.json` captures the progress report, not
+        // the archive (which goes to --output, defaulting to ~/.flair/backups/...).
+        // The result was exit 0 and a plausible-looking file of a few hundred bytes —
+        // a false success immediately before a destructive upgrade.
+        //
+        // When stdout is not a TTY, route progress output to stderr. The archive
+        // still goes to --output / the default path. This makes `flair backup >
+        // file.json` produce an EMPTY file — unmistakably not a valid archive —
+        // while leaving default-path callers (schedulers, cron) completely
+        // unaffected.
+        const log = process.stdout.isTTY
+            ? console.log.bind(console)
+            : console.error.bind(console);
+        const auth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
+        async function adminGet(path) {
+            const res = await fetch(`${baseUrl}${path}`, {
+                headers: { Authorization: auth },
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`GET ${path} failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        }
+        log("Fetching agents...");
+        const allAgents = await adminGet("/Agent/");
+        const filterIds = opts.agents ? opts.agents.split(",").map((s) => s.trim()) : null;
+        const agents = filterIds ? allAgents.filter((a) => filterIds.includes(a.id)) : allAgents;
+        log(`Fetching memories for ${agents.length} agent(s)...`);
+        const memories = [];
+        for (const agent of agents) {
+            try {
+                const agentMemories = await adminGet(`/Memory/?agentId=${encodeURIComponent(agent.id)}`);
+                if (Array.isArray(agentMemories))
+                    memories.push(...agentMemories);
+            }
+            catch (err) {
+                console.warn(`  Warning: could not fetch memories for ${agent.id}: ${err.message}`);
+            }
+        }
+        log("Fetching souls...");
+        const souls = [];
+        for (const agent of agents) {
+            try {
+                const agentSouls = await adminGet(`/Soul/?agentId=${encodeURIComponent(agent.id)}`);
+                if (Array.isArray(agentSouls))
+                    souls.push(...agentSouls);
+            }
+            catch (err) {
+                console.warn(`  Warning: could not fetch souls for ${agent.id}: ${err.message}`);
+            }
+        }
+        const backup = {
+            version: 1,
+            createdAt: new Date().toISOString(),
+            source: baseUrl,
+            agents,
+            memories,
+            souls,
+        };
+        // Determine output path
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+        const defaultOutput = join(homedir(), ".flair", "backups", `flair-backup-${timestamp}.json`);
+        const outputPath = opts.output ?? defaultOutput;
+        mkdirSync(join(outputPath, ".."), { recursive: true });
+        const tmp = outputPath + ".tmp";
+        writeFileSync(tmp, JSON.stringify(backup, null, 2) + "\n", "utf-8");
+        renameSync(tmp, outputPath);
+        log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Backup complete")}`);
+        log(render.kv("Agents", render.wrap(render.c.bold, String(agents.length))));
+        log(render.kv("Memories", render.wrap(render.c.bold, String(memories.length))));
+        log(render.kv("Souls", render.wrap(render.c.bold, String(souls.length))));
+        log(render.kv("Output", render.wrap(render.c.dim, outputPath)));
+    });
+}

package/dist/commands/bootstrap.js

@@ -0,0 +1,91 @@
+import { authedRequest } from "../lib/auth-resolve.js";
+import * as render from "../render.js";
+let cli;
+/** Bind the cli-locals this module depends on. */
+export function bindCli(fns) {
+    cli = fns;
+}
+function resolveBaseUrl(...args) {
+    return cli.resolveBaseUrl(...args);
+}
+function resolveSigningAgentId(...args) {
+    return cli.resolveSigningAgentId(...args);
+}
+export function register(program) {
+    // ─── flair bootstrap ─────────────────────────────────────────────────────────
+    //
+    // `flair bootstrap` prints agent context (soul, memories) and a structured budget
+    // footer summarizing token usage and memory inclusion/truncation. The footer is
+    // parseable for downstream agents to react to budget pressure.
+    //
+    // Budget footer format (printed to stderr):
+    //   [budget: <used>/<max> tokens, <included> included, <truncated> truncated]
+    //
+    // Fields:
+    //   - tokens: estimated tokens used / max budget
+    //   - included: number of memories/soul entries included in context
+    //   - truncated: number of memories excluded due to token budget
+    //
+    // When truncated &gt; 0, the agent should consider asking for more context or reducing scope.
+    program
+        .command("bootstrap")
+        .description("Cold-start context: get soul + recent memories as formatted text")
+        .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+        .option("--max-tokens <n>", "Maximum tokens in output", "4000")
+        .option("--port <port>", "Harper HTTP port")
+        .option("--url <url>", "Flair base URL (overrides --port)")
+        .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
+        .option("--key <path>", "Ed25519 private key path")
+        .option("--json", "Emit JSON {context, tokenEstimate, memoriesIncluded, ...} (also: pipe + FLAIR_OUTPUT=json)")
+        .action(async (opts) => {
+        const { agentId, source } = resolveSigningAgentId(opts, "bootstrap");
+        if (!agentId) {
+            console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
+            process.exit(2);
+        }
+        const baseUrl = resolveBaseUrl(opts);
+        const mode = render.resolveOutputMode(opts);
+        try {
+            // flair#747: routed through the shared resolver — --key is an
+            // explicit tier-1 override (as before), now additionally backstopped
+            // by env admin-pass / ~/.flair/admin-pass / the Ed25519 floor if
+            // neither --key nor the agent's own resolveKeyPath(agentId) lookup
+            // finds a usable key. Previously this only ever tried Ed25519 (no
+            // admin fallback at all) and sent NO Authorization header when no key
+            // was found, relying on Harper's local passthrough.
+            const result = (await authedRequest("POST", "/BootstrapMemories", { agentId, maxTokens: parseInt(opts.maxTokens, 10) }, { baseUrl, agentId, agentIdSource: source, explicitKeyPath: opts.key }));
+            if (mode === "json") {
+                // Agent-first: emit the full server response, augmented with the cap
+                // that was requested. Includes context, sections, tokenEstimate, etc.
+                console.log(render.asJSON({ ...result, maxTokens: parseInt(opts.maxTokens, 10) }));
+                return;
+            }
+            // Human mode: print context to stdout, budget footer to stderr (parseable).
+            if (result.context) {
+                console.log(result.context);
+            }
+            else {
+                console.error(`${render.icons.error} No context available.`);
+                process.exit(1);
+            }
+            // flair#1199 — the budget footer reflects the PROSE the human injects
+            // (stdout = result.context), not the full serialized payload. tokenEstimate
+            // now measures the whole response (structured containers + prose), which
+            // the CLI's structured fields the human doesn't read would inflate.
+            const tokensUsed = typeof result.context === "string" && result.context.length > 0
+                ? Math.ceil(result.context.length / 4)
+                : (result.tokenEstimate ?? 0);
+            const maxTokens = parseInt(opts.maxTokens, 10);
+            const included = result.memoriesIncluded ?? 0;
+            const truncated = result.memoriesTruncated ?? 0;
+            const tokenPct = maxTokens > 0 ? (tokensUsed / maxTokens) * 100 : 0;
+            const tokenIcon = tokenPct >= 90 ? render.icons.warn : tokenPct >= 70 ? render.icons.info : render.icons.ok;
+            const truncIcon = truncated > 0 ? render.icons.warn : render.icons.ok;
+            console.error(`${tokenIcon} budget ${tokensUsed}/${maxTokens} tokens (${tokenPct.toFixed(0)}%) ${render.icons.bullet} ${render.icons.ok} ${included} included ${render.icons.bullet} ${truncIcon} ${truncated} truncated`);
+        }
+        catch (err) {
+            console.error(`${render.icons.error} Bootstrap failed: ${err.message}`);
+            process.exit(1);
+        }
+    });
+}