@getbourdon/participants 0.3.1 → 0.4.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { L5ManifestModel, SessionModel, VisibilityPolicyModel } from '@getbourdon/l5';
+import { L5ManifestModel, SessionModel, VisibilityPolicyModel, EntityModel, Visibility } from '@getbourdon/l5';
 export { EntityModel, L5ManifestModel, SessionModel, Visibility, VisibilityPolicyModel, applyVisibility, filterForFederation, toDict, validateManifest } from '@getbourdon/l5';
 import DatabaseT from 'better-sqlite3';
 
@@ -1081,4 +1081,172 @@ declare function discoverParticipants(ctors?: ParticipantCtor[]): BourdonPartici
  */
 declare function resolvePluginParticipants(): ParticipantCtor[];
 
-export { type AgentStore, type AuthProvider, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, CascadeParticipant, ClaudeCodeAutomationsParticipant, ClaudeCodeParticipant, ClaudeDesktopCodeParticipant, ClaudeDesktopCoworkParticipant, CodexAutomationsParticipant, CopilotAutomationsParticipant, CopilotCliParticipant, CopilotParticipant, CopilotVscodeParticipant, CursorAutomationsParticipant, CursorParticipant, DEFAULT_CACHE_TTL_SECONDS, DEFAULT_RECENT_THREAD_LIMIT, DEFAULT_TITLE_LIMIT, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, MIN_PATCHED_VERSION, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, OpenClawApiClient, OpenClawParticipant, type OpenReadonlyOptions, PROJECT_HINTS_ENV, ParticipantAuthError, type ParticipantCtor, ParticipantDiscoveryError, ParticipantError, ParticipantExportError, ParticipantVersionMismatchError, PayloadCache, type RecentThread, SPEC_VERSION, type SqliteDatabase, defaultCacheRoot, discoverParticipants, envAuthProvider, epochToIsoDate, epochToIsoDatetime, friendlyLabel, ghTokenProvider, isParticipant, loadProjectHints, openReadonly, parseSessionIndex, projectKeyFromCwd, recentSessionThreads, resolveCodexHome, resolvePluginParticipants, sessionThreadTitles, sqliteAvailable, tableColumns, tableExists, tryOpenReadonly, verifyInstance };
+/**
+ * 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.
+ */
+
+type Dict = Record<string, unknown>;
+/**
+ * `_parse_visibility`: a recognized visibility string, else null (meaning
+ * "inherit the policy default"), never a throw.
+ */
+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.
+ */
+declare function isoDate(raw: unknown): string | null;
+/** `_safe_str`: trim, then route through the redaction SSOT. "" stays "". */
+declare function safeStr(raw: unknown, limit?: number): string;
+/** `_str_list` in the Bolt/v0 spelling: redact every item, drop the empties. */
+declare function safeStrList(raw: unknown, limit?: number): string[];
+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;
+}
+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;
+}
+
+/**
+ * StackBlitz Bolt.new participant — port of `participants/bolt.py`.
+ *
+ * Bolt.new builds and runs full-stack apps in WebContainers, in the browser,
+ * so nothing useful lands on the user's machine. It federates through an
+ * export directory; see {@link ExportStoreParticipant} for the store layout
+ * and the mechanics this shares with Lovable and v0.
+ */
+
+declare const BOLT_CONFIG: ExportStoreConfig;
+declare class BoltParticipant extends ExportStoreParticipant {
+    constructor(options?: {
+        stateDir?: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    static defaultNativePath(home?: string): string;
+}
+
+/**
+ * Lovable participant — port of `participants/lovable.py`.
+ *
+ * Lovable builds full-stack web apps from chat in the cloud, so nothing useful
+ * lands on the user's machine. It federates through an export directory; see
+ * {@link ExportStoreParticipant} for the store layout and the mechanics this
+ * shares with Bolt.new and v0.
+ *
+ * ⚠ The mapper below is NOT Bolt's with the names swapped, and must not be
+ * refactored into it. Lovable's oracle differs in four ways, each reproduced
+ * exactly here:
+ *
+ *   1. the project name is capped at 120 characters, not 80;
+ *   2. a record with no description yields a NULL summary, where Bolt
+ *      synthesizes `"Bolt.new project <name>"`;
+ *   3. the `"lovable"` tag is APPENDED unconditionally, so a record that
+ *      already carries it ends up with it twice — Bolt inserts only if absent;
+ *   4. `updated_at` falls back to `created_at`, where Bolt leaves
+ *      `last_touched` null.
+ *
+ * (3) also means the tag lands LAST rather than first. None of this is
+ * defensible design; all of it is what the oracle does, and the mirror's job
+ * is to agree with the oracle, not to improve on it. Fixing any of it is an
+ * oracle-side change the conformance fixtures would have to absorb first.
+ */
+
+declare const LOVABLE_CONFIG: ExportStoreConfig;
+declare class LovableParticipant extends ExportStoreParticipant {
+    constructor(options?: {
+        stateDir?: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    static defaultNativePath(home?: string): string;
+}
+
+/**
+ * Vercel v0 participant — port of `participants/v0.py`.
+ *
+ * v0 generates React / Next.js / Tailwind UI and full-stack web apps from
+ * chat, entirely server-side, so nothing useful lands on the user's machine.
+ * It federates through an export directory; see {@link ExportStoreParticipant}
+ * for the store layout and the mechanics this shares with Bolt.new and
+ * Lovable. The mapper below is byte-for-byte Bolt's rule with v0's own name
+ * and tag — that is the oracle's shape, not a shortcut taken here.
+ */
+
+declare const V0_CONFIG: ExportStoreConfig;
+declare class V0Participant extends ExportStoreParticipant {
+    constructor(options?: {
+        stateDir?: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    static defaultNativePath(home?: string): string;
+}
+
+export { type AgentStore, type AuthProvider, BOLT_CONFIG, BoltParticipant, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, CascadeParticipant, ClaudeCodeAutomationsParticipant, ClaudeCodeParticipant, ClaudeDesktopCodeParticipant, ClaudeDesktopCoworkParticipant, CodexAutomationsParticipant, CopilotAutomationsParticipant, CopilotCliParticipant, CopilotParticipant, CopilotVscodeParticipant, CursorAutomationsParticipant, CursorParticipant, DEFAULT_CACHE_TTL_SECONDS, DEFAULT_RECENT_THREAD_LIMIT, DEFAULT_TITLE_LIMIT, type ExportStoreConfig, ExportStoreParticipant, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, LOVABLE_CONFIG, LovableParticipant, MIN_PATCHED_VERSION, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, OpenClawApiClient, OpenClawParticipant, type OpenReadonlyOptions, PROJECT_HINTS_ENV, ParticipantAuthError, type ParticipantCtor, ParticipantDiscoveryError, ParticipantError, ParticipantExportError, ParticipantVersionMismatchError, PayloadCache, type RecentThread, SPEC_VERSION, type SqliteDatabase, V0Participant, V0_CONFIG, defaultCacheRoot, discoverParticipants, envAuthProvider, epochToIsoDate, epochToIsoDatetime, friendlyLabel, ghTokenProvider, isParticipant, isoDate, loadProjectHints, openReadonly, parseSessionIndex, parseVisibility, projectKeyFromCwd, recentSessionThreads, resolveCodexHome, resolvePluginParticipants, safeStr, safeStrList, sessionThreadTitles, sqliteAvailable, tableColumns, tableExists, tryOpenReadonly, verifyInstance };

package/dist/index.d.ts

@@ -41,3 +41,7 @@ export { DEFAULT_RECENT_THREAD_LIMIT, DEFAULT_TITLE_LIMIT, parseSessionIndex, re
 export type { RecentThread } from "./readers/codex-sessions.js";
 export { FIRST_PARTY, discoverParticipants, resolvePluginParticipants, type ParticipantCtor, } from "./registry.js";
 export { Visibility, applyVisibility, filterForFederation, toDict, validateManifest, type EntityModel, type L5ManifestModel, type SessionModel, type VisibilityPolicyModel, } from "@getbourdon/l5";
+export { ExportStoreParticipant, isoDate, parseVisibility, safeStr, safeStrList, type ExportStoreConfig, } from "./export-store-base.js";
+export { BOLT_CONFIG, BoltParticipant } from "./readers/bolt.js";
+export { LOVABLE_CONFIG, LovableParticipant } from "./readers/lovable.js";
+export { V0_CONFIG, V0Participant } from "./readers/v0.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: BUSL-1.1
 /**
  * @getbourdon/participants — the external-agent → L5 reader layer (BUSL-1.1).
  *
@@ -51,3 +52,11 @@ export { FIRST_PARTY, discoverParticipants, resolvePluginParticipants, } from ".
 // Re-exported from @getbourdon/l5 for convenience (the L5 model + serialization
 // the readers build on; only this output shape is the parity contract).
 export { Visibility, applyVisibility, filterForFederation, toDict, validateManifest, } from "@getbourdon/l5";
+// The JSON export-store family — cloud builders that persist nothing locally
+// and federate through an exported directory. The shared mechanics live in
+// export-store-base.ts; each reader keeps its OWN entity/session mapper,
+// because the oracle's three differ in ways that are not cosmetic.
+export { ExportStoreParticipant, isoDate, parseVisibility, safeStr, safeStrList, } from "./export-store-base.js";
+export { BOLT_CONFIG, BoltParticipant } from "./readers/bolt.js";
+export { LOVABLE_CONFIG, LovableParticipant } from "./readers/lovable.js";
+export { V0_CONFIG, V0Participant } from "./readers/v0.js";