@druumen/sessions-db 0.1.0

package/types/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @druumen/sessions-db — public TypeScript entry point.
+ *
+ * This file is HAND-CRAFTED and committed to the repo (not regenerated by
+ * `tsc`). The `tsc` build emits per-source-file declarations as `.d.mts`
+ * (because the sources are `.mjs`); this `.d.ts` curates the public type
+ * surface so cockpit-class consumers can write:
+ *
+ *     import type {
+ *       KnownSession,
+ *       Projection,
+ *       SessionEvent,
+ *       ActivityState,
+ *       Outcome,
+ *     } from '@druumen/sessions-db';
+ *
+ * and resolve everything through one entry — without having to memorise
+ * which lib/* file each typedef lives in.
+ *
+ * The `lib/index.mjs` runtime entry is intentionally a Day-1 stub
+ * (re-exports happen on Day 3 — once the public *function* surface is
+ * settled). This `.d.ts` is safe to ship today because it is types-only
+ * and has zero runtime side effects.
+ *
+ * Convention for tsc-emitted neighbours:
+ *   - Auto-generated:     `types/<name>.d.mts`  (mirrors `lib/<name>.mjs`)
+ *   - Hand-crafted:       `types/index.d.ts`    (this file)
+ *
+ * `package.json` `"types"` points at `./types/index.d.ts` so this is the
+ * resolution entry. The neighbouring `.d.mts` files exist for direct
+ * sub-path imports (`@druumen/sessions-db/lib/storage.d.mts`) but cockpit
+ * should prefer this curated surface for forward compat.
+ */
+
+// ---------------------------------------------------------------------------
+// Type vocabulary — re-exported from `lib/types.d.mts` (which `tsc` lifted
+// from the `@typedef` block in `lib/types.mjs`). This is the canonical
+// surface for cockpit consumers.
+// ---------------------------------------------------------------------------
+
+export type {
+  // Branded scalars
+  SessionStableId,
+  ClaudeSessionId,
+  EventId,
+  Iso8601,
+  // Enums
+  ActivityState,
+  Outcome,
+  IdentitySource,
+  IdentityConfidence,
+  EventOp,
+  // Composite shapes
+  TranscriptFile,
+  IdentityResolution,
+  ParentCandidate,
+  KnownSession,
+  ProjectionMeta,
+  Projection,
+  SessionEvent,
+} from './types.d.mts';
+
+// ---------------------------------------------------------------------------
+// Function signatures — re-exported from per-source `.d.mts` neighbours.
+//
+// We re-export TYPES of functions (typeof) rather than the runtime symbols
+// because Day 2 keeps `lib/index.mjs` a runtime stub. Day 3 will flip
+// `lib/index.mjs` into a real re-export hub and at that point `tsc` will
+// regenerate `types/index.d.mts` with the same shape — but consumers who
+// imported through this `.d.ts` see no breakage because the type names
+// are identical.
+//
+// The `typeof import(...)` pattern is the standard TypeScript ambient
+// re-export when the source is JS-with-JSDoc.
+// ---------------------------------------------------------------------------
+
+// uuid.mjs
+export type GenerateSessionId = typeof import('./uuid.d.mts').generateSessionId;
+export type IsSessionId = typeof import('./uuid.d.mts').isSessionId;
+export type ExtractTimestamp = typeof import('./uuid.d.mts').extractTimestamp;
+
+// projection.mjs
+export type ApplyEvent = typeof import('./projection.d.mts').applyEvent;
+export type EmptyProjection = typeof import('./projection.d.mts').emptyProjection;
+export type EmptySession = typeof import('./projection.d.mts').emptySession;
+export type RebuildFromEvents = typeof import('./projection.d.mts').rebuildFromEvents;
+
+// storage.mjs
+export type NewEvent = typeof import('./storage.d.mts').newEvent;
+export type AppendEvent = typeof import('./storage.d.mts').appendEvent;
+export type ReadAllEvents = typeof import('./storage.d.mts').readAllEvents;
+export type LoadProjection = typeof import('./storage.d.mts').loadProjection;
+export type SaveProjection = typeof import('./storage.d.mts').saveProjection;
+export type RebuildProjection = typeof import('./storage.d.mts').rebuildProjection;
+export type TryUpdateProjection = typeof import('./storage.d.mts').tryUpdateProjection;
+export type RecordSessionSeen = typeof import('./storage.d.mts').recordSessionSeen;
+
+// identity.mjs
+export type ResolveIdentity = typeof import('./identity.d.mts').resolveIdentity;
+export type FindByClaudeSessionId = typeof import('./identity.d.mts').findByClaudeSessionId;
+export type FindByTranscriptLineage = typeof import('./identity.d.mts').findByTranscriptLineage;
+export type ScanFingerprintCandidates = typeof import('./identity.d.mts').scanFingerprintCandidates;
+export type CollectParentCandidates = typeof import('./identity.d.mts').collectParentCandidates;
+export type CapParentCandidates = typeof import('./identity.d.mts').capParentCandidates;
+export type ClassifyCorroborators = typeof import('./identity.d.mts').classifyCorroborators;
+export type MeetsThreshold = typeof import('./identity.d.mts').meetsThreshold;
+
+// sweep.mjs
+export type ComputeSweepTransitions = typeof import('./sweep.d.mts').computeSweepTransitions;
+export type ComputeEffectiveLastProgress = typeof import('./sweep.d.mts').computeEffectiveLastProgress;
+
+// sanitize.mjs
+export type SanitizeFirstPrompt = typeof import('./sanitize.d.mts').sanitizeFirstPrompt;
+export type StripSystemReminders = typeof import('./sanitize.d.mts').stripSystemReminders;
+export type StripIdeWrappers = typeof import('./sanitize.d.mts').stripIdeWrappers;
+
+// transcript.mjs
+export type ParseTranscriptFile = typeof import('./transcript.d.mts').parseTranscriptFile;
+export type ListTranscriptFiles = typeof import('./transcript.d.mts').listTranscriptFiles;
+export type WorkspaceHashFromCwd = typeof import('./transcript.d.mts').workspaceHashFromCwd;
+
+// git-context.mjs
+export type GitContextFn = typeof import('./git-context.d.mts').gitContext;
+
+// paths.mjs (Day 4 — storage path resolution chain)
+export type ResolveStoragePaths = typeof import('./paths.d.mts').resolveStoragePaths;
+export type PathsFromRoot = typeof import('./paths.d.mts').pathsFromRoot;

