@tpsdev-ai/flair 0.6.1 → 0.7.0

package/README.md

@@ -162,17 +162,17 @@ openclaw plugins install @tpsdev-ai/openclaw-flair
 
 The plugin auto-detects your agent identity, provides `memory_store`/`memory_recall`/`memory_get` tools, and injects relevant memories at session start. See the [plugin README](plugins/openclaw-flair/README.md) for details.
 
-### Claude Code / Codex / Cursor (MCP)
+### Claude Code / Gemini CLI / OpenAI Codex CLI / Cursor (MCP)
 
-Install the MCP server for native tool integration:
+One MCP server, many CLIs. Install the MCP server for native tool integration in any MCP-capable client:
 
 ```json
-// .mcp.json in your project root
+// .mcp.json in your project root (Claude Code / Cursor format)
 {
   "mcpServers": {
     "flair": {
       "command": "npx",
-      "args": ["@tpsdev-ai/flair-mcp"],
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
       "env": { "FLAIR_AGENT_ID": "mybot" }
     }
   }
@@ -183,7 +183,9 @@ Add to your `CLAUDE.md`:
 
     At the start of every session, run mcp__flair__bootstrap before responding.
 
-Claude Code gets native tools: `memory_store`, `memory_search`, `bootstrap`, `soul_set`, and more. See the [MCP README](packages/flair-mcp/README.md) and [Claude Code guide](docs/claude-code.md).
+Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The MCP server exposes `memory_store`, `memory_search`, `memory_get`, `memory_delete`, `bootstrap`, `soul_set`, `soul_get`.
+
+For per-CLI config snippets (Gemini CLI's `~/.gemini/settings.json`, Codex CLI's `~/.codex/config.toml`, etc.), see **[docs/mcp-clients.md](docs/mcp-clients.md)**. For a deeper Claude Code walk-through with `CLAUDE.md` patterns, see [docs/claude-code.md](docs/claude-code.md).
 
 ### JavaScript / TypeScript (Client Library)
 

package/dist/bridges/runtime/allow-list.js

@@ -0,0 +1,198 @@
+/**
+ * Trust allow-list for npm code-plugin bridges.
+ *
+ * A Shape B bridge is arbitrary JavaScript fetched from npm. The spec §7
+ * requires explicit operator opt-in on first use: `flair bridge allow <name>`
+ * records the approval; subsequent invocations see the bridge on the
+ * allow-list and skip the prompt. `flair bridge revoke <name>` removes it.
+ *
+ * Approvals are pinned to a concrete package location and its package.json
+ * content digest. A name-only approval is not enough: a malicious package
+ * squatting on an allowed short-name in a different `node_modules` tree
+ * (e.g. the user approved `mem0` in ProjectA, then cd'd into ProjectB which
+ * ships a planted `node_modules/flair-bridge-mem0`) would otherwise load
+ * under the existing trust record. Each entry therefore captures:
+ *
+ *   - packageDir:        canonical (realpath) directory where the approved
+ *                        package lives on disk at allow-time.
+ *   - packageJsonSha256: hex sha256 of the package's package.json content.
+ *   - version:           the package's self-reported version (display only;
+ *                        the sha is what enforces identity).
+ *
+ * At load-time, `verifyAllow(discovered)` re-checks all three. A change in
+ * any triggers a BridgeRuntimeError pointing the operator back at
+ * `flair bridge allow` — either the move is intentional (re-approve) or
+ * it is a squat (refuse).
+ *
+ * Design notes:
+ *  - YAML (Shape A) + built-in bridges skip this gate entirely. They don't
+ *    execute arbitrary JS.
+ *  - The store is a simple JSON file at ~/.flair/bridges-allowed.json.
+ *    No separate DB, no Harper dependency — the trust decision should
+ *    still work when Flair's own service is down.
+ *  - Migration: older entries from 0.6.0/0.6.1 carry only {name, allowedAt}.
+ *    `verifyAllow` treats those as invalid and forces re-approval on next
+ *    load. Acceptable cost — no known external consumers pre-1.0.
+ */
+import { promises as fsp } from "node:fs";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+function resolvePath(opts) {
+    return opts?.path ?? join(homedir(), ".flair", "bridges-allowed.json");
+}
+function hasEntryFields(e) {
+    return (typeof e?.name === "string" &&
+        typeof e?.allowedAt === "string" &&
+        typeof e?.packageDir === "string" &&
+        typeof e?.packageJsonSha256 === "string");
+}
+async function read(path) {
+    if (!existsSync(path))
+        return { allowed: [] };
+    try {
+        const raw = await fsp.readFile(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.allowed))
+            return { allowed: [] };
+        // Keep structurally valid entries only. Legacy name-only rows are
+        // dropped here so `verifyAllow` reports not-allowed (forcing re-approve).
+        return {
+            allowed: parsed.allowed.filter(hasEntryFields).map((e) => ({
+                name: e.name,
+                allowedAt: e.allowedAt,
+                packageDir: e.packageDir,
+                packageJsonSha256: e.packageJsonSha256,
+                ...(typeof e.version === "string" ? { version: e.version } : {}),
+            })),
+        };
+    }
+    catch {
+        return { allowed: [] };
+    }
+}
+async function write(path, data) {
+    await fsp.mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    await fsp.rename(tmp, path);
+}
+/**
+ * Canonicalize a filesystem path. Resolves symlinks so node_modules hoisting
+ * and pnpm-style content-addressed stores still hash-match reliably.
+ */
+async function canonical(path) {
+    try {
+        return await fsp.realpath(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Hash a package's package.json file. The sha changes whenever the package
+ * contents "change enough to matter" — version bumps, name changes, and
+ * realistically most substantive updates touch package.json. It is NOT a
+ * hash of every file in the package; that would be slower and more fragile
+ * without closing the meaningful attack paths (since a squatter needs the
+ * right package.json anyway to survive discovery).
+ */
+export async function digestPackage(packageDir) {
+    const canonicalDir = await canonical(packageDir);
+    const pkgJsonPath = join(canonicalDir, "package.json");
+    const raw = await fsp.readFile(pkgJsonPath, "utf-8");
+    const sha = createHash("sha256").update(raw).digest("hex");
+    let version;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.version === "string")
+            version = parsed.version;
+    }
+    catch {
+        // A malformed package.json is itself a refusal signal — but leave that
+        // to the import path; here we just decline to record a version.
+    }
+    return { canonicalDir, sha256: sha, version };
+}
+/**
+ * Check if a name appears in the allow-list. Useful for UI listings; NOT a
+ * trust decision — use `verifyAllow` for load-time security checks.
+ */
+export async function isAllowed(name, opts) {
+    const data = await read(resolvePath(opts));
+    return data.allowed.some((e) => e.name === name);
+}
+/**
+ * Load-time trust check. Verifies the discovered package still matches the
+ * approval record by canonical path AND package.json sha. Anything else is
+ * a refusal — the operator must re-run `flair bridge allow <name>`.
+ */
+export async function verifyAllow(discovered, opts) {
+    const data = await read(resolvePath(opts));
+    const entry = data.allowed.find((e) => e.name === discovered.name);
+    if (!entry)
+        return { ok: false, reason: "not-allowed" };
+    // Guard: if we ever loaded a partial record, refuse. Belt-and-braces;
+    // read() already filters these, but if someone hand-edits the file we
+    // don't want to silently bypass the check.
+    if (!entry.packageDir || !entry.packageJsonSha256) {
+        return { ok: false, reason: "entry-incomplete", entry };
+    }
+    let observed;
+    try {
+        observed = await digestPackage(discovered.path);
+    }
+    catch {
+        return { ok: false, reason: "package-missing", entry };
+    }
+    if (observed.canonicalDir !== entry.packageDir) {
+        return { ok: false, reason: "path-mismatch", entry, observedPath: observed.canonicalDir };
+    }
+    if (observed.sha256 !== entry.packageJsonSha256) {
+        return { ok: false, reason: "digest-mismatch", entry, observedDigest: observed.sha256 };
+    }
+    return { ok: true, entry };
+}
+/**
+ * Approve a package for code-plugin execution. `packageDir` must be the
+ * directory holding the package.json — typically discovered via
+ * `flair bridge list` and passed through by the CLI layer.
+ */
+export async function allow(name, packageDir, opts) {
+    const listPath = resolvePath(opts);
+    const data = await read(listPath);
+    const { canonicalDir, sha256, version } = await digestPackage(packageDir);
+    const now = new Date().toISOString();
+    const existing = data.allowed.find((e) => e.name === name);
+    if (existing && existing.packageDir === canonicalDir && existing.packageJsonSha256 === sha256) {
+        return { alreadyAllowed: true, updated: false, entry: existing };
+    }
+    const entry = {
+        name,
+        allowedAt: now,
+        packageDir: canonicalDir,
+        packageJsonSha256: sha256,
+        ...(version ? { version } : {}),
+    };
+    data.allowed = data.allowed.filter((e) => e.name !== name);
+    data.allowed.push(entry);
+    data.allowed.sort((a, b) => a.name.localeCompare(b.name));
+    await write(listPath, data);
+    return { alreadyAllowed: false, updated: !!existing, entry };
+}
+export async function revoke(name, opts) {
+    const path = resolvePath(opts);
+    const data = await read(path);
+    const before = data.allowed.length;
+    data.allowed = data.allowed.filter((e) => e.name !== name);
+    if (data.allowed.length === before) {
+        return { wasAllowed: false };
+    }
+    await write(path, data);
+    return { wasAllowed: true };
+}
+export async function list(opts) {
+    const data = await read(resolvePath(opts));
+    return data.allowed;
+}

package/dist/bridges/runtime/import-runner.js

@@ -26,7 +26,11 @@ export async function runImport(opts) {
     let total = 0;
     let imported = 0;
     let skipped = 0;
-    for await (const m of importFromYaml(opts.descriptor, { cwd: opts.cwd, ctx: opts.ctx })) {
+    const iterable = opts.source
+        ?? (opts.descriptor
+            ? importFromYaml(opts.descriptor, { cwd: opts.cwd, ctx: opts.ctx })
+            : (() => { throw new BridgeRuntimeError({ bridge: opts.bridgeName, op: "import", field: "(source)", expected: "descriptor or source", got: "neither", hint: "runImport requires exactly one of opts.descriptor (YAML) or opts.source (AsyncIterable)" }); })());
+    for await (const m of iterable) {
         total++;
         const resolvedAgent = m.agentId ?? opts.agentId;
         if (!resolvedAgent) {
@@ -35,7 +39,7 @@ export async function runImport(opts) {
             // the operator should know whether this is a descriptor bug or a
             // missing flag.
             throw new BridgeRuntimeError({
-                bridge: opts.descriptor.name,
+                bridge: opts.bridgeName,
                 op: "import",
                 field: "agentId",
                 expected: "set on record OR provided via --agent",
@@ -86,7 +90,7 @@ export async function runImport(opts) {
         catch (err) {
             // Wrap PUT errors so they read consistently with other BridgeRuntimeErrors.
             throw new BridgeRuntimeError({
-                bridge: opts.descriptor.name,
+                bridge: opts.bridgeName,
                 op: "import",
                 record: total,
                 field: "(write)",

package/dist/bridges/runtime/load-bridge.js

@@ -0,0 +1,126 @@
+/**
+ * Unified loader for all bridge sources (replaces load-descriptor.ts).
+ *
+ * Returns a `LoadedBridge` discriminated union. Runners dispatch on
+ * `.kind`:
+ *   - "yaml": use the existing YAML runtime (applyMap, parseRecords, etc.)
+ *   - "code": call the plugin's bridge.import() / bridge.export() directly
+ *
+ * For code-plugin sources (npm packages), the allow-list gate runs first:
+ * if not allowed, throw a BridgeRuntimeError pointing the operator at
+ * `flair bridge allow <name>`.
+ */
+import { BridgeRuntimeError } from "../types.js";
+import { loadYamlDescriptor } from "./yaml-loader.js";
+import { BUILTIN_BY_NAME } from "../builtins/index.js";
+import { loadCodePlugin } from "./load-plugin.js";
+import { verifyAllow } from "./allow-list.js";
+export async function loadBridge(discovered, opts = {}) {
+    switch (discovered.source) {
+        case "builtin": {
+            const builtin = BUILTIN_BY_NAME.get(discovered.name);
+            if (!builtin) {
+                throw new BridgeRuntimeError({
+                    bridge: discovered.name,
+                    op: "import",
+                    field: "(builtin)",
+                    expected: "registered built-in name",
+                    got: discovered.name,
+                    hint: `built-in "${discovered.name}" not in the registry — likely code drift between discover.ts and builtins/index.ts`,
+                });
+            }
+            return { kind: "yaml", descriptor: builtin.descriptor, source: discovered };
+        }
+        case "project-yaml":
+        case "user-yaml": {
+            const descriptor = await loadYamlDescriptor(discovered.path);
+            return { kind: "yaml", descriptor, source: discovered };
+        }
+        case "npm-package": {
+            if (!opts.skipAllowCheck) {
+                const verdict = await verifyAllow(discovered, { path: opts.allowListPath });
+                if (!verdict.ok) {
+                    throw new BridgeRuntimeError({
+                        bridge: discovered.name,
+                        op: "import",
+                        path: discovered.path,
+                        field: "(trust)",
+                        expected: verdict.reason === "not-allowed" ? "allow-listed code plugin" : "approved package at recorded location/digest",
+                        got: verdict.reason,
+                        hint: trustHint(discovered.name, verdict),
+                        context: trustContext(discovered, verdict),
+                    });
+                }
+            }
+            const plugin = await loadCodePlugin(discovered, { importer: opts.importer });
+            return { kind: "code", plugin, source: discovered };
+        }
+    }
+}
+function trustContext(discovered, verdict) {
+    switch (verdict.reason) {
+        case "not-allowed":
+            return { name: discovered.name };
+        case "path-mismatch":
+            return {
+                name: discovered.name,
+                approvedPath: verdict.entry.packageDir,
+                observedPath: verdict.observedPath,
+                approvedVersion: verdict.entry.version ?? "(unknown)",
+                approvedAt: verdict.entry.allowedAt,
+            };
+        case "digest-mismatch":
+            return {
+                name: discovered.name,
+                packagePath: verdict.entry.packageDir,
+                approvedVersion: verdict.entry.version ?? "(unknown)",
+                approvedDigest: verdict.entry.packageJsonSha256,
+                observedDigest: verdict.observedDigest,
+                approvedAt: verdict.entry.allowedAt,
+            };
+        case "entry-incomplete":
+            return { name: discovered.name };
+        case "package-missing":
+            return {
+                name: discovered.name,
+                approvedPath: verdict.entry?.packageDir ?? "(unknown)",
+                discoveredPath: discovered.path,
+            };
+    }
+}
+function trustHint(name, verdict) {
+    const reapprove = `flair bridge allow ${name}`;
+    switch (verdict.reason) {
+        case "not-allowed":
+            return `npm code plugins run arbitrary JavaScript. First-use approval required. Run: ${reapprove}`;
+        case "path-mismatch":
+            return `approved package lives at ${verdict.entry.packageDir}, but a different package with the same name was discovered at ${verdict.observedPath}. This is how local squatting attacks present. If the new location is intentional, re-run: ${reapprove}`;
+        case "digest-mismatch":
+            return `package.json contents changed since approval (recorded sha ${verdict.entry.packageJsonSha256.slice(0, 12)}…, observed ${verdict.observedDigest.slice(0, 12)}…). Re-run if the update is intentional: ${reapprove}`;
+        case "entry-incomplete":
+            return `allow-list entry for "${name}" is missing a location/digest (likely from a pre-fix Flair version). Re-run: ${reapprove}`;
+        case "package-missing":
+            return `package at ${verdict.entry?.packageDir ?? "(unknown)"} could not be read; allow-list verification cannot proceed`;
+    }
+}
+/**
+ * Kept as a shim for code paths that still call the old name. Remove once
+ * all call sites move to loadBridge directly.
+ *
+ * Returns the YAML descriptor when the source produces one; throws for
+ * code plugins (they don't have a YamlBridgeDescriptor representation).
+ */
+export async function loadDescriptor(discovered) {
+    const loaded = await loadBridge(discovered);
+    if (loaded.kind === "yaml")
+        return loaded.descriptor;
+    throw new BridgeRuntimeError({
+        bridge: discovered.name,
+        op: "import",
+        path: discovered.path,
+        field: "(kind)",
+        expected: "yaml descriptor",
+        got: "code plugin",
+        hint: "this code path expected a YAML descriptor; the bridge is a code plugin — caller should dispatch on loadBridge().kind instead",
+    });
+}

package/dist/bridges/runtime/load-plugin.js

@@ -0,0 +1,127 @@
+/**
+ * Dynamic loader for Shape B code-plugin bridges.
+ *
+ * Given a discovered `npm-package` source, dynamic-import the package,
+ * validate that it exports a `MemoryBridge`, and return the loaded module.
+ * The import is done via `createRequire` relative to the package root so
+ * scoped packages and deep nested deps resolve correctly.
+ *
+ * Validation is deliberately minimal: `name`, `version`, `kind`, and at
+ * least one of `import` / `export` must be present and look right. The
+ * spec §6 contract is "duck-type at runtime, strict error messages."
+ */
+import { pathToFileURL } from "node:url";
+import { BridgeRuntimeError } from "../types.js";
+const DEFAULT_IMPORTER = (spec) => import(spec);
+export async function loadCodePlugin(discovered, opts = {}) {
+    if (discovered.source !== "npm-package") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            field: "source",
+            expected: "npm-package",
+            got: discovered.source,
+            hint: "loadCodePlugin only handles Shape B (npm code plugin) bridges; YAML descriptors go through the YAML loader",
+        });
+    }
+    const importer = opts.importer ?? DEFAULT_IMPORTER;
+    // Package root path — the entry point is resolved by Node's package.json
+    // "main"/"exports" fields. Use a file:// URL so Node resolves it as a
+    // filesystem path rather than a bare specifier.
+    const spec = pathToFileURL(discovered.path + "/").href;
+    let mod;
+    try {
+        mod = await importer(spec);
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "(import)",
+            expected: "importable npm package",
+            got: err?.code ?? "import error",
+            hint: `could not dynamic-import ${spec}: ${err?.message ?? err}`,
+        });
+    }
+    const candidate = pickBridgeExport(mod);
+    if (!candidate) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "exports",
+            expected: "named `bridge` export or default export implementing MemoryBridge",
+            got: typeof mod === "object" && mod !== null ? `exports=${Object.keys(mod).join(",") || "(empty)"}` : typeof mod,
+            hint: `flair-bridge-<name> packages must export \`bridge\` (or default-export) a MemoryBridge. See specs/FLAIR-BRIDGES.md §6`,
+        });
+    }
+    // Validate the shape. Keep this minimal — we trust the plugin author
+    // to build a working MemoryBridge; we just need enough to route calls.
+    validateBridge(discovered, candidate);
+    return candidate;
+}
+function pickBridgeExport(mod) {
+    if (!mod || typeof mod !== "object")
+        return null;
+    const m = mod;
+    if (isBridgeLike(m.bridge))
+        return m.bridge;
+    if (isBridgeLike(m.default))
+        return m.default;
+    if (isBridgeLike(m))
+        return m;
+    return null;
+}
+function isBridgeLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const o = x;
+    return typeof o.name === "string" && (typeof o.import === "function" || typeof o.export === "function");
+}
+function validateBridge(discovered, b) {
+    if (typeof b.name !== "string" || !b.name) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "name",
+            expected: "non-empty string",
+            got: JSON.stringify(b.name),
+            hint: "MemoryBridge.name must be a non-empty string matching the npm package's flair-bridge-<name>",
+        });
+    }
+    if (b.name !== discovered.name) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "name",
+            expected: `"${discovered.name}" (from package name flair-bridge-${discovered.name})`,
+            got: `"${b.name}"`,
+            hint: "MemoryBridge.name must match the npm package's public name suffix — mismatch would surprise discovery and allow-list lookups",
+        });
+    }
+    if (b.kind !== "file" && b.kind !== "api") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "kind",
+            expected: `"file" | "api"`,
+            got: JSON.stringify(b.kind),
+            hint: "MemoryBridge.kind must be 'file' or 'api'",
+        });
+    }
+    if (typeof b.import !== "function" && typeof b.export !== "function") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "(methods)",
+            expected: "at least one of `import` or `export`",
+            got: "neither",
+            hint: "MemoryBridge needs at least one of import/export implemented. See spec §6",
+        });
+    }
+}