@getbourdon/participants 0.2.0 → 0.2.2

package/dist/readers/copilot.js

@@ -1,413 +0,0 @@
-/**
- * GitHub Copilot (local convention) participant — reads the convention-based
- * memory file at `~/.copilot-bourdon/memory.md`. Port of `participants/copilot.py`.
- *
- * Copilot has no accessible local session index (its reasoning is cloud-side and
- * its native memory is not exposed on disk), so — like the Codex pre-distillation
- * fallback — this reader normalizes a user-maintained convention file into a
- * Bourdon L5 manifest. The file is YAML front-matter (structured `entities:` /
- * `sessions:`) followed by an optional freeform markdown body that Copilot Chat
- * reads as plain context but this reader ignores.
- *
- * NOT the cloud GitHub-Copilot network adapter ({@link GitHubCopilotParticipant})
- * and NOT the Copilot CLI SQLite reader.
- *
- * Paths checked (in order):
- *   1. `COPILOT_BOURDON_HOME` env-var override
- *   2. `~/.copilot-bourdon/`  (default convention path)
- *
- * Defensive throughout: a missing convention directory raises
- * {@link ParticipantDiscoveryError} from `discover()`; malformed YAML degrades to
- * an empty manifest rather than raising; `healthCheck` never throws.
- */
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { homedir, hostname } from "node:os";
-import { join } from "node:path";
-import { parse as yamlParse } from "yaml";
-import { Visibility, filterForFederation, makeAgentInfo, makeEntity, makeManifest, makeSession, makeVisibilityPolicy, } from "@getbourdon/l5";
-import { redactText } from "@getbourdon/redaction";
-import { ParticipantDiscoveryError, SPEC_VERSION, } from "../base.js";
-const AGENT_ID = "copilot";
-const AGENT_TYPE = "code-assistant";
-const DISPLAY_NAME = "GitHub Copilot";
-const ROLE_NARRATIVE = "Inline completion and chat assistant present across every IDE the team uses. " +
-    "Works alongside the human at the keystroke level -- the ambient layer that " +
-    "recognises what is being typed before a full turn is even formed. Bourdon " +
-    "gives Copilot cross-session entity awareness it would otherwise lack entirely.";
-// Convention directory and file names. Override dir with COPILOT_BOURDON_HOME.
-const CONVENTION_DIR_NAME = ".copilot-bourdon";
-const MEMORY_FILENAME = "memory.md";
-// Front-matter delimiters (mirrors claude-code's parseFrontmatter conventions).
-const FRONTMATTER_OPEN = "---\n";
-const FRONTMATTER_CLOSE = "\n---\n";
-const DEFAULT_POLICY = makeVisibilityPolicy({
-    default: Visibility.TEAM,
-    private_tags: ["personal", "financial", "credential", "health", "family", "legal"],
-    team_tags: ["copilot-memory", "workspace", "copilot"],
-});
-/** Minimal logger so a degraded read is visible without pulling in a dep
- * (matches the registry's logging idiom). */
-const logger = {
-    warn(msg) {
-        // eslint-disable-next-line no-console
-        console.warn(`[bourdon.participants] ${msg}`);
-    },
-};
-/** Starter template written by `bourdon copilot init`. */
-const MEMORY_TEMPLATE = `---
-# Copilot Bourdon Memory
-# Edit this file to give Copilot cross-session entity awareness.
-# The YAML front-matter is parsed by \`bourdon copilot export\`.
-# The markdown body below the closing \`---\` is freeform context for Copilot Chat.
-
-entities: []
-
-sessions: []
----
-
-# Copilot notes
-
-Add project notes, preferences, or anything else you want Copilot Chat to
-remember here. This section is freeform -- the participant only reads the YAML
-front-matter above.
-`;
-// -- fs helpers ---------------------------------------------------------------
-function homeDir() {
-    // os.homedir() can throw under some sandboxes; stay defensive so import +
-    // construction never crash even when HOME points at an unreadable path.
-    try {
-        return homedir();
-    }
-    catch {
-        return process.env.HOME || process.env.USERPROFILE || ".";
-    }
-}
-function isDir(p) {
-    try {
-        return statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-function isFile(p) {
-    try {
-        return statSync(p).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-// -- Path helpers -------------------------------------------------------------
-/**
- * Return the conventional `~/.copilot-bourdon/` directory path. Respects the
- * `COPILOT_BOURDON_HOME` env-var override (returned verbatim, even if absent;
- * the directory is not created here).
- */
-export function defaultCopilotBourdonDir() {
-    const env = process.env.COPILOT_BOURDON_HOME;
-    if (env)
-        return env;
-    return join(homeDir(), CONVENTION_DIR_NAME);
-}
-/** Return the path to the convention memory file. */
-export function defaultCopilotMemoryPath(copilotDir) {
-    return join(copilotDir || defaultCopilotBourdonDir(), MEMORY_FILENAME);
-}
-// -- Coercion helpers (mirror Python str() / isinstance filtering) ------------
-/** Mirror Python `str(value)` for the value types YAML yields here. The `yaml`
- * lib parses timestamps into JS `Date`; Python's `yaml.safe_load` yields
- * `date`/`datetime` whose `str()` is ISO-ish, so a Date is rendered as its ISO
- * date (date-only callers slice to 10 anyway). */
-function coerceStr(v) {
-    if (v instanceof Date)
-        return v.toISOString().slice(0, 10);
-    return String(v);
-}
-/** Mirror Python `str(raw.get(key) or "") or None`. */
-function strOrUndef(v) {
-    const s = coerceStr(v || "");
-    return s || undefined;
-}
-/** Mirror `[str(x) for x in raw if isinstance(x, str) and x.strip()]`. */
-function strList(v) {
-    if (!Array.isArray(v))
-        return [];
-    return v.filter((x) => typeof x === "string" && x.trim() !== "");
-}
-function isRecord(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-function asArray(v) {
-    return Array.isArray(v) ? v : [];
-}
-// -- YAML frontmatter ---------------------------------------------------------
-/**
- * Extract and parse the YAML front-matter block from memory file text. Returns
- * an empty object when the file has no front-matter or when the YAML cannot be
- * parsed (logged at WARNING in the oracle; never raises here either).
- */
-function parseFrontmatter(text, source) {
-    if (!text.startsWith(FRONTMATTER_OPEN))
-        return {};
-    const end = text.indexOf(FRONTMATTER_CLOSE, FRONTMATTER_OPEN.length);
-    if (end === -1)
-        return {};
-    const fmText = text.slice(FRONTMATTER_OPEN.length, end);
-    let parsed;
-    try {
-        parsed = yamlParse(fmText);
-    }
-    catch (err) {
-        const where = source ? ` in ${source}` : "";
-        const detail = String(err).replace(/\n/g, " ").slice(0, 200);
-        logger.warn(`CopilotParticipant: malformed YAML frontmatter${where}; ` +
-            `treating as no-frontmatter (${detail})`);
-        return {};
-    }
-    return isRecord(parsed) ? parsed : {};
-}
-/**
- * Read and parse a copilot-bourdon memory file. Returns an empty object on any
- * I/O or parse error — the participant degrades to an empty manifest.
- */
-function readMemoryFile(path) {
-    if (!isFile(path))
-        return {};
-    let text;
-    try {
-        text = readFileSync(path, "utf8");
-    }
-    catch (err) {
-        logger.warn(`CopilotParticipant: cannot read ${path}: ${String(err)}`);
-        return {};
-    }
-    return parseFrontmatter(text, path);
-}
-// -- Entity / Session converters ----------------------------------------------
-/** Convert a raw YAML entity record to a Bourdon Entity. Skips malformed
- * entries (oracle logs at DEBUG). Never raises. */
-function buildEntity(raw) {
-    if (!isRecord(raw))
-        return null;
-    const name = raw["name"];
-    if (typeof name !== "string" || name.trim() === "")
-        return null;
-    const summaryRaw = raw["summary"] || "";
-    const summary = summaryRaw ? redactText(coerceStr(summaryRaw)) : undefined;
-    return makeEntity({
-        name: name.trim(),
-        type: strOrUndef(raw["type"]),
-        aliases: strList(raw["aliases"]),
-        summary,
-        last_touched: strOrUndef(raw["last_touched"]),
-        tags: strList(raw["tags"]),
-        valid_from: strOrUndef(raw["valid_from"]),
-        valid_to: strOrUndef(raw["valid_to"]),
-    });
-}
-/** Convert a raw YAML session record to a Bourdon Session. Skips malformed
- * entries (oracle logs at DEBUG). Never raises. */
-function buildSession(raw) {
-    if (!isRecord(raw))
-        return null;
-    const dateVal = raw["date"];
-    if (!dateVal)
-        return null;
-    const dateStr = coerceStr(dateVal).slice(0, 10); // keep YYYY-MM-DD prefix only
-    return makeSession({
-        date: dateStr,
-        cwd: strOrUndef(raw["cwd"]),
-        project_focus: strList(raw["project_focus"]),
-        key_actions: strList(raw["key_actions"]),
-        files_touched: strList(raw["files_touched"]),
-    });
-}
-// -- Diagnostics --------------------------------------------------------------
-/** Diagnostic summary of the copilot-bourdon memory file (`bourdon copilot
- * doctor`). Never raises. */
-export function inspectCopilotMemory(copilotDir) {
-    const memPath = defaultCopilotMemoryPath(copilotDir);
-    const report = {
-        path: memPath,
-        present: isFile(memPath),
-        readable: false,
-        frontmatter_valid: false,
-        entity_count: 0,
-        session_count: 0,
-        error: null,
-    };
-    if (!isFile(memPath)) {
-        report["error"] = "missing";
-        return report;
-    }
-    let text;
-    try {
-        text = readFileSync(memPath, "utf8");
-        report["readable"] = true;
-    }
-    catch (err) {
-        report["error"] = String(err);
-        return report;
-    }
-    const data = parseFrontmatter(text, memPath);
-    if (Object.keys(data).length > 0)
-        report["frontmatter_valid"] = true;
-    report["entity_count"] = asArray(data["entities"]).length;
-    report["session_count"] = asArray(data["sessions"]).length;
-    return report;
-}
-// -- Participant --------------------------------------------------------------
-/**
- * External participant for GitHub Copilot via `~/.copilot-bourdon/memory.md`.
- * Implements {@link BourdonParticipant} structurally.
- */
-export class CopilotParticipant {
-    agentId = AGENT_ID;
-    agentType = AGENT_TYPE;
-    displayName = DISPLAY_NAME;
-    nativePath;
-    /** Conventional `~/.copilot-bourdon` dir used by the setup wizard's detection. */
-    static defaultNativePath(home) {
-        if (home !== undefined)
-            return join(home, CONVENTION_DIR_NAME);
-        return defaultCopilotBourdonDir();
-    }
-    copilotDir;
-    constructor(copilotDir) {
-        this.copilotDir = copilotDir ?? null;
-        this.nativePath = this.copilotDir || defaultCopilotBourdonDir();
-    }
-    discover() {
-        const path = this.copilotDir || defaultCopilotBourdonDir();
-        if (!isDir(path)) {
-            throw new ParticipantDiscoveryError(`Copilot convention directory not found at '${path}'. ` +
-                "Run `bourdon copilot init` to create it with a starter template, " +
-                "or create ~/.copilot-bourdon/memory.md manually.");
-        }
-        const memPath = join(path, MEMORY_FILENAME);
-        return {
-            path,
-            version: "convention-v1",
-            metadata: {
-                memory_file: memPath,
-                memory_file_present: isFile(memPath),
-            },
-        };
-    }
-    exportSessions(since, limit = 100) {
-        const data = this.read();
-        const sinceIso = since ? since.toISOString().slice(0, 10) : null;
-        const sessions = [];
-        for (const raw of asArray(data["sessions"])) {
-            const session = buildSession(raw);
-            if (session === null)
-                continue;
-            if (sinceIso && session.date && session.date < sinceIso)
-                continue;
-            sessions.push(session);
-            if (sessions.length >= limit)
-                break;
-        }
-        return sessions;
-    }
-    exportL5(since) {
-        const data = this.read();
-        const entities = [];
-        for (const raw of asArray(data["entities"])) {
-            const entity = buildEntity(raw);
-            if (entity !== null)
-                entities.push(entity);
-        }
-        const visibleEntities = filterForFederation(entities, DEFAULT_POLICY);
-        const sinceIso = since ? since.toISOString().slice(0, 10) : null;
-        const sessions = [];
-        for (const raw of asArray(data["sessions"])) {
-            const session = buildSession(raw);
-            if (session === null)
-                continue;
-            if (sinceIso && session.date && session.date < sinceIso)
-                continue;
-            sessions.push(session);
-        }
-        return makeManifest({
-            spec_version: SPEC_VERSION,
-            agent: makeAgentInfo({
-                id: AGENT_ID,
-                type: AGENT_TYPE,
-                instance: hostname() || "unknown",
-                spec_version_compat: `>=${SPEC_VERSION}`,
-                role_narrative: ROLE_NARRATIVE,
-            }),
-            last_updated: new Date().toISOString(),
-            capabilities: ["inline-completion", "chat", "pr-review", "convention-memory"],
-            recent_sessions: sessions,
-            known_entities: visibleEntities,
-            visibility_policy: DEFAULT_POLICY,
-        });
-    }
-    healthCheck() {
-        const path = this.copilotDir || defaultCopilotBourdonDir();
-        if (!isDir(path)) {
-            return {
-                status: "blocked",
-                reason: `Convention directory ${path} not found. ` +
-                    "Run `bourdon copilot init` to create it.",
-                details: { expected_path: path },
-                proposedFix: "Run `bourdon copilot init` to create the convention directory.",
-            };
-        }
-        const memPath = join(path, MEMORY_FILENAME);
-        if (!isFile(memPath)) {
-            return {
-                status: "degraded",
-                reason: `Memory file ${memPath} not found. ` +
-                    "Run `bourdon copilot init` to write a starter template.",
-                details: { expected_memory_file: memPath },
-                proposedFix: "Run `bourdon copilot init` to write the starter memory.md template.",
-            };
-        }
-        let data;
-        try {
-            data = this.read();
-        }
-        catch (err) {
-            logger.warn(`CopilotParticipant health_check failed: ${String(err)}`);
-            return {
-                status: "degraded",
-                reason: "Memory file present but could not be parsed.",
-                details: { error: String(err) },
-                proposedFix: `Inspect ${memPath} for malformed YAML front-matter. ` +
-                    "The opening and closing `---` fences must wrap a valid YAML " +
-                    "block. See docs/agent-integration-status.md for the schema.",
-            };
-        }
-        return {
-            status: "ok",
-            details: {
-                memory_file: memPath,
-                entity_count: asArray(data["entities"]).length,
-                session_count: asArray(data["sessions"]).length,
-            },
-        };
-    }
-    // -- Internal ---------------------------------------------------------------
-    read() {
-        return readMemoryFile(defaultCopilotMemoryPath(this.copilotDir));
-    }
-}
-// -- Init helper --------------------------------------------------------------
-/**
- * Create `~/.copilot-bourdon/memory.md` with a starter template. Returns the
- * written path. Throws when the file already exists unless `force` is true.
- */
-export function initMemoryFile(copilotDir, force = false) {
-    const targetDir = copilotDir || defaultCopilotBourdonDir();
-    mkdirSync(targetDir, { recursive: true });
-    const memPath = join(targetDir, MEMORY_FILENAME);
-    if (isFile(memPath) && !force) {
-        throw new Error(`${memPath} already exists. Pass --force to overwrite.`);
-    }
-    writeFileSync(memPath, MEMORY_TEMPLATE, "utf8");
-    return memPath;
-}

package/dist/readers/cursor.d.ts

@@ -1,50 +0,0 @@
-/**
- * Cursor participant — reads Cursor's (the AI-first IDE) SQLite-backed
- * workspace/composer state and normalizes it into L5. Port of
- * `participants/cursor.py` + the extraction helper `participants/_cursor_sqlite.py`.
- *
- * Cursor stores workspace state in `state.vscdb` SQLite DBs at platform-specific
- * paths (`~/.config/Cursor/`, `~/Library/Application Support/Cursor/`,
- * `%APPDATA%/Cursor/`). This reader discovers those stores, reads the `ItemTable`
- * key/value rows read-only, parses the composer/chat records into sessions +
- * project/topic entities, and merges curated `.cursor/memory/short-index.json`
- * entities alongside them.
- *
- * SQLite access: the Python oracle copies each DB (+ its `-wal`/`-shm`
- * companions) to a tmp file and opens it read-write so SQLite folds the WAL into
- * a consistent snapshot. The TS mirror instead leans on {@link tryOpenReadonly}
- * (`mode=ro`), which respects SQLite locking and reads the `-wal` sidecar of a
- * live writer — the same consistent view without the copy. Read-only,
- * deterministic, visibility-enforced-before-emission, redaction on every native
- * string; `healthCheck` never throws.
- */
-import { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
-import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
-/**
- * Platform-specific Cursor data dir (the SQLite workspace state lives here),
- * `$CURSOR_DIR` override first. Returns null on an unrecognized platform (or
- * Windows without `%APPDATA%`). Mirrors `default_cursor_dir`.
- */
-export declare function defaultCursorDir(): string | null;
-/** External participant for Cursor's SQLite workspace state. */
-export declare class CursorParticipant implements BourdonParticipant {
-    agentId: string;
-    agentType: string;
-    private readonly cursorDir;
-    private readonly workspaceRoot;
-    private readonly policy;
-    /**
-     * Conventional Cursor config dir (`~/.cursor`) used by the setup wizard. The
-     * wizard probes `~/.cursor` for presence; the SQLite workspace state that
-     * `exportL5` actually reads lives at {@link defaultCursorDir}. Detection and
-     * extraction intentionally use different anchors.
-     */
-    static defaultNativePath(home?: string): string;
-    constructor(cursorDir?: string | null, workspaceRoot?: string | null);
-    get nativePath(): string;
-    discover(): AgentStore;
-    exportSessions(since?: Date, limit?: number): SessionModel[];
-    exportL5(since?: Date): L5ManifestModel;
-    healthCheck(): HealthStatus;
-    private extract;
-}