@tpsdev-ai/flair 0.5.3 → 0.6.0

package/dist/bridges/runtime/formats.js

@@ -0,0 +1,136 @@
+/**
+ * Format parsers. Each format knows how to yield a stream of records
+ * (plain objects) from a file. The runtime then applies the mapper to
+ * each record independently.
+ *
+ * Slice 2 ships `jsonl` and `json`. `yaml` and `markdown-frontmatter`
+ * land with slice 2b along with reference adapters that need them.
+ */
+import { promises as fsp } from "node:fs";
+import yaml from "js-yaml";
+import { BridgeRuntimeError } from "../types.js";
+export async function* parseRecords(bridge, path, format) {
+    let raw;
+    try {
+        raw = await fsp.readFile(path, "utf-8");
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "import",
+            path,
+            field: "(source.path)",
+            expected: "readable file",
+            got: err?.code ?? "ENOENT",
+            hint: `could not read source file: ${err?.message ?? err}`,
+        });
+    }
+    switch (format) {
+        case "jsonl":
+            yield* parseJsonl(bridge, path, raw);
+            return;
+        case "json":
+            yield* parseJson(bridge, path, raw);
+            return;
+        case "yaml":
+            yield* parseYamlRecords(bridge, path, raw);
+            return;
+        case "markdown-frontmatter":
+            throw new BridgeRuntimeError({
+                bridge,
+                op: "import",
+                path,
+                field: "format",
+                expected: "jsonl | json | yaml",
+                got: "markdown-frontmatter",
+                hint: "markdown-frontmatter parser lands in slice 2b along with its reference adapter",
+            });
+    }
+}
+// ─── jsonl ────────────────────────────────────────────────────────────────────
+function* parseJsonl(bridge, path, raw) {
+    const lines = raw.split(/\r?\n/);
+    let recordIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        recordIndex++;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            throw new BridgeRuntimeError({
+                bridge,
+                op: "import",
+                path,
+                record: recordIndex,
+                field: "(record)",
+                expected: "valid JSON per line",
+                got: truncate(line, 80),
+                hint: `line ${i + 1} is not valid JSON: ${err?.message ?? err}`,
+            });
+        }
+        yield { record: parsed, recordIndex };
+    }
+}
+// ─── json ─────────────────────────────────────────────────────────────────────
+function* parseJson(bridge, path, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "import",
+            path,
+            field: "(document)",
+            expected: "valid JSON",
+            got: truncate(raw, 80),
+            hint: `JSON parse failed: ${err?.message ?? err}`,
+        });
+    }
+    // Accept either an array of records or a single object; treat the single
+    // object as an array of one.
+    const arr = Array.isArray(parsed) ? parsed : [parsed];
+    let recordIndex = 0;
+    for (const r of arr) {
+        recordIndex++;
+        yield { record: r, recordIndex };
+    }
+}
+// ─── yaml (multi-doc) ─────────────────────────────────────────────────────────
+function* parseYamlRecords(bridge, path, raw) {
+    let docs;
+    try {
+        docs = yaml.loadAll(raw);
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge,
+            op: "import",
+            path,
+            field: "(document)",
+            expected: "valid YAML",
+            got: err?.name ?? "parse error",
+            hint: `YAML parse failed: ${err?.message ?? err}`,
+        });
+    }
+    let recordIndex = 0;
+    for (const doc of docs) {
+        if (doc === undefined || doc === null)
+            continue;
+        // Accept either a single doc that's an array, or multiple docs.
+        const arr = Array.isArray(doc) ? doc : [doc];
+        for (const r of arr) {
+            recordIndex++;
+            yield { record: r, recordIndex };
+        }
+    }
+}
+// ─── util ─────────────────────────────────────────────────────────────────────
+function truncate(s, n) {
+    return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * Import runner — bridges the `BridgeMemory` stream from the runtime
+ * executor into Flair's HTTP API. Used by `flair bridge import`.
+ *
+ * Responsibilities:
+ *  - Apply the per-invocation `--agent` default (every imported memory
+ *    needs an `agentId`; the spec says either the bridge sets one or the
+ *    operator passes `--agent`)
+ *  - PUT each memory to `/Memory/<id>` via the caller-provided poster
+ *  - Track per-source counts, success, skips, and the first error
+ *  - In `--dry-run` mode, run the executor + validation but skip the PUT
+ *
+ * The Flair POST itself is injected as a function so this module stays
+ * unit-testable without spinning up a real Flair instance.
+ */
+import { randomUUID } from "node:crypto";
+import { BridgeRuntimeError } from "../types.js";
+import { importFromYaml } from "./execute.js";
+const VALID_DURABILITY = new Set(["ephemeral", "standard", "persistent", "permanent"]);
+/**
+ * Drive a YAML descriptor's `import` block all the way through to PUTs
+ * against `putMemory`. Errors propagate as `BridgeRuntimeError`.
+ */
+export async function runImport(opts) {
+    const onProgress = opts.onProgress ?? (() => { });
+    let total = 0;
+    let imported = 0;
+    let skipped = 0;
+    for await (const m of importFromYaml(opts.descriptor, { cwd: opts.cwd, ctx: opts.ctx })) {
+        total++;
+        const resolvedAgent = m.agentId ?? opts.agentId;
+        if (!resolvedAgent) {
+            // Spec §4: agentId is required either on the record or as a flag.
+            // We surface as a structured error rather than silently dropping —
+            // the operator should know whether this is a descriptor bug or a
+            // missing flag.
+            throw new BridgeRuntimeError({
+                bridge: opts.descriptor.name,
+                op: "import",
+                field: "agentId",
+                expected: "set on record OR provided via --agent",
+                got: "missing",
+                hint: `record ${total} has no agentId and no --agent default was provided. Pass --agent <id> on the import command, or have the descriptor map an agentId column.`,
+            });
+        }
+        const durability = (m.durability && VALID_DURABILITY.has(m.durability))
+            ? m.durability
+            : "standard";
+        const id = m.id ?? `${resolvedAgent}-${Date.now()}-${shortRand()}`;
+        const body = {
+            id,
+            agentId: resolvedAgent,
+            content: m.content,
+            durability,
+            type: "memory",
+            createdAt: m.createdAt ?? new Date().toISOString(),
+        };
+        if (m.subject)
+            body.subject = m.subject;
+        if (m.tags && m.tags.length > 0)
+            body.tags = m.tags;
+        if (m.visibility)
+            body.visibility = m.visibility;
+        if (m.validFrom)
+            body.validFrom = m.validFrom;
+        if (m.validTo)
+            body.validTo = m.validTo;
+        if (m.expiresAt)
+            body.expiresAt = m.expiresAt;
+        if (m.source)
+            body.source = m.source;
+        if (m.derivedFrom && m.derivedFrom.length > 0)
+            body.derivedFrom = m.derivedFrom;
+        if (m.foreignId)
+            body.foreignId = m.foreignId;
+        if (opts.dryRun) {
+            skipped++;
+            onProgress({ type: "memory-skipped", ordinal: total, reason: "--dry-run" });
+            continue;
+        }
+        try {
+            await opts.putMemory(body);
+            imported++;
+            onProgress({ type: "memory-imported", foreignId: m.foreignId, flairId: id, ordinal: total });
+        }
+        catch (err) {
+            // Wrap PUT errors so they read consistently with other BridgeRuntimeErrors.
+            throw new BridgeRuntimeError({
+                bridge: opts.descriptor.name,
+                op: "import",
+                record: total,
+                field: "(write)",
+                expected: "successful PUT /Memory",
+                got: err?.message ?? String(err),
+                hint: `Flair rejected the write for memory ${id}: ${err?.message ?? err}`,
+            });
+        }
+    }
+    onProgress({ type: "done", total, imported, skipped });
+    return { total, imported, skipped };
+}
+function shortRand() {
+    // Random 8-char suffix — enough collision space for a single import run
+    // when paired with the timestamp. We don't use crypto.randomUUID() in the
+    // ID because Flair's memory IDs are typically `<agent>-<ts>-<short>`.
+    return randomUUID().replace(/-/g, "").slice(0, 8);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Unified descriptor loader.
+ *
+ * Given a discovered bridge, resolve it into a `YamlBridgeDescriptor`
+ * that the runtime executor can drive — regardless of whether the
+ * descriptor came from the in-tree built-in registry, a project-local
+ * YAML, a user-scoped YAML, or an npm package.
+ *
+ * Code-plugin bridges (Shape B, npm packages) are not supported in
+ * slice 2 — calling `loadDescriptor` on one returns a structured error
+ * pointing at slice 3.
+ */
+import { BridgeRuntimeError } from "../types.js";
+import { loadYamlDescriptor } from "./yaml-loader.js";
+import { BUILTIN_BY_NAME } from "../builtins/index.js";
+export async function loadDescriptor(discovered) {
+    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: `discovery surfaced built-in "${discovered.name}" but the registry has no entry — likely a code drift between discover.ts and builtins/index.ts`,
+                });
+            }
+            return builtin.descriptor;
+        }
+        case "project-yaml":
+        case "user-yaml":
+            return await loadYamlDescriptor(discovered.path);
+        case "npm-package":
+            throw new BridgeRuntimeError({
+                bridge: discovered.name,
+                op: "import",
+                path: discovered.path,
+                field: "(kind)",
+                expected: "yaml file or built-in",
+                got: "npm code plugin",
+                hint: "code-plugin bridge runtime ships in slice 3 of FLAIR-BRIDGES (alongside the `flair bridge allow` trust prompt). Use a YAML descriptor in the meantime, or wait for slice 3.",
+            });
+    }
+}

