@druumen/sessions-db 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -5,6 +5,121 @@ All notable changes to `@druumen/sessions-db` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.5] — 2026-05-16
+
+Hook now writes to the same storage location its reader is watching,
+instead of always carving a fresh `tickets/_logs/` subdirectory into
+whichever workspace it happens to fire in.
+
+### Changed (hook)
+
+- `cli/sessions-db-session-start-main.mjs` — storage location strategy
+  is now three-tier (in order):
+
+  1. **`DRUUMEN_SESSIONS_DB_ROOT` env var** — explicit override forwarded
+     as `{ rootPath }`. Treated as the bare storage directory (no
+     `tickets/_logs/` prefix added). Cockpit's Setup Wizard plumbs the
+     workspace's chosen storage path through this env so a single source
+     of truth controls both reader and writer location.
+
+  2. **Auto-detect `<workspaceRoot>/.dru-code/sessions-db.json`** — when
+     this file exists (i.e. cockpit Setup Wizard or a prior init created
+     it), the hook writes alongside it via `{ rootPath: <ws>/.dru-code }`.
+     Marketplace cockpit users no longer end up with a phantom
+     `tickets/_logs/` subdirectory in their non-druumen project.
+
+  3. **Legacy `{ root: workspaceRoot }`** — falls back to the
+     pre-existing tickets/_logs/ layout anchored on the workspace root.
+     Druumen monorepo (which has a `tickets/_logs/` already) keeps
+     accumulating in the same place.
+
+### Why
+
+Before this fix, cockpit-marketplace users who clicked Setup Wizard's
+Enable button got `<ws>/.dru-code/sessions-db.json` created by the
+extension, but the SessionStart hook (running in a separate process)
+ignored that location and wrote every event to a fresh
+`<ws>/tickets/_logs/` subtree. Two consequences:
+
+- **Visible split-brain**: cockpit's path-discovery priority chain
+  picks `tickets/_logs/` once it exists (priority 3 > priority 4),
+  but until the user did a window reload the orchestrator kept
+  watching the wizard's empty `.dru-code/` stub. SESSIONS panel
+  appeared frozen at `0 active` even though events were being written.
+
+- **Workspace pollution**: an academic thesis or any non-druumen
+  project ended up with a `tickets/_logs/` subdirectory it had no
+  reason to own. With 0.1.5 the hook honors whichever convention was
+  set up — cockpit-marketplace users stay clean inside `.dru-code/`.
+
+### Test
+
+- New `contract-1c` covers the env-override path: with
+  `DRUUMEN_SESSIONS_DB_ROOT` set to a tmp dir outside the workspace,
+  the hook writes there and creates no `tickets/_logs/` in the
+  workspace.
+- Existing `contract-1b` updated: when `.dru-code/sessions-db.json`
+  pre-exists, the hook now writes to `.dru-code/` (NOT
+  `tickets/_logs/` which the old version did).
+- `happy path` and druumen-monorepo tests unchanged — workspaces with
+  no `.dru-code/` marker still get the legacy `tickets/_logs/` layout.
+- Full suite: 447 tests, 0 fail.
+
+### Backward compatibility
+
+- Druumen monorepo: zero change (no `.dru-code/` exists at any
+  ancestor → step (3) legacy path).
+- Cockpit-marketplace 0.3.0–0.3.2 users with `.dru-code/`: hook now
+  writes to `.dru-code/`. Their old data (if any) in
+  `<ws>/tickets/_logs/` is NOT migrated automatically; it stays as
+  historical record. Future events go to `.dru-code/`. After upgrading
+  cockpit to 0.3.3, the new wizard will additionally write a
+  `DRUUMEN_SESSIONS_DB_ROOT` env prefix into the hook command so
+  future enables explicitly pin the location.
+
+## [0.1.4] — 2026-05-16
+
+Hook gate relaxation so marketplace cockpit users on non-druumen
+workspaces can actually record sessions.
+
+### Changed (hook)
+
+- `cli/sessions-db-session-start-main.mjs` — the cwd-gate accepts a
+  workspace as authorized when EITHER:
+  1. a `CLAUDE.md` containing the `Druumen Workspace` sentinel exists
+     at cwd or any ancestor (original 0.1.x behavior), OR
+  2. `.dru-code/sessions-db.json` or `tickets/_logs/sessions-db.json`
+     exists at cwd or any ancestor — i.e. the workspace was already
+     opted in via cockpit's Setup Wizard or a manual `initProjection`.
+  Either marker counts as explicit user consent for this workspace.
+  Workspaces with neither still bail silently — random scratch dirs
+  still don't get session events.
+
+### Why
+
+Cockpit-vscode 0.3.0+ ships the Setup Wizard which creates
+`<workspace>/.dru-code/sessions-db.json` on Enable. Before this fix,
+the hook then rejected every SessionStart in that workspace because no
+CLAUDE.md sentinel was present — events.jsonl stayed empty and the
+SESSIONS panel showed `0 active` forever. The `.dru-code/` file
+already represents user consent; the gate now treats it as such.
+
+### Test
+
+- New `contract-1b` test in
+  `__tests__/hook/sessions-db-session-start.test.mjs` plants a
+  `.dru-code/sessions-db.json` in a workspace with NO CLAUDE.md
+  sentinel and verifies the hook records a session_seen event.
+  Existing `contract-1` still passes (workspace with neither marker
+  still rejects).
+- Full suite: 446 tests, 0 fail.
+
+### No public API change
+
+Same exported surface as 0.1.3. The gate widening is additive;
+consumers that previously passed still pass. Cockpit pin
+`>=0.1.0 <0.2.0` picks up 0.1.4 automatically on `npm install`.
+
 ## [0.1.3] — 2026-05-15
 
 CI metadata patch. **Same source code as 0.1.1 / 0.1.2** — both prior

