@tpsdev-ai/flair 0.6.0 → 0.6.1

package/dist/bridges/runtime/roundtrip.js

@@ -0,0 +1,154 @@
+/**
+ * Round-trip test harness for bridges.
+ *
+ * A bridge passes the round-trip test iff:
+ *   1. Parse the fixture (or descriptor's first import.source.path) → pass1 BridgeMemory[]
+ *   2. Apply export.targets[0]: when-filter → map → write to tmp in the
+ *      target's format
+ *   3. Re-import the tmp file using import.sources[0] → pass2 BridgeMemory[]
+ *   4. pass1 and pass2 must agree on the round-trip-stable fields from the
+ *      spec (§8): content, subject, tags, durability.
+ *
+ * This exercises the full mapper + predicate + writer + parser chain —
+ * if a bridge author's descriptor has mapping bugs, the round-trip
+ * surfaces them before memories ever reach Flair.
+ *
+ * Implementation note: does NOT talk to Flair. Fixture-to-fixture only.
+ * Lives here so slice-3c code plugins can reuse the same harness.
+ */
+import { promises as fsp } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { BridgeRuntimeError } from "../types.js";
+import { parseRecords } from "./formats.js";
+import { applyMap } from "./mapper.js";
+import { evaluatePredicate } from "./predicate.js";
+import { writeRecords } from "./writers.js";
+/** Fields the spec (§8) requires to survive round-trip. */
+export const ROUND_TRIP_STABLE_FIELDS = ["content", "subject", "tags", "durability"];
+export async function runRoundTrip(opts) {
+    const { descriptor, cwd } = opts;
+    if (!descriptor.import || descriptor.import.sources.length === 0) {
+        throw new BridgeRuntimeError({
+            bridge: descriptor.name,
+            op: "test",
+            field: "import",
+            expected: "descriptor with at least one import source",
+            got: "missing or empty",
+            hint: "round-trip needs an import block to start from. Add `import.sources:` to the descriptor.",
+        });
+    }
+    if (!descriptor.export || descriptor.export.targets.length === 0) {
+        throw new BridgeRuntimeError({
+            bridge: descriptor.name,
+            op: "test",
+            field: "export",
+            expected: "descriptor with at least one export target",
+            got: "missing or empty",
+            hint: "round-trip needs an export block to round-trip through. Add `export.targets:` to the descriptor.",
+        });
+    }
+    const importSource = descriptor.import.sources[0];
+    const exportTarget = descriptor.export.targets[0];
+    const resolvedFixture = resolvePath(cwd, opts.fixturePath ?? importSource.path);
+    const tmpDir = await fsp.mkdtemp(join(tmpdir(), `flair-bridge-test-${descriptor.name}-`));
+    const tmpPath = join(tmpDir, `roundtrip.${suffixForFormat(exportTarget.format)}`);
+    // Pass 1: fixture → BridgeMemory[]
+    const pass1 = [];
+    for await (const { record } of parseRecords(descriptor.name, resolvedFixture, importSource.format)) {
+        const mapped = applyMap(importSource.map, record);
+        pass1.push(mapped);
+    }
+    // Filter pass1 by the export target's when: (records filtered out wouldn't make it to the target).
+    const expected = [];
+    for (const m of pass1) {
+        if (!exportTarget.when || exportTarget.when.trim() === "") {
+            expected.push(m);
+            continue;
+        }
+        const result = evaluatePredicate(exportTarget.when, m);
+        if (result === "match" || result === "unparsable")
+            expected.push(m);
+    }
+    // Export phase: apply export.map, write to tmp
+    const shaped = [];
+    for (const m of expected) {
+        const out = applyMap(exportTarget.map, m);
+        if (Object.keys(out).length === 0)
+            continue;
+        shaped.push(out);
+    }
+    await writeRecords(descriptor.name, tmpPath, exportTarget.format, shaped);
+    // Pass 2: re-import the tmp using import.sources[0]'s map + format
+    // (round-trip requires the bridge's own import map applied to what export wrote).
+    const pass2 = [];
+    for await (const { record } of parseRecords(descriptor.name, tmpPath, importSource.format)) {
+        const mapped = applyMap(importSource.map, record);
+        pass2.push(mapped);
+    }
+    // Match pass1[expected] with pass2 by key (foreignId if present, else content)
+    // and diff the stable fields.
+    const keyOf = (m) => m.foreignId ?? (m.content ? `content:${m.content}` : "");
+    const pass2ByKey = new Map();
+    for (const m of pass2)
+        pass2ByKey.set(keyOf(m), m);
+    const mismatches = [];
+    const missingInPass2 = [];
+    for (let i = 0; i < expected.length; i++) {
+        const a = expected[i];
+        const key = keyOf(a);
+        const b = pass2ByKey.get(key);
+        if (!b) {
+            missingInPass2.push({ ordinal: i + 1, key });
+            continue;
+        }
+        for (const field of ROUND_TRIP_STABLE_FIELDS) {
+            if (!deepEqualField(a[field], b[field])) {
+                mismatches.push({ ordinal: i + 1, key, field, expected: a[field], got: b[field] });
+            }
+        }
+        // Matched this pass2 entry; remove so leftover tracking works
+        pass2ByKey.delete(key);
+    }
+    const unexpectedInPass2 = Array.from(pass2ByKey.keys()).map((key) => ({ key }));
+    const passed = mismatches.length === 0 && missingInPass2.length === 0 && unexpectedInPass2.length === 0;
+    return {
+        passed,
+        expectedCount: expected.length,
+        actualCount: pass2.length,
+        mismatches,
+        missingInPass2,
+        unexpectedInPass2,
+        tmpExportPath: tmpPath,
+    };
+}
+function deepEqualField(a, b) {
+    // tags is the only array-valued stable field today; deep-equal shallowly
+    // (order matters per our mapping; if a bridge re-orders tags, that's a
+    // round-trip regression worth catching).
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (a[i] !== b[i])
+                return false;
+        return true;
+    }
+    // string / number / boolean / undefined: strict equality
+    return a === b;
+}
+function suffixForFormat(format) {
+    switch (format) {
+        case "jsonl": return "jsonl";
+        case "json": return "json";
+        case "yaml": return "yaml";
+        case "markdown-frontmatter": return "md";
+        default: return "out";
+    }
+}
+function resolvePath(cwd, p) {
+    return isAbsolute(p) ? p : join(cwd, p);
+}
+// Keep randomUUID imported; future slice may use it for named tmp files.
+void randomUUID;

