@druumen/sessions-db 0.1.0 → 0.1.4

package/CHANGELOG.md

@@ -5,6 +5,254 @@ 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.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
+versions stayed tombstone tags because separate npm-side gates
+rejected the publish. This release fixes the second one. Cockpit pin
+`>=0.1.0 <0.2.0` will pick up 0.1.3.
+
+### Fixed (CI / supply chain)
+
+- `package.json` `repository.url` switched from
+  `git+ssh://git@gitlab.tinfant.org:8922/druumen/sessions-db.git` to
+  `git+https://github.com/druumen/sessions-db.git`. Required by npm
+  registry's provenance verification: when a package is published with
+  `--provenance` from GitHub Actions, npm rejects (HTTP 422) if the
+  signed provenance source URL doesn't match `repository.url` in the
+  shipped tarball's package.json. Defense against supply-chain attacks
+  where attestation comes from a different repo than the metadata
+  claims.
+
+### Repo SSoT vs publish-canonical mirror
+
+- **Source-of-truth (development)**: `gitlab.tinfant.org/druumen/sessions-db`
+  (private to tinfant org, where MRs land + CI runs first).
+- **Publish-canonical (npm-visible)**: `github.com/druumen/sessions-db`
+  (public mirror, what `npm publish --provenance` attests to + what
+  `npm view @druumen/sessions-db | grep repository` shows consumers).
+
+This split is now documented in `README.md` and `RELEASING.md`. Issues
++ MRs continue to live on GitLab; the GitHub mirror is for `npm
+install` consumers' "view source" link + provenance attestation.
+
+### Tombstone tag note (0.1.2)
+
+- `v0.1.2` exists on GitLab + GitHub mirror as a permanent tag against
+  commit `d908df77` but is **NOT published to npm**. The OIDC publish
+  attempt got past the auth fix from 0.1.2's CI change (npm 11.5.x),
+  signed provenance to Sigstore log `1549510274` (immutable), but
+  failed at the registry PUT with `422 Unprocessable Entity` because
+  of the repo URL mismatch fixed in 0.1.3.
+- Together with `v0.1.1` (logIndex 1547090299 / 1549427812), there are
+  now **3 sigstore provenance records** on the public transparency log
+  for failed-publish attempts of this package's 0.1.x series. They
+  prove the GitHub Actions runner attempted publishes and serve as
+  audit trail.
+
+### `[ASSUMPTION]` lessons recorded (per `feedback_tag_vendor_assumptions_in_plans`)
+
+Day-of-OIDC-bringup assumption miss #2 (after the npm-version one):
+- "Provenance verification accepts any repository.url in package.json"
+  → wrong. npm rejects 422 if signed provenance source doesn't match
+  metadata. This is npm's documented behavior but wasn't surfaced in
+  the original D15 design or RELEASING.md.
+
+Will save a second feedback memory specifically for "OIDC publish
+requires repo-URL alignment with provenance signer" so future plans
+flag it.
+
+## [0.1.2] — 2026-05-15
+
+CI-only patch. **Same source code as 0.1.1** — but 0.1.1 never actually
+landed on the npm registry; it stayed a tombstone tag because the
+GitHub Actions OIDC publish workflow used npm 10.8.2 (default for
+Node 20), which signs sigstore provenance fine but lacks the OIDC
+trusted-publisher token-exchange flow that npm registry requires
+(added in npm **11.5.1**). The publish PUT got 404 (npm-style auth
+masking) twice in a row.
+
+This release fixes the workflow + ships the same library code under
+0.1.2. Cockpit pinning `>=0.1.0 <0.2.0` will pick this up
+automatically; no manual install change needed.
+
+### Fixed (CI / supply chain)
+
+- `.github/workflows/publish.yml` now runs `npm install -g npm@latest`
+  before the publish step. Picks up OIDC trusted publisher support
+  (≥11.5.1) without changing the runner's Node version (constrained
+  by `engines: ">=18.0.0"` in package.json).
+
+### Tombstone tag note (0.1.1)
+
+- `v0.1.1` exists on GitLab + GitHub mirror as a permanent tag against
+  commit `4350814e` but is **NOT published to npm**. Two failed OIDC
+  publish attempts left two sigstore provenance records on the public
+  transparency log (`logIndex 1547090299` and `logIndex 1549427812`),
+  immutable forever — they prove the GitHub Actions runner attempted
+  to publish that tag. Consumers should ignore `v0.1.1` entirely.
+- The 0.1.1 CHANGELOG entry is preserved below as the full record of
+  the packaging fixes that **shipped under 0.1.2**.
+
+### `[ASSUMPTION]` lesson recorded
+
+- Per memory `feedback_tag_vendor_assumptions_in_plans` (saved
+  2026-05-15): the assumption "npm CLI shipped with Node 20 supports
+  OIDC trusted publisher" was written as fact in the original D15
+  publish.yml. Both Codex round-2 review and the cockpit owner's
+  bootstrap step 7 missed it because both audited "trusted publisher
+  is configured" without checking "is the runner's npm version
+  capable of using it." Real-world v0.1.1 publish surfaced the gap.
+
+## [0.1.1] — 2026-05-15
+
+Packaging-only patch release. Fixes 3 independent bugs surfaced by the
+first real consumer (Druumen Cockpit Phase 3 B1 integration) within
+hours of 0.1.0 publish. **Zero runtime/library code changes** — same
+public API surface, same test coverage. The fix is in how the package
+is shipped, not what it does.
+
+This is also the **first OIDC publish path test** — released via
+GitHub Actions trusted publisher (no NPM_TOKEN_BOOTSTRAP), with
+`--provenance` attestations. Consumers can now verify provenance via
+`npm view @druumen/sessions-db@0.1.1 --json | jq .dist.attestations`.
+
+### Fixed
+
+- **Bug A — Node16 module resolution ignores top-level `types`** when
+  `exports` map is present. 0.1.0 had bare-string-form
+  `"exports": { ".": "./lib/index.mjs" }` plus a top-level
+  `"types": "./types/index.d.ts"` — the top-level was silently
+  dropped under cockpit's `moduleResolution: "Node16"`. Symptom:
+  `TS7016: Could not find a declaration file for module '@druumen/sessions-db'`.
+  Fix: conditional exports map with explicit `types` + `import` +
+  `require` + `default` per entry. The top-level `types` is kept as
+  legacy fallback for `moduleResolution: "node"` (older TypeScript).
+
+- **Bug B — `types/index.d.ts` re-exported type aliases not values**.
+  0.1.0 had a hand-crafted `types/index.d.ts` with patterns like
+  `export type LoadProjection = typeof import('./storage.d.mts').loadProjection`
+  — these are TYPE ALIASES, not VALUE re-exports. Consumer could write
+  `import type { LoadProjection }` but not `import { loadProjection }`.
+  Symptom: `TS2305: Module '@druumen/sessions-db' has no exported
+  member 'loadProjection'`. Root cause: stale Day-2 artifact when
+  `lib/index.mjs` was a stub; never updated when Day 3 added real
+  value re-exports to `lib/index.mjs`. Fix: replace with a barrel
+  pattern that stitches `./index.d.mts` (auto-emitted value re-exports
+  mirroring lib/index.mjs) + `./types.d.mts` (auto-emitted type
+  declarations from lib/types.mjs `@typedef` block).
+
+- **Bug C — pure ESM rejected by Node16 CJS context**. 0.1.0 was pure
+  ESM (`"type": "module"` + only `.mjs` source). Cockpit (Node16 +
+  no `"type":"module"` → CJS context) hit `TS1479: ECMAScript module
+  cannot be imported with require`. Fix: dual CJS+ESM build via
+  esbuild — `lib/index.cjs` (62 KB bundle) is generated alongside
+  `lib/index.mjs` by `npm run build:cjs`. Exports map's `require`
+  condition routes CJS consumers to the bundle, `import` condition
+  keeps ESM consumers on the per-file structure. The bundle is
+  regenerated at `prepublishOnly` time so it always matches the
+  current `lib/index.mjs` exports.
+
+### Added
+
+- **Regression guards** so Bug A / B / C class issues surface at
+  publish time, not consumer integration time:
+  - `__tests__/pack-install-smoke/pack-install-smoke.test.mjs` —
+    end-to-end packaged-consumer smoke. `npm pack`s the source,
+    installs the tarball into a temp consumer dir, then exercises
+    the actual `package.json` exports map via 3 consumer styles:
+    (a) CJS `require('@druumen/sessions-db')`, (b) ESM
+    `import('@druumen/sessions-db')`, (c) TypeScript
+    `moduleResolution: "Node16"` with both type and value imports.
+    This is the canonical "consumer's POV" test — it would have
+    caught all 3 of 0.1.0's Bug A / B / C at publish time. The other
+    smokes complement it but bypass the exports map.
+  - `__tests__/cjs-smoke/cjs-smoke.test.mjs` — runtime CJS smoke
+    against `lib/index.cjs` directly. Asserts 35+ functions + 7+
+    constants are callable.
+  - `__tests__/types-smoke/cockpit-import.ts` — added VALUE imports
+    block (was type-imports-only).
+  - `__tests__/types-smoke/tsconfig.json` switched from
+    `moduleResolution: "Bundler"` to `"Node16"`.
+- **CI build-freshness gate** — both GitLab `test-linux` and GitHub
+  Actions `Windows CI` now run `npm run build` followed by
+  `git diff --exit-code lib/index.cjs types/`. If a contributor
+  edits `lib/*.mjs` (changing exported signatures) but forgets to
+  rerun the build before commit, CI fails fast at PR time instead
+  of shipping a stale bundle to npm.
+
+### Build
+
+- **`esbuild` ^0.25.x** added as a devDependency (single dep, no
+  runtime cost — bundle output has zero deps). `npm run build:cjs`
+  produces `lib/index.cjs` from `lib/index.mjs`. `npm run build`
+  runs both `build:types` (tsc) and `build:cjs` (esbuild).
+  `prepublishOnly` runs `npm run build` so the tarball always
+  contains the freshly-bundled CJS + freshly-emitted .d.mts.
+
+- `package.json` `"main"` switched to `./lib/index.cjs` (CJS entry
+  for legacy tooling). `"module"` field added pointing to
+  `./lib/index.mjs` (legacy bundler hint, e.g. webpack 4).
+
+### Tarball delta vs 0.1.0
+
+- 50 → 51 files (+1: `lib/index.cjs`)
+- 108.6 KB → 123.6 KB (+15 KB, all CJS bundle)
+- 371.2 KB → 432.8 KB unpacked (still well under target)
+
+### Codex round + lessons
+
+- Codex adversarial review applied (agentId: see commit message of
+  the round-2 fix commit).
+- Per `feedback_tag_vendor_assumptions_in_plans` saved 2026-05-15:
+  the assumption "ESM-only is fine for npm publishing" should have
+  been tagged `[ASSUMPTION]` in the original D-path plan, not
+  written as fact. Real-world consumer (cockpit Node16 CJS) surfaced
+  the gap. Documented for future plan-drafting discipline.
+
 ## [0.1.0] — 2026-05-15
 
 First public release. Extracted from the Druumen monorepo as a
