@tpsdev-ai/flair 0.5.6 → 0.6.1

package/README.md

@@ -94,6 +94,9 @@ Context-signal-aware preloading. Bootstrap reads active project context, recent
 ### Auto Entity Detection
 Passive extraction of entities from memory content on write. Entities are indexed automatically — no tagging required. Feeds the relationship graph without agent intervention.
 
+### Memory Bridges
+Pluggable import/export to foreign memory systems. Every agent-memory format (agentic-stack, Mem0, Letta, Anthropic memory, the next viral one) shouldn't need its own Flair PR. Bridges give you one contract with two shapes — a YAML descriptor for file-format targets or a code plugin for API targets — and a scaffold/test loop that lets an agent ship a working adapter in one pass. See [docs/bridges.md](docs/bridges.md).
+
 ## Quick Start
 
 ### Prerequisites

package/dist/bridges/builtins/agentic-stack.js

@@ -0,0 +1,58 @@
+/**
+ * Built-in bridge: agentic-stack
+ *
+ * Imports lessons from agentic-stack's `.agent/memory/semantic/lessons.jsonl`
+ * (and similar conventional paths) into Flair memories tagged
+ * `source: "agentic-stack/lessons"`.
+ *
+ * The descriptor is an in-tree typed object rather than a YAML string —
+ * built-ins ship inside the @tpsdev-ai/flair package and don't need the
+ * YAML round-trip a user-authored descriptor goes through. The loader
+ * for user descriptors (`yaml-loader.ts`) and this object both produce
+ * a `YamlBridgeDescriptor`, so the runtime executor doesn't care which
+ * source they came from.
+ */
+export const agenticStackDescriptor = {
+    name: "agentic-stack",
+    version: 1,
+    kind: "file",
+    description: "Import agentic-stack `.agent/memory/semantic/lessons.jsonl` into Flair persistent memories",
+    detect: {
+        anyExists: [
+            ".agent/AGENTS.md",
+            ".agent/memory/semantic/lessons.jsonl",
+        ],
+    },
+    import: {
+        sources: [{
+                path: ".agent/memory/semantic/lessons.jsonl",
+                format: "jsonl",
+                map: {
+                    content: "$.claim",
+                    subject: "$.topic",
+                    tags: "$.tags[*]",
+                    foreignId: "$.id",
+                    durability: "persistent",
+                    source: "agentic-stack/lessons",
+                },
+            }],
+    },
+    export: {
+        targets: [{
+                path: ".agent/memory/semantic/lessons.jsonl",
+                format: "jsonl",
+                // Only export memories durable enough to be worth round-tripping back
+                // into agentic-stack. ephemeral / standard scratch memory stays in Flair.
+                when: "durability in ['persistent', 'permanent']",
+                map: {
+                    // Preserve the foreign id when round-tripping; if the memory was
+                    // Flair-native it'll just be missing from the output (and import-side
+                    // generates a new id on first import anyway).
+                    id: "$.foreignId",
+                    claim: "$.content",
+                    topic: "$.subject",
+                    tags: "$.tags[*]",
+                },
+            }],
+    },
+};

package/dist/bridges/builtins/index.js

@@ -0,0 +1,36 @@
+/**
+ * Built-in bridge registry.
+ *
+ * Each built-in ships as a typed `YamlBridgeDescriptor` (see
+ * `agentic-stack.ts`). The CLI passes this registry to `discover()` so
+ * built-ins surface in `flair bridge list` alongside user-authored
+ * bridges, and to the import/export runtime so it knows how to load
+ * the descriptor for a built-in name.
+ *
+ * To add a new built-in: write `src/bridges/builtins/<name>.ts`
+ * exporting a `YamlBridgeDescriptor`, then register it here.
+ */
+import { agenticStackDescriptor } from "./agentic-stack.js";
+function builtin(d) {
+    return {
+        discovered: {
+            name: d.name,
+            kind: d.kind,
+            source: "builtin",
+            path: `(builtin:${d.name})`,
+            description: d.description,
+            version: d.version,
+        },
+        descriptor: d,
+    };
+}
+/** All bridges shipped inside @tpsdev-ai/flair. Order doesn't matter. */
+export const BUILTINS = [
+    builtin(agenticStackDescriptor),
+];
+/** Map name → descriptor for O(1) runtime lookup. */
+export const BUILTIN_BY_NAME = new Map(BUILTINS.map((b) => [b.discovered.name, b]));
+/** What `discover()` consumes for the `builtins` option. */
+export function builtinDiscoveryRecords() {
+    return BUILTINS.map((b) => b.discovered);
+}