package/dist/cli.js

@@ -324,6 +324,51 @@ async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adm
         throw new Error(`Operations API insert failed (${res.status}): ${text}`);
     }
 }
+// ─── Upgrade presence probes ──────────────────────────────────────────────────
+//
+// `flair upgrade` previously called `npm list -g <pkg>` to detect the installed
+// version. That assumed the default npm global prefix and failed (silently,
+// reporting "not installed") for mise / fnm / nvm / volta users whose prefix
+// lives elsewhere — including for the running flair binary itself, which is
+// clearly installed somewhere. These probes locate the package regardless of
+// install path.
+export function probeBinVersion(execFileSync, bin) {
+    // Run the binary's --version via argv (no shell). PATH resolution still
+    // happens (so we find the binary wherever npm/mise/fnm installed it),
+    // but there's no shell-string to inject into. CodeQL-safe and simpler.
+    try {
+        const out = execFileSync(bin, ["--version"], {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!out)
+            return null;
+        // Accept either "0.6.0" on its own or a line containing a semver.
+        const m = out.match(/\b(\d+\.\d+\.\d+(?:[\d.a-z.-]*)?)\b/);
+        return m ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function probeLibVersion(pkgName) {
+    // Resolve the package's package.json from the running flair's module graph.
+    // If the lib is installed anywhere Node can see (including bundled as a
+    // dep of flair itself, sibling global install, or linked workspace), this
+    // finds it. If it's truly missing, require.resolve throws → null.
+    try {
+        const { createRequire } = require("node:module");
+        const req = createRequire(import.meta.url);
+        const pkgJsonPath = req.resolve(`${pkgName}/package.json`);
+        const { readFileSync } = require("node:fs");
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function templateSoul(choice) {
     const templates = {
         "1": [
@@ -2363,52 +2408,80 @@ program
     .option("--check", "Only check for updates, don't install")
     .option("--restart", "Restart Flair after upgrade")
     .action(async (opts) => {
-    const { execSync } = await import("node:child_process");
+    const { execSync, execFileSync } = await import("node:child_process");
     const checkOnly = opts.check ?? false;
     console.log("Checking for updates...\n");
+    // Per-package install probes. `npm list -g` assumed the default global
+    // prefix and silently mis-reported "not installed" for anyone using
+    // mise / fnm / nvm / volta / non-default-prefix npm — including the
+    // running flair binary itself, which was obviously installed. Each
+    // entry now has a locator that works regardless of install path:
+    //
+    //   - For packages with a bin: shell out to the bin with --version
+    //     (same PATH lookup that got them invokable in the first place).
+    //   - For library packages: require.resolve the package.json from the
+    //     running flair's module graph (works whether it's a sibling
+    //     global install or a bundled dep).
     const packages = [
-        "@tpsdev-ai/flair",
-        "@tpsdev-ai/flair-client",
-        "@tpsdev-ai/flair-mcp",
+        {
+            name: "@tpsdev-ai/flair",
+            probe: () => probeBinVersion(execFileSync, "flair"),
+        },
+        {
+            name: "@tpsdev-ai/flair-client",
+            probe: () => probeLibVersion("@tpsdev-ai/flair-client"),
+        },
+        {
+            name: "@tpsdev-ai/flair-mcp",
+            probe: () => probeBinVersion(execFileSync, "flair-mcp"),
+        },
     ];
-    const upgrades = [];
-    for (const pkg of packages) {
+    const findings = [];
+    for (const { name, probe } of packages) {
         try {
-            const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, { signal: AbortSignal.timeout(5000) });
+            const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(5000) });
             if (!res.ok)
                 continue;
             const data = await res.json();
             const latest = data.version ?? "unknown";
-            let installed = "not installed";
-            try {
-                const out = execSync(`npm list -g ${pkg} --depth=0 2>/dev/null || true`, { encoding: "utf-8" }).trim();
-                const match = out.match(/@(\d+\.\d+[\d.a-z-]*)/);
-                installed = match ? match[1] : "not installed";
-            }
-            catch { /* best effort */ }
-            const upToDate = installed === latest;
-            const icon = upToDate ? "✅" : "⬆️";
-            console.log(`  ${icon} ${pkg}: ${installed} → ${latest}${upToDate ? " (current)" : ""}`);
-            if (!upToDate && installed !== "not installed") {
-                upgrades.push({ pkg, installed, latest });
-            }
+            const installed = probe();
+            const status = installed === null ? "missing" : installed === latest ? "current" : "outdated";
+            findings.push({ name, installed, latest, status });
+            const icon = status === "current" ? "✅" : status === "outdated" ? "⬆️" : "❔";
+            const installedLabel = installed ?? "not detected";
+            const suffix = status === "current" ? " (current)" : status === "missing" ? " (run: npm install -g)" : "";
+            console.log(`  ${icon} ${name}: ${installedLabel} → ${latest}${suffix}`);
         }
         catch { /* skip unavailable packages */ }
     }
-    if (upgrades.length === 0) {
+    const outdated = findings.filter((f) => f.status === "outdated");
+    const missing = findings.filter((f) => f.status === "missing");
+    const upgrades = outdated.map(({ name, installed, latest }) => ({ pkg: name, installed: installed ?? "unknown", latest }));
+    if (outdated.length === 0 && missing.length === 0) {
         console.log("\n✅ Everything is up to date.");
         return;
     }
+    if (missing.length > 0 && outdated.length === 0) {
+        console.log(`\n❔ ${missing.length} package${missing.length > 1 ? "s" : ""} not detected — all detected packages are up to date.`);
+        console.log(`   Install missing: npm install -g ${missing.map((f) => f.name).join(" ")}`);
+        return;
+    }
     if (checkOnly) {
-        console.log(`\n${upgrades.length} update${upgrades.length > 1 ? "s" : ""} available. Run: flair upgrade`);
+        console.log(`\n${outdated.length} update${outdated.length > 1 ? "s" : ""} available. Run: flair upgrade`);
+        if (missing.length > 0) {
+            console.log(`${missing.length} package${missing.length > 1 ? "s" : ""} not detected${missing.length > 0 ? ": " + missing.map((f) => f.name).join(", ") : ""}.`);
+        }
         return;
     }
-    // Perform upgrade
+    // Perform upgrade. `latest` comes from the npm registry's HTTP
+    // response, so CodeQL (correctly) treats it as untrusted input.
+    // Use execFileSync with argv — the spec `<name>@<version>` becomes a
+    // single argument to npm, no shell to inject into.
     console.log(`\nUpgrading ${upgrades.length} package${upgrades.length > 1 ? "s" : ""}...\n`);
     for (const { pkg, latest } of upgrades) {
         try {
             console.log(`  Installing ${pkg}@${latest}...`);
-            execSync(`npm install -g ${pkg}@${latest}`, { stdio: "pipe" });
+            execFileSync("npm", ["install", "-g", `${pkg}@${latest}`], { stdio: "pipe" });
             console.log(`  ✅ ${pkg}@${latest} installed`);
         }
         catch (err) {
@@ -3679,15 +3752,78 @@ bridge
         process.exit(1);
     }
 });
-// `test` still stubbed — round-trip harness lands in slice 3b.
 bridge
-    .command("test <name> [args...]")
-    .description("test a bridge — not yet implemented (slice 3b of FLAIR-BRIDGES)")
-    .allowUnknownOption()
-    .action(() => {
-    console.error(`\`flair bridge test\` is not yet implemented — landing in slice 3b of FLAIR-BRIDGES.`);
-    console.error(`Slice 3a ships export (Shape A YAML); the round-trip test harness pairs with it.`);
-    process.exit(2);
+    .command("test <name>")
+    .description("Round-trip a bridge through its fixture: import → export → re-import → diff. Pass iff the stable fields (content/subject/tags/durability) match.")
+    .option("--fixture <path>", "Override the import source path (defaults to descriptor's import.sources[0].path)")
+    .option("--cwd <dir>", "Filesystem root the descriptor's relative paths resolve against (default: cwd)")
+    .option("--json", "Emit the full RoundTripResult as JSON on stdout")
+    .action(async (name, opts) => {
+    const cwd = opts.cwd ?? process.cwd();
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { runRoundTrip } = await import("./bridges/runtime/roundtrip.js");
+    const { BridgeRuntimeError } = await import("./bridges/types.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    const target = found.find((b) => b.name === name);
+    if (!target) {
+        console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
+        process.exit(1);
+    }
+    let descriptor;
+    try {
+        descriptor = await loadDescriptor(target);
+    }
+    catch (err) {
+        printBridgeError(err);
+        process.exit(1);
+    }
+    try {
+        const result = await runRoundTrip({ descriptor, cwd, fixturePath: opts.fixture });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(result.passed ? 0 : 1);
+        }
+        if (result.passed) {
+            console.log(`✅ ${descriptor.name} round-trip passed (${result.expectedCount} record${result.expectedCount === 1 ? "" : "s"}).`);
+            process.exit(0);
+        }
+        console.log(`❌ ${descriptor.name} round-trip failed.`);
+        console.log(`   expected ${result.expectedCount} records, got ${result.actualCount} back.`);
+        if (result.missingInPass2.length > 0) {
+            console.log(`   missing from re-import (${result.missingInPass2.length}):`);
+            for (const m of result.missingInPass2.slice(0, 5))
+                console.log(`     - ${m.key}`);
+            if (result.missingInPass2.length > 5)
+                console.log(`     ... ${result.missingInPass2.length - 5} more`);
+        }
+        if (result.unexpectedInPass2.length > 0) {
+            console.log(`   unexpected extras in re-import (${result.unexpectedInPass2.length}):`);
+            for (const m of result.unexpectedInPass2.slice(0, 5))
+                console.log(`     - ${m.key}`);
+            if (result.unexpectedInPass2.length > 5)
+                console.log(`     ... ${result.unexpectedInPass2.length - 5} more`);
+        }
+        if (result.mismatches.length > 0) {
+            console.log(`   field mismatches (${result.mismatches.length}):`);
+            for (const m of result.mismatches.slice(0, 10)) {
+                console.log(`     - record ${m.ordinal} (${m.key}) field ${m.field}: expected ${JSON.stringify(m.expected)}, got ${JSON.stringify(m.got)}`);
+            }
+            if (result.mismatches.length > 10)
+                console.log(`     ... ${result.mismatches.length - 10} more`);
+        }
+        console.log(`\n   Intermediate export at: ${result.tmpExportPath}`);
+        process.exit(1);
+    }
+    catch (err) {
+        if (err instanceof BridgeRuntimeError) {
+            printBridgeError(err);
+            process.exit(1);
+        }
+        console.error(`Bridge test failed: ${err?.message ?? err}`);
+        process.exit(1);
+    }
 });
 function printBridgeError(err) {
     // Pretty-print BridgeRuntimeError as the structured shape from §10 of the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",