@tpsdev-ai/flair 0.5.6 → 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/bridges/runtime/writers.js

@@ -0,0 +1,130 @@
+/**
+ * Output writers for export targets. Slice 3a ships `jsonl` and `json`.
+ * `yaml` and `markdown-frontmatter` land with slice 3b alongside any
+ * built-in that needs them.
+ *
+ * Each writer takes a stream of "shaped output records" (whatever the
+ * descriptor's `map:` produced) and writes to a target file path.
+ * Atomic via tmp-file + rename, so a crash mid-write doesn't leave a
+ * half-written target.
+ */
+import { promises as fsp } from "node:fs";
+import { dirname, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import yaml from "js-yaml";
+import { BridgeRuntimeError } from "../types.js";
+export async function writeRecords(bridge, path, format, records) {
+    switch (format) {
+        case "jsonl": return writeJsonl(bridge, path, records);
+        case "json": return writeJson(bridge, path, records);
+        case "yaml": return writeYaml(bridge, path, records);
+        case "markdown-frontmatter":
+            throw new BridgeRuntimeError({
+                bridge,
+                op: "export",
+                path,
+                field: "format",
+                expected: "jsonl | json | yaml",
+                got: "markdown-frontmatter",
+                hint: "markdown-frontmatter writer lands in slice 3b along with its reference adapter",
+            });
+    }
+}
+async function writeJsonl(bridge, path, records) {
+    const tmpPath = await stageTmp(bridge, path, "export");
+    let written = 0;
+    try {
+        const fh = await fsp.open(tmpPath, "w");
+        try {
+            for (const r of records) {
+                await fh.write(JSON.stringify(r) + "\n");
+                written++;
+            }
+        }
+        finally {
+            await fh.close();
+        }
+        await fsp.rename(tmpPath, path);
+    }
+    catch (err) {
+        await fsp.unlink(tmpPath).catch(() => { });
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "export",
+            path,
+            field: "(write)",
+            expected: "successful write",
+            got: err?.message ?? String(err),
+            hint: `failed writing to ${path}: ${err?.message ?? err}`,
+        });
+    }
+    return { written };
+}
+async function writeJson(bridge, path, records) {
+    const arr = [];
+    for (const r of records)
+        arr.push(r);
+    const tmpPath = await stageTmp(bridge, path, "export");
+    try {
+        await fsp.writeFile(tmpPath, JSON.stringify(arr, null, 2));
+        await fsp.rename(tmpPath, path);
+    }
+    catch (err) {
+        await fsp.unlink(tmpPath).catch(() => { });
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "export",
+            path,
+            field: "(write)",
+            expected: "successful write",
+            got: err?.message ?? String(err),
+            hint: `failed writing to ${path}: ${err?.message ?? err}`,
+        });
+    }
+    return { written: arr.length };
+}
+async function writeYaml(bridge, path, records) {
+    const arr = [];
+    for (const r of records)
+        arr.push(r);
+    const tmpPath = await stageTmp(bridge, path, "export");
+    try {
+        await fsp.writeFile(tmpPath, yaml.dump(arr));
+        await fsp.rename(tmpPath, path);
+    }
+    catch (err) {
+        await fsp.unlink(tmpPath).catch(() => { });
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "export",
+            path,
+            field: "(write)",
+            expected: "successful write",
+            got: err?.message ?? String(err),
+            hint: `failed writing to ${path}: ${err?.message ?? err}`,
+        });
+    }
+    return { written: arr.length };
+}
+/**
+ * Allocate a sibling temp file in the same directory as `targetPath`.
+ * Same-fs rename is atomic on POSIX; using a sibling guarantees that.
+ */
+async function stageTmp(bridge, targetPath, op) {
+    const dir = dirname(targetPath);
+    try {
+        await fsp.mkdir(dir, { recursive: true });
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "export",
+            path: targetPath,
+            field: "(mkdir)",
+            expected: "writable directory",
+            got: err?.message ?? String(err),
+            hint: `could not create directory ${dir}: ${err?.message ?? err}`,
+        });
+    }
+    return `${dir}/.${basename(targetPath)}.${op}.${randomUUID().slice(0, 8)}.tmp`;
+}

