skein-js 0.4.0 → 0.6.3

package/README.md

@@ -52,15 +52,19 @@ LangGraph Studio — any Agent Protocol client works with only a URL change. See
 
 ## Commands
 
-| Command            | What it does                                                   | LangGraph CLI equivalent | Key flags                                      |
-| ------------------ | -------------------------------------------------------------- | ------------------------ | ---------------------------------------------- |
-| `skein dev`        | In-process dev server, hot reload, `.skein/` state, no Docker. | `langgraph dev`          | see [`skein dev` flags](#skein-dev-flags)      |
-| `skein up`         | Self-hosted stack via Docker Compose (app + Postgres + Redis). | `langgraph up`           | `-p, --port` (8123) · `--host` (0.0.0.0)       |
-| `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>`                          |
+| Command            | What it does                                                   | LangGraph CLI equivalent | Key flags                                                             |
+| ------------------ | -------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
+| `skein dev`        | In-process dev server, hot reload, `.skein/` state, no Docker. | `langgraph dev`          | see [`skein dev` flags](#skein-dev-flags)                             |
+| `skein up`         | Self-hosted stack via Docker Compose (app + Postgres + Redis). | `langgraph up`           | `-p, --port` (8123) · `--host` (0.0.0.0) · `-n, --npmrc <path>`       |
+| `skein build`      | Build a deployable Docker image from the config.               | `langgraph build`        | `-t, --tag` (defaults to the project dir name) · `-n, --npmrc <path>` |
+| `skein dockerfile` | Emit a standalone Dockerfile (stdout by default).              | `langgraph dockerfile`   | `-o, --output <path>`                                                 |
 
 All commands take `-c, --config <path>` (default `langgraph.json`).
 
+`--npmrc <path>` (on `build`/`up`) mounts an `.npmrc` as a BuildKit secret so the image's dependency
+install can authenticate against a **private/authenticated npm registry** without baking a token into
+any layer. Public-registry builds don't need it.
+
 ## `skein dev` flags
 
 | Flag               | Values               | Default     | Notes                                                          |

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { createRequire } from "module";
+import { createRequire as createRequire3 } from "module";
 import { Command, InvalidArgumentError } from "@commander-js/extra-typings";
 
 // src/dev-command.ts
@@ -26,7 +26,7 @@ var bold = paint(1);
 var dim = paint(2);
 
 // src/banner.ts
-function printBanner(info, logger) {
+function printBanner(info, logger2) {
   const { host, port, graphIds, authPath, workerCount } = info;
   const base = `http://${host}:${port}`;
   console.log();
@@ -35,10 +35,10 @@ function printBanner(info, logger) {
   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}`);
+  for (const id of graphIds) logger2.info(`Registering graph with id '${id}'`);
+  if (authPath) logger2.info(`Loading auth from ${authPath}`);
+  logger2.info(`Starting ${workerCount} worker${workerCount === 1 ? "" : "s"}`);
+  logger2.info(`Server running at ${base}`);
 }
 
 // src/dev-logger.ts
@@ -135,13 +135,27 @@ async function applyProjectEnv(config, configDir) {
   }
 }
 
+// src/serve-env.ts
+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 envHost(fallback) {
+  const host = process.env.HOST;
+  return host !== void 0 && host.trim() !== "" ? host : fallback;
+}
+function describeBindError(error, port) {
+  const code = error.code;
+  if (code === "EADDRINUSE") {
+    return `port ${port} is already in use. Stop the other process or pass --port.`;
+  }
+  return `failed to start server: ${error instanceof Error ? error.message : String(error)}`;
+}
+
 // src/vite-graph-loader.ts
 import { createServer as createNetServer } from "net";
-import {
-  createServer,
-  createServerModuleRunner,
-  searchForWorkspaceRoot
-} from "vite";
 function findFreePort() {
   return new Promise((resolve, reject) => {
     const probe = createNetServer();
@@ -154,6 +168,7 @@ function findFreePort() {
   });
 }
 async function createViteGraphLoader(root, ignored = []) {
+  const { createServer, createServerModuleRunner, searchForWorkspaceRoot } = await import("vite");
   const workspaceRoot = searchForWorkspaceRoot(root);
   const server = await createServer({
     root,
@@ -195,16 +210,6 @@ var RELOAD_DEBOUNCE_MS = 120;
 var AUTOSAVE_MS = 2e3;
 var FORCE_EXIT_MS = 5e3;
 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 envHost(fallback) {
-  const host = process.env.HOST;
-  return host !== void 0 && host.trim() !== "" ? host : fallback;
-}
 async function runDev(options) {
   const configPath = path3.resolve(process.cwd(), options.config);
   const { config, configDir } = await loadConfig({ configPath });
@@ -263,10 +268,7 @@ async function runDev(options) {
     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)}`
-    );
+    console.error(`skein: ${describeBindError(error, port)}`);
     process.exitCode = 1;
     return;
   }
@@ -357,9 +359,206 @@ async function runDev(options) {
 
 // src/docker/commands.ts
 import { spawn, spawnSync } from "child_process";
-import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync4, writeFileSync as writeFileSync2 } from "fs";
+import { createRequire as createRequire2 } from "module";
 import path5 from "path";
-import { loadConfig as loadConfig2 } from "@skein-js/config";
+import { loadConfig as loadConfig3 } from "@skein-js/config";
+
+// src/bundle/bundle-project.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import { createRequire, isBuiltin } from "module";
+import path4 from "path";
+import { loadConfig as loadConfig2, parseGraphSpec } from "@skein-js/config";
+import { embedRuntimePackage, isCustomFunctionPath } from "@skein-js/runtime";
+
+// src/bundle/precompute-schemas.ts
+async function precomputeSchemas(graphs) {
+  const entries = await Promise.all(
+    graphs.ids.map(async (id) => [id, await graphs.schemas(id)])
+  );
+  return Object.fromEntries(entries);
+}
+
+// src/bundle/write-manifest.ts
+function buildProductionConfig(source, rewrites) {
+  const config = structuredClone(source);
+  config.graphs = { ...rewrites.graphs };
+  if (rewrites.auth && config.auth) {
+    config.auth = { ...config.auth, path: rewrites.auth };
+  }
+  if (rewrites.embed && config.store?.index) {
+    config.store = {
+      ...config.store,
+      index: { ...config.store.index, embed: rewrites.embed }
+    };
+  }
+  if (typeof config.env === "string") delete config.env;
+  return config;
+}
+function buildArtifactPackageJson(appName, dependencies) {
+  const sorted = Object.fromEntries(
+    Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b))
+  );
+  const pkg = {
+    name: `${appName}-skein-artifact`,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    dependencies: sorted
+  };
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
+
+// src/bundle/bundle-project.ts
+var SKEIN_RUNTIME_PEERS = ["@langchain/langgraph", "@langchain/langgraph-checkpoint-postgres"];
+function packageNameOf(specifier) {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0] ?? specifier;
+}
+function safeName(graphId) {
+  return graphId.replace(/[^A-Za-z0-9._-]+/g, "-");
+}
+function uniqueSafeName(graphId, used) {
+  const base = safeName(graphId);
+  let candidate = base;
+  let suffix = 2;
+  while (used.has(candidate)) candidate = `${base}-${suffix++}`;
+  used.add(candidate);
+  return candidate;
+}
+function nodeMajor(nodeVersion) {
+  return nodeVersion?.trim().match(/\d+/)?.[0] ?? "20";
+}
+function readVersion(pkgJsonPath) {
+  try {
+    const parsed = JSON.parse(readFileSync3(pkgJsonPath, "utf8"));
+    return parsed.version;
+  } catch {
+    return void 0;
+  }
+}
+function resolveInstalledVersion(pkg, fromDir) {
+  const require3 = createRequire(path4.join(fromDir, "__skein_resolver__.js"));
+  try {
+    const version2 = readVersion(require3.resolve(`${pkg}/package.json`));
+    if (version2) return version2;
+  } catch {
+  }
+  try {
+    let dir = path4.dirname(require3.resolve(pkg));
+    while (dir !== path4.dirname(dir)) {
+      const pkgJson = path4.join(dir, "package.json");
+      if (existsSync3(pkgJson)) {
+        const parsed = JSON.parse(readFileSync3(pkgJson, "utf8"));
+        if (parsed.name === pkg && parsed.version) return parsed.version;
+      }
+      dir = path4.dirname(dir);
+    }
+  } catch {
+  }
+  throw new Error(
+    `skein build: could not resolve an installed version of "${pkg}". Install it in your project (it is imported by a graph/auth/embed module and must ship in the production image).`
+  );
+}
+function externalizeNodeModules(externals) {
+  return {
+    name: "skein-externalize-node-modules",
+    enforce: "post",
+    async resolveId(source, importer, options) {
+      if (source.startsWith("\0") || source.startsWith("/") || source.startsWith(".")) return null;
+      if (isBuiltin(source) || source.startsWith("node:")) return { id: source, external: true };
+      const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
+      if (!resolved || resolved.id.includes("node_modules")) {
+        externals.add(packageNameOf(source));
+        return { id: source, external: true };
+      }
+      return resolved;
+    }
+  };
+}
+async function bundleProject(options) {
+  const { configPath, outDir, nodeVersion, skeinVersion } = options;
+  const { build, searchForWorkspaceRoot } = await import("vite");
+  const { config, configDir, graphs } = await loadConfig2({ configPath });
+  const workspaceRoot = searchForWorkspaceRoot(configDir);
+  const input = {};
+  const rewrites = { graphs: {} };
+  const usedGraphNames = /* @__PURE__ */ new Set();
+  for (const graphId of graphs.ids) {
+    const spec = graphs.spec(graphId);
+    const entryKey = `graphs/${uniqueSafeName(graphId, usedGraphNames)}`;
+    input[entryKey] = spec.sourceFile;
+    rewrites.graphs[graphId] = `./${entryKey}.js:${spec.exportSymbol}`;
+  }
+  if (config.auth?.path) {
+    const spec = parseGraphSpec(config.auth.path, configDir);
+    input["auth"] = spec.sourceFile;
+    rewrites.auth = `./auth.js:${spec.exportSymbol}`;
+  }
+  if (config.store?.index?.embed && isCustomFunctionPath(config.store.index.embed)) {
+    const spec = parseGraphSpec(config.store.index.embed, configDir);
+    input["embed"] = spec.sourceFile;
+    rewrites.embed = `./embed.js:${spec.exportSymbol}`;
+  }
+  const externals = /* @__PURE__ */ new Set();
+  const [, schemas] = await Promise.all([
+    build({
+      root: workspaceRoot,
+      configFile: false,
+      logLevel: "warn",
+      resolve: { tsconfigPaths: true },
+      plugins: [externalizeNodeModules(externals)],
+      build: {
+        ssr: true,
+        outDir,
+        emptyOutDir: true,
+        target: `node${nodeMajor(nodeVersion)}`,
+        minify: true,
+        sourcemap: true,
+        rollupOptions: {
+          input,
+          output: {
+            format: "es",
+            entryFileNames: "[name].js",
+            chunkFileNames: "chunks/[name]-[hash].js"
+          }
+        }
+      }
+    }),
+    precomputeSchemas(graphs)
+  ]);
+  const dependencies = {};
+  for (const pkg of externals) dependencies[pkg] = resolveInstalledVersion(pkg, workspaceRoot);
+  dependencies["skein-js"] = skeinVersion;
+  for (const peer of SKEIN_RUNTIME_PEERS) {
+    dependencies[peer] = resolveInstalledVersion(peer, workspaceRoot);
+  }
+  const embedPkg = config.store?.index?.embed && embedRuntimePackage(config.store.index.embed);
+  if (embedPkg) dependencies[embedPkg] = resolveInstalledVersion(embedPkg, workspaceRoot);
+  for (const dep of config.dependencies ?? []) {
+    if (dep.startsWith(".") || dep.startsWith("/")) continue;
+    const pkg = packageNameOf(dep);
+    dependencies[pkg] = resolveInstalledVersion(pkg, workspaceRoot);
+  }
+  await mkdir(outDir, { recursive: true });
+  const productionConfig = buildProductionConfig(config, rewrites);
+  await Promise.all([
+    writeFile(
+      path4.join(outDir, "langgraph.json"),
+      `${JSON.stringify(productionConfig, null, 2)}
+`
+    ),
+    writeFile(path4.join(outDir, "schemas.json"), `${JSON.stringify(schemas, null, 2)}
+`),
+    writeFile(
+      path4.join(outDir, "package.json"),
+      buildArtifactPackageJson(path4.basename(configDir), dependencies)
+    )
+  ]);
+  return { outDir, graphIds: graphs.ids, externals: dependencies };
+}
 
 // src/docker/compose.ts
 function portMapping(options) {
@@ -369,10 +568,19 @@ function portMapping(options) {
 }
 function generateCompose(options) {
   const ports = portMapping(options);
+  const appBuild = options.npmrcPath ? `build:
+      context: .
+      secrets:
+        - npmrc` : `build: .`;
+  const secretsBlock = options.npmrcPath ? `
+secrets:
+  npmrc:
+    file: ${JSON.stringify(options.npmrcPath)}
+` : "";
   return `# Generated by skein \u2014 regenerated by \`skein up\`. Edit with care.
 services:
   app:
-    build: .
+    ${appBuild}
     # 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
@@ -417,41 +625,14 @@ services:
 
 volumes:
   skein-pgdata:
-`;
+${secretsBlock}`;
 }
 
 // src/docker/dockerfile.ts
-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 (existsSync3(path4.join(projectDir, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync3(path4.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 --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 --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 --mount=type=cache,target=/root/.npm npm ci || npm install"
-      };
-  }
-}
 function generateDockerignore() {
   return [
     "# Generated by skein \u2014 regenerated by `skein build` / `skein up`.",
@@ -459,7 +640,9 @@ function generateDockerignore() {
     "node_modules",
     ".env",
     ".env.*",
-    ".skein",
+    // Never bake a registry credential into a layer — it's supplied via a BuildKit secret at install.
+    ".npmrc",
+    ".npmrc.*",
     "Dockerfile",
     "compose.yaml",
     ".dockerignore",
@@ -468,65 +651,88 @@ function generateDockerignore() {
   ].join("\n");
 }
 function generateDockerfile(options) {
-  const { nodeVersion, dockerfileLines = [], port, packageManager } = options;
-  const { copyLock, install } = installSteps(packageManager);
+  const { nodeVersion, dockerfileLines = [], port } = options;
   const lines = [
-    // The syntax directive must be the first line to be honored — it enables the RUN cache mounts.
+    // The syntax directive must be the first line to be honored — it enables the RUN cache mount.
     `# syntax=docker/dockerfile:1`,
     `# Generated by skein \u2014 do not edit by hand (regenerated by \`skein build\` / \`skein up\`).`,
+    // The build context must be a skein artifact dir (bundled JS + pinned package.json + schemas.json),
+    // which `skein build`/`up` create under `.skein/build`. Building this Dockerfile against a raw
+    // project dir will fail — run `skein build` instead of `docker build` by hand.
+    `# Build context: a \`.skein/build\` artifact produced by \`skein build\` (not the project root).`,
     `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 (BuildKit cache mount speeds rebuilds).`,
-    copyLock,
-    install,
+    // Install prod deps first for layer caching: the artifact's pinned package.json changes rarely,
+    // so this layer is reused across rebuilds while only the bundle layer below re-runs. The BuildKit
+    // cache mount keeps the npm cache out of the committed layer. The `npmrc` secret mount lets private
+    // scoped deps authenticate against a private/authenticated registry without baking a token into any
+    // layer; it is optional (BuildKit secrets are not required by default), so a public-registry build
+    // that passes no secret is unaffected. Supply it via `skein build --npmrc <path>` or, for the
+    // standalone Dockerfile, `docker build --secret id=npmrc,src=<path>`.
+    `# Install the artifact's pinned production dependencies (exact versions \u2014 deterministic).`,
+    `COPY package.json ./`,
+    `RUN --mount=type=cache,target=/root/.npm \\`,
+    `    --mount=type=secret,id=npmrc,target=/app/.npmrc \\`,
+    `    npm install --omit=dev --omit=optional --no-audit --no-fund`,
     ``,
-    `# Copy the rest of the project (graphs, langgraph.json, source).`,
+    `# Copy the pre-built artifact (bundled JS graphs, production langgraph.json, baked schemas).`,
     `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`,
+    // The bundle ships sourcemaps; enable them so stack traces map back to the original TypeScript.
+    `ENV NODE_OPTIONS=--enable-source-maps`,
     `EXPOSE ${port}`,
+    // Liveness probe against skein's `/ok` endpoint, targeting the same port the server binds.
+    `HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \\`,
+    `    CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||${port})+'/ok').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"`,
+    // Run unprivileged. The bundle writes nothing to disk, and /app is world-readable, so no chown.
     `USER node`,
     ...dockerfileLines,
     ``,
-    `# Serve the Agent Protocol against Postgres + Redis (POSTGRES_URI / REDIS_URI from the environment).`,
+    `# Serve the compiled artifact against Postgres + Redis (POSTGRES_URI / REDIS_URI from the env).`,
     `# No --port: the server binds $PORT when the platform injects one (Railway/Fly/Render), else its`,
     `# default. Exec form keeps node as PID 1 so SIGTERM reaches skein's graceful-shutdown handler.`,
-    `CMD ["npx", "skein", "dev", "--no-reload", "--no-persist", "--store", "postgres", "--queue", "redis", "--host", "0.0.0.0"]`
+    `CMD ["npx", "skein", "start", "--store", "postgres", "--queue", "redis", "--host", "0.0.0.0"]`
   ];
   return `${lines.join("\n")}
 `;
 }
 
 // src/docker/commands.ts