@@ -41,7 +289,7 @@ dependencies.
   never walks to `/` on a slow networked mount.
 - **TypeScript types**: hand-curated `types/index.d.ts` re-export hub
   plus auto-emitted `.d.mts` siblings via `tsc --emitDeclarationOnly`
-  + JSDoc on the source `.mjs` files. Cockpit and other TS consumers
+  driven by JSDoc on the source `.mjs` files. Cockpit and other TS consumers
   can `import type { KnownSession, Projection } from '@druumen/sessions-db'`.
 - **Cross-platform**: macOS / Linux / Windows all supported and
   CI-gated. Linux runs on GitLab `test-linux` (Node 20). Windows runs
@@ -88,6 +336,13 @@ dependencies.
   using a one-time `NPM_TOKEN_BOOTSTRAP` Granular Access Token (48h
   expiry, `@druumen` scope, masked + protected + environment-scoped
   variable, revoked immediately after publish).
+- **v0.1.0 published WITHOUT provenance attestations** — intentional.
+  The bootstrap path runs from GitLab CI which has no GitHub-Actions-
+  style OIDC token issuer for npm; the npm registry only accepts
+  provenance from a recognized OIDC publisher (currently GitHub Actions
+  and GitLab.com SaaS). `npm view @druumen/sessions-db@0.1.0 --json | jq
+  .dist.attestations` returns `{}`. This is a one-time gap covering
+  only the bootstrap release; v0.1.1 onwards have full provenance.
 - **v0.1.1 onwards** publish from GitHub Actions
   (`.github/workflows/publish.yml`) via npm **OIDC trusted publishing**
   — no long-lived secrets, short-lived OIDC tokens validated by npm