package/dist/bridges/runtime/yaml-loader.js

@@ -0,0 +1,148 @@
+/**
+ * YAML bridge descriptor loader.
+ *
+ * Reads a `.flair-bridge/<name>.yaml` (or `~/.flair/bridges/<name>.yaml`),
+ * parses it with js-yaml, and normalizes it into a typed
+ * `YamlBridgeDescriptor`. Validation is strict for required fields
+ * (`name`, `kind`, at least one of `import`/`export`), lenient elsewhere —
+ * unknown fields are preserved but ignored; the spec is allowed to grow.
+ *
+ * Errors are always `BridgeRuntimeError` with LLM-readable `{field, expected, got, hint}`.
+ */
+import { promises as fsp } from "node:fs";
+import yaml from "js-yaml";
+import { BridgeRuntimeError } from "../types.js";
+const VALID_FORMATS = [
+    "jsonl",
+    "json",
+    "yaml",
+    "markdown-frontmatter",
+];
+function failLoad(path, field, expected, got, hint) {
+    throw new BridgeRuntimeError({
+        bridge: "(unknown)",
+        op: "import",
+        path,
+        field,
+        expected,
+        got: typeof got === "string" ? got : JSON.stringify(got),
+        hint,
+    });
+}
+function fail(bridge, path, field, expected, got, hint) {
+    throw new BridgeRuntimeError({
+        bridge,
+        op: "import",
+        path,
+        field,
+        expected,
+        got: typeof got === "string" ? got : JSON.stringify(got),
+        hint,
+    });
+}
+function normalizeSourceTarget(bridge, path, fieldBase, raw) {
+    if (typeof raw !== "object" || raw === null) {
+        fail(bridge, path, fieldBase, "object", raw, `each entry under ${fieldBase} must be an object with 'path', 'format', and 'map'`);
+    }
+    const obj = raw;
+    if (typeof obj.path !== "string" || !obj.path) {
+        fail(bridge, path, `${fieldBase}.path`, "non-empty string", obj.path, `${fieldBase}.path must be a non-empty string`);
+    }
+    if (typeof obj.format !== "string") {
+        fail(bridge, path, `${fieldBase}.format`, "string", obj.format, `${fieldBase}.format must be one of: ${VALID_FORMATS.join(", ")}`);
+    }
+    if (!VALID_FORMATS.includes(obj.format)) {
+        fail(bridge, path, `${fieldBase}.format`, VALID_FORMATS.join(" | "), obj.format, `unsupported format "${obj.format}"; supported: ${VALID_FORMATS.join(", ")}`);
+    }
+    if (typeof obj.map !== "object" || obj.map === null || Array.isArray(obj.map)) {
+        fail(bridge, path, `${fieldBase}.map`, "object", obj.map, `${fieldBase}.map must be an object of BridgeMemory-field → mapping expression`);
+    }
+    const mapIn = obj.map;
+    const map = {};
+    for (const [k, v] of Object.entries(mapIn)) {
+        if (typeof v !== "string") {
+            fail(bridge, path, `${fieldBase}.map.${k}`, "string expression", v, `map entries must be strings; got ${typeof v} for ${k}`);
+        }
+        map[k] = v;
+    }
+    const out = {
+        path: obj.path,
+        format: obj.format,
+        map,
+    };
+    if (typeof obj.when === "string")
+        out.when = obj.when;
+    return out;
+}
+export async function loadYamlDescriptor(yamlPath) {
+    let raw;
+    try {
+        raw = await fsp.readFile(yamlPath, "utf-8");
+    }
+    catch (err) {
+        failLoad(yamlPath, "(file)", "readable file", err?.code ?? "ENOENT", `could not read YAML file: ${err?.message ?? err}`);
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (err) {
+        failLoad(yamlPath, "(yaml)", "valid YAML", err?.name ?? "parse error", `YAML parse failed: ${err?.message ?? err}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        failLoad(yamlPath, "(root)", "mapping", parsed, "descriptor must be a YAML mapping at the top level");
+    }
+    const d = parsed;
+    if (typeof d.name !== "string" || !d.name) {
+        failLoad(yamlPath, "name", "non-empty string", d.name, "descriptor must have a top-level 'name' string");
+    }
+    const bridge = d.name;
+    if (d.kind !== "file") {
+        fail(bridge, yamlPath, "kind", "'file'", d.kind, "YAML descriptors have kind: file. API plugins use a TypeScript code plugin — see docs/bridges.md §6");
+    }
+    const versionRaw = d.version;
+    const version = typeof versionRaw === "number" ? versionRaw : versionRaw === undefined ? 1 : NaN;
+    if (!Number.isFinite(version)) {
+        fail(bridge, yamlPath, "version", "number", versionRaw, "version must be a number; defaulting to 1 if omitted is supported");
+    }
+    const descriptor = {
+        name: bridge,
+        version,
+        kind: "file",
+    };
+    if (typeof d.description === "string")
+        descriptor.description = d.description;
+    if (d.detect && typeof d.detect === "object") {
+        const det = d.detect;
+        const detect = {};
+        if (Array.isArray(det.anyExists)) {
+            detect.anyExists = det.anyExists.filter((x) => typeof x === "string");
+        }
+        if (Array.isArray(det.allExist)) {
+            detect.allExist = det.allExist.filter((x) => typeof x === "string");
+        }
+        descriptor.detect = detect;
+    }
+    if (d.import && typeof d.import === "object") {
+        const imp = d.import;
+        if (!Array.isArray(imp.sources) || imp.sources.length === 0) {
+            fail(bridge, yamlPath, "import.sources", "non-empty array", imp.sources, "import must have a 'sources' array with at least one entry");
+        }
+        descriptor.import = {
+            sources: imp.sources.map((s, i) => normalizeSourceTarget(bridge, yamlPath, `import.sources[${i}]`, s)),
+        };
+    }
+    if (d.export && typeof d.export === "object") {
+        const exp = d.export;
+        if (!Array.isArray(exp.targets) || exp.targets.length === 0) {
+            fail(bridge, yamlPath, "export.targets", "non-empty array", exp.targets, "export must have a 'targets' array with at least one entry");
+        }
+        descriptor.export = {
+            targets: exp.targets.map((t, i) => normalizeSourceTarget(bridge, yamlPath, `export.targets[${i}]`, t)),
+        };
+    }
+    if (!descriptor.import && !descriptor.export) {
+        fail(bridge, yamlPath, "(root)", "import or export block", "neither", "descriptor must define at least one of `import` or `export`");
+    }
+    return descriptor;
+}

package/dist/bridges/scaffold.js

@@ -0,0 +1,224 @@
+/**
+ * Bridge scaffolding — emits a working starter for a new bridge.
+ *
+ * From FLAIR-BRIDGES.md §2: "Scaffold & test in-tree. `flair bridge
+ * scaffold <name>` emits a working starter; `flair bridge test <name>`
+ * runs a round-trip diff." This file handles the `scaffold` half.
+ *
+ * Two shapes supported:
+ *  - --file: YAML descriptor at `.flair-bridge/<name>.yaml` + fixture
+ *  - --api:  TS code plugin at `flair-bridge-<name>/` + package.json + fixture
+ */
+import { promises as fsp } from "node:fs";
+import { join, dirname } from "node:path";
+const NAME_RE = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+async function exists(path) {
+    try {
+        await fsp.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeIfAbsent(path, content, force) {
+    if (!force && (await exists(path)))
+        return { wrote: false };
+    await fsp.mkdir(dirname(path), { recursive: true });
+    await fsp.writeFile(path, content, "utf-8");
+    return { wrote: true };
+}
+function fileDescriptorTemplate(name) {
+    return `# .flair-bridge/${name}.yaml
+#
+# Generated by \`flair bridge scaffold ${name} --file\`.
+# Edit to match your foreign system, then run \`flair bridge test ${name}\`.
+#
+# Spec: see FLAIR-BRIDGES.md §4 (memory schema) and §5 (YAML shape).
+name: ${name}
+version: 1
+kind: file
+# description shown in 'flair bridge list':
+description: "TODO — one-line description of what this bridge does"
+
+# 'detect' lets auto-discovery confirm the foreign system is present.
+# Use 'anyExists' (any one path matching is enough) or 'allExist'.
+detect:
+  anyExists:
+    - ".example/AGENTS.md"
+
+# Import: foreign → Flair memories.
+import:
+  sources:
+    - path: ".example/memory/lessons.jsonl"
+      format: jsonl          # jsonl | json | yaml | markdown-frontmatter
+      map:
+        # JSONPath subset: $.field, $.nested.field, $.array[*]
+        content: "$.claim"
+        subject: "$.topic"
+        tags: "$.tags"
+        foreignId: "$.id"
+        durability: "persistent"
+        source: "${name}/lessons"
+
+# Export: Flair memories → foreign. Optional. Drop this block if read-only.
+export:
+  targets:
+    - path: ".example/memory/lessons.jsonl"
+      format: jsonl
+      # 'when' is a boolean expression over BridgeMemory fields.
+      # Omit for "always export".
+      when: "durability in ['persistent', 'permanent']"
+      map:
+        # Right-hand side is a BridgeMemory field (or expression).
+        id: "foreignId ?? id"
+        claim: "content"
+        topic: "subject"
+        tags: "tags"
+`;
+}
+function fileFixtureTemplate(name) {
+    // JSONL fixture matching the default template's 'sources[0].path'.
+    return [
+        JSON.stringify({ id: "lesson-1", claim: "Always run tests before pushing.", topic: "engineering", tags: ["process", "ci"] }),
+        JSON.stringify({ id: "lesson-2", claim: "Name workarounds as workarounds.", topic: "communication", tags: ["writing"] }),
+        "",
+    ].join("\n");
+}
+function apiIndexTemplate(name) {
+    return `/**
+ * flair-bridge-${name}
+ *
+ * Generated by \`flair bridge scaffold ${name} --api\`.
+ * Spec: see FLAIR-BRIDGES.md §4 (memory schema) and §6 (code plugin shape).
+ *
+ * After editing, run:
+ *   flair bridge test ${name}
+ */
+
+import type {
+  MemoryBridge,
+  BridgeMemory,
+  BridgeContext,
+} from "@tpsdev-ai/flair";
+
+export const bridge: MemoryBridge = {
+  name: "${name}",
+  version: 1,
+  kind: "api",
+
+  options: {
+    apiKey:  { env: "${name.toUpperCase().replace(/-/g, "_")}_API_KEY", required: true, description: "API token" },
+    userId:  { required: true, description: "Account or user identifier in the foreign system" },
+    baseUrl: { default: "https://api.example.com", description: "Foreign API base URL" },
+  },
+
+  async *import(opts, ctx: BridgeContext): AsyncIterable<BridgeMemory> {
+    ctx.log.info("starting import", { user: String(opts.userId) });
+    const res = await ctx.fetch(\`\${String(opts.baseUrl)}/v1/memories?user=\${String(opts.userId)}\`, {
+      headers: { Authorization: \`Bearer \${String(opts.apiKey)}\` },
+    });
+    if (!res.ok) {
+      throw new Error(\`foreign API returned \${res.status}: \${await res.text()}\`);
+    }
+    const payload = await res.json() as { results?: Array<Record<string, unknown>> };
+    for (const m of payload.results ?? []) {
+      yield {
+        foreignId: String(m.id ?? ""),
+        content: String(m.content ?? ""),
+        createdAt: typeof m.created_at === "string" ? m.created_at : undefined,
+        tags: Array.isArray(m.tags) ? m.tags.map(String) : undefined,
+        source: "${name}",
+      };
+    }
+  },
+
+  async export(memories, opts, ctx): Promise<void> {
+    ctx.log.info("starting export", { user: String(opts.userId) });
+    for await (const m of memories) {
+      await ctx.fetch(\`\${String(opts.baseUrl)}/v1/memories\`, {
+        method: "POST",
+        headers: {
+          Authorization: \`Bearer \${String(opts.apiKey)}\`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          user: String(opts.userId),
+          content: m.content,
+          tags: m.tags ?? [],
+        }),
+      });
+    }
+  },
+};
+
+export default bridge;
+`;
+}
+function apiPackageJsonTemplate(name) {
+    const pkg = {
+        name: `flair-bridge-${name}`,
+        version: "0.1.0",
+        type: "module",
+        description: `Flair bridge for ${name}`,
+        main: "index.js",
+        types: "index.d.ts",
+        scripts: {
+            build: "tsc",
+        },
+        flair: { kind: "api", version: 1 },
+        peerDependencies: {
+            "@tpsdev-ai/flair": ">=1.0.0",
+        },
+    };
+    return JSON.stringify(pkg, null, 2) + "\n";
+}
+function apiFixtureTemplate(name) {
+    return JSON.stringify({
+        description: `Mock responses for flair-bridge-${name}. Used by 'flair bridge test ${name}'.`,
+        import: {
+            "GET /v1/memories?user=example": {
+                status: 200,
+                body: {
+                    results: [
+                        { id: "m-1", content: "First imported memory.", tags: ["example"] },
+                        { id: "m-2", content: "Second imported memory.", tags: ["example"] },
+                    ],
+                },
+            },
+        },
+        export: {
+            "POST /v1/memories": { status: 201, body: { ok: true } },
+        },
+    }, null, 2) + "\n";
+}
+export async function scaffold(opts) {
+    if (!NAME_RE.test(opts.name)) {
+        throw new Error(`invalid bridge name "${opts.name}" — must match ${NAME_RE} (lowercase, digits, hyphens; start with letter).`);
+    }
+    const cwd = opts.cwd ?? process.cwd();
+    const force = opts.force ?? false;
+    const createdFiles = [];
+    const skippedFiles = [];
+    const track = async (path, content) => {
+        const { wrote } = await writeIfAbsent(path, content, force);
+        if (wrote)
+            createdFiles.push(path);
+        else
+            skippedFiles.push(path);
+    };
+    if (opts.kind === "file") {
+        await track(join(cwd, ".flair-bridge", `${opts.name}.yaml`), fileDescriptorTemplate(opts.name));
+        await track(join(cwd, ".flair-bridge", "fixtures", `${opts.name}.fixture.jsonl`), fileFixtureTemplate(opts.name));
+    }
+    else {
+        const pkgDir = join(cwd, `flair-bridge-${opts.name}`);
+        await track(join(pkgDir, "index.ts"), apiIndexTemplate(opts.name));
+        await track(join(pkgDir, "package.json"), apiPackageJsonTemplate(opts.name));
+        await track(join(pkgDir, "fixtures", `${opts.name}.mock.json`), apiFixtureTemplate(opts.name));
+    }
+    const summary = createdFiles.length === 0
+        ? `nothing created — all files already exist. Pass --force to overwrite.`
+        : `scaffolded ${opts.kind} bridge "${opts.name}". Next: edit the descriptor, then run \`flair bridge test ${opts.name}\`.`;
+    return { createdFiles, skippedFiles, summary };
+}

package/dist/bridges/types.js

@@ -0,0 +1,30 @@
+/**
+ * Types for the Flair memory bridge plugin system.
+ *
+ * Mirrors the contract in specs/FLAIR-BRIDGES.md. These types are the
+ * public surface a bridge author (human or agent) targets.
+ *
+ * IMPORTANT: the YAML bridge format (shape A) also conforms to these types
+ * after parsing — the runtime normalizes YAML descriptors into the same
+ * shape a code plugin (shape B) exports.
+ */
+// Fields a bridge MUST NOT set — computed by Flair on ingest.
+export const FLAIR_RESERVED_FIELDS = [
+    "contentHash",
+    "embedding",
+    "embeddingModel",
+    "retrievalCount",
+    "lastRetrieved",
+    "promotionStatus",
+    "_safetyFlags",
+    "createdBy",
+    "updatedBy",
+    "archivedBy",
+];
+export class BridgeRuntimeError extends Error {
+    detail;
+    constructor(detail) {
+        super(`${detail.bridge}:${detail.op} — ${detail.hint}`);
+        this.detail = detail;
+    }
+}