package/dist/bridges/discover.js

@@ -0,0 +1,195 @@
+/**
+ * Bridge discovery — scans the four conventional sources defined in
+ * FLAIR-BRIDGES.md §7:
+ *
+ *   1. Project YAML:   <cwd>/.flair-bridge/*.yaml
+ *   2. User YAML:      ~/.flair/bridges/*.yaml
+ *   3. npm packages:   node_modules/flair-bridge-*  |  node_modules/@*\/flair-bridge-*
+ *   4. Built-ins:      bundled adapters inside @tpsdev-ai/flair
+ *
+ * Discovery is metadata-only — it reads names, versions, and kinds without
+ * executing any code plugin. Runtime execution is slice 2.
+ */
+import { promises as fsp } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, basename } from "node:path";
+async function exists(path) {
+    try {
+        await fsp.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readYamlBridge(path) {
+    try {
+        const raw = await fsp.readFile(path, "utf-8");
+        // Lightweight parse — we only pull the top-level fields we advertise.
+        // Avoids pulling in a YAML dep just for discovery; a real parse happens
+        // later when the bridge runs. Deliberately string-only (no dynamic
+        // RegExp) so ReDoS lint rules stay happy. Top-level means no leading
+        // whitespace on the line — indented values (under import:/export:)
+        // are correctly ignored.
+        const lines = raw.split(/\r?\n/);
+        const get = (field) => {
+            const prefix = `${field}:`;
+            for (const line of lines) {
+                if (!line.startsWith(prefix))
+                    continue;
+                const rest = line.slice(prefix.length);
+                // Accept "name: foo", "name:foo", "name:  foo"
+                const value = rest.trim();
+                // Strip surrounding single or double quotes (yaml-ish)
+                if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                    return value.slice(1, -1);
+                }
+                return value;
+            }
+            return undefined;
+        };
+        const name = get("name");
+        if (!name)
+            return null;
+        const kindStr = get("kind") ?? "file";
+        const kind = kindStr === "api" ? "api" : "file";
+        const versionRaw = get("version");
+        const version = versionRaw ? parseInt(versionRaw, 10) : undefined;
+        const description = get("description");
+        return {
+            name,
+            kind,
+            source: path.includes(join(".flair", "bridges")) ? "user-yaml" : "project-yaml",
+            path,
+            description,
+            version: Number.isFinite(version) ? version : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function scanYamlDir(dir) {
+    if (!(await exists(dir)))
+        return [];
+    let names;
+    try {
+        names = await fsp.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (!/\.ya?ml$/i.test(name))
+            continue;
+        const parsed = await readYamlBridge(join(dir, name));
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+async function readNpmBridge(pkgDir) {
+    const pkgPath = join(pkgDir, "package.json");
+    if (!(await exists(pkgPath)))
+        return null;
+    try {
+        const raw = await fsp.readFile(pkgPath, "utf-8");
+        const json = JSON.parse(raw);
+        // Convention: the bridge's public name is what ends with `flair-bridge-<name>`.
+        // Package name may be `flair-bridge-foo` or `@scope/flair-bridge-foo`.
+        const pkgName = String(json.name ?? "");
+        const match = pkgName.match(/flair-bridge-([^/]+)$/);
+        if (!match)
+            return null;
+        const flairMeta = json.flair ?? {};
+        const kind = flairMeta.kind === "file" ? "file" : "api"; // npm bridges default to api
+        return {
+            name: match[1],
+            kind,
+            source: "npm-package",
+            path: pkgDir,
+            description: json.description,
+            version: typeof flairMeta.version === "number" ? flairMeta.version : 1,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function scanModuleRoot(base) {
+    if (!(await exists(base)))
+        return [];
+    let entries;
+    try {
+        entries = await fsp.readdir(base);
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        const full = join(base, entry);
+        if (entry.startsWith("flair-bridge-")) {
+            const b = await readNpmBridge(full);
+            if (b)
+                results.push(b);
+        }
+        else if (entry.startsWith("@")) {
+            // Scoped dir — enumerate one level deeper
+            let scoped;
+            try {
+                scoped = await fsp.readdir(full);
+            }
+            catch {
+                continue;
+            }
+            for (const s of scoped) {
+                if (s.startsWith("flair-bridge-")) {
+                    const b = await readNpmBridge(join(full, s));
+                    if (b)
+                        results.push(b);
+                }
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Discover all installed bridges across the four conventional sources.
+ * Results are deduped by name; built-ins win, then project, then user,
+ * then npm (shadowing a more-specific adapter with a less-specific one
+ * is never desirable).
+ */
+export async function discover(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const moduleRoots = opts.moduleRoots ?? [
+        join(cwd, "node_modules"),
+        join(home, ".flair", "node_modules"),
+    ];
+    const [projectYaml, userYaml, ...moduleResults] = await Promise.all([
+        scanYamlDir(join(cwd, ".flair-bridge")),
+        scanYamlDir(join(home, ".flair", "bridges")),
+        ...moduleRoots.map((r) => scanModuleRoot(r)),
+    ]);
+    const all = [
+        ...(opts.builtins ?? []),
+        ...projectYaml,
+        ...userYaml,
+        ...moduleResults.flat(),
+    ];
+    // Dedup by name with source precedence (earlier wins since all[] is ordered).
+    const seen = new Map();
+    for (const b of all) {
+        if (!seen.has(b.name))
+            seen.set(b.name, b);
+    }
+    return Array.from(seen.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+// Exported helpers for tests & for the scaffold command, which needs to
+// confirm a bridge name isn't already taken.
+export const __test = { readYamlBridge, readNpmBridge, scanYamlDir, scanModuleRoot };
+// Suppress "unused" warnings in strict builds — dirname/basename kept for future expansion.
+void dirname;
+void basename;

package/dist/bridges/runtime/context.js

@@ -0,0 +1,59 @@
+/**
+ * Minimal BridgeContext implementation for slice 2.
+ *
+ * Slice 2 bridges only exercise the YAML/declarative runtime, which doesn't
+ * hit ctx.fetch or ctx.cache. But the types and the contract must exist so
+ * slice-3 code-plugin bridges can drop in against the same object shape.
+ *
+ * Implementation is intentionally simple here:
+ *   - fetch is a thin passthrough to global fetch (slice 3 adds the token
+ *     bucket + rate-limiting + audit tap)
+ *   - log writes to stderr with structured JSON so the operator can redirect
+ *     and an agent caller can grep
+ *   - cache is in-memory for the invocation (persisted cache lands later)
+ */
+const DEFAULT_EMIT = (ev) => {
+    // One JSON object per line; stderr so stdout stays clean for bridge output
+    process.stderr.write(JSON.stringify(ev) + "\n");
+};
+export function makeContext(opts) {
+    const emit = opts.emit ?? DEFAULT_EMIT;
+    const cache = new Map();
+    const log = (level) => (message, meta) => {
+        emit({
+            bridge: opts.bridge,
+            level,
+            message,
+            meta,
+            timestamp: new Date().toISOString(),
+        });
+    };
+    return {
+        fetch: (input, init) => fetch(input, init),
+        log: {
+            debug: log("debug"),
+            info: log("info"),
+            warn: log("warn"),
+            error: log("error"),
+        },
+        cache: {
+            async get(key) {
+                const entry = cache.get(key);
+                if (!entry)
+                    return null;
+                if (entry.expiresAt !== null && entry.expiresAt < Date.now()) {
+                    cache.delete(key);
+                    return null;
+                }
+                return entry.value;
+            },
+            async set(key, value, ttlSeconds) {
+                const expiresAt = ttlSeconds !== undefined ? Date.now() + ttlSeconds * 1000 : null;
+                cache.set(key, { value, expiresAt });
+            },
+            async del(key) {
+                cache.delete(key);
+            },
+        },
+    };
+}

package/dist/bridges/runtime/execute.js

@@ -0,0 +1,92 @@
+/**
+ * Runtime executor for YAML (Shape A) bridges.
+ *
+ * `importFromYaml` takes a parsed `YamlBridgeDescriptor` plus a root directory
+ * and yields `BridgeMemory` records — one per source record after the
+ * descriptor's `map` has been applied. Callers stream the output into Flair
+ * via the CLI (slice 2b) or the HTTP API directly.
+ *
+ * Failures are always `BridgeRuntimeError` with LLM-readable
+ * `{bridge, op, path, record, field, expected, got, hint}`.
+ */
+import { join, isAbsolute } from "node:path";
+import { BridgeRuntimeError } from "../types.js";
+import { parseRecords } from "./formats.js";
+import { applyMap } from "./mapper.js";
+const FLAIR_RESERVED_FIELDS_SET = new Set([
+    "contentHash",
+    "embedding",
+    "embeddingModel",
+    "retrievalCount",
+    "lastRetrieved",
+    "promotionStatus",
+    "_safetyFlags",
+    "createdBy",
+    "updatedBy",
+    "archivedBy",
+]);
+/**
+ * Drive a YAML bridge's `import` block and yield `BridgeMemory` records.
+ * Runs sources in order; one failure in a source halts the stream (the
+ * spec's "every bridge error is structured" contract says we don't
+ * silently discard partial imports).
+ */
+export async function* importFromYaml(descriptor, opts) {
+    if (!descriptor.import) {
+        throw new BridgeRuntimeError({
+            bridge: descriptor.name,
+            op: "import",
+            field: "import",
+            expected: "object with sources",
+            got: "missing",
+            hint: "descriptor has no `import` block — run `flair bridge export` instead, or add one",
+        });
+    }
+    for (let srcIdx = 0; srcIdx < descriptor.import.sources.length; srcIdx++) {
+        const source = descriptor.import.sources[srcIdx];
+        const resolvedPath = resolvePath(opts.cwd, source.path);
+        opts.ctx?.log.info(`importing source`, {
+            source: source.path,
+            format: source.format,
+            resolved: resolvedPath,
+        });
+        for await (const { record, recordIndex } of parseRecords(descriptor.name, resolvedPath, source.format)) {
+            const mapped = applyMap(source.map, record);
+            // Reject any attempt to set Flair-reserved fields (spec §4).
+            for (const f of Object.keys(mapped)) {
+                if (FLAIR_RESERVED_FIELDS_SET.has(f)) {
+                    throw new BridgeRuntimeError({
+                        bridge: descriptor.name,
+                        op: "import",
+                        path: resolvedPath,
+                        record: recordIndex,
+                        field: `map.${f}`,
+                        expected: "non-reserved BridgeMemory field",
+                        got: f,
+                        hint: `Flair computes ${f} on ingest; bridges MUST NOT set it. Remove from the 'map:' block`,
+                    });
+                }
+            }
+            // `content` is the only hard requirement from the spec (§4).
+            if (typeof mapped.content !== "string" || mapped.content.length === 0) {
+                throw new BridgeRuntimeError({
+                    bridge: descriptor.name,
+                    op: "import",
+                    path: resolvedPath,
+                    record: recordIndex,
+                    field: "map.content",
+                    expected: "non-empty string",
+                    got: mapped.content === undefined ? "missing" : String(mapped.content),
+                    hint: "every record must produce a non-empty `content`; check the source data and the 'map.content' expression",
+                });
+            }
+            // Cast through unknown to honor BridgeMemory's declared shape without
+            // trusting the mapper output.
+            const bridgeMemory = mapped;
+            yield bridgeMemory;
+        }
+    }
+}
+function resolvePath(cwd, p) {
+    return isAbsolute(p) ? p : join(cwd, p);
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Export runner — drives a YAML descriptor's `export` block.
+ *
+ * Reads memories from Flair (via an injected fetcher), filters them
+ * through the descriptor's `when:` predicate when present, applies the
+ * `map:` to produce shaped output records, and writes to the target via
+ * the format writer.
+ *
+ * Slice 3a supports Shape A (YAML descriptors) and the jsonl/json
+ * formats. Markdown-frontmatter and code-plugin (Shape B) export land
+ * in slice 3b/3c.
+ *
+ * As with import-runner, the Flair I/O is injected so the runner stays
+ * unit-testable without spinning up a real Flair instance.
+ */
+import { isAbsolute, join } from "node:path";
+import { BridgeRuntimeError } from "../types.js";
+import { applyMap } from "./mapper.js";
+import { evaluatePredicate } from "./predicate.js";
+import { writeRecords } from "./writers.js";
+export async function runExport(opts) {
+    if (!opts.descriptor.export) {
+        throw new BridgeRuntimeError({
+            bridge: opts.descriptor.name,
+            op: "export",
+            field: "export",
+            expected: "object with targets",
+            got: "missing",
+            hint: "descriptor has no `export` block — run `flair bridge import` instead, or add one",
+        });
+    }
+    const onProgress = opts.onProgress ?? (() => { });
+    const perTarget = [];
+    let total = 0;
+    let exported = 0;
+    // Pull all memories once and reuse across targets — typical case is a
+    // single target. If a descriptor has multiple targets each with its own
+    // when:, re-fetching per target would surprise the operator with N×
+    // backend calls.
+    const memories = [];
+    for await (const m of opts.fetchMemories(opts.filters ?? {})) {
+        memories.push(m);
+        total++;
+    }
+    for (let tIdx = 0; tIdx < opts.descriptor.export.targets.length; tIdx++) {
+        const target = opts.descriptor.export.targets[tIdx];
+        const resolvedPath = isAbsolute(target.path) ? target.path : join(opts.cwd, target.path);
+        // Apply when: filter
+        const passing = [];
+        if (target.when && target.when.trim()) {
+            let unparsableSeen = false;
+            for (let i = 0; i < memories.length; i++) {
+                const result = evaluatePredicate(target.when, memories[i]);
+                if (result === "unparsable") {
+                    if (!unparsableSeen) {
+                        unparsableSeen = true;
+                        opts.ctx?.log.warn(`when: clause unparsable, including all records for this target`, {
+                            when: target.when,
+                            targetPath: resolvedPath,
+                        });
+                    }
+                    passing.push(memories[i]);
+                }
+                else if (result === "match") {
+                    passing.push(memories[i]);
+                }
+                else {
+                    onProgress({ type: "memory-skipped", ordinal: i + 1, reason: `when: ${target.when}` });
+                }
+            }
+        }
+        else {
+            passing.push(...memories);
+        }
+        // Apply map: to each surviving memory
+        const shaped = [];
+        for (let i = 0; i < passing.length; i++) {
+            const out = applyMap(target.map, passing[i]);
+            // The ONLY hard requirement on output is that the map produced at
+            // least one field — empty mappings would produce empty JSONL lines
+            // which are technically valid but suspicious. Skip them with a hint.
+            if (Object.keys(out).length === 0) {
+                onProgress({ type: "memory-skipped", ordinal: i + 1, reason: "map produced no fields" });
+                continue;
+            }
+            shaped.push(out);
+        }
+        if (opts.dryRun) {
+            onProgress({ type: "target-skipped", path: resolvedPath, reason: "--dry-run" });
+            perTarget.push({ path: resolvedPath, written: 0 });
+            continue;
+        }
+        opts.ctx?.log.info(`exporting target`, {
+            target: target.path,
+            format: target.format,
+            records: shaped.length,
+        });
+        const { written } = await writeRecords(opts.descriptor.name, resolvedPath, target.format, shaped);
+        perTarget.push({ path: resolvedPath, written });
+        exported += written;
+        onProgress({ type: "target-write", path: resolvedPath, written });
+    }
+    onProgress({ type: "done", total, exported });
+    return { total, exported, perTarget };
+}