@getbourdon/participants 0.2.2 → 0.2.4

package/dist/sqlite-base.js

@@ -0,0 +1,163 @@
+/**
+ * Shared read-only SQLite + normalization helpers — port of
+ * `participants/_sqlite_base.py`.
+ *
+ * A SQLite-backed participant (hermes today; cursor/copilot_cli in the follow-on
+ * slice) reads a foreign agent's native DB read-only so a live writer's lock can
+ * never block the export, probes the schema defensively (native schemas drift
+ * across versions), and turns epoch timestamps + paths into the L5 shapes.
+ *
+ * `better-sqlite3` is a NATIVE addon. It is loaded lazily through `createRequire`
+ * inside a try/catch so this package — and the file/network readers — keep
+ * working even on a toolchain where the addon failed to build: in that case
+ * {@link sqliteAvailable} returns false and the sqlite readers degrade rather
+ * than crashing import. Nothing here applies visibility or builds manifests;
+ * that stays in the participant (per PARTICIPANT_CONTRACT.md).
+ */
+import { statSync } from "node:fs";
+import { createRequire } from "node:module";
+const moduleUrl = (typeof import.meta !== "undefined" && import.meta.url) ||
+    (typeof __filename !== "undefined" ? __filename : process.cwd());
+const nodeRequire = createRequire(moduleUrl);
+let driver;
+/** Lazily resolve the better-sqlite3 constructor, or null if the addon is
+ * unavailable (failed native build). Cached after the first attempt. */
+function loadDriver() {
+    if (driver !== undefined)
+        return driver;
+    try {
+        driver = nodeRequire("better-sqlite3");
+    }
+    catch {
+        driver = null;
+    }
+    return driver;
+}
+/** True when the better-sqlite3 native addon loaded successfully. Tests gate
+ * the SQLite-reader assertions on this so a missing addon skips, not fails. */
+export function sqliteAvailable() {
+    return loadDriver() !== null;
+}
+// -- Read-only connection -----------------------------------------------------
+/**
+ * Open a SQLite DB read-only so a live writer is never disturbed. The default
+ * (`immutable` omitted) is the safe `mode=ro`: it respects SQLite locking and
+ * reads the `-wal` sidecar of a live, actively-writing agent. Raises on a
+ * genuine open failure; callers wanting the never-raises contract use
+ * {@link tryOpenReadonly}.
+ */
+export function openReadonly(dbPath, opts = {}) {
+    const Ctor = loadDriver();
+    if (!Ctor) {
+        throw new Error("better-sqlite3 native addon is not available");
+    }
+    // better-sqlite3 maps `{readonly:true}` to SQLITE_OPEN_READONLY. There is no
+    // first-class `immutable=1` knob; for our static snapshots `readonly` is
+    // sufficient (we never open a concurrently-written fixture DB).
+    return new Ctor(dbPath, {
+        readonly: true,
+        fileMustExist: true,
+        timeout: opts.timeoutMs ?? 2000,
+    });
+}
+/**
+ * Like {@link openReadonly} but returns null instead of raising — for the
+ * export/health path where a missing or corrupt DB must degrade to "no rows".
+ */
+export function tryOpenReadonly(dbPath, opts = {}) {
+    try {
+        if (!statSync(dbPath).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    try {
+        return openReadonly(dbPath, opts);
+    }
+    catch {
+        return null;
+    }
+}
+// -- Defensive schema probes --------------------------------------------------
+/** True if `name` is a table in the connected DB (swallows errors → false). */
+export function tableExists(db, name) {
+    try {
+        const row = db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=? LIMIT 1")
+            .get(name);
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** Column names for `table` (empty set if absent / on error). PRAGMA cannot be
+ * parameterized, matching the Python f-string. */
+export function tableColumns(db, table) {
+    try {
+        const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+        return new Set(rows.map((r) => r.name));
+    }
+    catch {
+        return new Set();
+    }
+}
+// -- Normalization ------------------------------------------------------------
+function toFiniteNumber(value) {
+    if (value === null || value === undefined)
+        return null;
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Convert epoch seconds (number/string) to an ISO `YYYY-MM-DD` UTC date, or
+ * null for missing/unparseable values. Mirrors `epoch_to_iso_date`.
+ */
+export function epochToIsoDate(value) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return null;
+    const d = new Date(n * 1000);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * Convert epoch seconds to a full ISO 8601 UTC datetime, or null. The offset is
+ * rendered `+00:00` (Python `datetime(...).isoformat()` style) rather than `Z`.
+ */
+export function epochToIsoDatetime(value) {
+    const n = toFiniteNumber(value);
+    if (n === null)
+        return null;
+    const d = new Date(n * 1000);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return d.toISOString().replace(/\.\d{3}Z$/, "+00:00").replace(/Z$/, "+00:00");
+}
+function basenameOf(p) {
+    const trimmed = p.replace(/[\\/]+$/, "");
+    const parts = trimmed.split(/[\\/]/);
+    return parts[parts.length - 1] ?? "";
+}
+/**
+ * Derive a lowercase project key from a working-directory path: the basename
+ * lowercased, or null when the cwd is empty or its basename is "generic"
+ * (carries no project identity). Mirrors `project_key_from_cwd`.
+ */
+export function projectKeyFromCwd(cwd, genericNames = new Set()) {
+    if (!cwd)
+        return null;
+    const name = basenameOf(cwd).trim().toLowerCase();
+    if (!name || genericNames.has(name))
+        return null;
+    return name;
+}
+/** Turn a slug-ish key (`my-cool_project`) into a Title Case label. */
+export function friendlyLabel(key) {
+    return key
+        .replace(/[-_]+/g, " ")
+        .trim()
+        .replace(/\S+/g, (w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getbourdon/participants",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Bourdon participants — the external-agent → L5 reader layer (BUSL-1.1). Each participant normalizes a foreign agent's native memory store into a visibility-filtered, redacted L5 manifest: read-only SQLite readers (better-sqlite3 mode=ro: hermes), file/convention readers (claude-code), and network readers (github-copilot) with a TTL JSON cache + lazy AuthProvider that never persists a token. Four invariants enforced in code, not by trust: visibility-filter-before-emission, deterministic exportL5, healthCheck never throws, redact every native string. Discovery is a static TS registry (agent_id-sorted, first-wins, log-and-skip) replacing Python's pkgutil scan. Python (pip install bourdon) is the oracle; this mirror asserts against @getbourdon/conformance native_stores fixtures.",
   "license": "BUSL-1.1",
   "type": "module",
@@ -29,21 +29,21 @@
   "homepage": "https://bourdon.ai",
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/getbourdon/bourdon-js.git",
+    "url": "git+https://gitlab.com/bourdonai/bourdon-js.git",
     "directory": "packages/participants"
   },
   "dependencies": {
     "smol-toml": "^1.7.0",
     "yaml": "^2.6.1",
-    "@getbourdon/l5": "0.1.2",
-    "@getbourdon/redaction": "0.1.2"
+    "@getbourdon/l5": "0.3.0",
+    "@getbourdon/redaction": "0.1.4"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.2.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",
-    "@getbourdon/conformance": "0.2.1"
+    "@getbourdon/conformance": "0.3.0"
   },
   "scripts": {
     "build": "tsup",