@druumen/sessions-db 0.1.0

package/lib/index.mjs

@@ -0,0 +1,145 @@
+/**
+ * @druumen/sessions-db — public library entry.
+ *
+ * Curated re-export hub for the v0.1.0 public surface. Library consumers
+ * (cockpit's primary integration target, plus any future tooling that talks
+ * to sessions-db without spawning the CLI) should import EXCLUSIVELY from
+ * `@druumen/sessions-db` (this file) — never from the deeper
+ * `@druumen/sessions-db/lib/<module>.mjs` paths.
+ *
+ * The depth-paths still resolve (the package.json `exports` would let them),
+ * but they're treated as unstable internals — no semver guarantee. This
+ * file is the documented surface; anything not re-exported here is subject
+ * to refactor without notice.
+ *
+ * Type-side mirror: `types/index.d.ts` (hand-crafted) re-exports the
+ * matching TypeScript types so cockpit can write
+ *
+ *     import { setAlias, watchProjection, type Projection } from '@druumen/sessions-db';
+ *
+ * and resolve everything through one entry.
+ */
+
+// ---------------------------------------------------------------------------
+// Storage primitives — for consumers that already have a fully-built event
+// and want direct lock-and-apply control. Most consumers should use
+// `operations.*` (validated, structured-result wrappers) instead.
+// ---------------------------------------------------------------------------
+
+export {
+  loadProjection,
+  rebuildProjection,
+  recordSessionSeen,
+  tryUpdateProjection,
+  newEvent,
+  appendEvent,
+  readAllEvents,
+  saveProjection,
+  PATHS,
+  MAX_EVENT_BYTES,
+} from './storage.mjs';
+
+// ---------------------------------------------------------------------------
+// Operations — the primary write surface for library consumers. Each
+// function: validates input, ensures the target session exists, writes
+// the event under the projection lock, returns
+// `{ ok, event_id?, error? }`.
+// ---------------------------------------------------------------------------
+
+export {
+  setAlias,
+  linkTask,
+  unlinkTask,
+  setParent,
+  closeSession,
+  runSweep,
+} from './operations.mjs';
+
+// ---------------------------------------------------------------------------
+// Lifecycle — initialize storage and watch projection for changes.
+// ---------------------------------------------------------------------------
+
+export { initProjection } from './init.mjs';
+export { watchProjection } from './watch.mjs';
+
+// ---------------------------------------------------------------------------
+// Path resolution — exposed so library consumers (cockpit Setup Wizard,
+// debug tooling) can introspect which storage location the resolver picks
+// before they commit to it. The same chain is used internally by every
+// storage primitive; surface it for explicit callers.
+// ---------------------------------------------------------------------------
+
+export {
+  resolveStoragePaths,
+  pathsFromRoot,
+  STORAGE_FILENAMES,
+  MAX_ASCEND_DEPTH,
+} from './paths.mjs';
+
+// ---------------------------------------------------------------------------
+// Identity — pure helpers for resolving stable_id from a Claude session
+// signal set. Useful for consumers that want to introspect the resolution
+// chain (e.g. visualize "matched by lineage" in a UI) without minting.
+// ---------------------------------------------------------------------------
+
+export {
+  resolveIdentity,
+  findByClaudeSessionId,
+  findByTranscriptLineage,
+  scanFingerprintCandidates,
+  collectParentCandidates,
+  capParentCandidates,
+  classifyCorroborators,
+  meetsThreshold,
+  MAX_PARENT_CANDIDATES,
+  STRONG_CORROBORATORS,
+  WEAK_CORROBORATORS,
+} from './identity.mjs';
+
+// ---------------------------------------------------------------------------
+// Sweep — pure planner. `runSweep` (above) wraps these for actual writes,
+// but consumers may want the planner alone (e.g. preview UI in cockpit).
+// ---------------------------------------------------------------------------
+
+export {
+  computeSweepTransitions,
+  computeEffectiveLastProgress,
+} from './sweep.mjs';
+
+// ---------------------------------------------------------------------------
+// Sanitize — pure prompt-cleanup helpers used by the hook to redact PII /
+// IDE wrappers / system reminders before persistence. Re-exported so any
+// consumer constructing payloads outside the hook can apply the same
+// guarantees.
+// ---------------------------------------------------------------------------
+
+export {
+  sanitizeFirstPrompt,
+  stripIdeWrappers,
+  stripSystemReminders,
+} from './sanitize.mjs';
+
+// ---------------------------------------------------------------------------
+// UUIDv7 — session_id minter + helpers. Cockpit currently relies on
+// `generateSessionId` to mint synthetic ids in tests; expose for parity
+// with the internal hook.
+// ---------------------------------------------------------------------------
+
+export {
+  generateSessionId,
+  isSessionId,
+  extractTimestamp,
+} from './uuid.mjs';
+
+// ---------------------------------------------------------------------------
+// Projection reducers — pure folders. Surface them so library consumers
+// (and tests) can build projections from event arrays without importing
+// the deep path.
+// ---------------------------------------------------------------------------
+
+export {
+  applyEvent,
+  emptyProjection,
+  emptySession,
+  rebuildFromEvents,
+} from './projection.mjs';

