From 41deb44b064a5900f1787c67db07432b448e1cc1 Mon Sep 17 00:00:00 2001
From: ozymandiashh <234437643+ozymandiashh@users.noreply.github.com>
Date: Tue, 4 Aug 2026 03:17:41 +0300
Subject: [PATCH] chore: pin node via .nvmrc, add the new-provider checklist

.nvmrc matches the engines floor and the appx pin (22.13.0), taming the
package-lock churn from contributors on drifting node/npm versions. The
checklist distills the house rules new-provider PRs keep relearning:
product split, cache-key coupling, reported-cost presence semantics,
defensive parsing, probeRoots for doctor, and the real-local-testing bar.
---
 .nvmrc                         |  1 +
 docs/providers/NEW_PROVIDER.md | 46 ++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 .nvmrc
 create mode 100644 docs/providers/NEW_PROVIDER.md

diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 00000000..6fa8dec4
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+22.13.0
diff --git a/docs/providers/NEW_PROVIDER.md b/docs/providers/NEW_PROVIDER.md
new file mode 100644
index 00000000..a13c071d
--- /dev/null
+++ b/docs/providers/NEW_PROVIDER.md
@@ -0,0 +1,46 @@
+# New provider checklist
+
+Guide for adding a new session-discovery provider to codeburn. Follow every item; most exist because a past provider broke without them.
+
+## One provider, one product
+
+- [ ] A provider is one product. Same-vendor IDE and CLI products get separate providers.
+- [ ] Precedents: `kimi` / `kimicode`, `cursor` / `cursor-agent`, `cline` / `cline-cli`.
+- [ ] Do not merge products under one provider name. `PROVIDER_PARSE_VERSIONS` and `PROVIDER_ENV_VARS` are keyed by provider name, so merging couples cache invalidation across products.
+- [ ] Separate providers also keep `codeburn doctor` output legible.
+
+## Required pieces
+
+- [ ] `src/providers/<name>.ts` implementing the Provider contract.
+- [ ] Registration in `src/providers/index.ts` `coreProviders` (or the lazy list).
+- [ ] `PROVIDER_ENV_VARS` entry in `src/session-cache.ts` when discovery reads env overrides.
+- [ ] `PROVIDER_PARSE_VERSIONS` entry when cached entries must re-parse after parser changes.
+- [ ] `probeRoots()` is required for new providers, not optional. `codeburn doctor` uses it to tell "not installed" from "override points somewhere empty" - the silent-$0.00 class (#874, #899).
+
+## Cost rules
+
+- [ ] If the tool meters its own per-message cost, add the provider to the reported-cost allowlist in `src/parser.ts` (`providerCallToCachedCall`).
+- [ ] Cost presence is a PRESENCE check, not truthiness: a metered $0 stays reported (free/cached calls).
+- [ ] Computed costs go through `calculateCost` and set `costIsEstimated: true`.
+
+## Parsing rules
+
+- [ ] Defensive reads on every field - records may be any JSON.
+- [ ] Dedup keys namespaced as `<provider>:<sessionId>:<messageId>`.
+- [ ] Timestamps guard against seconds-vs-milliseconds: promote and reject implausible values (see `kiro.ts` / `cline-cli.ts`).
+- [ ] Never let one corrupt file throw - skip it.
+
+## Tests
+
+- [ ] Fixture-based tests under `tests/providers/<name>.test.ts` covering discovery, parsing, cost semantics, and `probeRoots` resolution.
+- [ ] The suite scrubs env in `tests/setup/env-isolation.ts`, so tests set their own overrides.
+
+## PR expectations
+
+- [ ] Proof of real local testing in the PR body: generated sessions from the actual tool, not only fixtures.
+- [ ] No Claude/Anthropic co-author trailers - CI rejects them.
+- [ ] Docs page under `docs/providers/<name>.md` describing the storage layout and any quirks.
+
+## Fastest path
+
+Read `src/providers/cline-cli.ts` end to end first. It is the most recent provider and demonstrates every rule above.