package/types/init.d.mts

@@ -0,0 +1,53 @@
+/**
+ * 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 function initProjection(opts?: {
+    rootPath?: string;
+    paths?: {
+        eventsJsonl?: string;
+        projectionJson?: string;
+        lockFile?: string;
+    };
+}): Promise<{
+    ok: boolean;
+    created?: {
+        dir: boolean;
+        eventsJsonl: boolean;
+        projectionJson: boolean;
+    };
+    paths?: {
+        eventsJsonl: string;
+        projectionJson: string;
+    };
+    source?: string;
+    error?: string;
+}>;

package/types/lock.d.mts

@@ -0,0 +1,18 @@
+/**
+ * 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 function acquireLock(lockPath: string, opts?: {
+    timeoutMs?: number;
+    retryMs?: number;
+}): Promise<{
+    release: () => void;
+}>;

package/types/operations.d.mts

@@ -0,0 +1,204 @@
+/**
+ * Set or clear the human-readable alias on a session.
+ *
+ * Either `alias` (non-empty string) or `clear: true` must be provided —
+ * mutually exclusive. Validation matches the CLI's argparse behavior so the
+ * library consumer surface is symmetric with the CLI surface.
+ *
+ * @param {{
+ *   stableId: string,
+ *   alias?: string,
+ *   clear?: boolean,
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export function setAlias(opts: {
+    stableId: string;
+    alias?: string;
+    clear?: boolean;
+    rootPath?: string;
+    root?: string;
+    paths?: object;
+}): Promise<{
+    ok: boolean;
+    event_id?: string;
+    error?: string;
+}>;
+/**
+ * Link a session to one or more tasks / projects (additive, idempotent).
+ *
+ * At least one of `tasks` / `projects` must be a non-empty array. The
+ * reducer already de-dupes against existing entries so re-running with the
+ * same payload is a no-op on projection state (but still writes an audit
+ * event).
+ *
+ * @param {{
+ *   stableId: string,
+ *   tasks?: string[],
+ *   projects?: string[],
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export function linkTask(opts: {
+    stableId: string;
+    tasks?: string[];
+    projects?: string[];
+    rootPath?: string;
+    root?: string;
+    paths?: object;
+}): Promise<{
+    ok: boolean;
+    event_id?: string;
+    error?: string;
+}>;
+/**
+ * Unlink one or more tasks / projects from a session (set-based filter,
+ * idempotent). Removing an id that isn't present is a no-op on projection
+ * state but still produces an audit event — operator intent is recorded
+ * regardless of resulting state change.
+ *
+ * @param {{
+ *   stableId: string,
+ *   tasks?: string[],
+ *   projects?: string[],
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export function unlinkTask(opts: {
+    stableId: string;
+    tasks?: string[];
+    projects?: string[];
+    rootPath?: string;
+    root?: string;
+    paths?: object;
+}): Promise<{
+    ok: boolean;
+    event_id?: string;
+    error?: string;
+}>;
+/**
+ * Set or clear the hub-spoke parent relationship for a session.
+ *
+ * Either `parentId` (non-empty string, distinct from `childId`) or `clear:
+ * true` must be provided. When setting a parent we:
+ *   - reject self-cycle (parentId === childId, exit-1 in CLI)
+ *   - verify parent exists
+ *   - walk parent's ancestor chain up to MAX_PARENT_CHAIN_DEPTH and reject
+ *     if `childId` appears anywhere — that would close a cycle of length
+ *     ≥ 2 (e.g. existing A→B + proposed `setParent({childId: B, parentId: A})`
+ *     would form A→B→A).
+ *
+ * The MAX_PARENT_CHAIN_DEPTH bound is a defense against a stale projection
+ * cycle (rare; would require an earlier guard bypass). 50 is generous —
+ * real hub-spoke chains are 1-3 hops.
+ *
+ * @param {{
+ *   childId: string,
+ *   parentId?: string,
+ *   clear?: boolean,
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export function setParent(opts: {
+    childId: string;
+    parentId?: string;
+    clear?: boolean;
+    rootPath?: string;
+    root?: string;
+    paths?: object;
+}): Promise<{
+    ok: boolean;
+    event_id?: string;
+    error?: string;
+}>;
+/**
+ * Close (or reopen) a session with a terminal outcome.
+ *
+ * Outcome enum is enforced (matches projection schema): open | done |
+ * blocked | abandoned | merged | superseded. `open` is allowed — operators
+ * may reopen a previously-closed session by passing `outcome: 'open'`; the
+ * reducer's closed_at always tracks the latest close event so the reopen is
+ * visible in the audit trail.
+ *
+ * @param {{
+ *   stableId: string,
+ *   outcome: string,
+ *   reason?: string,
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export function closeSession(opts: {
+    stableId: string;
+    outcome: string;
+    reason?: string;
+    rootPath?: string;
+    root?: string;
+    paths?: object;
+}): Promise<{
+    ok: boolean;
+    event_id?: string;
+    error?: string;
+}>;
+/**
+ * Compute and (optionally) apply activity_state transitions across all
+ * sessions in the projection.
+ *
+ * Returns:
+ *   - dryRun: true → `{ ok: true, dryRun: true, transitions }` with the
+ *     planned transitions list (no events written).
+ *   - dryRun: false → `{ ok: boolean, applied, failed, summary }` after
+ *     attempting each transition through `tryUpdateProjection`. `ok` is
+ *     true when zero failures.
+ *
+ * Lock model: each transition acquires the projection lock independently
+ * via `tryUpdateProjection`. For typical sweep volumes (single digits per
+ * run) this is fine; if the workspace grows huge a future `--batch` mode
+ * can fold all transitions into a single under-lock pass.
+ *
+ * @param {{
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ *   idleThresholdDays?: number,
+ *   archiveThresholdDays?: number,
+ *   dryRun?: boolean,
+ *   now?: number,
+ * }} [opts]
+ * @returns {Promise<
+ *   | { ok: true, dryRun: true, transitions: Array<object> }
+ *   | { ok: boolean, applied: Array<object>, failed: Array<object>, summary: object }
+ * >}
+ */
+export function runSweep(opts?: {
+    rootPath?: string;
+    root?: string;
+    paths?: object;
+    idleThresholdDays?: number;
+    archiveThresholdDays?: number;
+    dryRun?: boolean;
+    now?: number;
+}): Promise<{
+    ok: true;
+    dryRun: true;
+    transitions: Array<object>;
+} | {
+    ok: boolean;
+    applied: Array<object>;
+    failed: Array<object>;
+    summary: object;
+}>;

