@getbourdon/participants 0.3.0 → 0.4.0

package/dist/base.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: BUSL-1.1
 /**
  * Bourdon participant base — the Protocol → TS interface, errors, and the
  * AgentStore / HealthStatus types. Faithful port of `participants/base.py`.

package/dist/export-store-base.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared mechanics for the "JSON export store" participant family.
+ *
+ * Bolt.new, Lovable and v0 are cloud builders that persist nothing useful on
+ * the user's machine, so each federates through a directory the user exports
+ * into:
+ *
+ *     $<AGENT>_STATE_DIR/          (default: ~/.<agent>/)
+ *         projects.json            array of project records, or {projects: [...]}
+ *         sessions/<id>.json       one JSON document per session
+ *
+ * The oracle implements this three times (`participants/{bolt,lovable,v0}.py`,
+ * ~1,130 lines). The store layout, the date parser, the visibility parser, the
+ * loader's error semantics and the health-check ladder are identical across
+ * all three, so they live here once.
+ *
+ * ⚠ What is NOT shared: each reader's `projectToEntity` / `sessionToRecord`.
+ * They look similar and are not the same — Lovable caps a project name at 120
+ * characters where Bolt caps at 80, emits a NULL summary where Bolt emits a
+ * `"Bolt.new project <name>"` fallback, and appends its own tag
+ * unconditionally where Bolt inserts only if absent (so Lovable really can
+ * emit a duplicate tag). Those differences are the oracle's behaviour and the
+ * mirror reproduces them rather than tidying them into agreement; each reader
+ * supplies its own mapper.
+ */
+import { Visibility, type EntityModel, type L5ManifestModel, type SessionModel, type VisibilityPolicyModel } from "@getbourdon/l5";
+import { type AgentStore, type HealthStatus } from "./base.js";
+type Dict = Record<string, unknown>;
+/**
+ * `_parse_visibility`: a recognized visibility string, else null (meaning
+ * "inherit the policy default"), never a throw.
+ */
+export declare function parseVisibility(raw: unknown): Visibility | null;
+/**
+ * `_iso_date`: normalize to a bare `YYYY-MM-DD`, or null if unparseable.
+ *
+ * Accepts a full ISO timestamp (trailing `Z` included) and reduces it to its
+ * date, which is what every L5 date field carries.
+ */
+export declare function isoDate(raw: unknown): string | null;
+/** `_safe_str`: trim, then route through the redaction SSOT. "" stays "". */
+export declare function safeStr(raw: unknown, limit?: number): string;
+/** `_str_list` in the Bolt/v0 spelling: redact every item, drop the empties. */
+export declare function safeStrList(raw: unknown, limit?: number): string[];
+export interface ExportStoreConfig {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    /** Directory name under $HOME, e.g. `.bolt`. */
+    directoryName: string;
+    /** Environment variable that overrides the state directory. */
+    stateEnvVar: string;
+    roleNarrative: string;
+    capabilities: string[];
+    policy: VisibilityPolicyModel;
+    /** Human label used in error and health text, e.g. "Bolt.new". */
+    label: string;
+    /** The `bourdon <x> init` verb named in remediation text. */
+    initCommand: string;
+    projectToEntity: (record: Dict) => EntityModel | null;
+    sessionToRecord: (record: Dict, fallbackDate: string | null) => SessionModel | null;
+}
+export declare class ExportStoreParticipant {
+    readonly agentId: string;
+    readonly agentType: string;
+    readonly displayName: string;
+    private readonly config;
+    private readonly stateDir;
+    private readonly env;
+    constructor(config: ExportStoreConfig, options?: {
+        stateDir?: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    static defaultNativePath(directoryName: string, home?: string): string;
+    get nativePath(): string;
+    private resolveStateDir;
+    private requireStateDir;
+    /**
+     * `projects.json`, accepting either a bare array or `{projects: [...]}`.
+     *
+     * A MISSING file is empty (the store may legitimately hold only sessions);
+     * a PRESENT but unreadable or wrongly-shaped file throws. The distinction is
+     * the point: absence is a state, corruption is an error.
+     */
+    private loadProjects;
+    private sessionFiles;
+    /** Newest first. An unreadable session is skipped, never fatal. */
+    private loadSessions;
+    discover(): AgentStore;
+    exportSessions(since: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date | null): L5ManifestModel;
+    /** MUST NOT throw: the L6 server calls this in a polling loop. */
+    healthCheck(): HealthStatus;
+    private resolveStateDirSafe;
+}
+export {};

package/dist/export-store-base.js

@@ -0,0 +1,316 @@
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * Shared mechanics for the "JSON export store" participant family.
+ *
+ * Bolt.new, Lovable and v0 are cloud builders that persist nothing useful on
+ * the user's machine, so each federates through a directory the user exports
+ * into:
+ *
+ *     $<AGENT>_STATE_DIR/          (default: ~/.<agent>/)
+ *         projects.json            array of project records, or {projects: [...]}
+ *         sessions/<id>.json       one JSON document per session
+ *
+ * The oracle implements this three times (`participants/{bolt,lovable,v0}.py`,
+ * ~1,130 lines). The store layout, the date parser, the visibility parser, the
+ * loader's error semantics and the health-check ladder are identical across
+ * all three, so they live here once.
+ *
+ * ⚠ What is NOT shared: each reader's `projectToEntity` / `sessionToRecord`.
+ * They look similar and are not the same — Lovable caps a project name at 120
+ * characters where Bolt caps at 80, emits a NULL summary where Bolt emits a
+ * `"Bolt.new project <name>"` fallback, and appends its own tag
+ * unconditionally where Bolt inserts only if absent (so Lovable really can
+ * emit a duplicate tag). Those differences are the oracle's behaviour and the
+ * mirror reproduces them rather than tidying them into agreement; each reader
+ * supplies its own mapper.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Visibility, filterForFederation, makeAgentInfo, makeManifest, } from "@getbourdon/l5";
+import { redactText } from "@getbourdon/redaction";
+import { ParticipantDiscoveryError, ParticipantExportError, SPEC_VERSION } from "./base.js";
+const VISIBILITY_VALUES = new Set(Object.values(Visibility));
+/**
+ * `_parse_visibility`: a recognized visibility string, else null (meaning
+ * "inherit the policy default"), never a throw.
+ */
+export function parseVisibility(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const value = raw.trim().toLowerCase();
+    return VISIBILITY_VALUES.has(value) ? value : null;
+}
+/**
+ * `_iso_date`: normalize to a bare `YYYY-MM-DD`, or null if unparseable.
+ *
+ * Accepts a full ISO timestamp (trailing `Z` included) and reduces it to its
+ * date, which is what every L5 date field carries.
+ */
+export function isoDate(raw) {
+    if (typeof raw !== "string" || !raw.trim())
+        return null;
+    const text = raw.trim();
+    if (text.includes("T")) {
+        const parsed = new Date(text.replace(/Z$/, "+00:00"));
+        if (Number.isNaN(parsed.getTime()))
+            return null;
+        return parsed.toISOString().slice(0, 10);
+    }
+    // Python's strptime("%Y-%m-%d") rejects anything else, including a real
+    // date in another format — matched here rather than letting Date() guess.
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(text))
+        return null;
+    const parsed = new Date(`${text}T00:00:00Z`);
+    if (Number.isNaN(parsed.getTime()))
+        return null;
+    // Rejects 2026-02-31, which the regex alone would accept.
+    return parsed.toISOString().slice(0, 10) === text ? text : null;
+}
+/** `_safe_str`: trim, then route through the redaction SSOT. "" stays "". */
+export function safeStr(raw, limit = 240) {
+    if (raw === null || raw === undefined)
+        return "";
+    const text = String(raw).trim();
+    return text ? redactText(text, limit) : "";
+}
+/** `_str_list` in the Bolt/v0 spelling: redact every item, drop the empties. */
+export function safeStrList(raw, limit = 200) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        const cleaned = safeStr(item, limit);
+        if (cleaned)
+            out.push(cleaned);
+    }
+    return out;
+}
+export class ExportStoreParticipant {
+    agentId;
+    agentType;
+    displayName;
+    config;
+    stateDir;
+    env;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.agentId = config.agentId;
+        this.agentType = config.agentType;
+        this.displayName = config.displayName;
+        this.stateDir = options.stateDir;
+        this.env = options.env ?? process.env;
+    }
+    static defaultNativePath(directoryName, home) {
+        return join(home ?? homedir(), directoryName);
+    }
+    get nativePath() {
+        return this.resolveStateDir();
+    }
+    resolveStateDir() {
+        if (this.stateDir !== undefined)
+            return this.stateDir;
+        const override = (this.env[this.config.stateEnvVar] ?? "").trim();
+        if (override)
+            return override;
+        return ExportStoreParticipant.defaultNativePath(this.config.directoryName);
+    }
+    requireStateDir() {
+        const dir = this.resolveStateDir();
+        if (!isDir(dir)) {
+            throw new ParticipantDiscoveryError(`${this.config.label} state directory not found at '${dir}'.`);
+        }
+        return dir;
+    }
+    /**
+     * `projects.json`, accepting either a bare array or `{projects: [...]}`.
+     *
+     * A MISSING file is empty (the store may legitimately hold only sessions);
+     * a PRESENT but unreadable or wrongly-shaped file throws. The distinction is
+     * the point: absence is a state, corruption is an error.
+     */
+    loadProjects(stateDir) {
+        const path = join(stateDir, "projects.json");
+        if (!isFile(path))
+            return [];
+        let payload;
+        try {
+            payload = JSON.parse(stripBom(readFileSync(path, "utf-8")));
+        }
+        catch (exc) {
+            throw new ParticipantExportError(`${this.config.label} projects store present but unreadable at ${path}: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
+        if (Array.isArray(payload))
+            return payload.filter(isDict);
+        if (isDict(payload) && Array.isArray(payload.projects))
+            return payload.projects.filter(isDict);
+        throw new ParticipantExportError(`${this.config.label} projects store at ${path} must be a JSON array or object with projects list.`);
+    }
+    sessionFiles(stateDir) {
+        const dir = join(stateDir, "sessions");
+        if (!isDir(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".json"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    /** Newest first. An unreadable session is skipped, never fatal. */
+    loadSessions(stateDir) {
+        const out = [];
+        for (const path of this.sessionFiles(stateDir)) {
+            let payload;
+            try {
+                payload = JSON.parse(stripBom(readFileSync(path, "utf-8")));
+            }
+            catch {
+                continue;
+            }
+            if (!isDict(payload))
+                continue;
+            const session = this.config.sessionToRecord(payload, null);
+            if (session !== null)
+                out.push(session);
+        }
+        out.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+        return out;
+    }
+    discover() {
+        const stateDir = this.resolveStateDir();
+        if (!isDir(stateDir)) {
+            throw new ParticipantDiscoveryError(`${this.config.label} state directory not found at '${stateDir}'. ` +
+                `Create it and add a projects.json export or run \`${this.config.initCommand}\`.`);
+        }
+        return {
+            path: stateDir,
+            version: "export-v1",
+            metadata: {
+                projects_file: isFile(join(stateDir, "projects.json")),
+                session_files: this.sessionFiles(stateDir).length,
+                env_override: Boolean((this.env[this.config.stateEnvVar] ?? "").trim()),
+            },
+        };
+    }
+    exportSessions(since, limit = 100) {
+        const stateDir = this.requireStateDir();
+        const sinceIso = since.toISOString().slice(0, 10);
+        // `limit` is honoured, not decorative: a caller asking for 5 gets 5.
+        return this.loadSessions(stateDir)
+            .filter((s) => s.date >= sinceIso)
+            .slice(0, limit);
+    }
+    exportL5(since) {
+        const stateDir = this.requireStateDir();
+        let sessions = this.loadSessions(stateDir);
+        if (since !== undefined && since !== null) {
+            const sinceIso = since.toISOString().slice(0, 10);
+            sessions = sessions.filter((s) => s.date >= sinceIso);
+        }
+        const entities = [];
+        const seen = new Set();
+        for (const record of this.loadProjects(stateDir)) {
+            const entity = this.config.projectToEntity(record);
+            if (entity === null)
+                continue;
+            const key = entity.name.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            entities.push(entity);
+        }
+        // The PII guardrail, and it belongs HERE: L6 trusts whatever a participant
+        // emits, so an entity that resolves to PRIVATE must never leave this
+        // function. Filtering downstream would be too late.
+        const visibleEntities = filterForFederation(entities, this.config.policy);
+        return makeManifest({
+            spec_version: SPEC_VERSION,
+            agent: makeAgentInfo({
+                id: this.config.agentId,
+                type: this.config.agentType,
+                role_narrative: this.config.roleNarrative,
+                spec_version_compat: SPEC_VERSION,
+            }),
+            last_updated: new Date().toISOString().replace(/\.\d{3}Z$/, "+00:00"),
+            capabilities: [...this.config.capabilities],
+            recent_sessions: sessions,
+            known_entities: visibleEntities,
+            visibility_policy: this.config.policy,
+        });
+    }
+    /** MUST NOT throw: the L6 server calls this in a polling loop. */
+    healthCheck() {
+        try {
+            const stateDir = this.resolveStateDir();
+            if (!isDir(stateDir)) {
+                return {
+                    status: "blocked",
+                    reason: `${this.config.label} state directory not found at '${stateDir}'.`,
+                    details: { expected: stateDir },
+                    proposedFix: `Run \`${this.config.initCommand}\` or create ${stateDir} and add projects.json.`,
+                };
+            }
+            const projectsFile = join(stateDir, "projects.json");
+            const sessionFiles = this.sessionFiles(stateDir);
+            if (!isFile(projectsFile) && sessionFiles.length === 0) {
+                return {
+                    status: "degraded",
+                    reason: "State directory exists but contains no projects.json or sessions.",
+                    details: { path: stateDir },
+                    proposedFix: `Run \`${this.config.initCommand}\` or export projects into projects.json.`,
+                };
+            }
+            // Parse both, so a corrupt store reports degraded here instead of
+            // throwing later inside a federation read.
+            this.loadProjects(stateDir);
+            this.loadSessions(stateDir);
+            return {
+                status: "ok",
+                details: {
+                    path: stateDir,
+                    projects_file: isFile(projectsFile),
+                    session_files: sessionFiles.length,
+                },
+            };
+        }
+        catch (exc) {
+            return {
+                status: "degraded",
+                reason: exc instanceof Error ? exc.message : String(exc),
+                details: {},
+                proposedFix: `Inspect ${this.resolveStateDirSafe()}/projects.json for syntax errors.`,
+            };
+        }
+    }
+    resolveStateDirSafe() {
+        try {
+            return this.resolveStateDir();
+        }
+        catch {
+            return `~/${this.config.directoryName}`;
+        }
+    }
+}
+// -- helpers ------------------------------------------------------------------
+function isDict(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Python reads these with `encoding="utf-8-sig"`, so a BOM is not a parse error. */
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}