@rigkit/runtime-client 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigkit/runtime-client",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "repository": {
     "type": "git",

package/src/api.ts

@@ -14,6 +14,7 @@ const OptionalString = Schema.optional(Schema.String);
 export const RuntimeControlHealthEffectSchema = Schema.Struct({
   ok: Schema.Boolean,
   projectId: Schema.String,
+  runtimeFingerprint: OptionalString,
   projectDir: Schema.String,
   configPath: Schema.String,
   statePath: OptionalString,

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   getOrStartRuntime,
   connectRemoteRuntime,
   projectIdFor,
+  runtimeFingerprintFor,
   runtimePaths,
   getOrStartRuntimeEffect,
   type GetOrStartRuntimeOptions,

package/src/manager.test.ts

@@ -1,11 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   connectRemoteRuntime,
   getOrStartRuntime,
   projectIdFor,
+  runtimeFingerprintFor,
   runtimePaths,
   SUPPORTED_RUNTIME_API_VERSION,
 } from "./manager.ts";
@@ -42,7 +43,7 @@ describe("runtime manager", () => {
     expect(differentSource).not.toBe(first);
   });
 
-  test("includes config contents in local runtime ids", () => {
+  test("keeps project ids stable while config fingerprints change", () => {
     const root = mkdtempSync(join(tmpdir(), "rigkit-runtime-client-id-"));
     try {
       const projectDir = join(root, "project");
@@ -52,16 +53,62 @@ describe("runtime manager", () => {
 
       const first = projectIdFor({ projectDir, configPath });
       const second = projectIdFor({ projectDir, configPath });
+      const firstFingerprint = runtimeFingerprintFor({ projectDir, configPath });
       writeFileSync(configPath, "export default { name: 'two' }\n");
       const changed = projectIdFor({ projectDir, configPath });
+      const changedFingerprint = runtimeFingerprintFor({ projectDir, configPath });
 
       expect(second).toBe(first);
-      expect(changed).not.toBe(first);
+      expect(changed).toBe(first);
+      expect(changedFingerprint).not.toBe(firstFingerprint);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
   });
 
+  test("restarts local runtimes when the runtime fingerprint changes", async () => {
+    const root = mkdtempSync(join(tmpdir(), "rigkit-runtime-client-restart-"));
+    let first: Awaited<ReturnType<typeof getOrStartRuntime>> | undefined;
+    let second: Awaited<ReturnType<typeof getOrStartRuntime>> | undefined;
+
+    try {
+      const projectDir = join(root, "project");
+      const rigkitHome = join(root, "home");
+      const configPath = join(projectDir, "rig.config.ts");
+      mkdirSync(projectDir, { recursive: true });
+      writeFileSync(configPath, "export default { name: 'one' }\n");
+      writeFakeRuntimeBin(projectDir);
+
+      first = await getOrStartRuntime({
+        projectDir,
+        configPath,
+        rigkitHome,
+        idleMs: 60_000,
+      });
+      const firstHealth = await first.control.health();
+
+      writeFileSync(configPath, "export default { name: 'two' }\n");
+      second = await getOrStartRuntime({
+        projectDir,
+        configPath,
+        rigkitHome,
+        idleMs: 60_000,
+      });
+      const secondHealth = await second.control.health();
+
+      expect(second.handle.projectId).toBe(first.handle.projectId);
+      expect(second.paths.handlePath).toBe(first.paths.handlePath);
+      expect(second.handle.runtimeFingerprint).not.toBe(first.handle.runtimeFingerprint);
+      expect(second.handle.pid).not.toBe(first.handle.pid);
+      expect(secondHealth.runtimeFingerprint).toBe(second.handle.runtimeFingerprint);
+      expect(firstHealth.projectId).toBe(secondHealth.projectId);
+    } finally {
+      await second?.control.shutdown().catch(() => {});
+      await first?.control.shutdown().catch(() => {});
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   test("derives handle, token, and lock paths from rigkit home", () => {
     const paths = runtimePaths("sha256-test", "/tmp/rigkit-home");
 
@@ -229,3 +276,72 @@ describe("runtime manager", () => {
     }
   });
 });
+
+function writeFakeRuntimeBin(projectDir: string): void {
+  const binDir = join(projectDir, "node_modules", ".bin");
+  mkdirSync(binDir, { recursive: true });
+  const binPath = join(binDir, process.platform === "win32" ? "rigkit-project-runtime.cmd" : "rigkit-project-runtime");
+  writeFileSync(
+    binPath,
+    `#!/usr/bin/env bun
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const options = {};
+for (let i = 1; i < args.length; i += 2) {
+  options[args[i].replace(/^--/, "")] = args[i + 1];
+}
+
+const token = readFileSync(options.token, "utf8").trim();
+let server;
+server = Bun.serve({
+  hostname: "127.0.0.1",
+  port: 0,
+  fetch(request) {
+    const url = new URL(request.url);
+    if (request.headers.get("authorization") !== \`Bearer \${token}\`) {
+      return Response.json({ error: { message: "Unauthorized" } }, { status: 401 });
+    }
+    if (url.pathname === "/health") {
+      return Response.json({
+        ok: true,
+        projectId: options["project-id"],
+        runtimeFingerprint: options["runtime-fingerprint"],
+        projectDir: resolve(options["project-dir"]),
+        configPath: resolve(options.config),
+        statePath: options.state ? resolve(options.state) : undefined,
+        engineVersion: "engine-test",
+        runtimeVersion: "runtime-test",
+        expiresAt: new Date(Date.now() + 60_000).toISOString(),
+      }, { headers: { "x-rigkit-api-version": "${SUPPORTED_RUNTIME_API_VERSION}" } });
+    }
+    if (url.pathname === "/shutdown") {
+      setTimeout(() => {
+        server.stop(true);
+        process.exit(0);
+      }, 0);
+      return Response.json({ ok: true }, { headers: { "x-rigkit-api-version": "${SUPPORTED_RUNTIME_API_VERSION}" } });
+    }
+    return Response.json({ error: { message: "Not found" } }, { status: 404 });
+  },
+});
+
+const handle = {
+  projectId: options["project-id"],
+  runtimeFingerprint: options["runtime-fingerprint"],
+  projectDir: resolve(options["project-dir"]),
+  configPath: resolve(options.config),
+  statePath: options.state ? resolve(options.state) : undefined,
+  pid: process.pid,
+  url: \`http://127.0.0.1:\${server.port}\`,
+  tokenPath: resolve(options.token),
+};
+mkdirSync(dirname(options.handle), { recursive: true });
+writeFileSync(options.handle, JSON.stringify(handle));
+console.log(JSON.stringify({ type: "ready", url: handle.url, token }));
+await new Promise(() => {});
+`,
+  );
+  chmodSync(binPath, 0o755);
+}

package/src/manager.ts

@@ -1,4 +1,4 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { spawn, type ChildProcessByStdio } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
@@ -93,13 +93,19 @@ async function getOrStartRuntimeUnsafe(options: GetOrStartRuntimeOptions): Promi
     statePath,
     source: options.source,
   });
+  const runtimeFingerprint = runtimeFingerprintFor({
+    projectDir,
+    configPath,
+    statePath,
+    source: options.source,
+  });
   const paths = runtimePaths(projectId, options.rigkitHome);
 
-  const existing = await tryExistingRuntime(paths, projectId);
+  const existing = await tryExistingRuntime(paths, projectId, runtimeFingerprint);
   if (existing) return existing;
 
   await withRuntimeLock(paths.lockPath, async () => {
-    const secondCheck = await tryExistingRuntime(paths, projectId);
+    const secondCheck = await tryExistingRuntime(paths, projectId, runtimeFingerprint);
     if (secondCheck) return;
     await startRuntime({
       ...options,
@@ -107,11 +113,12 @@ async function getOrStartRuntimeUnsafe(options: GetOrStartRuntimeOptions): Promi
       configPath,
       statePath,
       projectId,
+      runtimeFingerprint,
       paths,
     });
   });
 
-  const started = await tryExistingRuntime(paths, projectId);
+  const started = await tryExistingRuntime(paths, projectId, runtimeFingerprint);
   if (!started) {
     throw new RuntimeStartupError({
       reason: "unhealthy-after-start",
@@ -128,13 +135,36 @@ export function projectIdFor(options: RuntimeProjectOptions): string {
   hash.update(JSON.stringify({
     projectDir: resolve(options.projectDir),
     configPath,
-    configHash: configHashFor(configPath),
     statePath: options.statePath ? resolve(options.statePath) : null,
     source: options.source ?? null,
   }));
   return `sha256-${hash.digest("hex").slice(0, 32)}`;
 }
 
+export function runtimeFingerprintFor(options: RuntimeProjectOptions): string {
+  const projectDir = resolve(options.projectDir);
+  const configPath = resolve(options.configPath);
+  const statePath = options.statePath ? resolve(options.statePath) : null;
+  const hash = createHash("sha256");
+
+  hash.update("project\0");
+  hash.update(projectDir);
+  hash.update("\0config\0");
+  hash.update(configPath);
+  hash.update("\0state\0");
+  hash.update(statePath ?? "");
+  hash.update("\0source\0");
+  hash.update(JSON.stringify(options.source ?? null));
+
+  updateFileFingerprint(hash, "config", configPath);
+  for (const file of dotenvFilesFor(projectDir)) updateFileFingerprint(hash, "dotenv", file);
+  for (const file of projectFingerprintFiles(projectDir)) updateFileFingerprint(hash, "project-file", file);
+  updateProjectSurfaceFingerprint(hash, projectDir);
+  updateRigkitPackageFingerprint(hash, join(projectDir, "node_modules", "@rigkit"));
+
+  return `sha256-${hash.digest("hex")}`;
+}
+
 export function runtimePaths(projectId: string, rigkitHome = defaultRigkitHome()): RuntimePaths {
   const root = join(rigkitHome, "runtimes");
   return {
@@ -149,11 +179,24 @@ export function defaultRigkitHome(): string {
   return process.env.RIGKIT_HOME ? resolve(process.env.RIGKIT_HOME) : join(homedir(), ".rigkit");
 }
 
-async function tryExistingRuntime(paths: RuntimePaths, projectId: string): Promise<RuntimeClient | undefined> {
+async function tryExistingRuntime(
+  paths: RuntimePaths,
+  projectId: string,
+  runtimeFingerprint: string,
+): Promise<RuntimeClient | undefined> {
   const handle = readHandle(paths.handlePath);
   if (!handle || handle.projectId !== projectId) return undefined;
   const token = readToken(handle.tokenPath);
-  if (!token) return undefined;
+  if (!token) {
+    removeStale(paths);
+    return undefined;
+  }
+
+  if (handle.runtimeFingerprint !== runtimeFingerprint) {
+    await shutdownRuntime(handle, token);
+    removeStale(paths);
+    return undefined;
+  }
 
   try {
     const body = await createRuntimeHttpClient({ baseUrl: handle.url, token }).health();
@@ -164,6 +207,13 @@ async function tryExistingRuntime(paths: RuntimePaths, projectId: string): Promi
         message: `runtime project mismatch`,
       });
     }
+    if (body.runtimeFingerprint !== runtimeFingerprint) {
+      throw new RuntimeConnectionError({
+        method: "GET",
+        path: "/health",
+        message: `runtime fingerprint mismatch`,
+      });
+    }
     return createClient(handle, paths, token);
   } catch (error) {
     if (error instanceof RuntimeApiVersionError) throw error;
@@ -174,6 +224,7 @@ async function tryExistingRuntime(paths: RuntimePaths, projectId: string): Promi
 
 async function startRuntime(input: GetOrStartRuntimeOptions & {
   projectId: string;
+  runtimeFingerprint: string;
   paths: RuntimePaths;
 }): Promise<void> {
   mkdirSync(input.paths.root, { recursive: true });
@@ -183,6 +234,8 @@ async function startRuntime(input: GetOrStartRuntimeOptions & {
     "serve",
     "--project-id",
     input.projectId,
+    "--runtime-fingerprint",
+    input.runtimeFingerprint,
     "--project-dir",
     input.projectDir,
     "--config",
@@ -355,7 +408,7 @@ function readReadyLine(proc: ChildProcessByStdio<null, Readable, null>, paths: R
         reason: "startup-timeout",
         projectDir,
         message: `Timed out waiting for Rigkit runtime to start`,
-      }));
+      }), { kill: true });
     }, 15_000);
 
     const cleanup = () => {
@@ -374,10 +427,12 @@ function readReadyLine(proc: ChildProcessByStdio<null, Readable, null>, paths: R
       resolvePromise(line);
     };
 
-    function fail(error: unknown) {
+    function fail(error: unknown, options: { kill?: boolean } = {}) {
       if (settled) return;
       settled = true;
       cleanup();
+      if (options.kill) killRuntimeProcess(proc);
+      removeStale(paths);
       rejectPromise(error);
     }
 
@@ -414,15 +469,117 @@ function readReadyLine(proc: ChildProcessByStdio<null, Readable, null>, paths: R
   });
 }
 
+function killRuntimeProcess(proc: ChildProcessByStdio<null, Readable, null>): void {
+  if (!proc.pid) return;
+  try {
+    proc.kill("SIGTERM");
+  } catch {
+    // Best effort. The startup path will discard the stale handle either way.
+  }
+}
+
 function removeStale(paths: RuntimePaths): void {
   rmSync(paths.handlePath, { force: true });
 }
 
-function configHashFor(configPath: string): string | null {
-  if (!existsSync(configPath)) return null;
-  const hash = createHash("sha256");
-  hash.update(readFileSync(configPath));
-  return hash.digest("hex");
+async function shutdownRuntime(handle: RuntimeHandle, token: string): Promise<void> {
+  try {
+    await createRuntimeHttpClient({ baseUrl: handle.url, token }).shutdown();
+  } catch {
+    if (handle.pid !== process.pid) {
+      try {
+        process.kill(handle.pid);
+      } catch {
+        // Best effort. The stale handle is still removed below.
+      }
+    }
+  }
+}
+
+function updateFileFingerprint(hash: ReturnType<typeof createHash>, label: string, path: string): void {
+  hash.update(`\0${label}\0${path}\0`);
+  if (!existsSync(path)) {
+    hash.update("missing");
+    return;
+  }
+
+  const stat = statSync(path);
+  if (!stat.isFile()) {
+    hash.update(`not-file:${stat.mode}`);
+    return;
+  }
+
+  hash.update(readFileSync(path));
+}
+
+function projectFingerprintFiles(projectDir: string): string[] {
+  return [
+    "package.json",
+    "bun.lock",
+    "bun.lockb",
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+  ].map((file) => join(projectDir, file));
+}
+
+function updateProjectSurfaceFingerprint(hash: ReturnType<typeof createHash>, projectDir: string): void {
+  if (!existsSync(projectDir)) return;
+  const ignored = new Set([".git", ".rigkit", "node_modules", "dist", "build", ".next", ".astro"]);
+  const entries = readdirSync(projectDir, { withFileTypes: true })
+    .filter((entry) => !ignored.has(entry.name))
+    .map((entry) => `${entry.name}:${entry.isDirectory() ? "dir" : entry.isFile() ? "file" : "other"}`)
+    .sort();
+  hash.update("\0project-surface\0");
+  hash.update(entries.join("\n"));
+}
+
+function updateRigkitPackageFingerprint(hash: ReturnType<typeof createHash>, scopeDir: string): void {
+  if (!existsSync(scopeDir)) return;
+  const packageDirs = readdirSync(scopeDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+    .map((entry) => join(scopeDir, entry.name))
+    .sort();
+
+  for (const packageDir of packageDirs) {
+    updateFileFingerprint(hash, "rigkit-package", join(packageDir, "package.json"));
+    for (const file of collectFiles(join(packageDir, "src"))) {
+      updateFileFingerprint(hash, "rigkit-source", file);
+    }
+  }
+}
+
+function collectFiles(root: string): string[] {
+  if (!existsSync(root)) return [];
+  const out: string[] = [];
+  const visit = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(path);
+      } else if (entry.isFile()) {
+        out.push(path);
+      }
+    }
+  };
+  visit(root);
+  return out.sort();
+}
+
+function dotenvFilesFor(projectDir: string): string[] {
+  const files: string[] = [];
+  let current = projectDir;
+
+  while (true) {
+    const candidate = join(current, ".env");
+    if (existsSync(candidate)) files.unshift(candidate);
+
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return files;
 }
 
 function isFileExistsError(error: unknown): boolean {

package/src/schemas.ts

@@ -38,6 +38,7 @@ function runtimeClientSchema<T, I>(schema: Schema.Schema<T, I, never>): RuntimeC
 
 export const RuntimeHandleEffectSchema = Schema.Struct({
   projectId: Schema.String,
+  runtimeFingerprint: Schema.optional(Schema.String),
   projectDir: Schema.String,
   configPath: Schema.String,
   statePath: Schema.optional(Schema.String),
@@ -59,6 +60,7 @@ export const RuntimeReadyEffectSchema = Schema.Struct({
 export const RuntimeHealthEffectSchema = Schema.Struct({
   ok: Schema.Boolean,
   projectId: Schema.String,
+  runtimeFingerprint: Schema.optional(Schema.String),
   projectDir: Schema.optional(Schema.String),
   configPath: Schema.optional(Schema.String),
   statePath: Schema.optional(Schema.String),

package/src/version.ts

@@ -1 +1 @@
-export const RIGKIT_RUNTIME_CLIENT_VERSION = "0.2.0";
+export const RIGKIT_RUNTIME_CLIENT_VERSION = "0.2.2";