+function skeinCliVersion() {
+  return createRequire2(import.meta.url)("../package.json").version;
+}
+var ARTIFACT_SUBDIR = path5.join(".skein", "build");
 var CONTAINER_PORT = 8123;
 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 = path5.resolve(process.cwd(), configOption);
-  const { config, configDir } = await loadConfig2({ configPath });
-  return { config, configDir };
+  const { config, configDir } = await loadConfig3({ configPath });
+  return { config, configDir, configPath };
+}
+async function prepareArtifact(context, extraAssets = []) {
+  const outDir = path5.join(context.configDir, ARTIFACT_SUBDIR);
+  console.log("skein: bundling graphs into a production artifact\u2026");
+  await bundleProject({
+    configPath: context.configPath,
+    outDir,
+    nodeVersion: context.config.node_version,
+    skeinVersion: skeinCliVersion()
+  });
+  writeFileSync2(path5.join(outDir, DOCKERFILE_NAME), renderDockerfile(context, CONTAINER_PORT));
+  writeFileSync2(path5.join(outDir, DOCKERIGNORE_NAME), generateDockerignore());
+  for (const asset of extraAssets) writeFileSync2(path5.join(outDir, asset.name), asset.contents);
+  console.log(`skein: wrote artifact to ${path5.relative(process.cwd(), outDir) || "."}.`);
+  return outDir;
 }