package/types/paths.d.mts

@@ -0,0 +1,54 @@
+/**
+ * Resolve storage paths from caller opts + env + autodiscover.
+ *
+ * @param {{ rootPath?: string, cwd?: string }} [opts]
+ * @returns {{
+ *   root: string,
+ *   eventsJsonl: string,
+ *   projectionJson: string,
+ *   lockFile: string,
+ *   source: 'arg' | 'env' | 'tickets-logs' | 'dru-code' | 'default',
+ * }}
+ */
+export function resolveStoragePaths(opts?: {
+    rootPath?: string;
+    cwd?: string;
+}): {
+    root: string;
+    eventsJsonl: string;
+    projectionJson: string;
+    lockFile: string;
+    source: "arg" | "env" | "tickets-logs" | "dru-code" | "default";
+};
+/**
+ * Helper for callers that already have a fully-resolved root and want to
+ * compute file paths (tests, custom integrations). Public so consumers can
+ * mirror the layout invariant without importing internal helpers.
+ *
+ * @param {string} root absolute or relative; resolved against cwd if relative
+ * @returns {{ root: string, eventsJsonl: string, projectionJson: string, lockFile: string }}
+ */
+export function pathsFromRoot(root: string): {
+    root: string;
+    eventsJsonl: string;
+    projectionJson: string;
+    lockFile: string;
+};
+/**
+ * Hard cap on cwd-ascend depth. Twelve levels is generous — a typical
+ * worktree depth is 1-3, monorepos may go to 5-6. Pinning at 12 means the
+ * worst-case stat budget is 24 (two candidate paths × 12 levels) before
+ * we fall through to the default. Set deliberately conservative so the
+ * resolver never accidentally walks to `/` on a slow networked mount.
+ */
+export const MAX_ASCEND_DEPTH: 12;
+/**
+ * The three on-disk filenames (relative to whichever root the resolver
+ * picks). Frozen so callers can't accidentally mutate. Exported for tests
+ * + the rare library consumer that wants to know the canonical names.
+ */
+export const STORAGE_FILENAMES: Readonly<{
+    eventsJsonl: "sessions-db-events.jsonl";
+    projectionJson: "sessions-db.json";
+    lockFile: "sessions-db.json.lock";
+}>;

