@tpsdev-ai/flair 0.5.6 → 0.6.0

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;
+    }
+}