workerdeck 0.0.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Strebitzer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,105 @@
-# workerdeck
+# WorkerDeck
 
-**Name placeholder. There is no working release under this name yet — do not depend on `0.0.0`.**
+The turnkey [WorkerDeck](https://github.com/workerdeck/workerdeck) instance: the
+session gateway **and** the full dashboard, on one port, with nothing to clone.
 
-WorkerDeck is a web-controlled runner for coding-agent sessions: embed, watch, and control an
-agent session from a host app, over one HTTP + WebSocket gateway.
+```bash
+npx workerdeck
+```
 
-This package reserves the name ahead of the first real release. When that ships it will land at the
-project's current version — `0.0.0` will never be a usable version, and installing it gets you this
-README and nothing else.
+That serves `http://127.0.0.1:8787` — dashboard at the root, API under `/v1` — and persists parked
+sessions under `~/.workerdeck` so a restart doesn't drop them.
 
-The scoped packages live under [`@workerdeck`](https://www.npmjs.com/org/workerdeck).
+The `@workerdeck/*` packages are the libraries you embed in your own app. This one is the
+service you run.
 
-## License
+## Protecting it
+
+```bash
+npx workerdeck --auth-key "$SECRET" --host 0.0.0.0
+```
+
+One secret, two transports:
+
+- **Browsers** get a login page, trade the secret for an `HttpOnly` session cookie, and use that
+  for everything afterwards — including the WebSocket attach.
+- **Services** send the same secret as an `x-workerdeck-key` header (or
+  `Authorization: Bearer`).
+
+The cookie is not a convenience. A browser cannot set a header on a WebSocket handshake at all, so
+a cookie is the only credential a tab can present when it attaches to a session — and a cookie only
+rides requests to the origin that set it. That is why the dashboard and the API share a port.
+
+Neither transport authenticates *who* the person is; the secret is a door key. Put an
+identity-aware proxy in front if you need more than that.
+
+**Without `--auth-key`, the instance refuses to bind anything but a loopback address.** An
+unauthenticated gateway on a routable interface is a Claude Code shell for anyone who can reach the
+port. `--insecure` overrides that, for when something in front is doing the authenticating.
+
+## Options
+
+| Flag | Env | Default |
+| --- | --- | --- |
+| `--port <n>` | `WORKERDECK_PORT` | `8787` |
+| `--host <addr>` | `WORKERDECK_HOST` | `127.0.0.1` |
+| `--auth-key <secret>` | `WORKERDECK_AUTH_KEY` | none (no auth) |
+| `--cwd-root <path>` (repeatable) | `WORKERDECK_CWD_ROOTS` (`:`-separated) | unrestricted |
+| `--profile <name=dir>` (repeatable) | — | auto-detected from `~/.claude` |
+| `--state-dir <path>` | `WORKERDECK_STATE_DIR` | beside the config file, else `~/.workerdeck` |
+| `--no-parking-store` | — | durable parking on |
+| `--config <path>` | — | `./workerdeck.config.mjs` |
+| `--insecure`, `--open`, `--help`, `--version` | | |
+
+Precedence is narrowest-wins: flags > env > config file > defaults.
+
+## The config file
+
+`authenticate`, `buildRunnerConfig` and `createEngineRunner` are functions, so they can't come from
+a flag. `workerdeck.config.mjs` default-exports the
+[`createWorkerServer` options](https://workerdeck.github.io/workerdeck/docs/reference/server/)
+(or a function, sync or async, returning them):
+
+```js
+export default {
+  allowedCwdRoots: ['/srv/projects'],
+  profiles: [{ name: 'me', configDir: '/home/me/.claude' }],
+  requireApiKey: true,
+  buildRunnerConfig: (req) => ({ ...req, env: { ...process.env, CI: '1' } }),
+}
+```
+
+Supplying your own `authenticate` turns the built-in shared-secret auth **off entirely** — one
+hook, one scheme, rather than two paths where only one got audited. If you take it over, you own
+finding a credential the browser can actually present. There's a fuller example in
+[`examples/workerdeck.config.mjs`](https://github.com/workerdeck/workerdeck/blob/master/examples/workerdeck.config.mjs).
+
+## Restart guard
+
+```bash
+npx workerdeck guard --wait 300 --allow-parked && systemctl restart workerdeck
+```
+
+Exits `0` when a restart is safe, `1` while a session is mid-turn, awaiting an approval, or parked
+without durability behind it, and `2` when it couldn't tell — never treating "couldn't tell" as
+safe. `--allow-parked` and `--allow-queued` are you asserting that the `SessionStore` and the
+`QueueAdapter` respectively are durable; they're separate decisions. Point `--url` at any instance
+and authenticate with `--token` or `--header name=value`.
+
+## Credentials
+
+WorkerDeck implements **no Anthropic auth**. The official SDK/CLI resolves credentials from the
+operator's environment, per profile — `--auth-key` protects this gateway and nothing else. See the
+project's
+[Auth & Anthropic's terms](https://github.com/workerdeck/workerdeck#auth--anthropics-terms).
+
+## Mounting
+
+The dashboard's assets resolve from an absolute `/assets/...`, so it must be served at a **domain
+root**, not a subpath. A dedicated vhost reverse-proxying to the instance is the intended shape.
+
+The dashboard itself is [`@workerdeck/web`](https://www.npmjs.com/package/@workerdeck/web),
+a normal dependency of this package. Point `webRoot` in the config file at your own build to serve
+a fork instead.
 
 MIT

package/build/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/build/cli.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { a as ConfigError, d as parseArgs, f as resolveInstanceConfig, r as startInstance, u as loadConfigFile } from "./instance-kupxU5UD.mjs";
+import { dirname, join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+//#region src/cli.ts
+const HELP = `workerdeck — run a workerdeck instance: session gateway + dashboard, one port.
+
+Usage
+  workerdeck [options]
+  workerdeck guard [options]     check whether it is safe to restart an instance
+
+Options
+  -p, --port <n>            port to listen on (default 8787, WORKERDECK_PORT)
+      --host <addr>         interface to bind (default 127.0.0.1, WORKERDECK_HOST)
+      --auth-key <secret>   shared secret, min 12 chars; browsers log in with it,
+                            services send it as x-workerdeck-key
+                            (WORKERDECK_AUTH_KEY). Unset = no auth on loopback;
+                            on any other interface a key is generated instead,
+                            printed once, and stored in <state-dir>/auth-key for
+                            later starts to reuse.
+      --trust-proxy         trust x-forwarded-proto/-host/-for from one reverse
+                            proxy. Required behind TLS termination, or the session
+                            cookie loses its Secure flag and the origin check
+                            computes http:// where the browser says https://.
+      --allowed-origin <o>  extra origin accepted on browser requests, for when a
+                            proxy rewrites Host (repeatable)
+      --allowed-host <name> extra Host header accepted when running without auth
+                            (repeatable; loopback names are always accepted)
+      --insecure-host <name>
+                            bind host that may serve without auth — no key demanded,
+                            none generated — and, while unauthenticated, also
+                            accepted as a Host header (repeatable; config:
+                            insecureHosts). Names the host alone, no port.
+      --profile <name=dir>  Claude config dir a session may run under (repeatable)
+      --cwd-root <path>     restrict session cwds to this root (repeatable,
+                            WORKERDECK_CWD_ROOTS as a ':'-separated list)
+      --state-dir <path>    where parked sessions are persisted
+                            (default: beside the config file, else ~/.workerdeck)
+      --no-parking-store    keep parked sessions in memory only; a restart drops them
+  -c, --config <path>       config file (default: ./workerdeck.config.mjs)
+      --insecure            allow no-auth on a non-loopback address. Only when
+                            something in front is doing the authenticating.
+      --open                open the dashboard in a browser once it is up
+  -h, --help                show this
+  -v, --version             print the version
+
+Config file
+  Options that cannot fit on a command line — \`authenticate\`, \`buildRunnerConfig\`,
+  \`createEngineRunner\` are functions — live in workerdeck.config.mjs, which
+  default-exports the createWorkerServer options (or a function returning them).
+  Flags and env override it. Supplying your own \`authenticate\` turns the built-in
+  shared-secret auth off entirely.
+
+Credentials
+  workerdeck implements no Anthropic auth of its own: the official SDK/CLI
+  resolves credentials from the environment, per profile. --auth-key protects this
+  gateway, nothing else.
+`;
+async function readVersion() {
+	const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+	try {
+		const raw = await readFile(pkgPath, "utf8");
+		return JSON.parse(raw).version ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+/** Best-effort: a browser that won't open is a convenience missed, not a failure. */
+function openInBrowser(url) {
+	const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+	try {
+		const child = spawn(command, [url], {
+			stdio: "ignore",
+			detached: true,
+			shell: process.platform === "win32"
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+async function main(argv) {
+	if (argv[0] === "guard") {
+		const { runGuard } = await import("./guard-D3VN855w.mjs").then((n) => n.t);
+		return await runGuard(argv.slice(1));
+	}
+	const flags = parseArgs(argv);
+	if (flags.help) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	if (flags.version) {
+		process.stdout.write(`${await readVersion()}\n`);
+		return 0;
+	}
+	const config = resolveInstanceConfig(flags, await loadConfigFile(flags.config));
+	const instance = await startInstance(config);
+	if (config.open) openInBrowser(instance.url);
+	const shutdown = (signal) => {
+		process.stdout.write(`\n[workerdeck] ${signal} — shutting down\n`);
+		instance.close().then(() => process.exit(0)).catch(() => process.exit(1));
+	};
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
+	await instance.closed;
+	return 0;
+}
+main(process.argv.slice(2)).then((code) => {
+	if (code !== 0) process.exit(code);
+}).catch((error) => {
+	if (error instanceof ConfigError) {
+		process.stderr.write(`[workerdeck] ${error.message}\n`);
+		process.exit(2);
+	}
+	process.stderr.write(`[workerdeck] ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/build/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { spawn } from 'node:child_process'\nimport { readFile } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { ConfigError, loadConfigFile, parseArgs, resolveInstanceConfig } from './config.ts'\nimport { startInstance } from './instance.ts'\n\nconst HELP = `workerdeck — run a workerdeck instance: session gateway + dashboard, one port.\n\nUsage\n  workerdeck [options]\n  workerdeck guard [options]     check whether it is safe to restart an instance\n\nOptions\n  -p, --port <n>            port to listen on (default 8787, WORKERDECK_PORT)\n      --host <addr>         interface to bind (default 127.0.0.1, WORKERDECK_HOST)\n      --auth-key <secret>   shared secret, min 12 chars; browsers log in with it,\n                            services send it as x-workerdeck-key\n                            (WORKERDECK_AUTH_KEY). Unset = no auth on loopback;\n                            on any other interface a key is generated instead,\n                            printed once, and stored in <state-dir>/auth-key for\n                            later starts to reuse.\n      --trust-proxy         trust x-forwarded-proto/-host/-for from one reverse\n                            proxy. Required behind TLS termination, or the session\n                            cookie loses its Secure flag and the origin check\n                            computes http:// where the browser says https://.\n      --allowed-origin <o>  extra origin accepted on browser requests, for when a\n                            proxy rewrites Host (repeatable)\n      --allowed-host <name> extra Host header accepted when running without auth\n                            (repeatable; loopback names are always accepted)\n      --insecure-host <name>\n                            bind host that may serve without auth — no key demanded,\n                            none generated — and, while unauthenticated, also\n                            accepted as a Host header (repeatable; config:\n                            insecureHosts). Names the host alone, no port.\n      --profile <name=dir>  Claude config dir a session may run under (repeatable)\n      --cwd-root <path>     restrict session cwds to this root (repeatable,\n                            WORKERDECK_CWD_ROOTS as a ':'-separated list)\n      --state-dir <path>    where parked sessions are persisted\n                            (default: beside the config file, else ~/.workerdeck)\n      --no-parking-store    keep parked sessions in memory only; a restart drops them\n  -c, --config <path>       config file (default: ./workerdeck.config.mjs)\n      --insecure            allow no-auth on a non-loopback address. Only when\n                            something in front is doing the authenticating.\n      --open                open the dashboard in a browser once it is up\n  -h, --help                show this\n  -v, --version             print the version\n\nConfig file\n  Options that cannot fit on a command line — \\`authenticate\\`, \\`buildRunnerConfig\\`,\n  \\`createEngineRunner\\` are functions — live in workerdeck.config.mjs, which\n  default-exports the createWorkerServer options (or a function returning them).\n  Flags and env override it. Supplying your own \\`authenticate\\` turns the built-in\n  shared-secret auth off entirely.\n\nCredentials\n  workerdeck implements no Anthropic auth of its own: the official SDK/CLI\n  resolves credentials from the environment, per profile. --auth-key protects this\n  gateway, nothing else.\n`\n\nasync function readVersion(): Promise<string> {\n  // src/cli.ts and build/cli.mjs are both one level under the package root.\n  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')\n  try {\n    const raw = await readFile(pkgPath, 'utf8')\n    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'\n  } catch {\n    return 'unknown'\n  }\n}\n\n/** Best-effort: a browser that won't open is a convenience missed, not a failure. */\nfunction openInBrowser(url: string): void {\n  const command =\n    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'\n  try {\n    const child = spawn(command, [url], {\n      stdio: 'ignore',\n      detached: true,\n      shell: process.platform === 'win32',\n    })\n    child.on('error', () => {})\n    child.unref()\n  } catch {\n    // ignored\n  }\n}\n\nasync function main(argv: string[]): Promise<number> {\n  if (argv[0] === 'guard') {\n    const { runGuard } = await import('./guard.ts')\n    return await runGuard(argv.slice(1))\n  }\n\n  const flags = parseArgs(argv)\n  if (flags.help) {\n    process.stdout.write(HELP)\n    return 0\n  }\n  if (flags.version) {\n    process.stdout.write(`${await readVersion()}\\n`)\n    return 0\n  }\n\n  const loaded = await loadConfigFile(flags.config)\n  const config = resolveInstanceConfig(flags, loaded)\n  const instance = await startInstance(config)\n\n  if (config.open) openInBrowser(instance.url)\n\n  const shutdown = (signal: string): void => {\n    process.stdout.write(`\\n[workerdeck] ${signal} — shutting down\\n`)\n    // Parked sessions are already on disk; this is about letting in-flight\n    // requests finish rather than dropping sockets on the floor.\n    instance\n      .close()\n      .then(() => process.exit(0))\n      .catch(() => process.exit(1))\n  }\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n\n  // Resolves only on close; the process stays up serving.\n  await instance.closed\n  return 0\n}\n\nmain(process.argv.slice(2))\n  .then((code) => {\n    if (code !== 0) process.exit(code)\n  })\n  .catch((error: unknown) => {\n    if (error instanceof ConfigError) {\n      process.stderr.write(`[workerdeck] ${error.message}\\n`)\n      process.exit(2)\n    }\n    process.stderr.write(\n      `[workerdeck] ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\\n`,\n    )\n    process.exit(1)\n  })\n"],"mappings":";;;;;;;AAQA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDb,eAAe,cAA+B;CAE5C,MAAM,UAAU,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,MAAM,eAAe;AACnF,KAAI;EACF,MAAM,MAAM,MAAM,SAAS,SAAS,OAAO;AAC3C,SAAQ,KAAK,MAAM,IAAI,CAA0B,WAAW;SACtD;AACN,SAAO;;;;AAKX,SAAS,cAAc,KAAmB;CACxC,MAAM,UACJ,QAAQ,aAAa,WAAW,SAAS,QAAQ,aAAa,UAAU,UAAU;AACpF,KAAI;EACF,MAAM,QAAQ,MAAM,SAAS,CAAC,IAAI,EAAE;GAClC,OAAO;GACP,UAAU;GACV,OAAO,QAAQ,aAAa;GAC7B,CAAC;AACF,QAAM,GAAG,eAAe,GAAG;AAC3B,QAAM,OAAO;SACP;;AAKV,eAAe,KAAK,MAAiC;AACnD,KAAI,KAAK,OAAO,SAAS;EACvB,MAAM,EAAE,aAAa,MAAM,OAAO,wBAAA,MAAA,MAAA,EAAA,EAAA;AAClC,SAAO,MAAM,SAAS,KAAK,MAAM,EAAE,CAAC;;CAGtC,MAAM,QAAQ,UAAU,KAAK;AAC7B,KAAI,MAAM,MAAM;AACd,UAAQ,OAAO,MAAM,KAAK;AAC1B,SAAO;;AAET,KAAI,MAAM,SAAS;AACjB,UAAQ,OAAO,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI;AAChD,SAAO;;CAIT,MAAM,SAAS,sBAAsB,OAAO,MADvB,eAAe,MAAM,OAAO,CACE;CACnD,MAAM,WAAW,MAAM,cAAc,OAAO;AAE5C,KAAI,OAAO,KAAM,eAAc,SAAS,IAAI;CAE5C,MAAM,YAAY,WAAyB;AACzC,UAAQ,OAAO,MAAM,kBAAkB,OAAO,oBAAoB;AAGlE,WACG,OAAO,CACP,WAAW,QAAQ,KAAK,EAAE,CAAC,CAC3B,YAAY,QAAQ,KAAK,EAAE,CAAC;;AAEjC,SAAQ,GAAG,gBAAgB,SAAS,SAAS,CAAC;AAC9C,SAAQ,GAAG,iBAAiB,SAAS,UAAU,CAAC;AAGhD,OAAM,SAAS;AACf,QAAO;;AAGT,KAAK,QAAQ,KAAK,MAAM,EAAE,CAAC,CACxB,MAAM,SAAS;AACd,KAAI,SAAS,EAAG,SAAQ,KAAK,KAAK;EAClC,CACD,OAAO,UAAmB;AACzB,KAAI,iBAAiB,aAAa;AAChC,UAAQ,OAAO,MAAM,gBAAgB,MAAM,QAAQ,IAAI;AACvD,UAAQ,KAAK,EAAE;;AAEjB,SAAQ,OAAO,MACb,gBAAgB,iBAAiB,QAAS,MAAM,SAAS,MAAM,UAAW,OAAO,MAAM,CAAC,IACzF;AACD,SAAQ,KAAK,EAAE;EACf"}

package/build/guard-D3VN855w.mjs

@@ -0,0 +1,241 @@
+import { parseArgs } from "node:util";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/guard.ts
+var guard_exports = /* @__PURE__ */ __exportAll({ runGuard: () => runGuard });
+/**
+* Restart guard for a deploy: ask a running instance whether anything would be
+* lost by stopping it, and exit non-zero while the answer is yes.
+*
+*   workerdeck guard --wait 300 --allow-parked && launchctl kickstart -k …
+*
+* What a restart costs, and why this is policy and not a server route: an
+* in-flight turn dies with the process (the CLI subprocess and the provider
+* request both go), a pending permission request dies with it, and a running job
+* is left claimed. Two more depend on configuration rather than on state, so each
+* has an opt-out flag that says "I made that durable":
+*
+*   --allow-parked   parked sessions survive with a durable SessionStore, not
+*                    with the in-memory default. Note this covers the *session*:
+*                    a parked job's queue-side record lives in the QueueAdapter,
+*                    so with the bundled in-memory adapter the woken session
+*                    completes with no job attached to finish.
+*   --allow-queued   queued jobs survive only in a durable QueueAdapter; the
+*                    bundled one loses them with the process.
+*
+* Exit codes: 0 safe to restart, 1 still busy, 2 could not tell (bad URL, auth,
+* or an unexpected response — never treated as safe).
+*/
+const BUSY_STATUSES = new Set([
+	"starting",
+	"running",
+	"awaiting_approval"
+]);
+const HELP = `usage: workerdeck guard [--url URL] [--token TOKEN] [--header name=value]
+                           [--wait SECONDS] [--interval SECONDS]
+                           [--allow-parked] [--allow-queued] [--json]
+
+exit 0 = safe to restart, 1 = busy, 2 = could not tell
+`;
+var GuardError = class extends Error {};
+async function runGuard(argv) {
+	let values;
+	try {
+		values = parseArgs({
+			args: argv,
+			options: {
+				url: {
+					type: "string",
+					default: process.env.WORKERDECK_URL ?? "http://127.0.0.1:8787/v1"
+				},
+				token: {
+					type: "string",
+					default: process.env.WORKERDECK_TOKEN
+				},
+				header: {
+					type: "string",
+					multiple: true,
+					default: []
+				},
+				wait: {
+					type: "string",
+					default: "0"
+				},
+				interval: {
+					type: "string",
+					default: "5"
+				},
+				"allow-parked": {
+					type: "boolean",
+					default: false
+				},
+				"allow-queued": {
+					type: "boolean",
+					default: false
+				},
+				json: {
+					type: "boolean",
+					default: false
+				},
+				help: {
+					type: "boolean",
+					default: false
+				}
+			}
+		}).values;
+	} catch (error) {
+		process.stderr.write(`guard: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 2;
+	}
+	if (values.help) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const base = values.url.replace(/\/$/, "");
+	const headers = { accept: "application/json" };
+	if (values.token) headers.authorization = `Bearer ${values.token}`;
+	const seconds = (flag, raw) => {
+		const value = Number(raw);
+		if (!Number.isFinite(value) || value < 0) throw new GuardError(`${flag} must be a non-negative number of seconds`);
+		return value;
+	};
+	let waitMs;
+	let intervalMs;
+	try {
+		for (const entry of values.header) {
+			const at = entry.indexOf("=");
+			if (at < 1) throw new GuardError(`--header must be name=value, got '${entry}'`);
+			headers[entry.slice(0, at).trim()] = entry.slice(at + 1).trim();
+		}
+		waitMs = seconds("--wait", values.wait) * 1e3;
+		intervalMs = Math.max(seconds("--interval", values.interval), 1) * 1e3;
+	} catch (error) {
+		process.stderr.write(`guard: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 2;
+	}
+	const get = async (path) => {
+		let res;
+		try {
+			res = await fetch(base + path, { headers });
+		} catch (error) {
+			if (error?.cause?.code === "ECONNREFUSED") return {
+				ok: false,
+				status: "unreachable"
+			};
+			return {
+				ok: false,
+				detail: String(error instanceof Error ? error.message : error)
+			};
+		}
+		if (!res.ok) return {
+			ok: false,
+			code: res.status,
+			detail: `HTTP ${res.status}`
+		};
+		try {
+			return {
+				ok: true,
+				body: await res.json()
+			};
+		} catch {
+			return {
+				ok: false,
+				code: res.status,
+				detail: "response was not JSON"
+			};
+		}
+	};
+	/** One look at the server. Returns the reasons a restart would cost something. */
+	const inspect = async () => {
+		const sessions = await get("/sessions");
+		if (!sessions.ok && "status" in sessions) return {
+			unreachable: true,
+			reasons: [],
+			notes: []
+		};
+		if (!sessions.ok) return {
+			error: `GET ${base}/sessions → ${sessions.detail}`,
+			reasons: [],
+			notes: []
+		};
+		const listed = sessions.body.sessions;
+		if (!Array.isArray(listed)) return {
+			error: `GET ${base}/sessions returned no session list`,
+			reasons: [],
+			notes: []
+		};
+		const all = listed;
+		const reasons = [];
+		/** Worth saying out loud, but not worth blocking a deploy over. */
+		const notes = [];
+		for (const session of all.filter((s) => BUSY_STATUSES.has(s.status))) reasons.push(`session ${session.id} is ${session.status}`);
+		const parked = all.filter((s) => s.status === "parked");
+		if (parked.length > 0 && !values["allow-parked"]) reasons.push(`${parked.length} parked session(s) — pass --allow-parked once the server runs a durable SessionStore, or they are lost on restart`);
+		const queue = await get("/queue");
+		if (!queue.ok && !("status" in queue) && queue.code !== 404) return {
+			error: `GET ${base}/queue → ${queue.detail}`,
+			reasons: [],
+			notes: []
+		};
+		const stats = queue.ok ? queue.body.stats : void 0;
+		if ((stats?.running ?? 0) > 0) reasons.push(`${stats.running} job(s) running`);
+		if ((stats?.queued ?? 0) > 0 && !values["allow-queued"]) reasons.push(`${stats.queued} job(s) queued — pass --allow-queued once the server runs a durable QueueAdapter, or they are lost on restart`);
+		if ((stats?.parked ?? 0) > 0 && values["allow-parked"]) notes.push(`${stats.parked} parked job(s): their queue-side records are the QueueAdapter's, not the SessionStore's — with the in-memory adapter they never finish`);
+		return {
+			reasons,
+			notes,
+			sessions: all.length,
+			parked: parked.length
+		};
+	};
+	const report = (verdict, detail) => {
+		if (values.json) {
+			process.stdout.write(`${JSON.stringify({
+				verdict,
+				...detail
+			})}\n`);
+			return;
+		}
+		const lines = [...detail.reasons.map((reason) => `  - ${reason}`), ...detail.notes.map((note) => `  note: ${note}`)].join("\n");
+		process.stdout.write(`guard: ${verdict}${lines ? `\n${lines}` : ""}\n`);
+	};
+	const deadline = Date.now() + waitMs;
+	for (;;) {
+		const result = await inspect();
+		if (result.error) {
+			report("unknown", {
+				...result,
+				reasons: [result.error]
+			});
+			return 2;
+		}
+		if (result.unreachable) {
+			report("safe to restart (nothing listening on the given URL)", result);
+			return 0;
+		}
+		if (result.reasons.length === 0) {
+			report("safe to restart", result);
+			return 0;
+		}
+		if (Date.now() + intervalMs > deadline) {
+			report("busy — not safe to restart", result);
+			return 1;
+		}
+		report(`busy, waiting up to ${Math.round((deadline - Date.now()) / 1e3)}s`, result);
+		await new Promise((resolve) => setTimeout(resolve, intervalMs));
+	}
+}
+//#endregion
+export { runGuard as n, guard_exports as t };
+
+//# sourceMappingURL=guard-D3VN855w.mjs.map

package/build/guard-D3VN855w.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-D3VN855w.mjs","names":[],"sources":["../src/guard.ts"],"sourcesContent":["import { parseArgs } from 'node:util'\n\n/**\n * Restart guard for a deploy: ask a running instance whether anything would be\n * lost by stopping it, and exit non-zero while the answer is yes.\n *\n *   workerdeck guard --wait 300 --allow-parked && launchctl kickstart -k …\n *\n * What a restart costs, and why this is policy and not a server route: an\n * in-flight turn dies with the process (the CLI subprocess and the provider\n * request both go), a pending permission request dies with it, and a running job\n * is left claimed. Two more depend on configuration rather than on state, so each\n * has an opt-out flag that says \"I made that durable\":\n *\n *   --allow-parked   parked sessions survive with a durable SessionStore, not\n *                    with the in-memory default. Note this covers the *session*:\n *                    a parked job's queue-side record lives in the QueueAdapter,\n *                    so with the bundled in-memory adapter the woken session\n *                    completes with no job attached to finish.\n *   --allow-queued   queued jobs survive only in a durable QueueAdapter; the\n *                    bundled one loses them with the process.\n *\n * Exit codes: 0 safe to restart, 1 still busy, 2 could not tell (bad URL, auth,\n * or an unexpected response — never treated as safe).\n */\n\nconst BUSY_STATUSES = new Set(['starting', 'running', 'awaiting_approval'])\n\nconst HELP = `usage: workerdeck guard [--url URL] [--token TOKEN] [--header name=value]\n                           [--wait SECONDS] [--interval SECONDS]\n                           [--allow-parked] [--allow-queued] [--json]\n\nexit 0 = safe to restart, 1 = busy, 2 = could not tell\n`\n\ntype GetResult =\n  | { ok: true; body: Record<string, unknown> }\n  | { ok: false; status: 'unreachable' }\n  | { ok: false; code?: number; detail: string }\n\ntype Verdict = {\n  reasons: string[]\n  notes: string[]\n  unreachable?: boolean\n  error?: string\n  sessions?: number\n  parked?: number\n}\n\nclass GuardError extends Error {}\n\nexport async function runGuard(argv: string[]): Promise<number> {\n  let values: {\n    url: string\n    token?: string\n    header: string[]\n    wait: string\n    interval: string\n    'allow-parked': boolean\n    'allow-queued': boolean\n    json: boolean\n    help: boolean\n  }\n  try {\n    values = parseArgs({\n      args: argv,\n      options: {\n        url: {\n          type: 'string',\n          default: process.env.WORKERDECK_URL ?? 'http://127.0.0.1:8787/v1',\n        },\n        token: { type: 'string', default: process.env.WORKERDECK_TOKEN },\n        header: { type: 'string', multiple: true, default: [] },\n        wait: { type: 'string', default: '0' },\n        interval: { type: 'string', default: '5' },\n        'allow-parked': { type: 'boolean', default: false },\n        'allow-queued': { type: 'boolean', default: false },\n        json: { type: 'boolean', default: false },\n        help: { type: 'boolean', default: false },\n      },\n    }).values as typeof values\n  } catch (error) {\n    process.stderr.write(`guard: ${error instanceof Error ? error.message : String(error)}\\n`)\n    return 2\n  }\n\n  if (values.help) {\n    process.stdout.write(HELP)\n    return 0\n  }\n\n  const base = values.url.replace(/\\/$/, '')\n  const headers: Record<string, string> = { accept: 'application/json' }\n  // The token covers the common `Authorization: Bearer` case, including this\n  // CLI's own --auth-key; --header covers hosts whose `authenticate` hook reads\n  // something else.\n  if (values.token) headers.authorization = `Bearer ${values.token}`\n\n  const seconds = (flag: string, raw: string): number => {\n    const value = Number(raw)\n    if (!Number.isFinite(value) || value < 0) {\n      throw new GuardError(`${flag} must be a non-negative number of seconds`)\n    }\n    return value\n  }\n\n  let waitMs: number\n  let intervalMs: number\n  try {\n    for (const entry of values.header) {\n      const at = entry.indexOf('=')\n      if (at < 1) throw new GuardError(`--header must be name=value, got '${entry}'`)\n      headers[entry.slice(0, at).trim()] = entry.slice(at + 1).trim()\n    }\n    waitMs = seconds('--wait', values.wait) * 1000\n    intervalMs = Math.max(seconds('--interval', values.interval), 1) * 1000\n  } catch (error) {\n    process.stderr.write(`guard: ${error instanceof Error ? error.message : String(error)}\\n`)\n    return 2\n  }\n\n  const get = async (path: string): Promise<GetResult> => {\n    let res: Response\n    try {\n      res = await fetch(base + path, { headers })\n    } catch (error) {\n      // Nothing listening on the URL we were pointed at: there is no session to lose.\n      const code = (error as { cause?: { code?: string } })?.cause?.code\n      if (code === 'ECONNREFUSED') return { ok: false, status: 'unreachable' }\n      return { ok: false, detail: String(error instanceof Error ? error.message : error) }\n    }\n    if (!res.ok) return { ok: false, code: res.status, detail: `HTTP ${res.status}` }\n    try {\n      return { ok: true, body: (await res.json()) as Record<string, unknown> }\n    } catch {\n      return { ok: false, code: res.status, detail: 'response was not JSON' }\n    }\n  }\n\n  /** One look at the server. Returns the reasons a restart would cost something. */\n  const inspect = async (): Promise<Verdict> => {\n    const sessions = await get('/sessions')\n    if (!sessions.ok && 'status' in sessions) return { unreachable: true, reasons: [], notes: [] }\n    if (!sessions.ok) return { error: `GET ${base}/sessions → ${sessions.detail}`, reasons: [], notes: [] }\n    const listed = sessions.body.sessions\n    if (!Array.isArray(listed)) {\n      return { error: `GET ${base}/sessions returned no session list`, reasons: [], notes: [] }\n    }\n    const all = listed as { id: string; status: string }[]\n\n    const reasons: string[] = []\n    /** Worth saying out loud, but not worth blocking a deploy over. */\n    const notes: string[] = []\n    for (const session of all.filter((s) => BUSY_STATUSES.has(s.status))) {\n      reasons.push(`session ${session.id} is ${session.status}`)\n    }\n    const parked = all.filter((s) => s.status === 'parked')\n    if (parked.length > 0 && !values['allow-parked']) {\n      reasons.push(\n        `${parked.length} parked session(s) — pass --allow-parked once the server ` +\n          'runs a durable SessionStore, or they are lost on restart',\n      )\n    }\n\n    // A queue is optional: 404 here means this server declares none.\n    const queue = await get('/queue')\n    if (!queue.ok && !('status' in queue) && queue.code !== 404) {\n      return { error: `GET ${base}/queue → ${queue.detail}`, reasons: [], notes: [] }\n    }\n    const stats = queue.ok\n      ? (queue.body.stats as { running?: number; queued?: number; parked?: number } | undefined)\n      : undefined\n    if ((stats?.running ?? 0) > 0) reasons.push(`${stats!.running} job(s) running`)\n    if ((stats?.queued ?? 0) > 0 && !values['allow-queued']) {\n      reasons.push(\n        `${stats!.queued} job(s) queued — pass --allow-queued once the server runs a ` +\n          'durable QueueAdapter, or they are lost on restart',\n      )\n    }\n    if ((stats?.parked ?? 0) > 0 && values['allow-parked']) {\n      // Not a blocking reason: the operator has already said parks are durable.\n      // But session durability is not job durability, and only one of the two is theirs.\n      notes.push(\n        `${stats!.parked} parked job(s): their queue-side records are the QueueAdapter's, ` +\n          \"not the SessionStore's — with the in-memory adapter they never finish\",\n      )\n    }\n    return { reasons, notes, sessions: all.length, parked: parked.length }\n  }\n\n  const report = (verdict: string, detail: Verdict): void => {\n    if (values.json) {\n      process.stdout.write(`${JSON.stringify({ verdict, ...detail })}\\n`)\n      return\n    }\n    const lines = [\n      ...detail.reasons.map((reason) => `  - ${reason}`),\n      ...detail.notes.map((note) => `  note: ${note}`),\n    ].join('\\n')\n    process.stdout.write(`guard: ${verdict}${lines ? `\\n${lines}` : ''}\\n`)\n  }\n\n  const deadline = Date.now() + waitMs\n  for (;;) {\n    const result = await inspect()\n    if (result.error) {\n      report('unknown', { ...result, reasons: [result.error] })\n      return 2\n    }\n    if (result.unreachable) {\n      report('safe to restart (nothing listening on the given URL)', result)\n      return 0\n    }\n    if (result.reasons.length === 0) {\n      report('safe to restart', result)\n      return 0\n    }\n    if (Date.now() + intervalMs > deadline) {\n      report('busy — not safe to restart', result)\n      return 1\n    }\n    report(`busy, waiting up to ${Math.round((deadline - Date.now()) / 1000)}s`, result)\n    await new Promise((resolve) => setTimeout(resolve, intervalMs))\n  }\n}\n"],"mappings":"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"}