skein-js 0.2.1 → 0.4.0

package/README.md

@@ -67,8 +67,8 @@ All commands take `-c, --config <path>` (default `langgraph.json`).
 | ------------------ | -------------------- | ----------- | -------------------------------------------------------------- |
 | `-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).  |
+| `--store <driver>` | `memory`, `postgres` | `memory`    | `postgres` reads `POSTGRES_URI`; also selects `PostgresSaver`. |
+| `--queue <driver>` | `memory`, `redis`    | `memory`    | `redis` reads `REDIS_URI` (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).         |

package/dist/index.js

@@ -5,17 +5,143 @@ 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";
+import {
+  createServer,
+  createServerModuleRunner,
+  searchForWorkspaceRoot
+} from "vite";
 function findFreePort() {
   return new Promise((resolve, reject) => {
     const probe = createNetServer();
@@ -28,9 +154,14 @@ function findFreePort() {
   });
 }
 async function createViteGraphLoader(root, ignored = []) {
+  const workspaceRoot = searchForWorkspaceRoot(root);
   const server = await createServer({
     root,
     configFile: false,
+    // Resolve tsconfig `paths` natively (vite 8+): vite reads the project's tsconfig, follows
+    // `extends` to a base tsconfig (e.g. `tsconfig.base.json`), and honors `baseUrl` + wildcard
+    // aliases — so graphs that import workspace packages through path aliases resolve.
+    resolve: { tsconfigPaths: true },
     appType: "custom",
     logLevel: "warn",
     server: {
@@ -40,7 +171,10 @@ async function createViteGraphLoader(root, ignored = []) {
       // "port 24678 already in use" error — when two `skein dev`s run at once. Give it an ephemeral
       // port so instances never clash.
       hmr: { port: await findFreePort() },
-      watch: { ignored: ["**/node_modules/**", "**/.git/**", "**/dist/**", ...ignored] }
+      watch: { ignored: ["**/node_modules/**", "**/.git/**", "**/dist/**", ...ignored] },
+      // Aliased lib sources resolve outside the app `root` (e.g. `../../libs/**`). Widen vite's
+      // file-serving allowlist to the workspace root so the module runner can transform them.
+      fs: { allow: [workspaceRoot] }
     },
     optimizeDeps: { noDiscovery: true }
   });
@@ -60,39 +194,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 +218,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 +270,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 +334,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 +357,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,11 +373,17 @@ 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:
-      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/skein
-      REDIS_URL: redis://redis:6379
+      # 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}"
+      POSTGRES_URI: postgresql://postgres:postgres@postgres:5432/skein
+      REDIS_URI: redis://redis:6379
     depends_on:
       postgres:
         condition: service_healthy
@@ -275,15 +421,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 +437,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 +471,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}"]`
+    `# Serve the Agent Protocol against Postgres + Redis (POSTGRES_URI / REDIS_URI from the environment).`,
+    `# 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 +513,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 +530,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 +564,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 +577,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 +587,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 +608,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 +630,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 +712,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 (POSTGRES_URI)",
+  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.1",
+  "version": "0.4.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/config": "0.2.1",
-    "@skein-js/core": "0.2.1",
-    "@skein-js/express": "0.2.1",
-    "@skein-js/runtime": "0.2.1"
+    "@skein-js/core": "0.4.0",
+    "@skein-js/express": "0.4.0",
+    "@skein-js/config": "0.4.0",
+    "@skein-js/runtime": "0.4.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"