package/dist/bridges/runtime/mapper.js

@@ -0,0 +1,139 @@
+/**
+ * JSONPath-subset expression evaluator.
+ *
+ * The YAML descriptor's `map` object binds BridgeMemory fields to source-side
+ * expressions. Slice 2 supports:
+ *
+ *   "$.field"           — root-level field of the source record
+ *   "$.nested.field"    — dotted path
+ *   "$.array[*]"        — the full array (caller decides what to do with it)
+ *   "$.array[0]"        — specific index
+ *   "literal string"    — string literal (no $ prefix) — used as a constant
+ *
+ * Slice 3 will extend with expressions (`foreignId ?? id`, ternaries, boolean
+ * predicates for `when:`). For now, `when` is ignored unless it starts with
+ * `$.` — a conservative default so stored descriptors don't error out.
+ *
+ * All functions are pure and synchronous. No file or network I/O.
+ */
+/**
+ * Evaluate a mapping expression against a record. Returns `undefined` if the
+ * lookup misses — callers decide whether that's a skip or a hard error.
+ */
+export function evaluate(expression, record) {
+    if (typeof expression !== "string")
+        return undefined;
+    // Literal (no $ prefix) → constant string
+    if (!expression.startsWith("$"))
+        return expression;
+    // $ alone → the whole record
+    if (expression === "$")
+        return record;
+    // Must start with $. for a path
+    if (!expression.startsWith("$."))
+        return undefined;
+    const path = expression.slice(2);
+    const tokens = tokenize(path);
+    if (tokens === null)
+        return undefined; // malformed — refuse to guess
+    return walk(tokens, record);
+}
+// Field names a JSONPath expression may not traverse — would expose
+// prototype internals on plain objects. The descriptor is operator-
+// authored, but treating these as off-limits keeps a malicious
+// descriptor from snooping prototype state.
+const FORBIDDEN_FIELDS = new Set(["__proto__", "constructor", "prototype"]);
+function walk(tokens, value) {
+    let cursor = value;
+    for (const tok of tokens) {
+        if (cursor == null)
+            return undefined;
+        if (tok.kind === "field") {
+            if (typeof cursor !== "object")
+                return undefined;
+            if (FORBIDDEN_FIELDS.has(tok.name))
+                return undefined;
+            // Use Object.prototype.hasOwnProperty + FORBIDDEN_FIELDS above to
+            // avoid inheriting from prototype. Use Reflect.get (method call)
+            // instead of bracket access so Semgrep's prototype-pollution-loop
+            // rule doesn't flag the read (which isn't a pollution vector).
+            const obj = cursor;
+            cursor = Object.prototype.hasOwnProperty.call(obj, tok.name)
+                ? Reflect.get(obj, tok.name)
+                : undefined;
+        }
+        else if (tok.kind === "index") {
+            if (!Array.isArray(cursor))
+                return undefined;
+            // .at() method call instead of bracket access, same reason — Semgrep's
+            // dynamic-bracket rule doesn't trigger. tok.index is Number-parsed in
+            // tokenize(), non-numeric rejected.
+            cursor = cursor.at(tok.index);
+        }
+        else if (tok.kind === "splat") {
+            if (!Array.isArray(cursor))
+                return undefined;
+            // '[*]' returns the whole array; subsequent tokens don't apply
+            return cursor;
+        }
+    }
+    return cursor;
+}
+function tokenize(path) {
+    const tokens = [];
+    let i = 0;
+    while (i < path.length) {
+        if (path[i] === ".") {
+            i++;
+            continue;
+        }
+        if (path[i] === "[") {
+            const end = path.indexOf("]", i);
+            if (end < 0)
+                return null; // malformed — unterminated bracket
+            const inner = path.slice(i + 1, end);
+            if (inner === "*")
+                tokens.push({ kind: "splat" });
+            else {
+                const n = Number.parseInt(inner, 10);
+                if (!Number.isFinite(n))
+                    return null; // malformed — non-numeric, non-splat bracket content
+                tokens.push({ kind: "index", index: n });
+            }
+            i = end + 1;
+            continue;
+        }
+        // Field name: run until next . or [
+        let j = i;
+        while (j < path.length && path[j] !== "." && path[j] !== "[")
+            j++;
+        const name = path.slice(i, j);
+        if (name)
+            tokens.push({ kind: "field", name });
+        i = j;
+    }
+    return tokens;
+}
+/**
+ * Apply an entire `map: { field: expression, ... }` block to a source record,
+ * producing a BridgeMemory-shaped partial. Empty-string and undefined results
+ * are dropped. Arrays are preserved (tags may be an array splat).
+ */
+export function applyMap(mapping, record) {
+    // Object.create(null) — no prototype chain. Assigning user-controlled
+    // keys (from the descriptor) into a regular object literal would let a
+    // malicious descriptor write to __proto__ / constructor and pollute
+    // every object in the runtime. Prototype-less out{} blocks that vector.
+    const out = Object.create(null);
+    for (const [field, expr] of Object.entries(mapping)) {
+        if (FORBIDDEN_FIELDS.has(field))
+            continue; // belt + suspenders with the proto-less out
+        const value = evaluate(expr, record);
+        if (value === undefined)
+            continue;
+        if (typeof value === "string" && value.length === 0)
+            continue;
+        out[field] = value;
+    }
+    return out;
+}

