@druumen/sessions-db 0.1.0

package/README.md

@@ -0,0 +1,250 @@
+# @druumen/sessions-db
+
+Cross-session traceability for [Claude Code](https://claude.com/claude-code).
+
+## What it does
+
+Records every Claude Code session start (cwd, branch, transcript file,
+sanitized first prompt) into a local JSONL event log + projection cache.
+Provides 3-priority identity reconciliation across forks, resumes, and
+hub-spoke (sub-agent) relationships, so you can find related sessions
+across days and worktrees without losing the thread.
+
+**Local-only**: no network egress. All data stays on your machine.
+
+## Installation
+
+```bash
+npm install @druumen/sessions-db
+```
+
+Requires Node.js 18 or newer. Zero runtime dependencies.
+
+## Quick start
+
+### Library API
+
+```js
+import {
+  initProjection,
+  loadProjection,
+  watchProjection,
+  setAlias,
+  setParent,
+  closeSession,
+  runSweep,
+} from '@druumen/sessions-db';
+
+// 1. Bootstrap storage at .dru-code/ in current cwd. Idempotent — safe
+//    to call on every app start.
+const init = await initProjection({ rootPath: process.cwd() + '/.dru-code' });
+if (!init.ok) throw new Error(init.error);
+
+// 2. Load the current projection (sessions + meta).
+const projection = await loadProjection({ rootPath: init.paths.eventsJsonl.replace(/\/[^/]+$/, '') });
+console.log(Object.keys(projection.sessions).length, 'sessions');
+
+// 3. Watch for changes (debounced 80ms).
+const watcher = watchProjection(rootPath, (event) => {
+  console.log('changed:', event.type);
+});
+// Later: watcher.dispose();
+
+// 4. Mutate via the operations API. Each call returns
+//    { ok: true, event_id } or { ok: false, error }.
+await setAlias({ stableId: 'sess_xxx', alias: 'my session', rootPath });
+await setParent({ childId: 'sess_xxx', parentId: 'sess_yyy', rootPath });
+await closeSession({
+  stableId: 'sess_xxx',
+  outcome: 'done',
+  reason: 'shipped',
+  rootPath,
+});
+
+// 5. Sweep activity_state transitions (active → idle → archived).
+const sweep = await runSweep({ rootPath, dryRun: true });
+console.log(sweep.transitions.length, 'pending transitions');
+```
+
+All operations are lock-safe (single-writer through an exclusive-create
+lockfile) and idempotent at the projection level. Errors return as
+`{ ok: false, error }` rather than throwing — system-class failures (disk
+full, permission denied) and business-class failures (cycle, missing
+session) share the same shape.
+
+### CLI
+
+```bash
+npm install -g @druumen/sessions-db
+sessions-db --help
+
+sessions-db find --limit 10                   # list recent sessions
+sessions-db tree sess_019e0f2d-c6e3...        # ancestry / descendants
+sessions-db alias sess_019e0f2d-c6e3 "label"  # human-readable alias
+sessions-db link sess_xxx --task feat-foo.md  # link to ticket / project
+sessions-db link-parent sess_child sess_parent
+sessions-db close sess_xxx --outcome done --reason "shipped"
+sessions-db rebuild                            # rebuild projection from events
+sessions-db sweep --dry-run                    # preview activity transitions
+```
+
+The CLI is the same surface as the library API; both write through the
+same primitives, so a workflow that mixes hook-driven CLI commands with
+programmatic library calls observes a consistent projection.
+
+### Hook setup (Claude Code SessionStart)
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node /absolute/path/to/node_modules/@druumen/sessions-db/cli/sessions-db-session-start.mjs",
+        "timeout": 5
+      }]
+    }]
+  }
+}
+```
+
+The hook is bootstrap-safe by design:
+
+- Kill switch: set `DRUUMEN_SESSIONS_DB_DISABLED=1` to no-op the hook
+  without removing it from settings.
+- 2-second hard timeout on every operation; the hook always exits 0 so
+  it never blocks Claude Code start, even on disk full / permission
+  denied / lockfile contention.
+- Errors are logged to stderr (visible in Claude Code's session log)
+  but never surfaced as user-facing failures.
+
+## Path resolution
+
+When you don't pass an explicit `rootPath`, sessions-db walks a 5-priority
+chain. First hit wins:
+
+1. `opts.rootPath` — explicit caller arg (highest priority).
+2. `DRUUMEN_SESSIONS_DB_ROOT` — env var override (cockpit Setup Wizard,
+   CI matrix runs, ops incident pinning).
+3. cwd-ascend (≤12 levels) for an existing
+   `tickets/_logs/sessions-db.json` — preserves the druumen-monorepo
+   experience: any sessions-db command from anywhere inside the worktree
+   finds the canonical root.
+4. cwd-ascend (≤12 levels) for an existing `.dru-code/sessions-db.json`
+   — the new convention for fresh installs that have already been
+   initialized once.
+5. Default: `<cwd>/.dru-code/` — what fresh `initProjection({})` lands
+   when no existing storage is found. Cockpit marketplace's first
+   install creates this dir.
+
+The ascend bound caps the worst-case stat budget at 24 (two candidate
+file checks × 12 levels) before falling through to the default — the
+resolver never accidentally walks to `/` on a slow networked mount.
+
+The same three filenames are used at every layout:
+
+```
+<root>/sessions-db-events.jsonl   # append-only SSoT
+<root>/sessions-db.json           # projection cache
+<root>/sessions-db.json.lock      # exclusive-create lockfile
+```
+
+## Privacy
+
+`first_prompt_preview` stores a sanitized 200-char excerpt of the first
+user message in each session, so operators can recognize sessions in
+the projection without re-opening transcripts. Sanitization strips:
+
+- IDE-injected wrappers: `<ide_opened_file>`, `<ide_selection>`
+- Slash command wrappers: `<command-name>`, `<command-message>`,
+  `<command-args>`
+- System reminders: `<system-reminder>`, `<system>`, `<thinking>`
+- Tool-use blocks: `<tool_use>`, `<tool_result>`, `<parameter>`,
+  `<function_calls>`
+
+NFKC normalization is applied **before** stripping so fullwidth-bracket
+splice attacks (e.g. `＜system-reminder＞`) cannot bypass the redactor.
+The strip is double-pass — when removing one wrapper exposes a fresh
+inner wrapper, the second pass catches it. Truncation is UTF-16
+codepoint-safe (200 codepoints, not 200 bytes) so multi-byte characters
+are not split mid-glyph.
+
+### Privacy opt-out (available in 0.1.0)
+
+To disable preview storage entirely — useful for marketplace audits,
+shared-machine deployments, or any user who'd rather not persist the
+human-readable first prompt:
+
+**Library API:**
+
+```js
+import { recordSessionSeen } from '@druumen/sessions-db';
+
+await recordSessionSeen({
+  claudeSessionId,
+  // ...other opts...
+  storeFirstPrompt: false,   // payload.first_prompt_preview = null
+});
+```
+
+**Hook env var (Claude Code SessionStart):**
+
+```bash
+DRUUMEN_SESSIONS_DB_STORE_PREVIEW=0 \
+  claude code   # or whatever spawns the hook
+```
+
+`'0'` and `'false'` (case-insensitive) opt out; anything else (or unset)
+keeps the default. Default is `true` — backward compatible with the
+0.1.0-dev preview behavior.
+
+Fingerprints (`first_human_prompt_v1`, `lineage_prefix_v1`) and
+`transcript_file` metadata are intentionally **not** affected by this
+opt-out, so identity reconciliation (resume / fork detection) keeps
+working for opt-out users.
+
+## Schema
+
+The events log (`sessions-db-events.jsonl`) is the single source of
+truth; the projection (`sessions-db.json`) is a derivable cache. Run
+`sessions-db rebuild` at any time to regenerate the projection from
+events — useful after manual events-log inspection / surgery.
+
+`schema_version: 2` is the stable contract for the entire 0.1.x line.
+Reducers stay backward-compatible: new optional fields may appear in
+0.1.x minor releases, but no existing field is removed or repurposed.
+Schema-breaking changes (rename, type change, removal) ship at 0.2.0+.
+
+## Versioning
+
+0.x semver:
+
+- **Patch** (0.1.x): bug fixes, doc, internal refactors. No API change.
+- **Minor** (0.x.0): additive only. New library exports, new CLI
+  subcommands, new optional projection fields. Existing surface is
+  unchanged.
+- **Major** (1.0.0): commits the API as stable. Until then, treat 0.x as
+  "settling" — pin `>=0.1.0 <0.2.0` in your `package.json` if you want
+  field-additive but no breaking changes inside the 0.1 line.
+
+Schema-breaking changes always coincide with at least a 0.x minor bump
+(0.2.0+) and ship with a documented migration path.
+
+## License
+
+Apache 2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
+
+## Roadmap
+
+- **0.1.0** (current): Library + CLI + hook + 3-priority identity +
+  cross-platform (macOS / Linux verified in CI; Windows pending runner) +
+  privacy opt-out (`storeFirstPrompt: false` /
+  `DRUUMEN_SESSIONS_DB_STORE_PREVIEW=0`).
+- **0.2.0** (TBD): parent_candidate auto-promote heuristic, outcome
+  auto-derive on `/task-done` linkage.
+- **0.3.0** (TBD): Multi-machine sync (schema_version=3 break,
+  documented migration).
+- **0.4.0+** (TBD): Web UI / VS Code Sessions panel via
+  [Druumen Cockpit](https://druumen.com).

package/cli/_write-helpers.mjs

@@ -0,0 +1,99 @@
+/**
+ * Shared helpers for write subcommands (alias / link / link-parent / close).
+ *
+ * Day 3: the actual mutation logic lives in `lib/operations.mjs`. These
+ * helpers handle the CLI surface only:
+ *   - rendering planned events for `--dry-run`
+ *   - mapping the library result `{ ok, event_id?, error? }` into stdout /
+ *     stderr / exit code in three formats: human (default), `--json`,
+ *     `--quiet`.
+ *
+ * Why keep the helpers? The five write handlers all share the same
+ * presentation logic — centralizing it keeps each handler focused on flag
+ * plumbing + the operations-call signature mapping.
+ *
+ * Note on output messages: the test suite regex-matches phrases like
+ * `ok: <op> written for <stable_id>` and `error: stable_id not found`. Any
+ * change to wording here MUST be paired with a sweep of __tests__/cli/*.
+ */
+
+import { newEvent } from '../lib/storage.mjs';
+import { formatJSON } from './format.mjs';
+
+/**
+ * Render a planned event for --dry-run. Always returns the event so callers
+ * can post-process if they need to. Output goes to stdout for easy piping.
+ *
+ * The intent is that the rendered output be machine-grep-able (op + stable_id
+ * + payload as JSON) so pipelines can audit what would change without
+ * actually writing.
+ */
+export function renderDryRun({ op, stableId, payload, json = false }) {
+  const event = newEvent({ op, stable_id: stableId, payload });
+  if (json) {
+    process.stdout.write(formatJSON({ dry_run: true, event }));
+  } else {
+    process.stdout.write(`[dry-run] would write event:\n`);
+    process.stdout.write(`  op:        ${op}\n`);
+    process.stdout.write(`  stable_id: ${stableId}\n`);
+    process.stdout.write(`  payload:   ${JSON.stringify(payload)}\n`);
+  }
+  return event;
+}
+
+/**
+ * Standard success / failure feedback for write commands.
+ *
+ * Result shape comes straight from `lib/operations.mjs` —
+ * `{ ok, event_id?, error? }`. We render and return the exit code the caller
+ * should hand to process.exit().
+ *
+ * Exit code policy:
+ *   - 0 = success
+ *   - 1 = business error (stable_id not found, validation failure, lock
+ *     timeout, cycle detection — anything `operations.*` returned with
+ *     `{ ok: false }`)
+ *
+ * `--quiet` swallows stdout but preserves the exit code so cron / scripted
+ * usage stays observable via `$?`.
+ */
+export function reportResult({ result, op, stableId, json, quiet, extra = {} }) {
+  if (quiet) return result.ok ? 0 : 1;
+  if (json) {
+    process.stdout.write(formatJSON({
+      ok: result.ok,
+      op,
+      stable_id: stableId,
+      event_id: result.event_id,
+      error: result.error,
+      ...extra,
+    }));
+  } else if (result.ok) {
+    process.stdout.write(`ok: ${op} written for ${stableId} (event_id=${result.event_id})\n`);
+    for (const [k, v] of Object.entries(extra)) {
+      process.stdout.write(`  ${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}\n`);
+    }
+  } else {
+    process.stderr.write(`error: ${op} failed for ${stableId}: ${result.error}\n`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+/**
+ * Special-case the "stable_id not found" error so the CLI prints the
+ * historical exact phrase the tests pin against:
+ *
+ *   error: stable_id not found: <id>
+ *
+ * The operations layer uses the same wording for that error, but it embeds
+ * it inside the call's `result.error`. When the wrapper detects this prefix
+ * it re-emits the bare phrase to stderr so the existing test regex
+ * `/stable_id not found/` and operator muscle memory keep working.
+ *
+ * Returns the exit code the handler should hand to process.exit() —
+ * typically 1 for a not-found, but the caller may pass `code` to override.
+ */
+export function reportStableIdNotFound(error, code = 1) {
+  process.stderr.write(`error: ${error}\n`);
+  return code;
+}

package/cli/alias.mjs

@@ -0,0 +1,115 @@
+/**
+ * `sessions-db alias <stable_id> <alias>` — set or change the human-readable
+ * alias.
+ * `sessions-db alias <stable_id> --clear` — remove the alias (sets to null).
+ *
+ * Day 3 refactor: this handler is a thin wrapper around
+ * `lib/operations.setAlias` — argparse + dry-run rendering + result-to-exit
+ * mapping only. Existence-check is performed by the operation BEFORE the
+ * write so a typo'd stable_id surfaces as a clean exit-1 message instead
+ * of a synthesized empty session record.
+ */
+
+import { setAlias } from '../lib/operations.mjs';
+import { ArgparseError, formatHelp, parseArgs } from './argparse.mjs';
+import { renderDryRun, reportResult, reportStableIdNotFound } from './_write-helpers.mjs';
+
+const SPEC = {
+  positional: [
+    { name: 'stable_id', required: true },
+    { name: 'alias', required: false },
+  ],
+  flags: {
+    '--clear': { type: 'boolean' },
+    '--dry-run': { type: 'boolean' },
+    '--json': { type: 'boolean' },
+    '--root': { type: 'string' },
+    '--quiet': { type: 'boolean' },
+  },
+};
+
+export const HELP = formatHelp({
+  usage: 'sessions-db alias <stable_id> <alias>  |  sessions-db alias <stable_id> --clear',
+  summary: 'Set, change, or clear the human-readable alias for a session.',
+  flags: [
+    { name: '--clear',     desc: 'remove the alias (sets to null)' },
+    { name: '--dry-run',   desc: 'print the planned event but do not write' },
+    { name: '--json',      desc: 'JSON output (machine-readable)' },
+    { name: '--root <p>',  desc: 'override storage root (default cwd)' },
+  ],
+  examples: [
+    'sessions-db alias sess_01970000-... pricing-overhaul-main',
+    'sessions-db alias sess_01970000-... --clear',
+  ],
+});
+
+export async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv, SPEC);
+  } catch (err) {
+    if (err instanceof ArgparseError) {
+      process.stderr.write(`error: ${err.message}\n\n${HELP}`);
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+
+  if (parsed.helpRequested) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const stableId = parsed.positional.stable_id;
+  const aliasArg = parsed.positional.alias;
+  const clear = parsed.flags['--clear'] === true;
+  const root = parsed.flags['--root'];
+  const dryRun = parsed.flags['--dry-run'] === true;
+  const json = parsed.flags['--json'] === true;
+  const quiet = parsed.flags['--quiet'] === true;
+
+  // Mutually-exclusive intent check: must be EITHER alias positional OR
+  // --clear. Both or neither is an argparse-class error (exit 2). The
+  // operations layer also rejects this combination, but doing the check
+  // here keeps the error stream identical to the historical CLI behavior
+  // (no library prefix in the message).
+  if (clear && aliasArg !== undefined) {
+    process.stderr.write(`error: alias and --clear are mutually exclusive\n`);
+    process.exit(2);
+  }
+  if (!clear && aliasArg === undefined) {
+    process.stderr.write(`error: provide an alias positional or --clear\n`);
+    process.exit(2);
+  }
+
+  if (dryRun) {
+    const payload = clear ? { alias: null } : { alias: aliasArg };
+    renderDryRun({ op: 'alias_set', stableId, payload, json });
+    return;
+  }
+
+  const opts = root ? { root } : {};
+  const result = clear
+    ? await setAlias({ stableId, clear: true, ...opts })
+    : await setAlias({ stableId, alias: aliasArg, ...opts });
+
+  // Stable-id-not-found gets the historical "error: stable_id not found:
+  // <id>" phrasing (no `op failed for ...` prefix). Operations returns the
+  // bare phrase as `result.error`; we recognize it and bypass reportResult
+  // for that one case so muscle-memory regex `/stable_id not found/` keeps
+  // matching.
+  if (!result.ok && typeof result.error === 'string'
+      && result.error.startsWith('stable_id not found:')) {
+    if (!quiet) {
+      const code = reportStableIdNotFound(result.error);
+      process.exit(code);
+    }
+    process.exit(1);
+  }
+
+  const code = reportResult({
+    result, op: 'alias_set', stableId, json, quiet,
+    extra: clear ? { cleared: true } : { alias: aliasArg },
+  });
+  if (code !== 0) process.exit(code);
+}