@percher/shared 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_NODE_VERSION_LABEL, DEFAULT_NODE_VERSION_MAJOR } from "./runtime";
+export { TIMEOUTS, type TimeoutKey } from "./timeouts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_NODE_VERSION_LABEL, DEFAULT_NODE_VERSION_MAJOR } from "./runtime";
+export { TIMEOUTS } from "./timeouts";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAmB,MAAM,YAAY,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Single source of truth for the Node default applied when a user app
+ * pins neither `.nvmrc` nor `engines.node`. Two consumers must stay
+ * locked together:
+ *
+ *   - the build path (Nixpacks gets `DEFAULT_NODE_VERSION_MAJOR` written
+ *     into a synthetic `.nvmrc` — see packages/api/src/nixpacks/build.ts)
+ *   - the CLI preflight (the publish dry-run reports
+ *     `DEFAULT_NODE_VERSION_LABEL` so users see the same version the
+ *     server will use — see packages/core/src/commands/publish-node.ts)
+ *
+ * Pre-FUTURE14 the two ran from independent literals and drifted (API
+ * was bumped to 24, preflight stayed on 22 — Codex catch on de29914).
+ * Updating these constants here is the only edit needed when bumping
+ * the runtime; consumers + their tests import from this module so the
+ * `bun run check:runtime-currency` script alone is enough to confirm
+ * the bump is wired everywhere.
+ */
+export declare const DEFAULT_NODE_VERSION_MAJOR = "24";
+export declare const DEFAULT_NODE_VERSION_LABEL = "24 LTS";
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAC/C,eAAO,MAAM,0BAA0B,WAAsC,CAAC"}

package/dist/runtime.js

@@ -0,0 +1,21 @@
+/**
+ * Single source of truth for the Node default applied when a user app
+ * pins neither `.nvmrc` nor `engines.node`. Two consumers must stay
+ * locked together:
+ *
+ *   - the build path (Nixpacks gets `DEFAULT_NODE_VERSION_MAJOR` written
+ *     into a synthetic `.nvmrc` — see packages/api/src/nixpacks/build.ts)
+ *   - the CLI preflight (the publish dry-run reports
+ *     `DEFAULT_NODE_VERSION_LABEL` so users see the same version the
+ *     server will use — see packages/core/src/commands/publish-node.ts)
+ *
+ * Pre-FUTURE14 the two ran from independent literals and drifted (API
+ * was bumped to 24, preflight stayed on 22 — Codex catch on de29914).
+ * Updating these constants here is the only edit needed when bumping
+ * the runtime; consumers + their tests import from this module so the
+ * `bun run check:runtime-currency` script alone is enough to confirm
+ * the bump is wired everywhere.
+ */
+export const DEFAULT_NODE_VERSION_MAJOR = "24";
+export const DEFAULT_NODE_VERSION_LABEL = `${DEFAULT_NODE_VERSION_MAJOR} LTS`;
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAC/C,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,0BAA0B,MAAM,CAAC"}

