@tpsdev-ai/flair 0.52.0 → 0.54.1

package/dist/commands/inspect.js

@@ -0,0 +1,45 @@
+import * as render from "../render.js";
+import { existsSync, readFileSync } from "node:fs";
+export function register(program) {
+    // ─── flair backup inspect ────────────────────────────────────────────────────
+    program
+        .command("inspect <path>")
+        .description("Show contents of a backup or export file")
+        .option("--json", "Emit raw JSON of the file (also: pipe + FLAIR_OUTPUT=json)")
+        .action(async (filePath, opts) => {
+        if (!existsSync(filePath)) {
+            console.error(`${render.icons.error} File not found: ${render.wrap(render.c.dim, filePath)}`);
+            process.exit(1);
+        }
+        const data = JSON.parse(readFileSync(filePath, "utf-8"));
+        const mode = render.resolveOutputMode(opts);
+        if (mode === "json") {
+            console.log(render.asJSON(data));
+            return;
+        }
+        console.log(`${render.wrap(render.c.bold, "File:")}    ${render.wrap(render.c.dim, filePath)}`);
+        const type = data.type ?? "full-backup";
+        const typeColor = type === "agent-export" ? render.c.cyan : render.c.magenta;
+        console.log(render.kv("Type", render.wrap(typeColor, type)));
+        console.log(render.kv("Created", String(data.createdAt ?? data.exportedAt ?? render.wrap(render.c.dim, "unknown"))));
+        console.log(render.kv("Source", String(data.source ?? render.wrap(render.c.dim, "unknown"))));
+        if (data.type === "agent-export") {
+            console.log(`\n${render.wrap(render.c.bold, "Agent")}: ${render.wrap(render.c.bold, data.agent?.id ?? "unknown")}`);
+            console.log(render.kv("Name", String(data.agent?.name ?? data.agent?.id ?? "—")));
+            console.log(render.kv("Memories", render.wrap(render.c.bold, String((data.memories ?? []).length))));
+            console.log(render.kv("Souls", render.wrap(render.c.bold, String((data.souls ?? []).length))));
+            console.log(render.kv("Grants", render.wrap(render.c.bold, String((data.grants ?? []).length))));
+            const keyText = data.privateKey ? render.wrap(render.c.magenta, "yes") : render.wrap(render.c.dim, "no");
+            console.log(render.kv("Key included", keyText));
+        }
+        else {
+            const agents = data.agents ?? [];
+            console.log(`\n${render.wrap(render.c.bold, "Agents")}: ${render.wrap(render.c.bold, String(agents.length))}`);
+            for (const a of agents) {
+                console.log(`  ${render.wrap(render.c.dim, "·")} ${render.wrap(render.c.bold, a.id)} ${render.wrap(render.c.dim, `(${a.name ?? a.id})`)}`);
+            }
+            console.log(render.kv("Memories", render.wrap(render.c.bold, String((data.memories ?? []).length))));
+            console.log(render.kv("Souls", render.wrap(render.c.bold, String((data.souls ?? []).length))));
+        }
+    });
+}

package/dist/commands/keys.js