@@ -247,3 +502,44 @@ contract.
   releases, uses `id-token: write` + `--provenance` flag for npm
   attestations. Inactive until trusted publisher configured on npm
   web (Bootstrap step 7).
+
+### Day 8 — 2026-05-15 (v0.1.0 published — 3 lessons learned)
+
+- **Published**: `@druumen/sessions-db@0.1.0` live on npm registry at
+  2026-05-15T08:22:56Z, Apache-2.0, `dist.shasum a70980a7…`. Pipeline
+  #429 (post-release-prep merge `645a8a4e`): `test-linux` 9.4s +
+  `mirror-to-github` 5.2s + `publish-npm` 12.6s. Trusted publisher
+  configured on npm web (org=druumen, repo=sessions-db, workflow=
+  publish.yml, env=npm-publish) immediately after bootstrap revoke,
+  arming OIDC path for 0.1.1+.
+
+- **Lesson 1 (Δ35 — protected `v*` tag gap)**: First v0.1.0 tag
+  pipeline `mirror-to-github` failed because `GITHUB_MIRROR_TOKEN`
+  (protected variable) wasn't accessible from `v*` tag pipelines —
+  only `master` + `fix/*` were in the protected refs list. Fixed by
+  adding `v*` to GitLab Protected Tags (Maintainers can create).
+  RELEASING.md pre-flight now explicitly lists the protected-refs
+  audit including `v*`.
+
+- **Lesson 2 (Δ36 — npm Granular "Bypass 2FA" checkbox)**: 5
+  consecutive `EOTP npm error code EOTP` failures during initial
+  publish attempts. Root cause discovered: npm removed Classic
+  Automation tokens in November 2025; only Granular Access Tokens
+  are now supported, and Granular tokens require an OTP at publish
+  time **even when the account is in `auth-only` 2FA mode**, unless
+  the explicit "Bypass two-factor authentication (2FA)" checkbox is
+  ticked at token creation. Token regenerated with the checkbox →
+  immediate publish success. RELEASING.md Step 1 now flags this as
+  a `MUST be checked` item with prominent ⚠️ marker.
+
+- **Lesson 3 (Δ37 — v0.1.0 has no provenance)**: Documented in the
+  Supply chain section above. Bootstrap path runs from GitLab CI
+  which lacks GitHub-Actions-style npm OIDC integration; v0.1.0 ships
+  without `dist.attestations`. Intentional and one-time — v0.1.1+ via
+  OIDC restores full provenance.
+
+- **Cockpit Phase 3 unblocked**: B1-B14 implementation begins
+  immediately on cockpit side. `npm install @druumen/sessions-db`
+  works for marketplace prep. Expect 1-2 minor patch releases
+  (0.1.1 / 0.1.2) shaking out integration corner cases — these will
+  be the first real exercise of the OIDC publish path.