package/lib/init.mjs

@@ -0,0 +1,185 @@
+/**
+ * Idempotent storage initializer for sessions-db.
+ *
+ * `initProjection({ rootPath })` is the entry point used by cockpit's Setup
+ * Wizard (and any other library consumer) to bootstrap the on-disk layout
+ * before the first `recordSessionSeen` / CLI write lands. Concretely it:
+ *
+ *   - mkdir -p the parent directory for `tickets/_logs/` (or whatever
+ *     `paths.eventsJsonl` resolves to)
+ *   - create an empty (0-byte) `events.jsonl` if missing
+ *   - create a valid empty `projection.json` (with `_meta.schema_version =
+ *     2`, fingerprint_versions, event_count = 0, last_event_id = null,
+ *     sessions = {}) if missing
+ *
+ * The function is **idempotent**: calling it twice in a row leaves the
+ * second-call return value's `created.*` flags all `false` to indicate
+ * that the existing files were respected. Existing content is NEVER
+ * overwritten — the wizard MUST be safe to re-run.
+ *
+ * Failure mode: when permission / disk errors prevent creation we return
+ * `{ ok: false, error }` instead of throwing. That mirrors the rest of the
+ * library API (operations.mjs / tryUpdateProjection), so the wizard can
+ * surface errors uniformly.
+ *
+ * Why split this from storage.mjs? `loadProjection` already does a "create
+ * if missing → empty projection" path implicitly via rebuild-from-events,
+ * but it never persists that empty projection. The wizard needs visible
+ * on-disk artifacts so subsequent tools (file watchers, telemetry probes)
+ * have something to attach to.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import { resolveStoragePaths } from './paths.mjs';
+import { PATHS } from './storage.mjs';
+
+const SCHEMA_VERSION = 2;
+const FINGERPRINT_VERSIONS = ['first_human_prompt_v1', 'lineage_prefix_v1'];
+
+/**
+ * Initialize sessions-db storage at the given root.
+ *
+ * Resolution semantics (Day 4):
+ *
+ *   - `opts.paths` (legacy form) — fully-formed override: each `eventsJsonl`
+ *     / `projectionJson` is anchored on `opts.rootPath` (or treated as
+ *     absolute if it starts with `/`). Backward-compatible with Day 3
+ *     callers that passed `paths: { eventsJsonl: 'custom/events.jsonl', ... }`.
+ *
+ *   - `opts.rootPath` (Day 4 form, no `opts.paths`) — `rootPath` IS the
+ *     storage directory; files live directly under it as
+ *     `<rootPath>/sessions-db-events.jsonl` and `<rootPath>/sessions-db.json`.
+ *     This is what cockpit's Setup Wizard passes (typically resolved to
+ *     `<workspace>/.dru-code/`).
+ *
+ *   - No opts (default) — delegates to `resolveStoragePaths()` which runs
+ *     the env > existing-storage > cwd/.dru-code chain. Useful for ad-hoc
+ *     "init wherever the resolver thinks it should go" scripts.
+ *
+ * @param {{
+ *   rootPath?: string,
+ *   paths?: { eventsJsonl?: string, projectionJson?: string, lockFile?: string },
+ * }} [opts]
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   created?: { dir: boolean, eventsJsonl: boolean, projectionJson: boolean },
+ *   paths?: { eventsJsonl: string, projectionJson: string },
+ *   source?: string,
+ *   error?: string,
+ * }>}
+ */
+export async function initProjection(opts) {
+  if (!opts || typeof opts !== 'object') {
+    return { ok: false, error: 'initProjection: opts required' };
+  }
+  const { rootPath } = opts;
+
+  let eventsPath;
+  let projectionPath;
+  let source = 'arg';
+
+  if (opts.paths) {
+    // Legacy `paths` override — anchor each rel-path against rootPath
+    // (required when paths is supplied) unless it's absolute. This shape
+    // pre-dates Day 4 and is preserved verbatim for backward compat.
+    if (typeof rootPath !== 'string' || rootPath.length === 0) {
+      return { ok: false, error: 'initProjection: rootPath required when paths override is supplied' };
+    }
+    const eventsRel = opts.paths.eventsJsonl ?? PATHS.eventsJsonl;
+    const projectionRel = opts.paths.projectionJson ?? PATHS.projectionJson;
+    const abs = (p) => (isAbsolute(p) ? p : resolve(rootPath, p));
+    eventsPath = abs(eventsRel);
+    projectionPath = abs(projectionRel);
+  } else if (typeof rootPath === 'string' && rootPath.length > 0) {
+    // Day 4 form — rootPath IS the storage dir. Delegates to resolver so
+    // canonical filenames stay in one place.
+    const r = resolveStoragePaths({ rootPath });
+    eventsPath = r.eventsJsonl;
+    projectionPath = r.projectionJson;
+    source = r.source;
+  } else {
+    // No opts — full default chain (env → ascend → cwd/.dru-code).
+    const r = resolveStoragePaths();
+    eventsPath = r.eventsJsonl;
+    projectionPath = r.projectionJson;
+    source = r.source;
+  }
+
+  // Both files share a parent dir under tickets/_logs/. Compute the deeper
+  // of the two so we cover both even with custom path overrides.
+  const dirsToCreate = new Set([dirname(eventsPath), dirname(projectionPath)]);
+
+  const created = { dir: false, eventsJsonl: false, projectionJson: false };
+  try {
+    for (const dir of dirsToCreate) {
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        created.dir = true;
+      }
+    }
+    if (!existsSync(eventsPath)) {
+      // Touch — empty file (0 bytes). loadEvents reads this fine; the
+      // first `appendEvent` call will populate it.
+      writeFileSync(eventsPath, '', { flag: 'wx' });
+      created.eventsJsonl = true;
+    }
+    if (!existsSync(projectionPath)) {
+      const empty = emptyProjectionLiteral();
+      // `flag: 'wx'` so a concurrent initializer doesn't clobber a live
+      // projection. existsSync check + wx flag is belt-and-suspenders;
+      // the existsSync race would otherwise surface as EEXIST, which we
+      // re-translate as "not created" rather than an error.
+      try {
+        writeFileSync(
+          projectionPath,
+          JSON.stringify(empty, null, 2),
+          { flag: 'wx' },
+        );
+        created.projectionJson = true;
+      } catch (err) {
+        if (err && err.code === 'EEXIST') {
+          // Lost the race; another initializer beat us. That's fine —
+          // the file exists, the contract holds.
+          created.projectionJson = false;
+        } else {
+          throw err;
+        }
+      }
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      error: `initProjection: ${err && err.message ? err.message : String(err)}`,
+    };
+  }
+
+  return {
+    ok: true,
+    created,
+    paths: { eventsJsonl: eventsPath, projectionJson: projectionPath },
+    source,
+  };
+}
+
+/**
+ * Build the empty projection literal we serialize for fresh initialization.
+ *
+ * Kept inline (rather than importing `emptyProjection()` from
+ * `projection.mjs`) so the on-disk shape is decoupled from the in-memory
+ * reducer — `_meta.updated` here is set to a real timestamp so consumers
+ * have a non-null marker, while `applyEvent`'s `updated` is event-driven.
+ */
+function emptyProjectionLiteral() {
+  return {
+    _meta: {
+      schema_version: SCHEMA_VERSION,
+      fingerprint_versions: [...FINGERPRINT_VERSIONS],
+      updated: new Date().toISOString(),
+      event_count: 0,
+      last_event_id: null,
+    },
+    sessions: {},
+  };
+}