package/cli/sessions-db-session-start-main.mjs

@@ -9,8 +9,10 @@
  * from a hook that is purely observational.
  *
  * Six-item safety contract (every test below cross-references one item):
- *  1. cwd-gate: bail on any cwd whose nearest CLAUDE.md does not declare a
- *     "Druumen Workspace". No event written.
+ *  1. cwd-gate: bail on any cwd that is neither a Druumen Workspace
+ *     (CLAUDE.md sentinel) nor an opted-in workspace (existing
+ *     `.dru-code/sessions-db.json` or `tickets/_logs/sessions-db.json`
+ *     under cwd or any ancestor). No event written when both rejected.
  *  2. < 2 second budget: bootstrap's setTimeout(2000ms).unref() always wins.
  *     Each sub-probe respects a single global deadline derived from
  *     `gitContext({ totalBudgetMs })` — six probes can never sum past the
@@ -32,10 +34,11 @@
  * concurrent hooks for the same `claude_session_id` will serialize on the
  * lock and observe each other's mint, so identity does not split.
  *
- * cwd discipline: every storage call passes `{ root: storageRoot }` so the
- * events.jsonl + projection cache + lock file all anchor on the project
- * cwd (resolved via CLAUDE.md walk + git common-dir), NOT on the random
- * `process.cwd()` Claude Code happened to spawn the hook from.
+ * cwd discipline: every storage call passes one of `{ rootPath }` or
+ * `{ root }` derived from the gated cwd / git common-dir, NOT from the
+ * random `process.cwd()` Claude Code happened to spawn the hook from.
+ * `DRUUMEN_SESSIONS_DB_ROOT` env > auto-detected `.dru-code/` > legacy
+ * `tickets/_logs/` anchored on workspace root.
  */
 
 import { createHash } from 'node:crypto';
