Optional knob to waive npm release-age soak for the zero-dependency commy-mcp bundle (#29)

## Problem

An operator who runs npm's
[`min-release-age`](https://docs.npmjs.com/cli/using-npm/config#min-release-age)
supply-chain soak can't launch a freshly-published
`@codeforbreakfast/commy-mcp` release. npm compiles `min-release-age`
into a global `before=` publish-date cutoff over the whole install tree,
with **no per-package or per-scope exclude**, so every commy-mcp version
younger than the window is filtered → `ENOVERSIONS: No versions
available` → the MCP server never launches.

`min-release-age` exists to hold back a freshly-published release so a
compromised one can be caught before you auto-pull it — it guards you
against the **publisher's own not-yet-vetted code**. Waiving it is
therefore a deliberate trust decision about the publisher, not a free
pass.

## Change

Expose an optional, **off-by-default** operator knob,
`COMMY_NPM_MIN_RELEASE_AGE`, threaded into the launcher env as
`npm_config_min_release_age` (scoped to commy's own `npx` invocation).
Set it to `0` to trust the commy publisher and run a fresh release
immediately; leave it unset to keep your own npm setting fully in force.

The published package is a **zero-dependency bundle** —
`scripts/assemble-npm-package.ts` inlines every dependency into a single
`server.js`, and the generated manifest has no `dependencies` field. So
the waiver is cleanly scoped to exactly this one publisher: no
transitive dependency tree rides along with the decision.

The safety property — verified against npm 11.12.1 — is that an unset
knob never weakens the operator's own configuration: an unset/empty env
var leaves a consumer's `.npmrc min-release-age` untouched (npm ignores
an empty env var rather than overriding the file), and only an explicit
`0` waives the soak. The launcher test pins this by asserting the
userConfig is optional with no default.

## Surface

- `clients/claude-code/.claude-plugin/plugin.json` — optional
`COMMY_NPM_MIN_RELEASE_AGE` userConfig declaration
- `clients/claude-code/.mcp.json` — thread it as
`npm_config_min_release_age`
- `clients/claude-code/launcher.test.ts` — pin the threaded knob and its
off-by-default contract
- `docs/self-hosting.md` — document the knob and when an operator needs
it

Author: GraemeF

clients/claude-code/.claude-plugin/plugin.json

@@ -38,6 +38,12 @@
       "title": "Boot-time catch-up window (seconds)",
       "description": "How far back to fetch recent messages across the boot-time subscribe set on a persistent-bot restart (comms-3wl). Default 14400 (4 hours). Applies to channel: and thread: narrows only; the mentions: narrow uses a separate cursor-bounded mechanism. Set to 0 to disable boot-time channel/thread catch-up.",
       "required": false
+    },
+    "COMMY_NPM_MIN_RELEASE_AGE": {
+      "type": "string",
+      "title": "npm release-age soak override for this package",
+      "description": "Operator override for npm's min-release-age supply-chain soak, scoped to commy's own `npx @codeforbreakfast/commy-mcp` launch (threaded as npm_config_min_release_age). min-release-age soaks a freshly-published release so a compromised one can be caught before you auto-pull it — it protects you from the publisher's own not-yet-vetted code, which the soak would otherwise block with ENOVERSIONS until it ages in. Setting this to 0 waives that soak for commy: a deliberate decision to trust the commy publisher and run a new release immediately (the publisher's own posture). Because commy ships as a single zero-dependency bundle, the waiver is scoped to exactly this one publisher — no transitive dependency tree rides along. Leave UNSET to keep your own npm min-release-age fully in force; an unset value never weakens it.",
+      "required": false
     }
   }
 }

clients/claude-code/.mcp.json

@@ -9,7 +9,8 @@
         "ZULIP_MINTER_EMAIL": "${user_config.ZULIP_MINTER_EMAIL}",
         "ZULIP_MINTER_API_KEY": "${user_config.ZULIP_MINTER_API_KEY}",
         "COMMY_SUBSCRIBE": "${user_config.COMMY_SUBSCRIBE}",
-        "COMMY_CATCHUP_WINDOW_SECONDS": "${user_config.COMMY_CATCHUP_WINDOW_SECONDS}"
+        "COMMY_CATCHUP_WINDOW_SECONDS": "${user_config.COMMY_CATCHUP_WINDOW_SECONDS}",
+        "npm_config_min_release_age": "${user_config.COMMY_NPM_MIN_RELEASE_AGE}"
       }
     }
   }

clients/claude-code/launcher.test.ts

@@ -1,5 +1,6 @@
 import { expect, test } from 'bun:test'
 