package/types/projection.d.mts

@@ -0,0 +1,79 @@
+/**
+ * Build an empty projection skeleton. Sessions map starts empty; metadata
+ * has `event_count = 0` and `last_event_id = null`.
+ *
+ * @returns {{ _meta: object, sessions: Record<string, object> }}
+ */
+export function emptyProjection(): {
+    _meta: object;
+    sessions: Record<string, object>;
+};
+/**
+ * Build a default session record. Caller passes the stable_id and the
+ * `created_at` timestamp (typically the first observing event's `ts`).
+ *
+ * @param {string} stableId
+ * @param {string} ts - ISO timestamp string used for both created_at and
+ *   last_progress_at.
+ */
+export function emptySession(stableId: string, ts: string): {
+    stable_id: string;
+    alias: any;
+    claude_session_ids: any[];
+    transcript_files: any[];
+    fingerprints: {
+        first_human_prompt_v1: any;
+        lineage_prefix_v1: any;
+    };
+    parent_session_id: any;
+    parent_candidate_ids: any[];
+    parent_candidates_omitted_count: number;
+    identity_resolution: any;
+    worktree_path_observed: any;
+    worktree_realpath: any;
+    worktree_registry_name: any;
+    git_common_dir: any;
+    branch_at_start: any;
+    branch_current: any;
+    head_at_start: any;
+    head_last_seen: any;
+    tasks: any[];
+    projects: any[];
+    activity_state: string;
+    outcome: string;
+    closed_at: any;
+    closed_reason: any;
+    created_at: string;
+    last_progress_at: string;
+    first_prompt_preview: any;
+};
+/**
+ * Apply a single event to a projection (mutating). Returns the same
+ * projection reference for fluent chaining.
+ *
+ * Unknown ops are tolerated — they update _meta but otherwise no-op so a
+ * future schema bump applied against an older binary degrades cleanly. We
+ * still bump `event_count` so the rebuild detector remains accurate.
+ *
+ * @param {object} projection
+ * @param {{ ts: string, event_id: string, op: string, stable_id: string,
+ *   payload?: object }} event
+ * @returns {object} projection
+ */
+export function applyEvent(projection: object, event: {
+    ts: string;
+    event_id: string;
+    op: string;
+    stable_id: string;
+    payload?: object;
+}): object;
+/**
+ * Fold an event array into a fresh projection. Used both for full rebuilds
+ * (storage.rebuildProjection) and for unit tests.
+ *
+ * @param {Array<object>} events
+ */
+export function rebuildFromEvents(events: Array<object>): {
+    _meta: object;
+    sessions: Record<string, object>;
+};