@@ -76,9 +79,13 @@ async function main() {
     process.env.CLAUDE_PROJECT_DIR ||
     process.cwd();
 
-  // (3) cwd-gate. We walk up from cwd looking for a CLAUDE.md that contains
-  // the "Druumen Workspace" sentinel. Any other repo (admin, blog, a random
-  // scratch dir) bails silently.
+  // (3) cwd-gate. Accept the cwd when EITHER of:
+  //   - a CLAUDE.md "Druumen Workspace" sentinel exists at cwd or ancestor
+  //     (druumen-monorepo opt-in), OR
+  //   - a `.dru-code/sessions-db.json` or `tickets/_logs/sessions-db.json`
+  //     already exists under cwd or ancestor (cockpit Setup Wizard or
+  //     prior manual init already opted this workspace in).
+  // Any other repo bails silently.
   if (!isDruumenWorkspace(cwd)) {
     process.exit(0);
   }
@@ -97,10 +104,44 @@ async function main() {
     process.exit(0);
   }
 
-  // (5) Resolve the storage root. Prefer the worktree root (so different
-  // worktrees of the same repo each accumulate their own events.jsonl) and
-  // fall back to the gated cwd. NEVER fall back to process.cwd() — see (2).
-  const storageRoot = gitCtx.worktreePath || cwd;
+  // (5) Resolve the storage root. Three-tier strategy so cockpit-marketplace
+  // users (who have a `.dru-code/` storage dir) and druumen-monorepo users
+  // (who have a `tickets/_logs/` storage dir) BOTH have their hooks write
+  // into the exact location their reader is watching:
+  //
+  //   (5a) `DRUUMEN_SESSIONS_DB_ROOT` env var overrides everything. Cockpit
+  //        Setup Wizard writes this into the hook command line so the hook
+  //        knows the precise storage dir (typically `<ws>/.dru-code`) the
+  //        user opted into via Enable. Forwarded as `{ rootPath }` —
+  //        recordSessionSeen treats it as the bare storage dir (no
+  //        `tickets/_logs/` prefix added).
+  //
+  //   (5b) Auto-detect `<workspaceRoot>/.dru-code/sessions-db.json` when no
+  //        env override is set. If the user (or wizard) opted in via the
+  //        new-convention layout we honor it without polluting their repo
+  //        with a `tickets/_logs/` subdir.
+  //
+  //   (5c) Fall back to the historic `{ root: workspaceRoot }` form which
+  //        writes under `<workspaceRoot>/tickets/_logs/`. Druumen monorepo
+  //        relies on this; existing `tickets/_logs/sessions-db.json` data
+  //        keeps accumulating in the same place.
+  //
+  // NEVER fall back to process.cwd() — see (2).
+  const workspaceRoot = gitCtx.worktreePath || cwd;
+  const envRoot = process.env.DRUUMEN_SESSIONS_DB_ROOT;
+
+  let recordTargetOpts;
+  if (typeof envRoot === 'string' && envRoot.length > 0) {
+    // (5a) env override — new-convention rootPath shape.
+    recordTargetOpts = { rootPath: envRoot };
+  } else if (existsSync(join(workspaceRoot, '.dru-code', 'sessions-db.json'))) {
+    // (5b) auto-detect .dru-code/ — new-convention rootPath shape pointing
+    // at the storage subdir, not the workspace root.
+    recordTargetOpts = { rootPath: join(workspaceRoot, '.dru-code') };
+  } else {
+    // (5c) legacy fallback — tickets/_logs/ anchored at workspace root.
+    recordTargetOpts = { root: workspaceRoot };
+  }
 
   // (6) claude_session_id — required input. Without it we cannot reconcile
   // identity at all, so we bail rather than minting a stable_id we can never
@@ -167,14 +208,13 @@ async function main() {
   // ALL the signals we have so the resolver can walk the chain and surface
   // both the matched stable_id and any parent candidates (hub-spoke hints).
   //
-  // Every storage path is anchored on `storageRoot` — events.jsonl,
-  // projection cache, and lock file all land in <storageRoot>/tickets/_logs/.
-  // This is the cwd-plumb-through fix: process.cwd() is NEVER read by
-  // storage when called this way.
+  // Storage location: `recordTargetOpts` carries either `{ rootPath }` (env
+  // override or auto-detected `.dru-code/`) or `{ root }` (legacy
+  // tickets/_logs/ anchored on workspace root) — see step (5).
   try {
     await recordSessionSeen({
       claudeSessionId,
-      root: storageRoot,
+      ...recordTargetOpts,
       lockTimeoutMs: 1500,
       transcriptMeta,
       gitContext: gitCtx,
@@ -262,27 +302,59 @@ function readStdinJson({ timeoutMs }) {
 }
 
 /**
- * Walk up from `cwd` looking for a CLAUDE.md whose body contains the
- * "Druumen Workspace" sentinel. Bounded to 12 ancestors so a runaway loop
- * (e.g. weird filesystem mount) cannot stall us.
+ * Decide whether the hook is allowed to record events for `cwd`.
+ *
+ * Two acceptance fast-paths, either of which is sufficient:
  *
- * Returns true when sentinel found, false otherwise (incl. read errors).
+ *   1. **Druumen Workspace sentinel** — a `CLAUDE.md` at `cwd` or any
+ *      ancestor whose body contains the literal string "Druumen Workspace".
+ *      Original 0.1.x gate; how the Druumen monorepo opts in.
+ *
+ *   2. **Pre-initialized sessions-db storage** — `.dru-code/sessions-db.json`
+ *      or `tickets/_logs/sessions-db.json` already exists at `cwd` or any
+ *      ancestor. The cockpit Setup Wizard creates this file when the user
+ *      explicitly enables sessions tracking for a workspace; an external
+ *      project that has never opted in will not have either marker.
+ *
+ * Either marker is treated as user consent for this workspace. The walk
+ * is bounded to 12 ancestors so a runaway loop (e.g. weird FS mount)
+ * cannot stall us; the loop terminates early as soon as ANY marker is
+ * found at the current level.
+ *
+ * The function name is kept (`isDruumenWorkspace`) for git history clarity
+ * even though the semantic has broadened to "authorized workspace". Both
+ * acceptance criteria are checked at each ancestor before walking up
+ * (cheap stat-only probes for the storage paths).
+ *
+ * Returns true on the first hit, false after 12 ancestors / filesystem
+ * root / read errors with no marker found.
  */
 function isDruumenWorkspace(cwd) {
   if (typeof cwd !== 'string' || cwd.length === 0) return false;
   let dir = cwd;
   for (let i = 0; i < 12; i++) {
-    const candidate = join(dir, 'CLAUDE.md');
-    if (existsSync(candidate)) {
+    // Fast-path 1: CLAUDE.md sentinel
+    const claudeMd = join(dir, 'CLAUDE.md');
+    if (existsSync(claudeMd)) {
       try {
         // We only need the first ~8KB to find the sentinel; CLAUDE.md is
         // typically short, so reading the whole file is fine.
-        const body = readFileSync(candidate, 'utf8');
+        const body = readFileSync(claudeMd, 'utf8');
         if (body.includes('Druumen Workspace')) return true;
       } catch {
         // unreadable — keep walking up just in case there's a higher one.
       }
     }
+    // Fast-path 2: pre-initialized sessions-db storage. Stat-only — we
+    // don't read these files here, just check existence. Either convention
+    // (cockpit-marketplace `.dru-code/` or druumen-monorepo `tickets/_logs/`)
+    // counts as opt-in.
+    if (
+      existsSync(join(dir, '.dru-code', 'sessions-db.json')) ||
+      existsSync(join(dir, 'tickets', '_logs', 'sessions-db.json'))
+    ) {
+      return true;
+    }
     const parent = dirname(dir);
     if (parent === dir) return false;
     dir = parent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@druumen/sessions-db",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Cross-session traceability for Claude Code — events.jsonl SSoT + JSON projection cache + 3-priority identity reconciliation",
   "license": "Apache-2.0",
   "type": "module",