-function renderDockerfile({ config, configDir }, port) {
+function renderDockerfile({ config }, port) {
   return generateDockerfile({
     nodeVersion: config.node_version,
     dockerfileLines: config.dockerfile_lines,
-    port,
-    packageManager: detectPackageManager(configDir)
+    port
   });
 }
 function defaultImageTag(configDir) {
@@ -534,6 +740,16 @@ function defaultImageTag(configDir) {
   const trimmed = base.replace(/^[-.]+|[-.]+$/g, "");
   return trimmed.length > 0 ? trimmed : "skein-app";
 }
+function resolveNpmrcSecret(npmrc) {
+  if (npmrc === void 0) return void 0;
+  const resolved = path5.resolve(process.cwd(), npmrc);
+  if (!existsSync4(resolved)) {
+    console.error(`skein: --npmrc file not found: ${resolved}`);
+    process.exitCode = 1;
+    return null;
+  }
+  return resolved;
+}
 function dockerAvailable() {
   const probe = spawnSync("docker", ["--version"], { stdio: "ignore" });
   return probe.status === 0;
@@ -563,19 +779,12 @@ function wasInterrupted(result) {
 function describeExit(result) {
   return result.signal !== null ? `killed by ${result.signal}` : `exit ${result.code}`;
 }
-function writeGeneratedFile(file, contents) {
-  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";
-  }
-  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);
+  console.error(
+    "skein: this Dockerfile builds against a `.skein/build` artifact (run `skein build`), not the project root."
+  );
   if (options.output !== void 0) {
     const target = path5.resolve(process.cwd(), options.output);
     writeFileSync2(target, contents);
@@ -586,16 +795,24 @@ async function runDockerfile(options) {
 }
 async function runBuild(options) {
   const context = await loadConfigContext(options.config);
+  const npmrcPath = resolveNpmrcSecret(options.npmrc);
+  if (npmrcPath === null) return;
   if (!requireDocker()) return;
-  const dockerfilePath = path5.join(context.configDir, DOCKERFILE_NAME);
-  writeGeneratedFile(dockerfilePath, renderDockerfile(context, CONTAINER_PORT));
-  writeGeneratedFile(path5.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
+  let artifactDir;
+  try {
+    artifactDir = await prepareArtifact(context);
+  } catch (error) {
+    console.error(`skein: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+    return;
+  }
   const tag = options.tag ?? defaultImageTag(context.configDir);
+  const secretArgs = npmrcPath !== void 0 ? ["--secret", `id=npmrc,src=${npmrcPath}`] : [];
   console.log(`skein: building image "${tag}"\u2026`);
   const result = await runToCompletion(
     "docker",
-    ["build", "-t", tag, "-f", dockerfilePath, "."],
-    context.configDir
+    ["build", "-t", tag, "-f", path5.join(artifactDir, DOCKERFILE_NAME), ...secretArgs, "."],
+    artifactDir
   );
   if (!succeeded(result)) {
     console.error(`skein: docker build failed (${describeExit(result)}).`);
@@ -606,23 +823,34 @@ async function runBuild(options) {
 }
 async function runUp(options) {
   const context = await loadConfigContext(options.config);
+  const npmrcPath = resolveNpmrcSecret(options.npmrc);
+  if (npmrcPath === null) return;
   if (!requireDocker()) return;
-  writeGeneratedFile(
-    path5.join(context.configDir, DOCKERFILE_NAME),
-    renderDockerfile(context, CONTAINER_PORT)
-  );
-  writeGeneratedFile(path5.join(context.configDir, DOCKERIGNORE_NAME), generateDockerignore());
-  writeGeneratedFile(
-    path5.join(context.configDir, COMPOSE_NAME),
-    generateCompose({ hostPort: options.port, host: options.host, containerPort: CONTAINER_PORT })
-  );
+  let artifactDir;
+  try {
+    artifactDir = await prepareArtifact(context, [
+      {
+        name: COMPOSE_NAME,
+        contents: generateCompose({
+          hostPort: options.port,
+          host: options.host,
+          containerPort: CONTAINER_PORT,
+          npmrcPath
+        })
+      }
+    ]);
+  } catch (error) {
+    console.error(`skein: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+    return;
+  }
   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
+    artifactDir
   );
   if (!succeeded(result) && !wasInterrupted(result)) {
     console.error(`skein: docker compose up failed (${describeExit(result)}).`);
@@ -633,7 +861,7 @@ 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 { loadConfig as loadConfig4 } from "@skein-js/config";
 import {
   describeSnapshot as describeSnapshot2,
   loadSnapshotIntoStore,
@@ -645,7 +873,7 @@ function summarize(counts) {
 }
 async function runImportLanggraph(options) {
   const configPath = path6.resolve(process.cwd(), options.config);
-  const { config, configDir } = await loadConfig3({ configPath });
+  const { config, configDir } = await loadConfig4({ configPath });
   const sourceDir = options.from ? path6.resolve(process.cwd(), options.from) : path6.join(configDir, LANGGRAPH_DIR);
   const snapshot = await readLanggraphDevState2(sourceDir);
   if (snapshot === null) {
@@ -689,8 +917,87 @@ async function runImportLanggraph(options) {
   console.log(`skein: imported ${summarize(counts)} into Postgres.`);
 }
 
+// src/start-command.ts
+import { existsSync as existsSync6, readFileSync as readFileSync4 } from "fs";
+import path7 from "path";
+import { loadConfig as loadConfig5 } from "@skein-js/config";
+import { createExpressServer as createExpressServer2 } from "@skein-js/express";
+import {
+  buildRuntime as buildRuntime3
+} from "@skein-js/runtime";
+var FORCE_EXIT_MS2 = 5e3;
+var logger = createDevLogger();
+function readBakedSchemas(configDir) {
+  const schemasFile = path7.join(configDir, "schemas.json");
+  if (!existsSync6(schemasFile)) {
+    throw new Error(
+      `no schemas.json next to the config \u2014 \`skein start\` expects a built artifact. Run \`skein build\` (or \`skein up\`), or use \`skein dev\` for a source project.`
+    );
+  }
+  return JSON.parse(readFileSync4(schemasFile, "utf8"));
+}
+async function runStart(options) {
+  const configPath = path7.resolve(process.cwd(), options.config);
+  let schemas;
+  let configDir;
+  let authPath;
+  try {
+    const loaded = await loadConfig5({ configPath });
+    configDir = loaded.configDir;
+    authPath = loaded.config.auth?.path;
+    await applyProjectEnv(loaded.config, configDir);
+    schemas = readBakedSchemas(configDir);
+  } catch (error) {
+    console.error(`skein: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+    return;
+  }
+  let runtime;
+  try {
+    runtime = await buildRuntime3({
+      configPath,
+      store: options.store,
+      queue: options.queue,
+      schemas
+    });
+  } catch (error) {
+    console.error(`skein: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.verbose) runtime.deps.logRunActivity = true;
+  const port = options.portExplicit ? options.port : envPort(options.port);
+  const host = options.hostExplicit ? options.host : envHost(options.host);
+  let server;
+  try {
+    server = await createExpressServer2({
+      deps: runtime.deps,
+      cors: runtime.cors,
+      warm: true,
+      logger
+    });
+    await server.listen(port, host);
+  } catch (error) {
+    await runtime.dispose();
+    console.error(`skein: ${describeBindError(error, port)}`);
+    process.exitCode = 1;
+    return;
+  }
+  printBanner({ host, port, graphIds: runtime.deps.graphs.ids, authPath, workerCount: 1 }, logger);
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    const forceExit = setTimeout(() => process.exit(0), FORCE_EXIT_MS2);
+    forceExit.unref();
+    void Promise.allSettled([server.close(), runtime.dispose()]).then(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
 // src/index.ts
-var require2 = createRequire(import.meta.url);
+var require2 = createRequire3(import.meta.url);
 var { version } = require2("../package.json");
 function parsePort(value) {
   const port = Number(value);
@@ -719,8 +1026,21 @@ program.command("dev").description("Run the in-process dev server with hot reloa
     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("start").description("Serve a pre-built .skein/build artifact (the production image entrypoint).").option("-c, --config <path>", "Path to the artifact's langgraph.json", "langgraph.json").option("-p, --port <port>", "Port to bind", parsePort, 2024).option("--host <host>", "Host to bind", "127.0.0.1").option("--store <driver>", "Store driver: memory | postgres", parseStore, "memory").option("--queue <driver>", "Queue driver: memory | redis", parseQueue, "memory").option("-v, --verbose", "Log per-run activity: start/finish, tool calls, and interrupts").action(
+  (options, command) => runStart({
+    ...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").option(
+  "-n, --npmrc <path>",
+  "Path to an .npmrc for authenticating private-registry installs (wired in as a build secret)"
+).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)").option(
+  "-n, --npmrc <path>",
+  "Path to an .npmrc for authenticating private-registry installs (passed to docker build as a BuildKit secret)"
+).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>",

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "skein-js",
-  "version": "0.4.0",
+  "version": "0.6.3",
   "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-js/tree/main/packages/cli#readme",
+  "homepage": "https://github.com/skein-js/skein-js/tree/main/packages/cli#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mainawycliffe/skein-js.git",
+    "url": "git+https://github.com/skein-js/skein-js.git",
     "directory": "packages/cli"
   },
   "bugs": {
-    "url": "https://github.com/mainawycliffe/skein-js/issues"
+    "url": "https://github.com/skein-js/skein-js/issues"
   },
   "keywords": [
     "typescript",
@@ -47,11 +47,13 @@
     "@commander-js/extra-typings": "~13.1.0",
     "@langchain/langgraph-checkpoint-postgres": "^1.0.4",
     "commander": "~13.1.0",
-    "vite": "^8.1.0",
-    "@skein-js/core": "0.4.0",
-    "@skein-js/express": "0.4.0",
-    "@skein-js/config": "0.4.0",
-    "@skein-js/runtime": "0.4.0"
+    "@skein-js/config": "0.6.3",
+    "@skein-js/core": "0.6.3",
+    "@skein-js/express": "0.6.3",
+    "@skein-js/runtime": "0.6.3"
+  },
+  "optionalDependencies": {
+    "vite": "^8.1.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"