skein-js 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,82 @@
+# skein-js
+
+> The skein-js 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.
+
+**Status:** 🚧 Pre-alpha — `dev`, `up`, `build`, and `dockerfile` all work today.
+
+## Why skein-js
+
+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.
+
+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
+
+```bash
+pnpm add skein-js
+```
+
+## Usage
+
+Swap it into your `package.json` scripts (`"dev": "skein dev"`, `"up": "skein up"`) — your
+`langgraph.json` is unchanged.
+
+```bash
+npx skein dev --port 2024
+```
+
+### Commands
+
+| 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` |
+| `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>`                                                                                                              |
+
+All commands take `-c, --config <path>` (default `langgraph.json`).
+
+`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`.
+
+## Learn more
+
+- [skein-js overview](../../docs/index.md)
+- [Reuse-first architecture](../../docs/reuse.md)
+- [Roadmap](../../docs/roadmap.md)
+
+## License
+
+[Apache-2.0](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+
+// src/index.ts
+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 {
+  createExpressServer
+} from "@skein-js/express";
+import { buildRuntime } from "@skein-js/runtime";
+
+// src/vite-graph-loader.ts
+import { createServer as createNetServer } from "net";
+import { createServer, createServerModuleRunner } from "vite";
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const probe = createNetServer();
+    probe.on("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+      const address = probe.address();
+      const port = address !== null && typeof address !== "string" ? address.port : 0;
+      probe.close(() => resolve(port));
+    });
+  });
+}
+async function createViteGraphLoader(root, ignored = []) {
+  const server = await createServer({
+    root,
+    configFile: false,
+    appType: "custom",
+    logLevel: "warn",
+    server: {
+      middlewareMode: true,
+      // We drive reloads manually, so vite's HMR WebSocket server is unused. In middleware mode vite
+      // binds it anyway (ignoring `hmr: false`) on a fixed default port, which collides — with a red
+      // "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] }
+    },
+    optimizeDeps: { noDiscovery: true }
+  });
+  const runner = createServerModuleRunner(server.environments.ssr, { hmr: false });
+  return {
+    importModule: (sourceFile) => runner.import(sourceFile),
+    watcher: server.watcher,
+    clearCache: () => runner.clearCache(),
+    close: async () => {
+      await runner.close();
+      await server.close();
+    }
+  };
+}
+
+// src/dev-command.ts
+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;
+  }
+}
+function readConventionalDotEnv(dir) {
+  const envPath = path.join(dir, ".env");
+  if (!existsSync(envPath)) return {};
+  try {
+    return parseEnvFile(readFileSync(envPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function runDev(options) {
+  const configPath = path.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);
+  const loader = await createViteGraphLoader(configDir, [`${STATE_DIR}/**`, `**/${STATE_DIR}/**`]);
+  const runtime = await buildRuntime({
+    configPath,
+    importModule: loader.importModule,
+    store: options.store,
+    queue: options.queue
+  });
+  const { port, host } = options;
+  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)) {
+    try {
+      runtime.hydrateState?.(JSON.parse(readFileSync(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)}`
+      );
+    }
+  }
+  if (options.verbose) runtime.deps.logRunActivity = true;
+  let server;
+  try {
+    server = await createExpressServer({
+      deps: runtime.deps,
+      cors: runtime.cors,
+      warm: true,
+      logger: devLogger
+    });
+    await server.listen(port, host);
+  } catch (error) {
+    await Promise.allSettled([loader.close(), runtime.dispose()]);
+    const code = error.code;
+    console.error(
+      code === "EADDRINUSE" ? `skein: port ${port} is already in use. Stop the other process or pass --port.` : `skein: failed to start dev server: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`skein-js listening on http://${host}:${port}`);
+  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);
+      lastSaved = serialized;
+    } catch (error) {
+      console.warn(
+        `skein: could not persist dev state: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  };
+  let autosave;
+  if (canPersist) {
+    autosave = setInterval(saveState, AUTOSAVE_MS);
+    autosave.unref();
+  }
+  if (options.reload) {
+    let reloading = false;
+    let dirty = false;
+    let pending;
+    const reload = async () => {
+      if (reloading) {
+        dirty = true;
+        return;
+      }
+      reloading = true;
+      try {
+        console.log("skein: change detected, reloading\u2026");
+        loader.clearCache();
+        await runtime.reloadGraphs();
+        await Promise.all(
+          runtime.deps.graphs.ids.map(
+            (id) => runtime.deps.graphs.load(id).catch((error) => {
+              console.error(`skein: graph "${id}" failed to load: ${String(error)}`);
+            })
+          )
+        );
+        console.log("skein: reloaded.");
+      } catch (error) {
+        console.error(
+          `skein: reload failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      } finally {
+        reloading = false;
+        if (dirty) {
+          dirty = false;
+          void reload();
+        }
+      }
+    };
+    loader.watcher.on("change", (file) => {
+      if (`${path.resolve(file)}${path.sep}`.startsWith(`${stateDir}${path.sep}`)) return;
+      if (pending) clearTimeout(pending);
+      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)
+    );
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+// 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 { loadConfig as loadConfig2 } from "@skein-js/config";
+
+// src/docker/compose.ts
+function portMapping(options) {
+  const { hostPort, host, containerPort } = options;
+  const bindsAllInterfaces = host === void 0 || host === "0.0.0.0" || host === "::";
+  return bindsAllInterfaces ? `"${hostPort}:${containerPort}"` : `"${host}:${hostPort}:${containerPort}"`;
+}
+function generateCompose(options) {
+  const ports = portMapping(options);
+  return `# Generated by skein \u2014 regenerated by \`skein up\`. Edit with care.
+services:
+  app:
+    build: .
+    ports:
+      - ${ports}
+    environment:
+      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/skein
+      REDIS_URL: redis://redis:6379
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+
+  postgres:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: skein
+    volumes:
+      - skein-pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d skein"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  redis:
+    image: redis:7
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+volumes:
+  skein-pgdata:
+`;
+}
+
+// src/docker/dockerfile.ts
+import { existsSync as existsSync2 } from "fs";
+import path2 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";
+  return "npm";
+}
+function installSteps(manager) {
+  switch (manager) {
+    case "pnpm":
+      return {
+        copyLock: "COPY package.json pnpm-lock.yaml* ./",
+        install: "RUN corepack enable && pnpm install --frozen-lockfile"
+      };
+    case "yarn":
+      return {
+        copyLock: "COPY package.json yarn.lock* ./",
+        install: "RUN 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"
+      };
+  }
+}
+function generateDockerignore() {
+  return [
+    "# Generated by skein \u2014 regenerated by `skein build` / `skein up`.",
+    ".git",
+    "node_modules",
+    ".env",
+    ".env.*",
+    ".skein",
+    "Dockerfile",
+    "compose.yaml",
+    ".dockerignore",
+    "npm-debug.log*",
+    ""
+  ].join("\n");
+}
+function generateDockerfile(options) {
+  const { nodeVersion, dockerfileLines = [], port, packageManager } = options;
+  const { copyLock, install } = installSteps(packageManager);
+  const lines = [
+    `# Generated by skein \u2014 do not edit by hand (regenerated by \`skein build\` / \`skein up\`).`,
+    `FROM ${baseImage(nodeVersion)}`,
+    `WORKDIR /app`,
+    ``,
+    `# Install dependencies first for better layer caching.`,
+    copyLock,
+    install,
+    ``,
+    `# Copy the rest of the project (graphs, langgraph.json, source).`,
+    `COPY . .`,
+    ``,
+    `ENV NODE_ENV=production`,
+    `EXPOSE ${port}`,
+    ...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}"]`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+
+// src/docker/commands.ts
+var CONTAINER_PORT = 8123;
+var DOCKERFILE_NAME = "Dockerfile";
+var COMPOSE_NAME = "compose.yaml";
+var DOCKERIGNORE_NAME = ".dockerignore";
+var GENERATED_MARKER = "# Generated by skein";
+async function loadConfigContext(configOption) {
+  const configPath = path3.resolve(process.cwd(), configOption);
+  const { config, configDir } = await loadConfig2({ configPath });
+  return { config, configDir };
+}
+function renderDockerfile({ config, configDir }, port) {
+  return generateDockerfile({
+    nodeVersion: config.node_version,
+    dockerfileLines: config.dockerfile_lines,
+    port,
+    packageManager: detectPackageManager(configDir)
+  });
+}
+function defaultImageTag(configDir) {
+  const base = path3.basename(configDir).toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+  const trimmed = base.replace(/^[-.]+|[-.]+$/g, "");
+  return trimmed.length > 0 ? trimmed : "skein-app";
+}
+function dockerAvailable() {
+  const probe = spawnSync("docker", ["--version"], { stdio: "ignore" });
+  return probe.status === 0;
+}
+function requireDocker() {
+  if (dockerAvailable()) return true;
+  console.error("skein: the `docker` CLI was not found on PATH. Install Docker and try again.");
+  process.exitCode = 1;
+  return false;
+}
+function runToCompletion(command, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit" });
+    child.on("error", (error) => {
+      console.error(`skein: failed to run \`${command}\`: ${error.message}`);
+      resolve({ code: null, signal: null });
+    });
+    child.on("exit", (code, signal) => resolve({ code, signal }));
+  });
+}
+function succeeded(result) {
+  return result.code === 0 && result.signal === null;
+}
+function wasInterrupted(result) {
+  return result.code === 130 || result.signal === "SIGINT" || result.signal === "SIGTERM";
+}
+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)) {
+    console.log(`skein: ${name} exists and wasn't generated by skein \u2014 using it as-is.`);
+    return "kept-user";
+  }
+  writeFileSync2(file, contents);
+  console.log(`skein: wrote ${name}.`);
+  return "wrote";
+}
+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);
+    writeFileSync2(target, contents);
+    console.log(`skein: wrote ${target}.`);
+    return;
+  }
+  process.stdout.write(contents);
+}
+async function runBuild(options) {
+  const context = await loadConfigContext(options.config);
+  if (!requireDocker()) return;
+  const dockerfilePath = path3.join(context.configDir, DOCKERFILE_NAME);
+  writeGeneratedFile(dockerfilePath, renderDockerfile(context, CONTAINER_PORT));
+  writeGeneratedFile(path3.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
+  const tag = options.tag ?? defaultImageTag(context.configDir);
+  console.log(`skein: building image "${tag}"\u2026`);
+  const result = await runToCompletion(
+    "docker",
+    ["build", "-t", tag, "-f", dockerfilePath, "."],
+    context.configDir
+  );
+  if (!succeeded(result)) {
+    console.error(`skein: docker build failed (${describeExit(result)}).`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`skein: built image "${tag}".`);
+}
+async function runUp(options) {
+  const context = await loadConfigContext(options.config);
+  if (!requireDocker()) return;
+  writeGeneratedFile(
+    path3.join(context.configDir, DOCKERFILE_NAME),
+    renderDockerfile(context, CONTAINER_PORT)
+  );
+  writeGeneratedFile(path3.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
+  writeGeneratedFile(
+    path3.join(context.configDir, COMPOSE_NAME),
+    generateCompose({ hostPort: options.port, host: options.host, containerPort: CONTAINER_PORT })
+  );
+  console.log(
+    `skein: bringing up the stack (app + Postgres + Redis) on http://${options.host}:${options.port}\u2026`
+  );
+  const result = await runToCompletion(
+    "docker",
+    ["compose", "-f", COMPOSE_NAME, "up", "--build"],
+    context.configDir
+  );
+  if (!succeeded(result) && !wasInterrupted(result)) {
+    console.error(`skein: docker compose up failed (${describeExit(result)}).`);
+    process.exitCode = 1;
+  }
+}
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new InvalidArgumentError("Port must be an integer between 0 and 65535.");
+  }
+  return port;
+}
+function parseChoice(choices) {
+  return (value) => {
+    if (!choices.includes(value)) {
+      throw new InvalidArgumentError(`Must be one of: ${choices.join(", ")}.`);
+    }
+    return value;
+  };
+}
+var parseStore = parseChoice(["memory", "postgres"]);
+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("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));
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  program.error(error instanceof Error ? error.message : String(error));
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "skein-js",
+  "version": "0.1.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>",
+  "homepage": "https://github.com/mainawycliffe/skein/tree/main/packages/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mainawycliffe/skein.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/mainawycliffe/skein/issues"
+  },
+  "keywords": [
+    "langgraph",
+    "cli",
+    "agent-protocol",
+    "langgraph-cli",
+    "self-hosted"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "skein": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "~13.1.0",
+    "@langchain/langgraph-checkpoint-postgres": "^1.0.4",
+    "commander": "~13.1.0",
+    "vite": "^8.1.0",
+    "@skein-js/config": "0.1.0",
+    "@skein-js/express": "0.1.0",
+    "@skein-js/core": "0.1.0",
+    "@skein-js/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "@langchain/langgraph": "^1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}