@@ -0,0 +1,187 @@
+import { existsSync, mkdirSync, renameSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import * as render from "../render.js";
+import { loadEd25519PrivateKeyFromFile } from "../mcp-client-assertion.js";
+import { defaultKeysDir } from "../lib/auth-resolve.js";
+import { classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "../doctor-client.js";
+let cli;
+/** Bind shared CLI helpers. cli.ts calls this immediately before register(program). */
+export function bindCli(fns) {
+    cli = fns;
+}
+const checkAgentRegistered = (baseUrl, agentId, keysDir) => cli.checkAgentRegistered(baseUrl, agentId, keysDir);
+const probeFlairReachable = (url, timeoutMs) => cli.probeFlairReachable(url, timeoutMs);
+const resolveBaseUrl = (opts) => cli.resolveBaseUrl(opts);
+/** Best-effort seed-validity check for a `.key` file: does it parse via any
+ *  of the formats loadEd25519PrivateKeyFromFile (src/mcp-client-assertion.ts
+ *  — the same loader `flair mcp token` uses) accepts? Never throws — used
+ *  only to decide "unidentified" vs. "worth a registration check", not to
+ *  actually sign anything. An unparseable file is not junk: the keys dir is
+ *  also where FileKeyStore writes AES-256-GCM blobs (flair#1026). */
+function isValidPrivateKeySeedFile(keyPath) {
+    try {
+        loadEd25519PrivateKeyFromFile(keyPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify every entry in `keysDir` for `flair keys prune`. Pure READ —
+ * never writes or moves anything; see applyKeyPrune below for the actual
+ * move. Directories (including keysDir's own `.pruned` archive, PRUNED_DIR_NAME)
+ * and files not ending in `.key` are "ignored" without any network call.
+ * `.key` files with an unparseable seed are "unidentified" without a network
+ * call either — reported, never pruned (flair#1026). Only a `.key` file that
+ * DOES parse triggers a signed `GET /Agent/:id` against `baseUrl`
+ * (checkAgentRegistered above, the exact same check doctor's registration
+ * gate uses).
+ *
+ * If that check EVER reports "unreachable" — the instance couldn't be
+ * confirmed up for that key — the WHOLE run aborts immediately
+ * (`aborted: true`, `entries: []`, short-circuiting the loop): never
+ * classify anything, prunable or not, while registration state can't be
+ * verified. A missing keysDir is treated as "nothing to classify" (fresh
+ * install), not an error — matches `flair doctor`'s own "Keys directory
+ * missing" being a separate, non-fatal finding.
+ */
+export async function classifyKeysDir(keysDir, baseUrl) {
+    if (!existsSync(keysDir))
+        return { aborted: false, entries: [] };
+    const dirents = readdirSync(keysDir, { withFileTypes: true });
+    const entries = [];
+    const candidates = [];
+    for (const d of dirents) {
+        if (d.isDirectory()) {
+            entries.push({
+                name: d.name,
+                class: "ignored",
+                reason: d.name === PRUNED_DIR_NAME ? "prune archive directory" : "directory (not a key file)",
+            });
+            continue;
+        }
+        if (!d.name.endsWith(".key")) {
+            entries.push({ name: d.name, class: "ignored", reason: "not a .key file" });
+            continue;
+        }
+        candidates.push({ name: d.name, agentId: d.name.slice(0, -".key".length) });
+    }
+    for (const c of candidates) {
+        const keyPath = join(keysDir, c.name);
+        if (!isValidPrivateKeySeedFile(keyPath)) {
+            const decision = classifyKeyFile(c.agentId, false, null, baseUrl);
+            entries.push({ name: c.name, class: decision.class, reason: decision.reason, agentId: c.agentId });
+            continue;
+        }
+        const reg = await checkAgentRegistered(baseUrl, c.agentId, keysDir);
+        if (reg.state === "unreachable") {
+            return {
+                aborted: true,
+                abortReason: `could not reach ${baseUrl} to verify agent '${c.agentId}' is registered` +
+                    `${reg.detail ? ` (${reg.detail})` : ""} — aborting; nothing was classified or moved. ` +
+                    `Pass --instance <url> to target a different instance.`,
+                entries: [],
+            };
+        }
+        // flair#1023 added "key-unreadable". It cannot occur here — this key's
+        // seed already parsed via isValidPrivateKeySeedFile above — but is
+        // handled explicitly rather than folded into the else: a key that will
+        // not load is "unidentified", not prunable "invalid" (flair#1026).
+        const decision = reg.state === "key-unreadable"
+            ? classifyKeyFile(c.agentId, false, null, baseUrl)
+            : classifyKeyFile(c.agentId, true, { state: reg.state, detail: reg.detail }, baseUrl);
+        entries.push({ name: c.name, class: decision.class, reason: decision.reason, agentId: c.agentId });
+    }
+    return { aborted: false, entries };
+}
+/**
+ * Move every "stale" or "invalid" entry from `keysDir` into
+ * `<keysDir>/.pruned/<dateStamp>/`, creating the archive dir as needed —
+ * MOVE, never delete, so a bad classification is always recoverable. Only
+ * ever called with entries classifyKeysDir already decided are prunable; a
+ * "keep" or "ignored" entry passed in here is simply skipped (defense in
+ * depth — a registered agent's key must never move, even if a caller bug
+ * fed it in). Collisions (same filename already archived from an earlier
+ * prune run today) get a numeric suffix (resolveCollisionSafeName) rather
+ * than silently overwriting the earlier archive.
+ */
+export function applyKeyPrune(keysDir, entries, dateStamp) {
+    const prunable = entries.filter((e) => e.class === "stale" || e.class === "invalid");
+    if (prunable.length === 0)
+        return [];
+    const destDir = join(keysDir, PRUNED_DIR_NAME, dateStamp);
+    mkdirSync(destDir, { recursive: true });
+    const existing = new Set(readdirSync(destDir));
+    const moved = [];
+    for (const e of prunable) {
+        const destName = resolveCollisionSafeName(existing, e.name);
+        existing.add(destName);
+        const from = join(keysDir, e.name);
+        const to = join(destDir, destName);
+        renameSync(from, to);
+        moved.push({ name: e.name, movedTo: to });
+    }
+    return moved;
+}
+/** Register the `flair keys` command group (flair#1629). */
+export function register(program) {
+    const keys = program.command("keys").description("Manage Ed25519 key files in the key directory");
+    keys
+        .command("prune")
+        .description("Move stale/unregistered/invalid keys to <keysDir>/.pruned/<date>/ — dry-run by default")
+        .option("--apply", "Actually move prunable keys (default: dry-run, prints what would move and why)")
+        .option("--keys-dir <dir>", "Directory to scan for key files (else FLAIR_KEY_DIR, ~/.flair/keys)")
+        .option("--instance <url>", "Flair instance to check registration against (else FLAIR_TARGET/FLAIR_URL/config)")
+        .option("--port <port>", "Harper HTTP port (used when --instance/FLAIR_URL/FLAIR_TARGET are not set)")
+        .action(async (opts) => {
+        const keysDir = opts.keysDir ?? process.env.FLAIR_KEY_DIR ?? defaultKeysDir();
+        const baseUrl = resolveBaseUrl({ target: opts.instance, port: opts.port });
+        const apply = !!opts.apply;
+        console.log(`\n${render.wrap(render.c.bold, "🔑 Flair Keys Prune")}${apply ? "" : render.wrap(render.c.dim, " (dry run)")}\n`);
+        console.log(`  Keys directory: ${render.wrap(render.c.dim, keysDir)}`);
+        console.log(`  Instance:       ${render.wrap(render.c.dim, baseUrl)}\n`);
+        const result = await classifyKeysDir(keysDir, baseUrl);
+        if (result.aborted) {
+            console.error(`  ${render.icons.error} ${result.abortReason}`);
+            console.log("");
+            process.exit(1);
+        }
+        const stale = result.entries.filter((e) => e.class === "stale");
+        const invalid = result.entries.filter((e) => e.class === "invalid");
+        const unidentified = result.entries.filter((e) => e.class === "unidentified");
+        const kept = result.entries.filter((e) => e.class === "keep");
+        const ignored = result.entries.filter((e) => e.class === "ignored");
+        const prunable = [...stale, ...invalid];
+        if (stale.length + invalid.length + unidentified.length + kept.length === 0) {
+            console.log(`  ${render.icons.ok} No key files found in ${render.wrap(render.c.dim, keysDir)} — nothing to prune.`);
+            console.log("");
+            return;
+        }
+        for (const e of prunable) {
+            const icon = e.class === "invalid" ? render.icons.error : render.icons.warn;
+            console.log(`  ${icon} ${render.wrap(render.c.bold, e.name)} — ${e.class}: ${e.reason}`);
+        }
+        for (const e of unidentified) {
+            console.log(`  ${render.icons.warn} ${render.wrap(render.c.bold, e.name)} — unidentified: ${e.reason}`);
+        }
+        for (const e of kept) {
+            console.log(`  ${render.icons.ok} ${e.name} — registered, keeping`);
+        }
+        if (!apply) {
+            console.log("");
+            console.log(`  ${render.wrap(render.c.dim, `${prunable.length} prunable (${stale.length} stale, ${invalid.length} invalid), ${kept.length} kept, ${unidentified.length} unidentified (left in place), ${ignored.length} ignored`)}`);
+            if (prunable.length > 0) {
+                console.log(`  ${render.wrap(render.c.dim, "Run with --apply to move prunable keys to")} ${join(keysDir, PRUNED_DIR_NAME, pruneDateStamp())}`);
+            }
+            console.log("");
+            return;
+        }
+        const moved = applyKeyPrune(keysDir, result.entries, pruneDateStamp());
+        console.log("");
+        for (const m of moved) {
+            console.log(`  ${render.icons.ok} moved ${m.name} -> ${m.movedTo}`);
+        }
+        console.log(`\n  ${render.wrap(render.c.bold, String(moved.length))} moved, ${kept.length} kept, ${unidentified.length} unidentified (left in place), ${ignored.length} ignored\n`);
+    });
+}