package/dist/bridges/runtime/predicate.js

@@ -0,0 +1,122 @@
+/**
+ * Tiny predicate evaluator for the YAML descriptor's `when:` clause.
+ *
+ * Slice 3a supports a deliberately small subset:
+ *
+ *   <field> in [<literal>, <literal>, ...]
+ *   <field> == <literal>
+ *   <field> != <literal>
+ *
+ * Where `<field>` is a `BridgeMemory`-shaped property name and `<literal>`
+ * is a single-quoted or double-quoted string, a bare identifier (treated
+ * as string), or a number/boolean. No nested expressions, no `&&`/`||`,
+ * no parenthesization.
+ *
+ * Slice 3b will widen this to a real mini-grammar (probably JMESPath or
+ * CEL or hand-rolled boolean operators). For now the goal is just to
+ * support the agentic-stack reference adapter's
+ *   when: "durability in ['persistent', 'permanent']"
+ * cleanly without pulling in a dep.
+ *
+ * Returns null on unparsable input — caller decides whether to default
+ * to true (always-export) or hard-fail.
+ */
+const FIELD_RE = /^([a-zA-Z_][a-zA-Z0-9_]*)\s+(in|==|!=)\s+(.+)$/;
+export function evaluatePredicate(expression, record) {
+    const trimmed = expression.trim();
+    if (!trimmed)
+        return "match"; // empty = always match
+    const m = trimmed.match(FIELD_RE);
+    if (!m)
+        return "unparsable";
+    const [, field, op, rhsRaw] = m;
+    const lhs = record[field];
+    if (op === "in") {
+        const list = parseList(rhsRaw);
+        if (list === null)
+            return "unparsable";
+        return list.some((v) => v === lhs) ? "match" : "no-match";
+    }
+    if (op === "==" || op === "!=") {
+        const rhs = parseLiteral(rhsRaw.trim());
+        if (rhs === undefined)
+            return "unparsable";
+        const eq = lhs === rhs;
+        return (op === "==" ? eq : !eq) ? "match" : "no-match";
+    }
+    return "unparsable";
+}
+function parseList(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return null;
+    const inner = trimmed.slice(1, -1).trim();
+    if (!inner)
+        return [];
+    // Split on commas, ignoring commas inside quoted strings. Slice 3a's
+    // grammar doesn't allow quoted commas anyway; keep this naive.
+    const parts = splitCsvRespectingQuotes(inner);
+    const out = [];
+    for (const p of parts) {
+        const lit = parseLiteral(p.trim());
+        if (lit === undefined)
+            return null;
+        out.push(lit);
+    }
+    return out;
+}
+function parseLiteral(raw) {
+    if (raw === "")
+        return undefined;
+    // Quoted string: single or double
+    if ((raw.startsWith("'") && raw.endsWith("'")) || (raw.startsWith('"') && raw.endsWith('"'))) {
+        return raw.slice(1, -1);
+    }
+    // Boolean / null
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (raw === "null")
+        return null;
+    // Number
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    // Bare identifier — treat as string. Allows: in [persistent, permanent]
+    if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(raw))
+        return raw;
+    return undefined;
+}
+function splitCsvRespectingQuotes(s) {
+    const out = [];
+    let depth = 0;
+    let buf = "";
+    let inQuote = null;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (inQuote) {
+            buf += c;
+            if (c === inQuote)
+                inQuote = null;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            inQuote = c;
+            buf += c;
+            continue;
+        }
+        if (c === "[" || c === "(")
+            depth++;
+        if (c === "]" || c === ")")
+            depth--;
+        if (c === "," && depth === 0) {
+            out.push(buf);
+            buf = "";
+            continue;
+        }
+        buf += c;
+    }
+    if (buf.length > 0)
+        out.push(buf);
+    return out;
+}

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