package/README.md

@@ -2,6 +2,14 @@
 
 Cross-session traceability for [Claude Code](https://claude.com/claude-code).
 
+> **Repository note**: development happens at
+> `gitlab.tinfant.org/druumen/sessions-db` (private to tinfant org —
+> file MRs there). The `github.com/druumen/sessions-db` mirror is
+> public and is the source-of-truth for npm provenance attestations
+> + the consumer-facing "view source" link from
+> <https://www.npmjs.com/package/@druumen/sessions-db>. Both are kept
+> in sync via GitLab CI's `mirror-to-github` job.
+
 ## What it does
 
 Records every Claude Code session start (cwd, branch, transcript file,
@@ -120,6 +128,26 @@ The hook is bootstrap-safe by design:
 - Errors are logged to stderr (visible in Claude Code's session log)
   but never surfaced as user-facing failures.
 
+#### Subpath imports `./cli` and `./hook` are ESM-only
+
+The `@druumen/sessions-db/cli` and `@druumen/sessions-db/hook` exports
+resolve to `.mjs` entry points and are intended to be **executed as
+processes** (via the `bin` field's shim, or invoked directly with
+`node <path>`). They are NOT intended for programmatic `require()` /
+`import` from a consumer's runtime code.
+
+If you need to run the CLI from your code, spawn it as a child process:
+
+```js
+// CJS or ESM consumer — spawn the CLI as a process
+import { spawnSync } from 'node:child_process';
+spawnSync('npx', ['sessions-db', 'find', '...'], { stdio: 'inherit' });
+```
+
+The main library entry (`@druumen/sessions-db`) IS dual-published as
+both CJS and ESM and works from either context. Only the bin-style
+subpaths are ESM-only.
+
 ## Path resolution
 
 When you don't pass an explicit `rootPath`, sessions-db walks a 5-priority

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
@@ -76,9 +78,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);
   }
@@ -262,27 +268,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`.
  *
- * Returns true when sentinel found, false otherwise (incl. read errors).
+ * Two acceptance fast-paths, either of which is sufficient:
+ *
+ *   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;