stitchkit 0.81.0 → 0.82.0

package/README.md

@@ -506,6 +506,10 @@ The full guide and API reference, in [`docs/`](./docs/README.md):
   [multi-tenant](./docs/guide/multi-tenant.md) ·
   [upgrading](./docs/guide/upgrading.md)
 - **[API reference](./docs/api/reference.md)** — every export, by entrypoint.
+- **Moving to a newer version?** Run `bunx stitchkit@latest upgrade` inside your
+  project. It reads the version you have from `node_modules` and the changelog
+  from inside the package, and prints every breaking change between the two —
+  oldest first, each with who must act. Nothing to clone, nobody to ask.
 - **Coding agent?** The package ships **`llms.txt`** (a curated index) and
   **`llms-full.txt`** (the whole guide inlined) — your agent reads them from
   `node_modules/stitchkit/`. For Claude Code, the repo also provides a

package/dist/internal/upgrade-plan.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The consumer upgrade plan: every `### ⚠️ Breaking changes` section an
+ * installed → target range crosses, oldest first.
+ *
+ * Pure over the changelog text. The reader is `stitchkit upgrade`, the binary
+ * this package installs; the changelog it reads ships in the package, so a
+ * consumer recovers the plan without cloning the repository or being told the
+ * range by whoever cut the release.
+ */
+export interface UpgradeBreakingChange {
+    version: string;
+    whoMustAct: string;
+    markdown: string;
+}
+/** Extract every breaking section crossed by an exact `from` (exclusive) → `to` (inclusive) upgrade. */
+export declare function planUpgrade(changelog: string, from: string, to: string): UpgradeBreakingChange[];
+export declare function renderUpgradePlan(changes: readonly UpgradeBreakingChange[], from: string, to: string): string;
+//# sourceMappingURL=upgrade-plan.d.ts.map

package/dist/internal/upgrade-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-plan.d.ts","sourceRoot":"","sources":["../../src/internal/upgrade-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAsBD,wGAAwG;AACxG,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,qBAAqB,EAAE,CAgCzB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CASR"}

package/dist/release/socket.d.ts

@@ -1,6 +1,19 @@
 import type { ReleaseMarker } from './marker.js';
 import type { ReleaseWatcher } from './watcher.js';