package/dist/timeouts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Cross-process publish timeout contract.
+ *
+ * The 2026-05-07 incident batch (`dep_lvi4lrwxbjzh4q799320` and three
+ * siblings) was caused by the CLI publish-poll giving up at 5 min while
+ * the worker build subprocess + API → worker fetch wrapper kept running
+ * for up to 11 min. The agent saw "WORKER_UNAVAILABLE: build worker did
+ * not respond within 11 minutes" — but the client had already given up
+ * 6 minutes earlier. The platform was healthy; the timeouts were misaligned.
+ *
+ * This module is the single source of truth for every timeout that
+ * needs to agree across the publish pipeline. Each layer adds slack on
+ * top of the layer below it so a healthy build that takes the entire
+ * worker budget never trips an outer timeout.
+ *
+ * Stack (top to bottom = outer to inner):
+ *
+ *   mcpWaitDeployMax  ── outermost agent-facing wait window
+ *      ≥ clientPublishPoll
+ *        ≥ apiToWorkerBuildFetch  + 60 s slack
+ *          ≥ workerBuildSubprocess + 60 s slack
+ *
+ * The invariants are encoded as runtime asserts in
+ * `packages/shared/test/timeouts.invariants.test.ts` and gate
+ * `bun run review:quick` so a future PR that introduces a hard-coded
+ * `5 * 60_000` while server budgets stay at 10 min fails CI.
+ */
+export declare const TIMEOUTS: {
+    /**
+     * Wall-clock build budget on the worker — enforced by the worker-side
+     * `setTimeout(...).proc.kill()` in `nixpacks/build.ts` and
+     * `nixpacks/docker-build.ts`. Beyond this the build is killed with
+     * exit code 124 → BUILD_TIMEOUT errorCode.
+     */
+    readonly workerBuildSubprocess: number;
+    /**
+     * API-side wrapper around the build-fetch HTTP call to the worker.
+     * Must exceed `workerBuildSubprocess` by at least 60 s so the worker
+     * has room to flush its response after killing the subprocess. If
+     * this fires the worker may still be running — the API treats it as
+     * `WORKER_UNAVAILABLE` (transient).
+     */
+    readonly apiToWorkerBuildFetch: number;
+    /**
+     * CLI/MCP sync-publish poll. Must exceed `apiToWorkerBuildFetch` by
+     * at least 60 s so a healthy build that fully consumes the API
+     * budget never preempts the client. The 2026-05-07 incident is
+     * exactly this invariant being violated (5 min < 11 min).
+     */
+    readonly clientPublishPoll: number;
+    /** Worker → /healthz self-check budget. */
+    readonly workerHealthcheck: 5000;
+    /** Pipeline watchdog list-fetch budget. */
+    readonly watchdogList: 15000;
+    /** Default `timeoutSeconds` for `percher_wait_for_deploy` MCP tool. */
+    readonly mcpWaitDeployDefault: 30000;
+    /**
+     * Maximum `timeoutSeconds` an MCP caller can request for a single
+     * `percher_wait_for_deploy` invocation. Equal to `clientPublishPoll`
+     * so the longest legal MCP wait can in principle ride a single
+     * publish all the way to live. Default stays short
+     * (`mcpWaitDeployDefault`) to favour resumable polling.
+     */
+    readonly mcpWaitDeployMax: number;
+};
+export type TimeoutKey = keyof typeof TIMEOUTS;
+//# sourceMappingURL=timeouts.d.ts.map

package/dist/timeouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../src/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;;OAKG;;IAGH;;;;;;OAMG;;IAGH;;;;;OAKG;;IAGH,2CAA2C;;IAG3C,2CAA2C;;IAG3C,uEAAuE;;IAGvE;;;;;;OAMG;;CAEK,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,QAAQ,CAAC"}

package/dist/timeouts.js