package/lib/lock.mjs

@@ -0,0 +1,86 @@
+/**
+ * File-based exclusive lock helper for sessions-db projection writes.
+ *
+ * Uses POSIX `O_CREAT | O_EXCL` semantics via `fs.openSync(path, 'wx')`:
+ * - Atomic create-or-fail across processes on a single filesystem
+ * - On EEXIST we retry until either the lock is released by the holder or
+ *   the timeout window elapses
+ *
+ * The lock file content is `<pid>\t<iso-ts>\n` (one line). Future phases will
+ * use the embedded PID for stale-lock detection (kill -0 PID); this phase
+ * intentionally does not implement stale recovery — Phase 1 ticket §"Stale
+ * lock detection (PID-based)" is explicitly out of scope.
+ *
+ * Zero new npm deps: only `node:fs`, `node:timers/promises`.
+ */
+
+import { closeSync, openSync, unlinkSync, writeSync } from 'node:fs';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_RETRY_MS = 50;
+
+/**
+ * Acquire an exclusive lock on `lockPath`.
+ *
+ * @param {string} lockPath - Absolute path to the lock file. Parent dir must
+ *   exist; we do not mkdir-p (callers control layout).
+ * @param {{ timeoutMs?: number, retryMs?: number }} [opts]
+ * @returns {Promise<{ release: () => void }>} - Resolves with a release
+ *   handle. `release()` is idempotent: calling it twice is a no-op.
+ *
+ * Throws on timeout: `Error("acquireLock: timeout after <ms>ms (path=...)").`
+ * Re-throws unexpected fs errors verbatim (anything other than EEXIST).
+ */
+export async function acquireLock(lockPath, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retryMs = opts.retryMs ?? DEFAULT_RETRY_MS;
+  const deadline = Date.now() + timeoutMs;
+
+  while (true) {
+    let fd;
+    try {
+      // 'wx' === O_WRONLY | O_CREAT | O_EXCL — atomic create-or-fail.
+      fd = openSync(lockPath, 'wx');
+    } catch (err) {
+      if (err && err.code === 'EEXIST') {
+        if (Date.now() >= deadline) {
+          throw new Error(
+            `acquireLock: timeout after ${timeoutMs}ms (path=${lockPath})`,
+          );
+        }
+        await sleep(retryMs);
+        continue;
+      }
+      throw err;
+    }
+
+    // Stamp PID + iso ts so future stale-lock detection has the metadata
+    // it needs. Failure to write metadata still gives us the lock — release
+    // proceeds normally.
+    try {
+      const stamp = `${process.pid}\t${new Date().toISOString()}\n`;
+      writeSync(fd, stamp);
+    } catch {
+      // Non-fatal: keep the lock, swallow metadata write error.
+    }
+
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      try {
+        closeSync(fd);
+      } catch {
+        // fd may already be closed in edge cases — ignore.
+      }
+      try {
+        unlinkSync(lockPath);
+      } catch {
+        // lock may already be gone — ignore.
+      }
+    };
+
+    return { release };
+  }
+}