-/** The little of a Socket.IO server this binding uses — structural, no peer import. */
+/**
+ * The little of a Socket.IO server this binding uses — structural, no peer
+ * import.
+ *
+ * `emit` is declared over `string` because the event name is configurable. A
+ * **typed** `Server<ClientToServer, ServerToClient>` narrows its own `emit` to
+ * the names in its map, so it satisfies this only once that map declares the
+ * event — `release: (payload: { buildId: string | null }) => void`, or whatever
+ * `options.event` renames it to. Until then the compiler reports a structural
+ * mismatch between two large socket.io types, which reads like a defect in this
+ * binding and is a missing line in the application's event map. Adding it is
+ * step 3 of the guide's adoption list for exactly this reason: the same
+ * declaration is what lets the application's own `on` know the event.
+ */
 export interface ReleaseSocketServer {
     on(event: 'connection', handler: (socket: ReleaseSocketEmitter) => void): unknown;
     emit(event: string, payload: {

package/dist/release/socket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/release/socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC;IAClF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC;CACnE;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC;CACnE;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IACnF,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC;CACtF;AAED,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,oBAAoB,GAAG;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACrE,MAAM,IAAI,CAcZ;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,oBAAyB,GACjC,MAAM,IAAI,CAQZ"}
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/release/socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC;IAClF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC;CACnE;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC;CACnE;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IACnF,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC;CACtF;AAED,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,oBAAoB,GAAG;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACrE,MAAM,IAAI,CAcZ;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,oBAAyB,GACjC,MAAM,IAAI,CAQZ"}

package/dist/tracking/contract.d.ts

@@ -27,6 +27,7 @@ export type TrackingContractEndpoints<TSchemas extends TrackingSchemas<z.ZodObje
     track: {
         method: 'POST';
         path: '/events';
+        expose: readonly ['HTTP'];
         desc: string;
         input: TSchemas['request'];
         output: TSchemas['response'];
@@ -40,6 +41,16 @@ export type TrackingContractEndpoints<TSchemas extends TrackingSchemas<z.ZodObje
  * `sendUnloadBeacon` with a string body — the only body a document that is
  * being unloaded can deliver to another origin (ADR 0165) — and the server
  * therefore needs an explicit `cors.origin` allow-list for it to arrive.
+ *
+ * **Both endpoints are HTTP-only, and that is not a formality.** An endpoint
+ * with no `expose` is a tool on MCP and AGENT by default, and this contract is
+ * built here rather than by the application's own contract factory — so a
+ * project that sets `toolExposure: 'explicit'` for everything it authors was
+ * still handed a `track` tool it never asked for. An agent has nothing to gain
+ * from a browser-event ingest and one thing to lose by having it: writes into
+ * the application's visitor data, under its own name, indistinguishable
+ * afterwards from a real visitor's. `bootstrap` said `['HTTP']` from the start;
+ * `track` not saying it was an omission, not a decision.
  */
 export declare function createTrackingContract<TType extends string, TScope extends string>(config: TrackingContractConfig<TType, undefined, TScope>): ContractDef<TrackingContractEndpoints<TrackingSchemas<z.ZodObject<TrackingEventShape<TType>>>>, TScope>;
 export declare function createTrackingContract<TType extends string, TExtras extends z.ZodRawShape, TScope extends string>(config: TrackingContractConfig<TType, TExtras, TScope>): ContractDef<TrackingContractEndpoints<TrackingSchemas<z.ZodObject<TrackingEventShape<TType> & TExtras>>>, TScope>;

package/dist/tracking/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/tracking/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,aAAa,CAAC;AAC/D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,sBAAsB,CACrC,KAAK,SAAS,MAAM,EACpB,OAAO,SAAS,CAAC,CAAC,WAAW,GAAG,SAAS,EACzC,MAAM,SAAS,MAAM,CACrB,SAAQ,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC;IAC7C,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,yFAAyF;AACzF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI;IACrF,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,QAAQ,CAAC;QACf,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;QACzB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;KAC/B,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,SAAS,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC3B,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC7B,cAAc,EAAE,IAAI,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM,EAChF,MAAM,EAAE,sBAAsB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,GACvD,WAAW,CACZ,yBAAyB,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAClF,MAAM,CACP,CAAC;AACF,wBAAgB,sBAAsB,CACpC,KAAK,SAAS,MAAM,EACpB,OAAO,SAAS,CAAC,CAAC,WAAW,EAC7B,MAAM,SAAS,MAAM,EAErB,MAAM,EAAE,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,GACrD,WAAW,CACZ,yBAAyB,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5F,MAAM,CACP,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/tracking/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,aAAa,CAAC;AAC/D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,sBAAsB,CACrC,KAAK,SAAS,MAAM,EACpB,OAAO,SAAS,CAAC,CAAC,WAAW,GAAG,SAAS,EACzC,MAAM,SAAS,MAAM,CACrB,SAAQ,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC;IAC7C,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,yFAAyF;AACzF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI;IACrF,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,QAAQ,CAAC;QACf,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;QACzB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;KAC/B,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC3B,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC7B,cAAc,EAAE,IAAI,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM,EAChF,MAAM,EAAE,sBAAsB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,GACvD,WAAW,CACZ,yBAAyB,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAClF,MAAM,CACP,CAAC;AACF,wBAAgB,sBAAsB,CACpC,KAAK,SAAS,MAAM,EACpB,OAAO,SAAS,CAAC,CAAC,WAAW,EAC7B,MAAM,SAAS,MAAM,EAErB,MAAM,EAAE,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,GACrD,WAAW,CACZ,yBAAyB,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5F,MAAM,CACP,CAAC"}

package/dist/tracking-server.d.ts

@@ -5,6 +5,7 @@
  * back; `issueVisitLease` runs the visit algorithm over a store interface the
  * application implements. No database, no schema, no domain. → ADR 0166.
  */
+export type { TrackingDisposition, VisitBootstrapResponse, VisitEntryContext, } from './tracking/schemas.js';
 export { type ActiveIntervalOptions, type ActiveTimeInterval, activeIntervalOf, } from './tracking/server/active-interval.js';
 export { DEFAULT_BOT_USER_AGENT_PATTERN, isBotUserAgent } from './tracking/server/bot.js';
 export { type DispositionEvent, type DispositionInput, type DispositionResult, dispositionTrackingBatch, type KnownVisit, } from './tracking/server/disposition.js';

package/dist/tracking-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracking-server.d.ts","sourceRoot":"","sources":["../src/tracking-server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,gBAAgB,GACjB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,8BAA8B,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,KAAK,UAAU,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"tracking-server.d.ts","sourceRoot":"","sources":["../src/tracking-server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,gBAAgB,GACjB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,8BAA8B,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,KAAK,UAAU,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,+BAA+B,CAAC"}

package/dist/tracking.js

@@ -778,6 +778,7 @@ function createTrackingContract(config) {
     track: {
       method: "POST",
       path: "/events",
+      expose: ["HTTP"],
       desc: "Batch track browser events",
       input: schemas.request,
       output: schemas.response,

package/dist/upgrade-cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+export interface UpgradeCliResult {
+    /** What to write to stdout. */
+    readonly output: string;
+    /** Process exit code — 0 when the plan (or "nothing to do") was produced. */
+    readonly code: number;
+}
+/**
+ * The whole command as a function of its arguments and the filesystem, so the
+ * gate can exercise the paths that matter — a project with no stitchkit
+ * installed, a range that runs backwards, a changelog the package did not ship.
+ */
+export declare function runUpgradeCli(argv: readonly string[]): UpgradeCliResult;
+/**
+ * Was this file executed as a program, rather than imported?
+ *
+ * Through the real install path that is a **symlink** question, not a string
+ * one: npm and bun link `node_modules/.bin/stitchkit` at the built file, Node
+ * keeps the link in `argv[1]` and resolves `import.meta.url` to its target. A
+ * direct comparison of the two is therefore false for every consumer, and the
+ * binary becomes a silent no-op — exit 0, no output, nothing to notice — while
+ * running the same file in place works perfectly. Both arguments are passed in
+ * so this is decidable without launching a process: under Bun `argv[1]` is
+ * already resolved, so a spawned symlink proves nothing about Node.
+ */
+export declare function isDirectInvocation(invoked: string | undefined, self: string): boolean;
+//# sourceMappingURL=upgrade-cli.d.ts.map

package/dist/upgrade-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-cli.d.ts","sourceRoot":"","sources":["../src/upgrade-cli.ts"],"names":[],"mappings":";AA4DA,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAqCvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CASrF"}

package/dist/upgrade-cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+// src/upgrade-cli.ts
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/internal/upgrade-plan.ts
+function semverParts(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match)
+    throw new Error(`Expected an exact semver, received "${version}"`);
+  const [, major, minor, patch] = match;
+  if (major === undefined || minor === undefined || patch === undefined) {
+    throw new Error(`Expected an exact semver, received "${version}"`);
+  }
+  return [Number(major), Number(minor), Number(patch)];
+}
+function compareSemver(left, right) {
+  const a = semverParts(left);
+  const b = semverParts(right);
+  for (const index of [0, 1, 2]) {
+    const difference = a[index] - b[index];
+    if (difference !== 0)
+      return difference;
+  }
+  return 0;
+}
+function planUpgrade(changelog, from, to) {
+  semverParts(from);
+  semverParts(to);
+  if (compareSemver(from, to) >= 0) {
+    throw new Error(`Upgrade range must increase: ${from} → ${to}`);
+  }
+  const releases = [...changelog.matchAll(/^## \[(\d+\.\d+\.\d+)\].*$/gm)];
+  const changes = [];
+  for (const [index, release] of releases.entries()) {
+    const version = release[1];
+    if (version === undefined)
+      continue;
+    if (compareSemver(version, from) <= 0 || compareSemver(version, to) > 0)
+      continue;
+    const bodyStart = (release.index ?? 0) + release[0].length;
+    const bodyEnd = releases[index + 1]?.index ?? changelog.length;
+    const body = changelog.slice(bodyStart, bodyEnd);
+    const breakingHeader = /^### ⚠️ Breaking changes\s*$/m.exec(body);
+    if (!breakingHeader)
+      continue;
+    const breakingStart = (breakingHeader.index ?? 0) + breakingHeader[0].length;
+    const afterHeader = body.slice(breakingStart);
+    const nextSection = /^### /m.exec(afterHeader);
+    const markdown = afterHeader.slice(0, nextSection?.index ?? afterHeader.length).trim();
+    const who = /^\*\*Who must act:\*\*\s*([\s\S]*?)(?=\n\s*\n|\n[-*] )/m.exec(markdown);
+    changes.push({
+      version,
+      whoMustAct: who?.[1]?.replace(/\s+/g, " ").trim() ?? "Not declared in this legacy changelog section.",
+      markdown
+    });
+  }
+  return changes.sort((left, right) => compareSemver(left.version, right.version));
+}
+function renderUpgradePlan(changes, from, to) {
+  const header = `# Stitchkit upgrade ${from} → ${to}`;
+  if (changes.length === 0)
+    return `${header}
+
+No breaking sections in this range.
+`;
+  return `${header}
+
+${changes.map((change) => `## ${change.version}
+
+**Who must act:** ${change.whoMustAct}
+
+${change.markdown.replace(/^\*\*Who must act:\*\*[\s\S]*?(?=\n\s*\n|\n[-*] )/m, "").trim()}`).join(`
+
+`)}
+`;
+}
+
+// src/upgrade-cli.ts
+var USAGE = `stitchkit upgrade — print every breaking change between the installed version and this one
+
+  bunx stitchkit@latest upgrade            in a project that depends on stitchkit
+  npx stitchkit@latest upgrade
+
+Options
+  --from <version>     installed version (default: the stitchkit in ./node_modules)
+  --to <version>       target version (default: the version of this package)
+  --cwd <dir>          project to read the installed version from (default: .)
+  --changelog <path>   changelog to plan from (default: the one in this package)
+`;
+function option(argv, name) {
+  const index = argv.indexOf(`--${name}`);
+  if (index < 0)
+    return;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`--${name} needs a value`);
+  }
+  return value;
+}
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function versionOf(packageJsonPath) {
+  let text;
+  try {
+    text = readFileSync(packageJsonPath, "utf8");
+  } catch {
+    return;
+  }
+  const parsed = JSON.parse(text);
+  if (typeof parsed !== "object" || parsed === null || !("version" in parsed))
+    return;
+  const { version } = parsed;
+  return typeof version === "string" ? version : undefined;
+}
+function runUpgradeCli(argv) {
+  if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
+    return { output: USAGE, code: 0 };
+  }
+  const [command] = argv;
+  if (command !== "upgrade") {
+    return { output: `Unknown command "${command}".
+
+${USAGE}`, code: 1 };
+  }
+  const root = packageRoot();
+  const to = option(argv, "to") ?? versionOf(join(root, "package.json"));
+  if (to === undefined) {
+    throw new Error(`Cannot read the version of the stitchkit at ${root}`);
+  }
+  const cwd = resolve(option(argv, "cwd") ?? process.cwd());
+  const from = option(argv, "from") ?? versionOf(join(cwd, "node_modules", "stitchkit", "package.json"));
+  if (from === undefined) {
+    throw new Error(`No stitchkit found in ${join(cwd, "node_modules")} — run this in the project that depends on it, or pass --from <installed version>`);
+  }
+  if (from === to) {
+    return { output: `Already on ${to}. Nothing to upgrade.
+`, code: 0 };
+  }
+  const changelogPath = option(argv, "changelog") ?? join(root, "CHANGELOG.md");
+  let changelog;
+  try {
+    changelog = readFileSync(changelogPath, "utf8");
+  } catch {
+    throw new Error(`Cannot read the changelog at ${changelogPath}`);
+  }
+  return { output: renderUpgradePlan(planUpgrade(changelog, from, to), from, to), code: 0 };
+}
+function isDirectInvocation(invoked, self) {
+  if (invoked === undefined)
+    return false;
+  if (invoked === self || pathToFileURL(invoked).href === pathToFileURL(self).href)
+    return true;
+  try {
+    return realpathSync(invoked) === realpathSync(self);
+  } catch {
+    return false;
+  }
+}
+if (isDirectInvocation(process.argv[1], fileURLToPath(import.meta.url))) {
+  try {
+    const { output, code } = runUpgradeCli(process.argv.slice(2));
+    process.stdout.write(output);
+    process.exit(code);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(1);
+  }
+}
+export {
+  runUpgradeCli,
+  isDirectInvocation
+};

package/llms-full.txt

@@ -67,7 +67,7 @@ own, recorded as an ADR.
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 11 of the 26 minors since 0.56.2, most recently 0.75.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 11 of the 27 minors since 0.56.2, most recently 0.75.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -75,7 +75,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 6 of the 26 minors since 0.56.2, most recently 0.79.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 6 of the 27 minors since 0.56.2, most recently 0.79.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -350,13 +350,42 @@ records the verdict and reloads nothing.
 
 ## Adopting it
 
-1. Bake the build id into the bundle: `NEXT_PUBLIC_BUILD_ID=$(git rev-parse
-   --short HEAD)` at build time, or Next's `generateBuildId`. Without it the
-   watcher has no `own` and never reloads.
+1. Bake the build id into the bundle, from **one** source. Without it the
+   watcher has no `own` and never reloads — and it never says so, which is the
+   part worth spending a paragraph on.
+
+   `NEXT_PUBLIC_BUILD_ID=$(git rev-parse --short HEAD)` in the build command is
+   the short version and it has a failure mode: on an immutable-release layout
+   that variable usually lives in a static environment file, so it is easy for
+   two releases to ship the same id. Then `own` equals what the server reports
+   on every response, the watcher is correct to stay quiet, and nothing
+   anywhere is red. A reload that never happens looks exactly like a reload
+   that was not needed.
+
+   So mint it once and let one value reach all three readers. In Next, that is
+   `next.config`:
+
+   ```ts
+   const buildId = process.env.BUILD_ID ?? execSync('git rev-parse --short HEAD').toString().trim()
+
+   export default {
+     generateBuildId: () => buildId,          // → .next/BUILD_ID, which the server marker reads
+     env: { NEXT_PUBLIC_BUILD_ID: buildId },  // → the bundle, which becomes `own`
+   }
+   ```
+
+   The bundle's id and the file the server reports now come from the same
+   expression evaluated once, so they cannot drift apart per release. Any
+   arrangement with that property will do; the one to avoid is two places that
+   each decide the id and are expected to agree.
 2. Point `read` at the id of the **active** release, not the process's cwd.
 3. Add `release: (data: { buildId: string | null }) => void` to your
    `ServerToClientEvents` map where you type your socket, so your own `on`
-   knows the event the binding emits.
+   knows the event the binding emits. This is also what makes a **typed**
+   `Server<…>` fit `bindReleaseToSocketServer`: its `emit` is narrowed to the
+   names in your map, so until `release` is one of them the call fails to
+   typecheck — as a long structural mismatch, which reads like a bug in the
+   binding and is this line instead.
 4. Send `SIGUSR2` from the deploy step that activates a frontend without
    restarting the backend, and name that step in the project's release steps.
 
@@ -10900,10 +10929,19 @@ A release that breaks a public API leads its `CHANGELOG.md` entry with a
 **`### ⚠️ Breaking changes`** section (exact heading), each item carrying a
 **before → after** snippet. A version with **no** such section is **purely
 additive** — adopting it changes nothing in your code. (See
-[`AGENTS.md` → Breaking changes](../../AGENTS.md).) `bun scripts/upgrade-plan.ts
-<installed> <target>` prints every breaking section your range crosses, oldest
-first, each with its **Who must act** line — the list this guide's migrations
-expand on.
+[`AGENTS.md` → Breaking changes](../../AGENTS.md).) So the list is recoverable
+mechanically, and the package recovers it for you:
+
+```bash
+bunx stitchkit@latest upgrade    # or: npx stitchkit@latest upgrade
+```
+
+Run it inside the project that depends on stitchkit. It reads your installed
+version out of `node_modules`, reads the changelog **shipped inside the
+package**, and prints every breaking section your range crosses, oldest first,
+each with its **Who must act** line — the list this guide's migrations expand
+on. Nothing to clone, nothing to be told: `--from` / `--to` override either end
+of the range if you want a different one.
 
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
@@ -10932,6 +10970,31 @@ makes one thing your job rather than the resolver's:
 The mechanical part is identical either way. Only the *noticing* differs, and an
 exact pin moves it onto you.
 
+## Released migration: 0.82.0
+
+One thing, and only if you mount MCP or agent tools from a `createTrackingContract` contract.
+
+```bash
+rg -n "createTrackingContract"
+```
+
+The event ingest (`track`, `POST /events`) is now `expose: ['HTTP']`, which is
+what its sibling `bootstrap` always declared. Before, it declared nothing — and
+an endpoint with no `expose` is a tool on MCP and AGENT by default, so the
+mounted surface carried a `track_<prefix>` tool. Since this contract is built
+inside the framework, an application that had made every tool opt-in for the
+endpoints *it* authors could not have opted this one out.
+
+**If you pin a tool-surface digest or count**, it moves by one; re-record it.
+**If you assert on tool names**, `track_<prefix>` is gone. **If nothing in your
+project mounts tools from this contract**, there is nothing to do — the HTTP
+routes, the client and the schemas are unchanged.
+
+Un-declaring the tool was never the intent, so there is no option to keep it. If
+an agent in your system genuinely needs to record something, give it your own
+endpoint with your own schema: the browser ingest trusts a client-minted event
+id and a visit lease, and an agent holds neither.
+
 ## Released migration: 0.81.0
 
 **Path literals own string params.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -34,6 +34,9 @@
     "bun": ">=1.2.0",
     "node": ">=22"
   },
+  "bin": {
+    "stitchkit": "./dist/upgrade-cli.js"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -42,6 +45,7 @@
     "llms.txt",
     "llms-full.txt",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "exports": {
@@ -186,7 +190,7 @@
     "check": "bun x tsc --noEmit",
     "build:js": "bun run build:entrypoints && bun scripts/preserve-webpack-ignore.mjs",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly && bun scripts/rewrite-declaration-specifiers.mjs",
-    "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-declarations-strict.mjs",
+    "build": "rm -rf dist && cp ../../CHANGELOG.md ./CHANGELOG.md && bun run build:js && chmod +x dist/upgrade-cli.js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-declarations-strict.mjs",
     "dev": "bun run build:entrypoints -- --watch",
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",