skein-js 0.9.1 → 0.10.0

package/README.md

@@ -17,6 +17,7 @@ one-word change (`langgraph dev` → `skein dev`).
 - [Commands](#commands)
 - [`skein dev` flags](#skein-dev-flags)
 - [Self-hosted, no lock-in](#self-hosted-no-lock-in)
+- [Deploy anywhere](#deploy-anywhere)
 - [When the managed platform may fit you better](#when-the-managed-platform-may-fit-you-better)
 - [Learn more](#learn-more)
 - [License](#license)
@@ -52,12 +53,13 @@ LangGraph Studio — any Agent Protocol client works with only a URL change. See
 
 ## Commands
 
-| Command            | What it does                                                   | LangGraph CLI equivalent | Key flags                                                             |
-| ------------------ | -------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
-| `skein dev`        | In-process dev server, hot reload, `.skein/` state, no Docker. | `langgraph dev`          | see [`skein dev` flags](#skein-dev-flags)                             |
-| `skein up`         | Self-hosted stack via Docker Compose (app + Postgres + Redis). | `langgraph up`           | `-p, --port` (8123) · `--host` (0.0.0.0) · `-n, --npmrc <path>`       |
-| `skein build`      | Build a deployable Docker image from the config.               | `langgraph build`        | `-t, --tag` (defaults to the project dir name) · `-n, --npmrc <path>` |
-| `skein dockerfile` | Emit a standalone Dockerfile (stdout by default).              | `langgraph dockerfile`   | `-o, --output <path>`                                                 |
+| Command            | What it does                                                        | LangGraph CLI equivalent | Key flags                                                                |
+| ------------------ | ------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ |
+| `skein dev`        | In-process dev server, hot reload, `.skein/` state, no Docker.      | `langgraph dev`          | see [`skein dev` flags](#skein-dev-flags)                                |
+| `skein up`         | Self-hosted stack via Docker Compose (app + Postgres + Redis).      | `langgraph up`           | `-p, --port` (8123) · `--host` (0.0.0.0) · `-n, --npmrc <path>`          |
+| `skein build`      | Build a deployable Docker image from the config.                    | `langgraph build`        | `-t, --tag` (defaults to the project dir name) · `-n, --npmrc <path>`    |
+| `skein dockerfile` | Emit a standalone Dockerfile (stdout by default).                   | `langgraph dockerfile`   | `-o, --output <path>`                                                    |
+| `skein start`      | Serve a pre-built `.skein/build` artifact (the image's entrypoint). | —                        | `-p, --port` (8123) · `--host` · `--store` · `--queue` · `--concurrency` |
 
 All commands take `-c, --config <path>` (default `langgraph.json`).
 
@@ -96,6 +98,23 @@ run your LangGraph.js graphs behind the standard Agent Protocol on **your own in
 license key, no per-deployment fee, and no vendor lock-in. `skein up` brings up a Docker Compose
 stack (app + your Postgres + your Redis) that you own end to end.
 
+## Deploy anywhere
+
+`skein build` produces an ordinary Docker image, so your LangGraph.js graphs run **anywhere you can
+run a container** — Google Cloud Run, Railway, Fly.io, Render, AWS App Runner or ECS Fargate,
+Kubernetes, or your own VPS.
+
+```bash
+skein build -t my-agent            # → a deployable Docker image
+docker run -p 8123:8123 \
+  -e POSTGRES_URI="postgresql://…" \
+  -e REDIS_URI="redis://…" my-agent
+```
+
+The image binds `$PORT` when a platform injects one (8123 when nothing does), runs as a non-root
+user, serves a `/ok` health probe, and drains in-flight runs on `SIGTERM`. Step-by-step guides per
+platform, and the knobs that are the same everywhere: [deploy anywhere](../../docs/deploy.md).
+
 ## When the managed platform may fit you better
 
 skein-js gives you the code and full ownership, not a support contract. If you're an established
@@ -107,6 +126,7 @@ on top of the open LangGraph runtime.
 
 ## Learn more
 
+- [Deploy anywhere](../../docs/deploy.md) — Cloud Run, Railway, Fly.io, Render, AWS, Kubernetes, VPS
 - [LangGraph CLI compatibility](../../docs/langgraph-cli-compat.md) — commands + `langgraph.json` fields
 - [skein-js overview](../../docs/index.md) · [Reuse-first architecture](../../docs/reuse.md) · [Roadmap](../../docs/roadmap.md)
 - [skein-js root README](../../README.md)

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   readLanggraphDevState
 } from "@skein-js/express";
 import { buildRuntime } from "@skein-js/runtime";
-import { resolveRunConcurrency } from "@skein-js/server-kit";
+import { resolveRunConcurrency, resolveShutdownGraceMs } from "@skein-js/server-kit";
 
 // src/colors.ts
 var colorEnabled = process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
@@ -139,6 +139,8 @@ async function applyProjectEnv(config, configDir) {
 }
 
 // src/serve-env.ts
+var DEFAULT_DEV_PORT = 2024;
+var DEFAULT_CONTAINER_PORT = 8123;
 function envPort(fallback) {
   const raw = process.env.PORT;
   if (raw === void 0 || raw.trim() === "") return fallback;
@@ -157,6 +159,32 @@ function describeBindError(error, port) {
   return `failed to start server: ${error instanceof Error ? error.message : String(error)}`;
 }
 
+// src/shutdown.ts
+import { DEFAULT_SHUTDOWN_GRACE_MS } from "@skein-js/server-kit";
+var FORCE_EXIT_BUFFER_MS = 3e3;
+function forceExitDelayMs(graceMs = DEFAULT_SHUTDOWN_GRACE_MS) {
+  return graceMs + FORCE_EXIT_BUFFER_MS;
+}
+var describe = (error) => error instanceof Error ? error.message : String(error);
+function createShutdownHandler(options) {
+  const { forceExitMs, close, onShutdownStart, exit = (code) => process.exit(code) } = options;
+  let shuttingDown = false;
+  return () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try {
+      onShutdownStart?.();
+    } catch (error) {
+      console.error(`skein: pre-shutdown step failed: ${describe(error)}`);
+    }
+    const forceExit = setTimeout(() => exit(0), forceExitMs);
+    forceExit.unref();
+    void close().catch((error) => {
+      console.error(`skein: shutdown did not complete cleanly: ${describe(error)}`);
+    }).finally(() => exit(0));
+  };
+}
+
 // src/vite-graph-loader.ts
 import { createServer as createNetServer } from "net";
 function findFreePort() {
@@ -211,12 +239,12 @@ async function createViteGraphLoader(root, ignored = []) {
 // src/dev-command.ts
 var RELOAD_DEBOUNCE_MS = 120;
 var AUTOSAVE_MS = 2e3;
-var FORCE_EXIT_MS = 5e3;
 var devLogger = createDevLogger();
 async function runDev(options) {
   const configPath = path3.resolve(process.cwd(), options.config);
   const { config, configDir } = await loadConfig({ configPath });
   await applyProjectEnv(config, configDir);
+  const shutdownGraceMs = resolveShutdownGraceMs();
   const stateDir = path3.join(configDir, STATE_DIR);
   const stateFile = devStateFile(configDir);
   const loader = await createViteGraphLoader(configDir, [`${STATE_DIR}/**`, `**/${STATE_DIR}/**`]);
@@ -268,7 +296,7 @@ async function runDev(options) {
       cors: runtime.cors,
       warm: true,
       logger: devLogger,
-      worker: { maxConcurrency: runConcurrency }
+      worker: { maxConcurrency: runConcurrency, shutdownGraceMs }
     });
     await server.listen(port, host);
   } catch (error) {
@@ -346,18 +374,25 @@ async function runDev(options) {
       pending = setTimeout(() => void reload(), RELOAD_DEBOUNCE_MS);
     });
   }
-  let shuttingDown = false;
-  const shutdown = () => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    if (autosave) clearInterval(autosave);
-    const forceExit = setTimeout(() => process.exit(0), FORCE_EXIT_MS);
-    forceExit.unref();
-    saveState();
-    void Promise.allSettled([server.close(), loader.close(), runtime.dispose()]).then(
-      () => process.exit(0)
-    );
-  };
+  const shutdown = createShutdownHandler({
+    forceExitMs: forceExitDelayMs(shutdownGraceMs),
+    // Stop autosaving and flush one last snapshot synchronously, before anything can race it.
+    onShutdownStart: () => {
+      if (autosave) clearInterval(autosave);
+      saveState();
+    },
+    // Strictly ordered, never concurrent. `server.close()` stops the worker, which needs the store
+    // and queue still alive to settle in-flight runs terminally — and needs the vite loader alive
+    // too, since a draining graph may still `await import(...)` a module it hasn't loaded yet.
+    // Tearing either down alongside the drain fails the runs it was meant to save.
+    close: async () => {
+      try {
+        await server.close();
+      } finally {
+        await Promise.allSettled([loader.close(), runtime.dispose()]);
+      }
+    }
+  });
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
 }
@@ -592,8 +627,9 @@ services:
     ports:
       - ${ports}
     environment:
-      # The container CMD passes no --port; it binds $PORT (as a hosting platform would inject).
-      # Set it here so the app listens on the port the mapping above publishes.
+      # The container CMD passes no --port; it binds $PORT (as a hosting platform would inject), and
+      # falls back to this same port anyway. Set explicitly so the mapping above stays correct even
+      # if a host port is published that differs from the port the container listens on.
       PORT: "${options.containerPort}"
       POSTGRES_URI: postgresql://postgres:postgres@postgres:5432/skein
       REDIS_URI: redis://redis:6379
@@ -603,6 +639,11 @@ services:
       redis:
         condition: service_healthy
     restart: unless-stopped
+    # Longer than Docker's 10s default so the app can finish its shutdown: it drains in-flight runs
+    # for SKEIN_SHUTDOWN_GRACE_MS, then aborts the stragglers so they settle to a terminal status.
+    # 10s leaves no headroom the moment that window is raised, and a SIGKILL mid-abort is exactly
+    # what leaves a run stuck in a non-terminal state.
+    stop_grace_period: 30s
 
   postgres:
     image: pgvector/pgvector:pg16
@@ -688,17 +729,28 @@ function generateDockerfile(options) {
     // The bundle ships sourcemaps; enable them so stack traces map back to the original TypeScript.
     `ENV NODE_OPTIONS=--enable-source-maps`,
     `EXPOSE ${port}`,
-    // Liveness probe against skein's `/ok` endpoint, targeting the same port the server binds.
+    // Liveness probe against skein's `/ok` endpoint, targeting the same port the server binds. PORT
+    // is resolved exactly as `envPort` resolves it — integer, in range, blank counts as unset —
+    // rather than by truthiness, so a malformed value (`PORT=8080a`, `PORT=0`) has the probe and the
+    // server agree on the fallback instead of probing a URL the server never bound.
     `HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \\`,
-    `    CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||${port})+'/ok').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"`,
+    `    CMD node -e "const r=Number(process.env.PORT);const p=Number.isInteger(r)&&r>=0&&r<=65535?r:${port};fetch('http://127.0.0.1:'+p+'/ok').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"`,
     // Run unprivileged. The bundle writes nothing to disk, and /app is world-readable, so no chown.
     `USER node`,
     ...dockerfileLines,
     ``,
     `# Serve the compiled artifact against Postgres + Redis (POSTGRES_URI / REDIS_URI from the env).`,
-    `# No --port: the server binds $PORT when the platform injects one (Railway/Fly/Render), else its`,
-    `# default. Exec form keeps node as PID 1 so SIGTERM reaches skein's graceful-shutdown handler.`,
-    `CMD ["npx", "skein", "start", "--store", "postgres", "--queue", "redis", "--host", "0.0.0.0"]`
+    `# No --port: the server binds $PORT when the platform injects one (Railway/Fly/Render/Cloud Run),`,
+    `# else \`skein start\`'s default \u2014 the port EXPOSEd above, so a bare \`docker run -p ${port}:${port}\``,
+    `# works too.`,
+    `#`,
+    `# Invoked as \`node <entry>\` rather than \`npx skein\` so that **node itself is PID 1**. Under npx,`,
+    `# PID 1 is npm, which forwards SIGTERM to a \`sh -c\` child and exits immediately \u2014 the server is`,
+    `# killed mid-shutdown and in-flight runs are left stranded in a non-terminal status. Exec form`,
+    `# (no shell) keeps the signal path direct, so SIGTERM reaches skein's graceful-shutdown handler.`,
+    // Absolute, so a `dockerfile_lines` entry that changes WORKDIR (spliced in just above) can't
+    // leave the CMD resolving against the wrong directory.
+    `CMD ["node", "/app/node_modules/skein-js/dist/index.js", "start", "--store", "postgres", "--queue", "redis", "--host", "0.0.0.0"]`
   ];
   return `${lines.join("\n")}
 `;
@@ -709,7 +761,7 @@ function skeinCliVersion() {
   return createRequire2(import.meta.url)("../package.json").version;
 }
 var ARTIFACT_SUBDIR = path5.join(".skein", "build");
-var CONTAINER_PORT = 8123;
+var CONTAINER_PORT = DEFAULT_CONTAINER_PORT;
 var DOCKERFILE_NAME = "Dockerfile";
 var COMPOSE_NAME = "compose.yaml";
 var DOCKERIGNORE_NAME = ".dockerignore";
@@ -930,8 +982,7 @@ import { createExpressServer as createExpressServer2 } from "@skein-js/express";
 import {
   buildRuntime as buildRuntime3
 } from "@skein-js/runtime";
-import { resolveRunConcurrency as resolveRunConcurrency2 } from "@skein-js/server-kit";
-var FORCE_EXIT_MS2 = 5e3;
+import { resolveRunConcurrency as resolveRunConcurrency2, resolveShutdownGraceMs as resolveShutdownGraceMs2 } from "@skein-js/server-kit";
 var logger = createDevLogger();
 function readBakedSchemas(configDir) {
   const schemasFile = path7.join(configDir, "schemas.json");
@@ -944,16 +995,21 @@ function readBakedSchemas(configDir) {
 }
 async function runStart(options) {
   const configPath = path7.resolve(process.cwd(), options.config);
+  let handleSignal = () => process.exit(0);
+  process.on("SIGINT", () => handleSignal());
+  process.on("SIGTERM", () => handleSignal());
   let schemas;
   let configDir;
   let authPath;
   let runConcurrency;
+  let shutdownGraceMs;
   try {
     const loaded = await loadConfig5({ configPath });
     configDir = loaded.configDir;
     authPath = loaded.config.auth?.path;
     await applyProjectEnv(loaded.config, configDir);
     runConcurrency = resolveRunConcurrency2(options.concurrency ?? options.nJobsPerWorker);
+    shutdownGraceMs = resolveShutdownGraceMs2();
     schemas = readBakedSchemas(configDir);
   } catch (error) {
     console.error(`skein: ${error instanceof Error ? error.message : String(error)}`);
@@ -983,7 +1039,7 @@ async function runStart(options) {
       cors: runtime.cors,
       warm: true,
       logger,
-      worker: { maxConcurrency: runConcurrency }
+      worker: { maxConcurrency: runConcurrency, shutdownGraceMs }
     });
     await server.listen(port, host);
   } catch (error) {
@@ -993,16 +1049,16 @@ async function runStart(options) {
     return;
   }
   printBanner({ host, port, graphIds: runtime.deps.graphs.ids, authPath, runConcurrency }, logger);
-  let shuttingDown = false;
-  const shutdown = () => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    const forceExit = setTimeout(() => process.exit(0), FORCE_EXIT_MS2);
-    forceExit.unref();
-    void Promise.allSettled([server.close(), runtime.dispose()]).then(() => process.exit(0));
-  };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
+  handleSignal = createShutdownHandler({
+    forceExitMs: forceExitDelayMs(shutdownGraceMs),
+    close: async () => {
+      try {
+        await server.close();
+      } finally {
+        await runtime.dispose();
+      }
+    }
+  });
 }
 
 // src/index.ts
@@ -1035,7 +1091,7 @@ var parseQueue = parseChoice(["memory", "redis"]);
 var program = new Command().name("skein").description(
   "Agent Protocol server for LangGraph.js \u2014 a drop-in replacement for the LangGraph CLI."
 ).version(version, "-v, --version");
-program.command("dev").description("Run the in-process dev server with hot reload (no Docker).").option("-c, --config <path>", "Path to langgraph.json", "langgraph.json").option("-p, --port <port>", "Port to bind", parsePort, 2024).option("--host <host>", "Host to bind", "127.0.0.1").option("--no-reload", "Disable hot reload").option("--no-persist", "Don't persist dev state to .skein/ between restarts").option("--store <driver>", "Store driver: memory | postgres", parseStore, "memory").option("--queue <driver>", "Queue driver: memory | redis", parseQueue, "memory").option(
+program.command("dev").description("Run the in-process dev server with hot reload (no Docker).").option("-c, --config <path>", "Path to langgraph.json", "langgraph.json").option("-p, --port <port>", "Port to bind", parsePort, DEFAULT_DEV_PORT).option("--host <host>", "Host to bind", "127.0.0.1").option("--no-reload", "Disable hot reload").option("--no-persist", "Don't persist dev state to .skein/ between restarts").option("--store <driver>", "Store driver: memory | postgres", parseStore, "memory").option("--queue <driver>", "Queue driver: memory | redis", parseQueue, "memory").option(
   "--concurrency <count>",
   "Queued runs the background worker executes at once (default 10; env SKEIN_RUN_CONCURRENCY)",
   parseConcurrency
@@ -1050,7 +1106,7 @@ program.command("dev").description("Run the in-process dev server with hot reloa
     hostExplicit: command.getOptionValueSource("host") === "cli"
   })
 );
-program.command("start").description("Serve a pre-built .skein/build artifact (the production image entrypoint).").option("-c, --config <path>", "Path to the artifact's langgraph.json", "langgraph.json").option("-p, --port <port>", "Port to bind", parsePort, 2024).option("--host <host>", "Host to bind", "127.0.0.1").option("--store <driver>", "Store driver: memory | postgres", parseStore, "memory").option("--queue <driver>", "Queue driver: memory | redis", parseQueue, "memory").option(
+program.command("start").description("Serve a pre-built .skein/build artifact (the production image entrypoint).").option("-c, --config <path>", "Path to the artifact's langgraph.json", "langgraph.json").option("-p, --port <port>", "Port to bind", parsePort, DEFAULT_CONTAINER_PORT).option("--host <host>", "Host to bind", "127.0.0.1").option("--store <driver>", "Store driver: memory | postgres", parseStore, "memory").option("--queue <driver>", "Queue driver: memory | redis", parseQueue, "memory").option(
   "--concurrency <count>",
   "Queued runs the background worker executes at once (default 10; env SKEIN_RUN_CONCURRENCY)",
   parseConcurrency
@@ -1065,7 +1121,7 @@ program.command("start").description("Serve a pre-built .skein/build artifact (t
     hostExplicit: command.getOptionValueSource("host") === "cli"
   })
 );
-program.command("up").description("Bring up the production stack (Docker Compose: app + Postgres + Redis).").option("-c, --config <path>", "Path to langgraph.json", "langgraph.json").option("-p, --port <port>", "Port to expose", parsePort, 8123).option("--host <host>", "Host to bind", "0.0.0.0").option(
+program.command("up").description("Bring up the production stack (Docker Compose: app + Postgres + Redis).").option("-c, --config <path>", "Path to langgraph.json", "langgraph.json").option("-p, --port <port>", "Port to expose", parsePort, DEFAULT_CONTAINER_PORT).option("--host <host>", "Host to bind", "0.0.0.0").option(
   "-n, --npmrc <path>",
   "Path to an .npmrc for authenticating private-registry installs (wired in as a build secret)"
 ).action((options) => runUp(options));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skein-js",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "The skein-js CLI — a drop-in replacement for the LangGraph CLI (dev/up/build/dockerfile).",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -16,10 +16,16 @@
   "keywords": [
     "typescript",
     "langgraph",
+    "langgraph-js",
     "cli",
     "agent-protocol",
     "langgraph-cli",
-    "self-hosted"
+    "self-hosted",
+    "ai-agents",
+    "deploy",
+    "docker",
+    "cloud-run",
+    "kubernetes"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -47,11 +53,11 @@
     "@commander-js/extra-typings": "~13.1.0",
     "@langchain/langgraph-checkpoint-postgres": "^1.0.4",
     "commander": "~13.1.0",
-    "@skein-js/core": "0.9.1",
-    "@skein-js/express": "0.9.1",
-    "@skein-js/runtime": "0.9.1",
-    "@skein-js/server-kit": "0.9.1",
-    "@skein-js/config": "0.9.1"
+    "@skein-js/core": "0.10.0",
+    "@skein-js/config": "0.10.0",
+    "@skein-js/express": "0.10.0",
+    "@skein-js/server-kit": "0.10.0",
+    "@skein-js/runtime": "0.10.0"
   },
   "optionalDependencies": {
     "vite": "^8.1.0"