package/types/sanitize.d.mts

@@ -0,0 +1,39 @@
+/**
+ * Strip every `<system-reminder>...</system-reminder>` block from `s`, plus
+ * the related harness/system envelopes (`<system>`, `<thinking>`, `<tool_use>`,
+ * `<tool_result>`, `<parameter>`).
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function stripSystemReminders(s: string): string;
+/**
+ * Strip IDE/harness wrappers (`<ide_opened_file>...`, `<ide_selection>...`,
+ * `<command-name>...</command-message>`).
+ * @param {string} s
+ * @returns {string}
+ */
+export function stripIdeWrappers(s: string): string;
+/**
+ * Sanitise a raw first-prompt string for safe persistence.
+ *
+ * Order matters and is the result of an adversarial review:
+ *   1. NFKC normalise FIRST. Fullwidth bracket variants (e.g.
+ *      `＜system-reminder＞`) only fold into ASCII `<>` after NFKC; if we
+ *      stripped before normalising the wrapper would survive the strip pass
+ *      and then leak its body once normalisation happens.
+ *   2. Strip system-reminders + system envelopes.
+ *   3. Strip IDE/harness wrappers.
+ *   4. Defensive second pass: re-strip both families. Removing one wrapper
+ *      can splice together text that now reads as a fresh wrapper (e.g.
+ *      `<sys` + IDE block + `tem>...</system>`); the second pass closes that.
+ *   5. Trim and collapse runs of 3+ newlines to a paragraph break.
+ *   6. Truncate to `maxLen` (default 200) on a code-point boundary, append `…`.
+ *
+ * @param {string} raw
+ * @param {{ maxLen?: number }} [opts]
+ * @returns {string}
+ */
+export function sanitizeFirstPrompt(raw: string, opts?: {
+    maxLen?: number;
+}): string;