@@ -0,0 +1,66 @@
+/**
+ * Cross-process publish timeout contract.
+ *
+ * The 2026-05-07 incident batch (`dep_lvi4lrwxbjzh4q799320` and three
+ * siblings) was caused by the CLI publish-poll giving up at 5 min while
+ * the worker build subprocess + API → worker fetch wrapper kept running
+ * for up to 11 min. The agent saw "WORKER_UNAVAILABLE: build worker did
+ * not respond within 11 minutes" — but the client had already given up
+ * 6 minutes earlier. The platform was healthy; the timeouts were misaligned.
+ *
+ * This module is the single source of truth for every timeout that
+ * needs to agree across the publish pipeline. Each layer adds slack on
+ * top of the layer below it so a healthy build that takes the entire
+ * worker budget never trips an outer timeout.
+ *
+ * Stack (top to bottom = outer to inner):
+ *
+ *   mcpWaitDeployMax  ── outermost agent-facing wait window
+ *      ≥ clientPublishPoll
+ *        ≥ apiToWorkerBuildFetch  + 60 s slack
+ *          ≥ workerBuildSubprocess + 60 s slack
+ *
+ * The invariants are encoded as runtime asserts in
+ * `packages/shared/test/timeouts.invariants.test.ts` and gate
+ * `bun run review:quick` so a future PR that introduces a hard-coded
+ * `5 * 60_000` while server budgets stay at 10 min fails CI.
+ */
+export const TIMEOUTS = {
+    /**
+     * Wall-clock build budget on the worker — enforced by the worker-side
+     * `setTimeout(...).proc.kill()` in `nixpacks/build.ts` and
+     * `nixpacks/docker-build.ts`. Beyond this the build is killed with
+     * exit code 124 → BUILD_TIMEOUT errorCode.
+     */
+    workerBuildSubprocess: 10 * 60_000,
+    /**
+     * API-side wrapper around the build-fetch HTTP call to the worker.
+     * Must exceed `workerBuildSubprocess` by at least 60 s so the worker
+     * has room to flush its response after killing the subprocess. If
+     * this fires the worker may still be running — the API treats it as
+     * `WORKER_UNAVAILABLE` (transient).
+     */
+    apiToWorkerBuildFetch: 11 * 60_000,
+    /**
+     * CLI/MCP sync-publish poll. Must exceed `apiToWorkerBuildFetch` by
+     * at least 60 s so a healthy build that fully consumes the API
+     * budget never preempts the client. The 2026-05-07 incident is
+     * exactly this invariant being violated (5 min < 11 min).
+     */
+    clientPublishPoll: 12 * 60_000,
+    /** Worker → /healthz self-check budget. */
+    workerHealthcheck: 5_000,
+    /** Pipeline watchdog list-fetch budget. */
+    watchdogList: 15_000,
+    /** Default `timeoutSeconds` for `percher_wait_for_deploy` MCP tool. */
+    mcpWaitDeployDefault: 30_000,
+    /**
+     * Maximum `timeoutSeconds` an MCP caller can request for a single
+     * `percher_wait_for_deploy` invocation. Equal to `clientPublishPoll`
+     * so the longest legal MCP wait can in principle ride a single
+     * publish all the way to live. Default stays short
+     * (`mcpWaitDeployDefault`) to favour resumable polling.
+     */
+    mcpWaitDeployMax: 12 * 60_000,
+};
+//# sourceMappingURL=timeouts.js.map

package/dist/timeouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.js","sourceRoot":"","sources":["../src/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB;;;;;OAKG;IACH,qBAAqB,EAAE,EAAE,GAAG,MAAM;IAElC;;;;;;OAMG;IACH,qBAAqB,EAAE,EAAE,GAAG,MAAM;IAElC;;;;;OAKG;IACH,iBAAiB,EAAE,EAAE,GAAG,MAAM;IAE9B,2CAA2C;IAC3C,iBAAiB,EAAE,KAAK;IAExB,2CAA2C;IAC3C,YAAY,EAAE,MAAM;IAEpB,uEAAuE;IACvE,oBAAoB,EAAE,MAAM;IAE5B;;;;;;OAMG;IACH,gBAAgB,EAAE,EAAE,GAAG,MAAM;CACrB,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@percher/shared",
+  "version": "0.1.1",
+  "description": "Shared constants and contracts (timeouts, etc.) used across the Percher CLI, API, MCP, and worker. Internal — values change in lockstep across packages.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./timeouts": {
+      "types": "./dist/timeouts.d.ts",
+      "import": "./dist/timeouts.js",
+      "default": "./dist/timeouts.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "default": "./dist/runtime.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "bun-types": "^1.1.0"
+  },
+  "license": "MIT",
+  "author": "Mattias Malmborg",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mattiasmalmborg/percher",
+    "directory": "packages/shared"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}