@tpsdev-ai/flair 0.53.0 → 0.54.2

package/dist/commands/restore.js

@@ -0,0 +1,130 @@
+import { resolveAdminUser } from "../lib/auth-resolve.js";
+import * as render from "../render.js";
+import { existsSync, readFileSync } from "node:fs";
+let cli;
+/** Bind the cli-locals this module depends on. */
+export function bindCli(fns) {
+    cli = fns;
+}
+function resolveHttpPort(...args) {
+    return cli.resolveHttpPort(...args);
+}
+export function register(program) {
+    // ─── flair restore ────────────────────────────────────────────────────────────
+    program
+        .command("restore <path>")
+        .description("Import a Flair backup archive")
+        .option("--merge", "Add/update records without deleting existing (default)")
+        .option("--replace", "Delete all existing data for backed-up agents first, then import")
+        .option("--port <port>", "Harper HTTP port")
+        .option("--url <url>", "Flair base URL (overrides --port)")
+        .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+        .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
+        .option("--dry-run", "Show what would be imported without making changes")
+        .action(async (backupPath, opts) => {
+        const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
+        const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+        const adminUser = resolveAdminUser(opts.adminUser);
+        const dryRun = Boolean(opts.dryRun);
+        const mode = opts.replace ? "replace" : "merge";
+        if (!adminPass) {
+            console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for restore");
+            process.exit(1);
+        }
+        if (!existsSync(backupPath)) {
+            console.error(`Error: backup file not found: ${backupPath}`);
+            process.exit(1);
+        }
+        const backup = JSON.parse(readFileSync(backupPath, "utf-8"));
+        if (backup.version !== 1) {
+            console.error(`Error: unsupported backup version: ${backup.version}`);
+            process.exit(1);
+        }
+        const { agents = [], memories = [], souls = [] } = backup;
+        const auth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
+        console.log(`Restoring from: ${backupPath}`);
+        console.log(`Mode: ${mode}${dryRun ? " (dry run)" : ""}`);
+        console.log(`  Agents:   ${agents.length}`);
+        console.log(`  Memories: ${memories.length}`);
+        console.log(`  Souls:    ${souls.length}`);
+        if (dryRun) {
+            console.log("\n✅ Dry run complete — no changes made");
+            return;
+        }
+        async function adminPut(path, body) {
+            const res = await fetch(`${baseUrl}${path}`, {
+                method: "PUT",
+                headers: { "Content-Type": "application/json", Authorization: auth },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`PUT ${path} failed (${res.status}): ${text}`);
+            }
+        }
+        async function adminDelete(path) {
+            const res = await fetch(`${baseUrl}${path}`, {
+                method: "DELETE",
+                headers: { Authorization: auth },
+                signal: AbortSignal.timeout(10_000),
+            });
+            // 404 is fine — already gone
+            if (!res.ok && res.status !== 404) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`DELETE ${path} failed (${res.status}): ${text}`);
+            }
+        }
+        // Replace mode: delete existing data for these agents first
+        if (mode === "replace") {
+            console.log("\nDeleting existing data (replace mode)...");
+            for (const memory of memories) {
+                if (memory.id)
+                    await adminDelete(`/Memory/${memory.id}`).catch((e) => console.warn(`  warn: ${e.message}`));
+            }
+            for (const soul of souls) {
+                if (soul.id)
+                    await adminDelete(`/Soul/${soul.id}`).catch((e) => console.warn(`  warn: ${e.message}`));
+            }
+        }
+        // Restore agents
+        console.log("\nRestoring agents...");
+        let agentCount = 0;
+        for (const agent of agents) {
+            try {
+                await adminPut(`/Agent/${agent.id}`, agent);
+                agentCount++;
+            }
+            catch (err) {
+                console.warn(`  warn: agent ${agent.id}: ${err.message}`);
+            }
+        }
+        // Restore souls before memories: refuseLearnedSoulWrite matches Memory text.
+        console.log("Restoring souls...");
+        let soulCount = 0;
+        for (const soul of souls) {
+            try {
+                await adminPut(`/Soul/${soul.id}`, soul);
+                soulCount++;
+            }
+            catch (err) {
+                console.warn(`  warn: soul ${soul.id}: ${err.message}`);
+            }
+        }
+        console.log("Restoring memories...");
+        let memoryCount = 0;
+        for (const memory of memories) {
+            try {
+                await adminPut(`/Memory/${memory.id}`, memory);
+                memoryCount++;
+            }
+            catch (err) {
+                console.warn(`  warn: memory ${memory.id}: ${err.message}`);
+            }
+        }
+        console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Restore complete")}`);
+        console.log(render.kv("Agents restored", `${render.wrap(render.c.bold, String(agentCount))}${render.wrap(render.c.dim, `/${agents.length}`)}`));
+        console.log(render.kv("Memories restored", `${render.wrap(render.c.bold, String(memoryCount))}${render.wrap(render.c.dim, `/${memories.length}`)}`));
+        console.log(render.kv("Souls restored", `${render.wrap(render.c.bold, String(soulCount))}${render.wrap(render.c.dim, `/${souls.length}`)}`));
+    });
+}