+import pluginManifest from './.claude-plugin/plugin.json'
 import mcpConfig from './.mcp.json'
 
 /**
@@ -56,5 +57,34 @@ test('the realm credentials and subscription env are still threaded through', ()
     'ZULIP_MINTER_API_KEY',
     'COMMY_SUBSCRIBE',
     'COMMY_CATCHUP_WINDOW_SECONDS',
+    'npm_config_min_release_age',
   ])
 })
+
+/**
+ * npm's `min-release-age` soaks a freshly-published release so a compromised
+ * one can be caught before a consumer auto-pulls it — it guards the publisher's
+ * own not-yet-vetted code. Waiving it is therefore a trust decision about the
+ * publisher, which the publisher itself can safely make (no detection window is
+ * needed for code you authored and released). The launcher exposes an optional
+ * knob for that: COMMY_NPM_MIN_RELEASE_AGE=0 waives the soak for commy;
+ * everyone else leaves it unset. commy ships as a ZERO-dependency bundle
+ * (scripts/assemble-npm-package.ts inlines every dep into one server.js), so the
+ * waiver is scoped to exactly this one publisher — no transitive tree rides
+ * along — and the consumer otherwise can't install a fresh release until it ages
+ * past their window (ENOVERSIONS).
+ *
+ * The safety property — proven against npm 11.12.1 — is that an UNSET knob must
+ * not weaken the consumer's own setting: an empty/absent env var leaves the
+ * consumer's `.npmrc min-release-age` untouched (npm ignores an empty env var
+ * rather than overriding the file), and only an explicit `0` waives the soak.
+ * That hinges on the userConfig being OPTIONAL with no default, so an
+ * unconfigured consumer threads nothing.
+ */
+test('the npm release-age knob is threaded from an optional userConfig, off by default', () => {
+  expect(commyServer.env.npm_config_min_release_age).toBe(
+    `\${user_config.COMMY_NPM_MIN_RELEASE_AGE}`,
+  )
+  expect(pluginManifest.userConfig.COMMY_NPM_MIN_RELEASE_AGE.required).toBe(false)
+  expect(pluginManifest.userConfig.COMMY_NPM_MIN_RELEASE_AGE).not.toHaveProperty('default')
+})

docs/self-hosting.md

@@ -30,6 +30,7 @@ no-op-ish values when unset):
 | `COMMY_PROJECT` | no | Project slug used for channel naming and the concierge's project subscriptions. When unset it is derived per-session from the calling cwd (git remote / git root). |
 | `COMMY_SUBSCRIBE` | no | Comma-separated auto-subscribe tokens applied at boot: `channel:<name>`, `thread:<channel>/<thread>`, `new-topics:<channel>`, `mentions`. Blank means no auto-subscription. |
 | `COMMY_CATCHUP_WINDOW_SECONDS` | no | How far back to fetch recent messages across the boot-time subscribe set on a persistent restart. Default `14400` (4 hours); `0` disables. |
+| `COMMY_NPM_MIN_RELEASE_AGE` | no | Operator override for npm's `min-release-age` supply-chain soak, scoped to commy's own `npx` launch. Set to `0` to run a freshly-published release that your global soak would otherwise block with `ENOVERSIONS`. Leave **unset** to fully respect your own npm setting. See [Running outside Claude Code](#running-outside-claude-code). |
 
 The live-test suite additionally needs a channel to exercise against:
 
@@ -58,7 +59,16 @@ npx -y @codeforbreakfast/commy-mcp
 `server.js` with every dependency inlined — and runs it under node; there is no
 install step and nothing to stage. (The package carries the `@codeforbreakfast`
 scope because `@commy` is taken on npm; the substrate is otherwise `commy`
-throughout.) Working from a source checkout instead, the dev toolchain runs the
+throughout.) If you run npm's `min-release-age` supply-chain soak — which holds
+back a freshly-published release so a compromised one can be caught before you
+auto-pull it — a commy release younger than your window fails to resolve
+(`ENOVERSIONS`) until it ages in. That soak guards you against the publisher's
+own not-yet-vetted code, so waiving it is a decision to trust the commy
+publisher and run a new release immediately: set `COMMY_NPM_MIN_RELEASE_AGE=0`
+(which the launcher threads as `npm_config_min_release_age`). Because the bundle
+has **no dependencies**, that waiver is scoped to exactly this one package — no
+transitive dependency tree rides along — and an unset value never weakens your
+own setting. Working from a source checkout instead, the dev toolchain runs the
 TypeScript entry point directly under [Bun][bun] with `bun packages/mcp/server.ts`
 — bun is the development runtime, never a consumer prerequisite. `nix` is **not**
 a runtime dependency either; the flake's dev shell stays supported for those who