skein-js 0.2.0 → 0.3.0

package/README.md

@@ -1,81 +1,104 @@
 # skein-js
 
-> The skein-js CLI — a drop-in replacement for the LangGraph CLI (dev/up/build/dockerfile).
+> The `skein` CLI — a drop-in replacement for the LangGraph CLI (`dev` / `up` / `build` / `dockerfile`).
 
-Part of **[skein-js](https://github.com/mainawycliffe/skein)** — a TypeScript [Agent Protocol](https://github.com/langchain-ai/agent-protocol) server for [LangGraph.js](https://github.com/langchain-ai/langgraphjs), and a drop-in replacement for the LangGraph CLI.
+Part of **[skein-js](../../README.md)** — a TypeScript [Agent Protocol](https://github.com/langchain-ai/agent-protocol) server for [LangGraph.js](https://github.com/langchain-ai/langgraphjs), and a drop-in replacement for the LangGraph CLI.
 
 **Status:** 🚧 Pre-alpha — `dev`, `up`, `build`, and `dockerfile` all work today.
 
-## Why skein-js
+This is the only package most projects install. Point `skein` at your existing `langgraph.json` and
+your graph code, config, and clients keep working unchanged — the swap from the LangGraph CLI is a
+one-word change (`langgraph dev` → `skein dev`).
 
-I wanted to self-host my LangGraph.js graphs behind the standard Agent Protocol — on my own infrastructure, without paying for a license to do it. That turns out to be the catch: the LangGraph Platform server that serves your graphs in production (`langgraph-api`) is under the **Elastic License 2.0**, and self-hosting it requires a paid **enterprise license key** (`LANGGRAPH_CLOUD_LICENSE_KEY`) — without one, the server won't start. So your options today are the hosted platform, or an enterprise contract to run it yourself.
+## Contents
 
-skein-js is the third option. It's **Apache-2.0**, built only on the **MIT-licensed** `@langchain/*` packages, so you can self-host your graphs with **no license key and no per-deployment fee**.
-
-None of this is a knock on LangGraph — skein-js exists _because_ of it. The agent runtime, checkpointers, SDK, and even the MIT JavaScript dev server (`@langchain/langgraph-api`, whose `langgraph.json` parser and schemas skein-js reuses) are all open source, and skein-js doesn't reinvent any of them — it stands on them. A commercially-licensed production server is a fair way for LangChain to fund that open work. skein-js simply fills the one gap that leaves for TypeScript teams: an open, self-hostable way to serve those graphs in production.
-
-**Why not just the LangGraph CLI?** `skein` reads your existing `langgraph.json` and mirrors `dev`/`up`/`build`/`dockerfile`, so the swap is one word. What differs is what happens when you go to production and self-host:
-
-|                            | `langgraph` CLI                                          | `skein` CLI                                     |
-| -------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
-| Local `dev`                | free in-memory dev server (Hono)                         | free in-process dev server, hot reload          |
-| Self-hosting in production | requires an enterprise license key (Elastic License 2.0) | Apache-2.0, **no license key**                  |
-| Production path            | LangGraph Platform (hosted, or licensed self-host)       | self-hosted Docker Compose you own (`skein up`) |
-| Persistence                | platform-managed                                         | your Postgres (+ pgvector) and Redis            |
-| HTTP framework             | Hono                                                     | Express (Fastify / NestJS to follow)            |
-
-### When the LangGraph Platform is the better call
-
-skein-js isn't strictly better — it's a different trade, and it's worth being clear about what the Enterprise plan actually buys. It isn't hosting: even on LangGraph's self-hosted tier you still run your own Postgres, Redis, and infrastructure. What you're paying for is **LangChain's support** — dedicated support, response-time SLAs, and architectural guidance from the team that builds LangGraph — plus enterprise features like SSO, RBAC, and SOC2. If you're an established product with real revenue and you want a vendor standing behind your agent stack, that's genuine value, and the Platform is a sound choice.
-
-skein-js gives you the code and full ownership — not a support contract. **It's for you if** you're earlier-stage or cost-sensitive, don't need (or don't want to buy) an enterprise support relationship, want to keep data in your own infrastructure, run a TypeScript/Node stack, or just want to own your agent infrastructure end to end with no license and no vendor lock-in.
-
-The graph code and `langgraph.json` stay unchanged — see the full [Why skein-js comparison](../../README.md#why-skein-js) and the [reuse-first architecture](../../docs/reuse.md).
-
-## What it does
-
-`skein dev` (in-process, hot reload, no Docker), `skein up` (Docker Compose: app + Postgres + Redis), `skein build` / `skein dockerfile`. The one-word swap from `langgraph dev` → `skein dev`.
-
-## Reuse
-
-Mirrors `@langchain/langgraph-cli` semantics and reads an unchanged `langgraph.json`. Reuses `@skein-js/config` (built on `@langchain/langgraph-api`'s parser) for graph loading.
+- [Install](#install)
+- [Usage](#usage)
+- [Commands](#commands)
+- [`skein dev` flags](#skein-dev-flags)
+- [Self-hosted, no lock-in](#self-hosted-no-lock-in)
+- [When the managed platform may fit you better](#when-the-managed-platform-may-fit-you-better)
+- [Learn more](#learn-more)
+- [License](#license)
 
 ## Install
 
 ```bash
-pnpm add skein-js
+pnpm add -D skein-js            # or: npm i -D skein-js  ·  yarn add -D skein-js
 ```
 
 ## Usage
 
-Swap it into your `package.json` scripts (`"dev": "skein dev"`, `"up": "skein up"`) — your
-`langgraph.json` is unchanged.
+Swap it into your `package.json` scripts — your `langgraph.json` is unchanged:
+
+```jsonc
+{
+  "scripts": {
+    "dev": "skein dev", // was: "langgraph dev"
+    "up": "skein up", //  was: "langgraph up"
+  },
+}
+```
+
+Then run the dev server (in-process, hot reload, no Docker):
 
 ```bash
-npx skein dev --port 2024
+pnpm skein dev                 # → http://127.0.0.1:2024
 ```
 
-### Commands
+Talk to it with the official `@langchain/langgraph-sdk` client, `useStream`, Agent Chat UI, or
+LangGraph Studio — any Agent Protocol client works with only a URL change. See the
+[Quick start](../../README.md#quick-start).
 
-| Command            | What it does                                                   | Key flags                                                                                                                                            |
-| ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `skein dev`        | In-process dev server, hot reload, no Docker.                  | `-p, --port` (2024) · `--host` (127.0.0.1) · `--no-reload` · `--no-persist` · `--store memory\|postgres` · `--queue memory\|redis` · `-v, --verbose` |
-| `skein up`         | Self-hosted stack via Docker Compose (app + Postgres + Redis). | `-p, --port` (8123) · `--host` (0.0.0.0)                                                                                                             |
-| `skein build`      | Build a deployable Docker image from the config.               | `-t, --tag` (defaults to the project dir name)                                                                                                       |
-| `skein dockerfile` | Emit a standalone Dockerfile (stdout by default).              | `-o, --output <path>`                                                                                                                                |
+## 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)       |
+| `skein build`      | Build a deployable Docker image from the config.               | `langgraph build`        | `-t, --tag` (defaults to the project dir name) |
+| `skein dockerfile` | Emit a standalone Dockerfile (stdout by default).              | `langgraph dockerfile`   | `-o, --output <path>`                          |
 
 All commands take `-c, --config <path>` (default `langgraph.json`).
 
+## `skein dev` flags
+
+| Flag               | Values               | Default     | Notes                                                          |
+| ------------------ | -------------------- | ----------- | -------------------------------------------------------------- |
+| `-p, --port`       | number               | `2024`      | Port to listen on.                                             |
+| `--host`           | host                 | `127.0.0.1` | Interface to bind.                                             |
+| `--store <driver>` | `memory`, `postgres` | `memory`    | `postgres` reads `DATABASE_URL`; also selects `PostgresSaver`. |
+| `--queue <driver>` | `memory`, `redis`    | `memory`    | `redis` reads `REDIS_URL` (BullMQ queue + Redis Streams bus).  |
+| `--no-persist`     | —                    | persists    | Don't snapshot dev state to `.skein/` across restarts.         |
+| `--no-reload`      | —                    | reloads     | Disable hot reload on source change.                           |
+| `-v, --verbose`    | —                    | off         | Log per-run activity (tool calls, interrupts, timing).         |
+
 `skein dev --store postgres --queue redis` is a capability the LangGraph CLI does **not** offer: it
 lets you develop against **production-shaped** storage (durable Postgres checkpoints, pgvector
-search, cross-instance Redis streaming) with hot reload and no Docker. Connection URLs come from
-`DATABASE_URL` / `REDIS_URL`.
+search, cross-instance Redis streaming) with hot reload and no Docker. Full mapping and the
+annotated `langgraph.json`: [docs/langgraph-cli-compat.md](../../docs/langgraph-cli-compat.md).
+
+## Self-hosted, no lock-in
+
+skein-js is **Apache-2.0** and builds only on the **MIT-licensed** `@langchain/*` packages, so you
+run your LangGraph.js graphs behind the standard Agent Protocol on **your own infrastructure** — no
+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.
+
+## 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
+product that wants a vendor standing behind your agent stack — dedicated support with response-time
+SLAs, plus enterprise features like SSO, RBAC, and SOC2 — LangGraph Platform's Enterprise plan is a
+sound choice. Your graph code and `langgraph.json` stay unchanged either way, so switching between
+them is cheap. See the [reuse-first architecture](../../docs/reuse.md) for how little skein-js adds
+on top of the open LangGraph runtime.
 
 ## Learn more
 
-- [skein-js overview](../../docs/index.md)
-- [Reuse-first architecture](../../docs/reuse.md)
-- [Roadmap](../../docs/roadmap.md)
+- [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)
 
 ## License
 

package/dist/index.js

@@ -5,14 +5,136 @@ import { createRequire } from "module";
 import { Command, InvalidArgumentError } from "@commander-js/extra-typings";
 
 // src/dev-command.ts
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
-import path from "path";
-import { loadConfig, parseEnvFile, resolveEnv } from "@skein-js/config";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import path3 from "path";
+import { loadConfig } from "@skein-js/config";
 import {
-  createExpressServer
+  createExpressServer,
+  describeSnapshot,
+  readLanggraphDevState
 } from "@skein-js/express";
 import { buildRuntime } from "@skein-js/runtime";
 
+// src/colors.ts
+var colorEnabled = process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
+var paint = (code) => (text) => colorEnabled ? `\x1B[${code}m${text}\x1B[0m` : text;
+var green = paint(32);
+var yellow = paint(33);
+var red = paint(31);
+var cyan = paint(36);
+var bold = paint(1);
+var dim = paint(2);
+
+// src/banner.ts
+function printBanner(info, logger) {
+  const { host, port, graphIds, authPath, workerCount } = info;
+  const base = `http://${host}:${port}`;
+  console.log();
+  console.log(`${bold(green("skein"))} ${dim("\xB7 Agent Protocol dev server")}`);
+  console.log();
+  console.log(`${dim("API ")}  ${cyan(base)}`);
+  console.log(`${dim("Docs")}  ${cyan(`${base}/docs`)}`);
+  console.log();
+  for (const id of graphIds) logger.info(`Registering graph with id '${id}'`);
+  if (authPath) logger.info(`Loading auth from ${authPath}`);
+  logger.info(`Starting ${workerCount} worker${workerCount === 1 ? "" : "s"}`);
+  logger.info(`Server running at ${base}`);
+}
+
+// src/dev-logger.ts
+var INDENT = "       ";
+function describeError(error) {
+  const head = error.stack ?? `${error.name}: ${error.message}`;
+  if (error.cause === void 0) return head;
+  const cause = error.cause instanceof Error ? describeError(error.cause) : String(error.cause);
+  return `${head}
+caused by: ${cause}`;
+}
+function metaBlock(meta) {
+  if (meta === void 0 || meta === null) return "";
+  if (meta instanceof Error) {
+    const trace = describeError(meta);
+    return `
+${INDENT}${dim(trace.replace(/\n/g, `
+${INDENT}`))}`;
+  }
+  if (typeof meta === "object") {
+    const pairs = Object.entries(meta).map(([key, value]) => {
+      const rendered = typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+      return `${dim(`${key}=`)}${rendered}`;
+    });
+    return pairs.length ? `
+${INDENT}${pairs.join("  ")}` : "";
+  }
+  return `
+${INDENT}${dim(String(meta))}`;
+}
+function paintHttp(message) {
+  if (message.startsWith("<-- ")) return dim(message);
+  if (message.startsWith("--> ")) {
+    const status = Number(message.match(/ (\d{3}) \d+ms$/)?.[1]);
+    if (status >= 500) return red(message);
+    if (status >= 400) return yellow(message);
+    if (status >= 300) return cyan(message);
+    return green(message);
+  }
+  return message;
+}
+function line(prefix, message, meta) {
+  return `${prefix} ${paintHttp(message)}${metaBlock(meta)}`;
+}
+function createDevLogger() {
+  return {
+    debug: (message, meta) => console.debug(line(dim("debug:"), message, meta)),
+    info: (message, meta) => console.log(line(green("info:"), message, meta)),
+    warn: (message, meta) => console.warn(line(yellow("warn:"), message, meta)),
+    error: (message, meta) => console.error(line(red("error:"), message, meta))
+  };
+}
+
+// src/dev-state.ts
+import { mkdirSync, renameSync, writeFileSync } from "fs";
+import path from "path";
+var STATE_DIR = ".skein";
+var STATE_FILE = "dev-state.json";
+var LANGGRAPH_DIR = ".langgraph_api";
+function devStateFile(configDir) {
+  return path.join(configDir, STATE_DIR, STATE_FILE);
+}
+function writeDevStateFile(stateFile, serialized) {
+  mkdirSync(path.dirname(stateFile), { recursive: true });
+  const tmp = `${stateFile}.tmp`;
+  writeFileSync(tmp, serialized);
+  renameSync(tmp, stateFile);
+}
+
+// src/project-env.ts
+import { existsSync, readFileSync } from "fs";
+import path2 from "path";
+import { parseEnvFile, resolveEnv } from "@skein-js/config";
+function applyEnv(resolved) {
+  for (const [key, value] of Object.entries(resolved)) {
+    if (process.env[key] === void 0) process.env[key] = value;
+  }
+}
+function readConventionalDotEnv(dir) {
+  const envPath = path2.join(dir, ".env");
+  if (!existsSync(envPath)) return {};
+  try {
+    return parseEnvFile(readFileSync(envPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function applyProjectEnv(config, configDir) {
+  const declaredEnvPath = typeof config.env === "string" ? path2.resolve(configDir, config.env) : void 0;
+  const conventional = declaredEnvPath === path2.join(configDir, ".env") ? {} : readConventionalDotEnv(configDir);
+  applyEnv({ ...conventional, ...await resolveEnv(config, configDir) });
+  if (declaredEnvPath !== void 0 && !existsSync(declaredEnvPath)) {
+    console.warn(`skein: env file "${config.env}" not found; continuing without it.`);
+  }
+}
+
 // src/vite-graph-loader.ts
 import { createServer as createNetServer } from "net";
 import { createServer, createServerModuleRunner } from "vite";
@@ -60,39 +182,23 @@ async function createViteGraphLoader(root, ignored = []) {
 var RELOAD_DEBOUNCE_MS = 120;
 var AUTOSAVE_MS = 2e3;
 var FORCE_EXIT_MS = 5e3;
-var STATE_DIR = ".skein";
-var STATE_FILE = "dev-state.json";
-var devLogger = {
-  debug: (message) => console.debug(message),
-  info: (message) => console.log(message),
-  warn: (message, meta) => meta === void 0 ? console.warn(message) : console.warn(message, meta),
-  error: (message, meta) => meta === void 0 ? console.error(message) : console.error(message, meta)
-};
-function applyEnv(resolved) {
-  for (const [key, value] of Object.entries(resolved)) {
-    if (process.env[key] === void 0) process.env[key] = value;
-  }
+var devLogger = createDevLogger();
+function envPort(fallback) {
+  const raw = process.env.PORT;
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  const port = Number(raw);
+  return Number.isInteger(port) && port >= 0 && port <= 65535 ? port : fallback;
 }
-function readConventionalDotEnv(dir) {
-  const envPath = path.join(dir, ".env");
-  if (!existsSync(envPath)) return {};
-  try {
-    return parseEnvFile(readFileSync(envPath, "utf8"));
-  } catch {
-    return {};
-  }
+function envHost(fallback) {
+  const host = process.env.HOST;
+  return host !== void 0 && host.trim() !== "" ? host : fallback;
 }
 async function runDev(options) {
-  const configPath = path.resolve(process.cwd(), options.config);
+  const configPath = path3.resolve(process.cwd(), options.config);
   const { config, configDir } = await loadConfig({ configPath });
-  const declaredEnvPath = typeof config.env === "string" ? path.resolve(configDir, config.env) : void 0;
-  const conventional = declaredEnvPath === path.join(configDir, ".env") ? {} : readConventionalDotEnv(configDir);
-  applyEnv({ ...conventional, ...await resolveEnv(config, configDir) });
-  if (declaredEnvPath !== void 0 && !existsSync(declaredEnvPath)) {
-    console.warn(`skein: env file "${config.env}" not found; continuing without it.`);
-  }
-  const stateDir = path.join(configDir, STATE_DIR);
-  const stateFile = path.join(stateDir, STATE_FILE);
+  await applyProjectEnv(config, configDir);
+  const stateDir = path3.join(configDir, STATE_DIR);
+  const stateFile = devStateFile(configDir);
   const loader = await createViteGraphLoader(configDir, [`${STATE_DIR}/**`, `**/${STATE_DIR}/**`]);
   const runtime = await buildRuntime({
     configPath,
@@ -100,22 +206,38 @@ async function runDev(options) {
     store: options.store,
     queue: options.queue
   });
-  const { port, host } = options;
+  const port = options.portExplicit ? options.port : envPort(options.port);
+  const host = options.hostExplicit ? options.host : envHost(options.host);
   const canPersist = options.persist && runtime.snapshotState !== void 0;
   if (options.persist && runtime.snapshotState === void 0) {
     console.log(
       `skein: state persists in ${options.store}/${options.queue}; skipping .skein snapshot.`
     );
   }
-  if (canPersist && existsSync(stateFile)) {
+  if (canPersist && existsSync2(stateFile)) {
     try {
-      runtime.hydrateState?.(JSON.parse(readFileSync(stateFile, "utf8")));
+      runtime.hydrateState?.(JSON.parse(readFileSync2(stateFile, "utf8")));
       console.log("skein: restored dev state.");
     } catch (error) {
       console.warn(
         `skein: could not restore dev state: ${error instanceof Error ? error.message : String(error)}`
       );
     }
+  } else if (canPersist && existsSync2(path3.join(configDir, LANGGRAPH_DIR))) {
+    try {
+      const imported = await readLanggraphDevState(path3.join(configDir, LANGGRAPH_DIR));
+      if (imported) {
+        runtime.hydrateState?.(imported);
+        const counts = describeSnapshot(imported);
+        console.log(
+          `skein: imported dev state from ${LANGGRAPH_DIR}/ (${counts.threads} thread(s), ${counts.checkpointedThreads} with history).`
+        );
+      }
+    } catch (error) {
+      console.warn(
+        `skein: could not import ${LANGGRAPH_DIR}/: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
   }
   if (options.verbose) runtime.deps.logRunActivity = true;
   let server;
@@ -136,17 +258,23 @@ async function runDev(options) {
     process.exitCode = 1;
     return;
   }
-  console.log(`skein-js listening on http://${host}:${port}`);
+  printBanner(
+    {
+      host,
+      port,
+      graphIds: runtime.deps.graphs.ids,
+      authPath: config.auth?.path,
+      workerCount: 1
+    },
+    devLogger
+  );
   let lastSaved;
   const saveState = () => {
     if (!canPersist || runtime.snapshotState === void 0) return;
     try {
       const serialized = JSON.stringify(runtime.snapshotState());
       if (serialized === lastSaved) return;
-      mkdirSync(path.dirname(stateFile), { recursive: true });
-      const tmp = `${stateFile}.tmp`;
-      writeFileSync(tmp, serialized);
-      renameSync(tmp, stateFile);
+      writeDevStateFile(stateFile, serialized);
       lastSaved = serialized;
     } catch (error) {
       console.warn(
@@ -194,7 +322,7 @@ async function runDev(options) {
       }
     };
     loader.watcher.on("change", (file) => {
-      if (`${path.resolve(file)}${path.sep}`.startsWith(`${stateDir}${path.sep}`)) return;
+      if (`${path3.resolve(file)}${path3.sep}`.startsWith(`${stateDir}${path3.sep}`)) return;
       if (pending) clearTimeout(pending);
       pending = setTimeout(() => void reload(), RELOAD_DEBOUNCE_MS);
     });
@@ -217,8 +345,8 @@ async function runDev(options) {
 
 // src/docker/commands.ts
 import { spawn, spawnSync } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import path3 from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import path5 from "path";
 import { loadConfig as loadConfig2 } from "@skein-js/config";
 
 // src/docker/compose.ts
@@ -233,9 +361,15 @@ function generateCompose(options) {
 services:
   app:
     build: .
+    # Reap zombies + forward signals with an init process (PID 1), so graph-spawned children don't
+    # accumulate; the app itself still handles SIGTERM for graceful shutdown.
+    init: true
     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.
+      PORT: "${options.containerPort}"
       DATABASE_URL: postgresql://postgres:postgres@postgres:5432/skein
       REDIS_URL: redis://redis:6379
     depends_on:
@@ -275,15 +409,15 @@ volumes:
 }
 
 // src/docker/dockerfile.ts
-import { existsSync as existsSync2 } from "fs";
-import path2 from "path";
+import { existsSync as existsSync3 } from "fs";
+import path4 from "path";
 function baseImage(nodeVersion) {
   const major = nodeVersion?.trim().match(/^\d+/)?.[0] ?? "20";
   return `node:${major}-slim`;
 }
 function detectPackageManager(projectDir) {
-  if (existsSync2(path2.join(projectDir, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync2(path2.join(projectDir, "yarn.lock"))) return "yarn";
+  if (existsSync3(path4.join(projectDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync3(path4.join(projectDir, "yarn.lock"))) return "yarn";
   return "npm";
 }
 function installSteps(manager) {
@@ -291,18 +425,18 @@ function installSteps(manager) {
     case "pnpm":
       return {
         copyLock: "COPY package.json pnpm-lock.yaml* ./",
-        install: "RUN corepack enable && pnpm install --frozen-lockfile"
+        install: "RUN --mount=type=cache,target=/root/.local/share/pnpm/store corepack enable && pnpm install --frozen-lockfile"
       };
     case "yarn":
       return {
         copyLock: "COPY package.json yarn.lock* ./",
-        install: "RUN corepack enable && yarn install --frozen-lockfile"
+        install: "RUN --mount=type=cache,target=/usr/local/share/.cache/yarn corepack enable && yarn install --frozen-lockfile"
       };
     case "npm":
       return {
         copyLock: "COPY package.json package-lock.json* ./",
         // `npm ci` needs a lockfile; fall back to `npm install` when there isn't one.
-        install: "RUN npm ci || npm install"
+        install: "RUN --mount=type=cache,target=/root/.npm npm ci || npm install"
       };
   }
 }
@@ -325,23 +459,37 @@ function generateDockerfile(options) {
   const { nodeVersion, dockerfileLines = [], port, packageManager } = options;
   const { copyLock, install } = installSteps(packageManager);
   const lines = [
+    // The syntax directive must be the first line to be honored — it enables the RUN cache mounts.
+    `# syntax=docker/dockerfile:1`,
     `# Generated by skein \u2014 do not edit by hand (regenerated by \`skein build\` / \`skein up\`).`,
     `FROM ${baseImage(nodeVersion)}`,
+    // Hand /app to the unprivileged 'node' user (uid 1000, shipped by the base image) so the server
+    // never runs as root. corepack/npm need root to install, so install as root, then chown the
+    // whole tree — including the root-created node_modules, where vite writes its cache at runtime.
     `WORKDIR /app`,
     ``,
-    `# Install dependencies first for better layer caching.`,
+    `# Install dependencies first for better layer caching (BuildKit cache mount speeds rebuilds).`,
     copyLock,
     install,
     ``,
     `# Copy the rest of the project (graphs, langgraph.json, source).`,
     `COPY . .`,
     ``,
+    `# Give the runtime user ownership of the app + installed node_modules so vite can write its`,
+    `# on-disk cache under node_modules/.vite without EACCES.`,
+    `RUN chown -R node:node /app`,
+    ``,
+    // Set NODE_ENV only after install so devDependencies (the vite/tsx toolchain `skein dev` loads
+    // graphs with) are installed; setting it before install would prune them and break graph loading.
     `ENV NODE_ENV=production`,
     `EXPOSE ${port}`,
+    `USER node`,
     ...dockerfileLines,
     ``,
     `# Serve the Agent Protocol against Postgres + Redis (DATABASE_URL / REDIS_URL from the environment).`,
-    `CMD ["npx", "skein", "dev", "--no-reload", "--no-persist", "--store", "postgres", "--queue", "redis", "--host", "0.0.0.0", "--port", "${port}"]`
+    `# 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", "dev", "--no-reload", "--no-persist", "--store", "postgres", "--queue", "redis", "--host", "0.0.0.0"]`
   ];
   return `${lines.join("\n")}
 `;
@@ -353,8 +501,11 @@ var DOCKERFILE_NAME = "Dockerfile";
 var COMPOSE_NAME = "compose.yaml";
 var DOCKERIGNORE_NAME = ".dockerignore";
 var GENERATED_MARKER = "# Generated by skein";
+function isSkeinGenerated(contents) {
+  return contents.split("\n", 3).some((line2) => line2.startsWith(GENERATED_MARKER));
+}
 async function loadConfigContext(configOption) {
-  const configPath = path3.resolve(process.cwd(), configOption);
+  const configPath = path5.resolve(process.cwd(), configOption);
   const { config, configDir } = await loadConfig2({ configPath });
   return { config, configDir };
 }
@@ -367,7 +518,7 @@ function renderDockerfile({ config, configDir }, port) {
   });
 }
 function defaultImageTag(configDir) {
-  const base = path3.basename(configDir).toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+  const base = path5.basename(configDir).toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
   const trimmed = base.replace(/^[-.]+|[-.]+$/g, "");
   return trimmed.length > 0 ? trimmed : "skein-app";
 }
@@ -401,8 +552,8 @@ function describeExit(result) {
   return result.signal !== null ? `killed by ${result.signal}` : `exit ${result.code}`;
 }
 function writeGeneratedFile(file, contents) {
-  const name = path3.basename(file);
-  if (existsSync3(file) && !readFileSync2(file, "utf8").startsWith(GENERATED_MARKER)) {
+  const name = path5.basename(file);
+  if (existsSync4(file) && !isSkeinGenerated(readFileSync3(file, "utf8"))) {
     console.log(`skein: ${name} exists and wasn't generated by skein \u2014 using it as-is.`);
     return "kept-user";
   }
@@ -414,7 +565,7 @@ async function runDockerfile(options) {
   const context = await loadConfigContext(options.config);
   const contents = renderDockerfile(context, CONTAINER_PORT);
   if (options.output !== void 0) {
-    const target = path3.resolve(process.cwd(), options.output);
+    const target = path5.resolve(process.cwd(), options.output);
     writeFileSync2(target, contents);
     console.log(`skein: wrote ${target}.`);
     return;
@@ -424,9 +575,9 @@ async function runDockerfile(options) {
 async function runBuild(options) {
   const context = await loadConfigContext(options.config);
   if (!requireDocker()) return;
-  const dockerfilePath = path3.join(context.configDir, DOCKERFILE_NAME);
+  const dockerfilePath = path5.join(context.configDir, DOCKERFILE_NAME);
   writeGeneratedFile(dockerfilePath, renderDockerfile(context, CONTAINER_PORT));
-  writeGeneratedFile(path3.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
+  writeGeneratedFile(path5.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
   const tag = options.tag ?? defaultImageTag(context.configDir);
   console.log(`skein: building image "${tag}"\u2026`);
   const result = await runToCompletion(
@@ -445,12 +596,12 @@ async function runUp(options) {
   const context = await loadConfigContext(options.config);
   if (!requireDocker()) return;
   writeGeneratedFile(
-    path3.join(context.configDir, DOCKERFILE_NAME),
+    path5.join(context.configDir, DOCKERFILE_NAME),
     renderDockerfile(context, CONTAINER_PORT)
   );
-  writeGeneratedFile(path3.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
+  writeGeneratedFile(path5.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
   writeGeneratedFile(
-    path3.join(context.configDir, COMPOSE_NAME),
+    path5.join(context.configDir, COMPOSE_NAME),
     generateCompose({ hostPort: options.port, host: options.host, containerPort: CONTAINER_PORT })
   );
   console.log(
@@ -467,6 +618,65 @@ async function runUp(options) {
   }
 }
 
+// src/import-command.ts
+import { existsSync as existsSync5 } from "fs";
+import path6 from "path";
+import { loadConfig as loadConfig3 } from "@skein-js/config";
+import {
+  describeSnapshot as describeSnapshot2,
+  loadSnapshotIntoStore,
+  readLanggraphDevState as readLanggraphDevState2
+} from "@skein-js/express";
+import { buildRuntime as buildRuntime2 } from "@skein-js/runtime";
+function summarize(counts) {
+  return `${counts.assistants} assistant(s), ${counts.threads} thread(s), ${counts.runs} run(s), ${counts.items} store item(s), checkpoint history for ${counts.checkpointedThreads} thread(s)`;
+}
+async function runImportLanggraph(options) {
+  const configPath = path6.resolve(process.cwd(), options.config);
+  const { config, configDir } = await loadConfig3({ configPath });
+  const sourceDir = options.from ? path6.resolve(process.cwd(), options.from) : path6.join(configDir, LANGGRAPH_DIR);
+  const snapshot = await readLanggraphDevState2(sourceDir);
+  if (snapshot === null) {
+    console.log(`skein: no LangGraph dev state found at ${sourceDir}; nothing to import.`);
+    return;
+  }
+  const counts = describeSnapshot2(snapshot);
+  if (options.store === "memory") {
+    const stateFile = devStateFile(configDir);
+    if (existsSync5(stateFile) && !options.force) {
+      console.error(
+        `skein: ${path6.relative(process.cwd(), stateFile)} already exists. Re-run with --force to overwrite it (or delete it first).`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    writeDevStateFile(stateFile, JSON.stringify(snapshot));
+    console.log(
+      `skein: imported ${summarize(counts)} \u2192 ${path6.relative(process.cwd(), stateFile)}.`
+    );
+    console.log("skein: run `skein dev` to use it.");
+    return;
+  }
+  await applyProjectEnv(config, configDir);
+  const loader = await createViteGraphLoader(configDir);
+  try {
+    const runtime = await buildRuntime2({
+      configPath,
+      importModule: loader.importModule,
+      store: "postgres",
+      queue: "memory"
+    });
+    try {
+      await loadSnapshotIntoStore(snapshot, runtime.deps.store, runtime.deps.checkpointer);
+    } finally {
+      await runtime.dispose();
+    }
+  } finally {
+    await loader.close();
+  }
+  console.log(`skein: imported ${summarize(counts)} into Postgres.`);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -490,10 +700,22 @@ 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("-v, --verbose", "Log per-run activity: start/finish, tool calls, and interrupts").action((options) => runDev(options));
+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("-v, --verbose", "Log per-run activity: start/finish, tool calls, and interrupts").action(
+  (options, command) => runDev({
+    ...options,
+    portExplicit: command.getOptionValueSource("port") === "cli",
+    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").action((options) => runUp(options));
 program.command("build").description("Build a deployable Docker image from the config.").option("-c, --config <path>", "Path to langgraph.json", "langgraph.json").option("-t, --tag <tag>", "Image tag (defaults to the project directory name)").action((options) => runBuild(options));
 program.command("dockerfile").description("Emit a standalone Dockerfile from the config.").option("-c, --config <path>", "Path to langgraph.json", "langgraph.json").option("-o, --output <path>", "Write the Dockerfile here instead of stdout").action((options) => runDockerfile(options));
+program.command("import-langgraph").description("Import an existing LangGraph in-memory dev state (.langgraph_api/) into skein.").option("-c, --config <path>", "Path to langgraph.json", "langgraph.json").option(
+  "--store <driver>",
+  "Import target: memory (.skein/dev-state.json) | postgres (DATABASE_URL)",
+  parseStore,
+  "memory"
+).option("--from <dir>", "Source .langgraph_api directory (defaults to alongside langgraph.json)").option("--force", "Overwrite an existing .skein/dev-state.json (memory target)", false).action((options) => runImportLanggraph(options));
 try {
   await program.parseAsync(process.argv);
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skein-js",
-  "version": "0.2.0",
+  "version": "0.3.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>",
@@ -48,10 +48,10 @@
     "@langchain/langgraph-checkpoint-postgres": "^1.0.4",
     "commander": "~13.1.0",
     "vite": "^8.1.0",
-    "@skein-js/core": "0.2.0",
-    "@skein-js/config": "0.2.0",
-    "@skein-js/express": "0.2.0",
-    "@skein-js/runtime": "0.2.0"
+    "@skein-js/core": "0.3.0",
+    "@skein-js/config": "0.3.0",
+    "@skein-js/express": "0.3.0",
+    "@skein-js/runtime": "0.3.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"