package/dist/commands/search.js

@@ -0,0 +1,244 @@
+import { buildEd25519Auth, resolveKeyPath } 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);
+}
+function parseRelativeOrIso(input) {
+    if (!input)
+        return null;
+    const m = input.match(/^(\d+)([smhdw])$/);
+    if (!m)
+        return input;
+    const n = Number.parseInt(m[1], 10);
+    const unit = m[2];
+    const multMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+    return new Date(Date.now() - n * (multMs[unit] ?? 0)).toISOString();
+}
+export function searchScoringFormula(scoring) {
+    return scoring === "composite"
+        ? "semantic × durability-weight × recency-decay × usage-boost"
+        : "cosine similarity only";
+}
+export function buildSearchExplain(record, scoring, now = Date.now()) {
+    const score = typeof record?._score === "number" ? record._score : undefined;
+    const rawScore = typeof record?._rawScore === "number" ? record._rawScore : undefined;
+    // composite mode: server sends both (_rawScore = pre-composite semantic).
+    // raw mode: server sends only _score, and that IS the raw score.
+    const raw = scoring === "composite" ? rawScore : score;
+    const composite = scoring === "composite" ? score : undefined;
+    let ageDays;
+    if (record?.createdAt) {
+        const created = new Date(String(record.createdAt)).getTime();
+        if (Number.isFinite(created))
+            ageDays = Math.max(0, Math.floor((now - created) / 86_400_000));
+    }
+    const explain = {
+        scoring,
+        formula: searchScoringFormula(scoring),
+        durability: record?.durability ?? "standard",
+        usageCount: typeof record?.usageCount === "number" ? record.usageCount : 0,
+    };
+    if (typeof raw === "number")
+        explain.raw = raw;
+    if (typeof composite === "number")
+        explain.composite = composite;
+    if (typeof ageDays === "number")
+        explain.ageDays = ageDays;
+    return explain;
+}
+// Human one-liner for a hit's breakdown. Scoring terms come from the shared
+// builder; the trailing tags/subject/supersedes are record context that json
+// mode already carries at top level, so they're appended here only.
+export function formatSearchExplain(explain, record) {
+    const parts = [];
+    if (typeof explain.raw === "number")
+        parts.push(`raw=${explain.raw.toFixed(3)}`);
+    if (typeof explain.composite === "number")
+        parts.push(`composite=${explain.composite.toFixed(3)}`);
+    parts.push(`durability=${explain.durability}`);
+    if (typeof explain.ageDays === "number")
+        parts.push(`age=${explain.ageDays}d`);
+    parts.push(`usage=${explain.usageCount}`);
+    if (Array.isArray(record?.tags) && record.tags.length > 0)
+        parts.push(`tags=[${record.tags.join(",")}]`);
+    if (record?.subject)
+        parts.push(`subject=${record.subject}`);
+    if (record?.supersedes)
+        parts.push(`supersedes=${record.supersedes}`);
+    return parts.join(" · ");
+}
+export function register(program) {
+    // ─── flair search (top-level shortcut) ───────────────────────────────────────
+    // Parse --since / --as-of: accept ISO 8601 OR relative expressions
+    // ("1h", "7d", "30m"). Returns ISO 8601 string or null if input is empty.
+    // Returns the original string unchanged if it looks like a date (caller
+    // passes through to server, which validates).
+    program
+        .command("search <query>")
+        .description("Search memories by meaning (shortcut for memory search) — filterable, with --explain ranking")
+        .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+        .option("--limit <n>", "Max results", "5")
+        .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")
+        // Server-side filters (forwarded to /SemanticSearch payload)
+        .option("--tag <tag>", "Filter to memories carrying this tag")
+        .option("--subject <subject>", "Filter to memories carrying this subject (case-insensitive)")
+        .option("--subjects <list>", "Comma-separated list of subjects to OR-filter (case-insensitive)")
+        .option("--since <iso-or-relative>", "Only memories created after this point (ISO 8601 or '7d'/'24h'/'30m')")
+        .option("--as-of <iso>", "Temporal validity: only memories valid at this point (ISO 8601)")
+        .option("--include-superseded", "Include memories that have been superseded")
+        .option("--scoring <mode>", "Scoring mode: raw (default) uses cosine similarity/BM25 only; composite re-ranks by durability/recency/retrieval (measurably hurts precision as of flair#623 — opt-in only)", "raw")
+        .option("--min-score <n>", "Drop results below this score (0..1)", "0")
+        // Client-side filters (applied after server response)
+        .option("--durability <level>", "Filter to permanent|persistent|standard|ephemeral (client-side)")
+        .option("--source <name>", "Filter by source/agentId (client-side)")
+        // Output modes
+        .option("--explain", "Show score breakdown (raw, composite, durability, age, usage) per hit — also added to --json output as _explain")
+        .option("--json", "Output raw JSON array")
+        .action(async (query, opts) => {
+        try {
+            const { agentId } = resolveSigningAgentId(opts, "search");
+            if (!agentId) {
+                console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+                process.exit(2);
+            }
+            const baseUrl = resolveBaseUrl(opts);
+            const headers = { "content-type": "application/json" };
+            const keyPath = opts.key || resolveKeyPath(agentId);
+            if (keyPath) {
+                headers["authorization"] = buildEd25519Auth(agentId, "POST", "/SemanticSearch", keyPath);
+            }
+            // Build payload from CLI options. Server validates types.
+            const payload = {
+                agentId,
+                q: query,
+                limit: Number.parseInt(opts.limit, 10) || 5,
+                scoring: opts.scoring === "composite" ? "composite" : "raw",
+            };
+            if (opts.tag)
+                payload.tag = opts.tag;
+            if (opts.subject)
+                payload.subject = opts.subject;
+            if (opts.subjects)
+                payload.subjects = String(opts.subjects).split(",").map((s) => s.trim()).filter(Boolean);
+            const since = parseRelativeOrIso(opts.since);
+            if (since)
+                payload.since = since;
+            if (opts.asOf)
+                payload.asOf = opts.asOf;
+            if (opts.includeSuperseded)
+                payload.includeSuperseded = true;
+            const minScore = Number.parseFloat(opts.minScore ?? "0");
+            if (Number.isFinite(minScore) && minScore > 0)
+                payload.minScore = minScore;
+            const res = await fetch(`${baseUrl}/SemanticSearch`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok)
+                throw new Error(await res.text());
+            const result = (await res.json());
+            let results = result.results || result || [];
+            if (!Array.isArray(results))
+                results = [];
+            // Client-side filters: durability + source. Server doesn't expose these
+            // as conditions, so we filter after fetch.
+            if (opts.durability) {
+                const allowed = new Set(String(opts.durability).split(",").map((d) => d.trim()));
+                results = results.filter((r) => allowed.has(r.durability ?? "standard"));
+            }
+            if (opts.source) {
+                const allowed = new Set(String(opts.source).split(",").map((s) => s.trim()));
+                results = results.filter((r) => allowed.has(r._source ?? r.agentId ?? ""));
+            }
+            const mode = render.resolveOutputMode(opts);
+            const scoringMode = payload.scoring === "composite" ? "composite" : "raw";
+            if (mode === "json") {
+                // flair#992: --explain must be honoured here, not silently dropped.
+                // This branch is what every non-TTY caller lands in. The breakdown
+                // rides ALONG the json contract as an opt-in `_explain` key — present
+                // only when the caller typed --explain, so default output is unchanged
+                // — rather than switching output mode behind the caller's back.
+                const out = opts.explain
+                    ? results.map((r) => ({ ...r, _explain: buildSearchExplain(r, scoringMode) }))
+                    : results;
+                console.log(render.asJSON(out));
+                return;
+            }
+            if (results.length === 0) {
+                console.log(`${render.icons.info} ${render.wrap(render.c.dim, "No results found.")}`);
+                const filters = [];
+                if (opts.tag)
+                    filters.push(`tag=${opts.tag}`);
+                if (opts.subject)
+                    filters.push(`subject=${opts.subject}`);
+                if (opts.subjects)
+                    filters.push(`subjects=${opts.subjects}`);
+                if (opts.since)
+                    filters.push(`since=${opts.since}`);
+                if (opts.durability)
+                    filters.push(`durability=${opts.durability}`);
+                if (opts.source)
+                    filters.push(`source=${opts.source}`);
+                if (filters.length > 0) {
+                    console.log(`  ${render.wrap(render.c.dim, "Filters:")} ${filters.join(render.wrap(render.c.dim, " · "))}`);
+                    console.log(`  ${render.icons.arrow} ${render.wrap(render.c.dim, "Try removing a filter or:")} flair search "${query}" --agent ${agentId}`);
+                }
+                return;
+            }
+            const durabilityColor = (d) => {
+                if (d === "permanent")
+                    return render.c.magenta;
+                if (d === "persistent")
+                    return render.c.blue;
+                if (d === "ephemeral")
+                    return render.c.gray;
+                return render.c.cyan;
+            };
+            for (const r of results) {
+                const date = r.createdAt ? String(r.createdAt).slice(0, 10) : "";
+                const scoreVal = typeof r._score === "number" ? r._score : 0;
+                const scorePct = typeof r._score === "number" ? `${(scoreVal * 100).toFixed(0)}%` : "";
+                const scoreColor = scoreVal >= 0.7 ? render.c.green : scoreVal >= 0.4 ? render.c.yellow : render.c.dim;
+                const durability = r.durability ?? "standard";
+                const metaParts = [];
+                if (date)
+                    metaParts.push(render.wrap(render.c.dim, date));
+                metaParts.push(render.wrap(durabilityColor(durability), durability));
+                if (scorePct)
+                    metaParts.push(render.wrap(scoreColor, scorePct));
+                if (r._source)
+                    metaParts.push(render.wrap(render.c.cyan, `from:${r._source}`));
+                const meta = metaParts.join(render.wrap(render.c.dim, " · "));
+                console.log(`  ${r.content}`);
+                if (meta)
+                    console.log(`  ${render.wrap(render.c.dim, "(")} ${meta} ${render.wrap(render.c.dim, ")")}`);
+                if (opts.explain) {
+                    const line = formatSearchExplain(buildSearchExplain(r, scoringMode), r);
+                    if (line) {
+                        console.log(`    ${render.wrap(render.c.gray, "└─")} ${render.wrap(render.c.dim, line)}`);
+                    }
+                }
+                console.log();
+            }
+            if (opts.explain) {
+                console.log(`${render.wrap(render.c.dim, "Scoring:")} ${render.wrap(render.c.bold, scoringMode)}  ${render.wrap(render.c.dim, `(${searchScoringFormula(scoringMode)})`)}`);
+            }
+        }
+        catch (err) {
+            console.error(`${render.icons.error} Search failed: ${err.message}`);
+            process.exit(1);
+        }
+    });
+}