@linzumi/cli 0.0.4-beta → 0.0.6-beta

package/src/localEditorRuntime.ts

@@ -0,0 +1,603 @@
+/*
+- Date: 2026-04-29
+  Spec: kandan/server_v2/plans/2026-04-29-local-runner-editor-runtime-distribution-note.md
+  Relationship: Keeps local editor launches on a Kandan-approved,
+  checksummed runtime distribution instead of relying on host package-manager
+  code-server layouts.
+*/
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { kandanHttpBaseUrl } from "./oauth";
+import { isJsonObject, type JsonObject } from "./protocol";
+
+export type EditorRuntimeManifest = {
+  readonly version: string;
+  readonly platform: string;
+  readonly archiveUrl: string;
+  readonly archiveSha256: string;
+  readonly codeServerVersion: string;
+  readonly codeServerBinPath: string;
+  readonly manifestPath: string;
+  readonly assets: readonly JsonObject[];
+};
+
+export type EditorRuntimeStatus =
+  | {
+      readonly status: "ready";
+      readonly mode: "server_managed";
+      readonly version: string;
+      readonly platform: string;
+      readonly archiveSha256: string;
+      readonly codeServerVersion: string;
+      readonly codeServerBin: string;
+      readonly updated: boolean;
+    }
+  | {
+      readonly status: "custom";
+      readonly mode: "custom";
+      readonly codeServerBin: string;
+    }
+  | {
+      readonly status: "unavailable";
+      readonly mode: "server_managed";
+      readonly reason:
+        | "unsupported_platform"
+        | "manifest_unavailable"
+        | "download_failed"
+        | "checksum_mismatch"
+        | "archive_extract_failed"
+        | "invalid_archive"
+        | "install_failed";
+    };
+
+export type InstalledEditorRuntime = {
+  readonly mode: "server_managed";
+  readonly root: string;
+  readonly codeServerBin: string;
+  readonly assets: {
+    readonly collaborationExtensionTarball: string;
+    readonly collaborationServerTarball: string;
+    readonly documentStateExtensionDir: string;
+  };
+};
+
+export type ResolveEditorRuntimeOptions = {
+  readonly kandanUrl: string;
+  readonly token: string;
+  readonly customCodeServerBin?: string | undefined;
+  readonly cacheRoot?: string | undefined;
+  readonly platform?: NodeJS.Platform | undefined;
+  readonly arch?: NodeJS.Architecture | undefined;
+  readonly fetchImpl?: typeof fetch | undefined;
+  readonly extractArchive?: ((archivePath: string, destination: string) => Promise<boolean>) | undefined;
+};
+
+export type ResolveEditorRuntimeResult = {
+  readonly status: EditorRuntimeStatus;
+  readonly codeServerBin?: string | undefined;
+  readonly runtime?: InstalledEditorRuntime | undefined;
+};
+
+export async function resolveEditorRuntime(
+  options: ResolveEditorRuntimeOptions,
+): Promise<ResolveEditorRuntimeResult> {
+  if (options.customCodeServerBin !== undefined) {
+    return {
+      codeServerBin: options.customCodeServerBin,
+      status: {
+        status: "custom",
+        mode: "custom",
+        codeServerBin: options.customCodeServerBin,
+      },
+    };
+  }
+
+  const platform = editorRuntimePlatform(
+    options.platform ?? process.platform,
+    options.arch ?? process.arch,
+  );
+
+  if (platform === undefined) {
+    return unavailable("unsupported_platform");
+  }
+
+  const manifest = await fetchApprovedManifest({
+    kandanUrl: options.kandanUrl,
+    token: options.token,
+    platform,
+    fetchImpl: options.fetchImpl ?? fetch,
+  });
+
+  if (!manifest.ok) {
+    return unavailable("manifest_unavailable");
+  }
+
+  const cacheRoot = options.cacheRoot ?? defaultEditorRuntimeCacheRoot();
+  const installed = installedRuntime(cacheRoot, manifest.manifest);
+
+  if (installed.ok) {
+    return ready(manifest.manifest, installed.runtime, false);
+  }
+
+  const installResult = await installRuntime({
+    kandanUrl: options.kandanUrl,
+    token: options.token,
+    manifest: manifest.manifest,
+    cacheRoot,
+    fetchImpl: options.fetchImpl ?? fetch,
+    extractArchive: options.extractArchive ?? extractTarGz,
+  });
+
+  if (!installResult.ok) {
+    return unavailable(installResult.reason);
+  }
+
+  return ready(manifest.manifest, installResult.runtime, true);
+}
+
+export function editorRuntimeStatusPayload(status: EditorRuntimeStatus): JsonObject {
+  switch (status.status) {
+    case "ready":
+      return {
+        status: "ready",
+        mode: status.mode,
+        version: status.version,
+        platform: status.platform,
+        archiveSha256: status.archiveSha256,
+        codeServerVersion: status.codeServerVersion,
+        updated: status.updated,
+      };
+    case "custom":
+      return {
+        status: "custom",
+        mode: status.mode,
+        codeServerBin: status.codeServerBin,
+      };
+    case "unavailable":
+      return {
+        status: "unavailable",
+        mode: status.mode,
+        reason: status.reason,
+      };
+  }
+}
+
+export function editorRuntimePlatform(
+  platform: NodeJS.Platform,
+  arch: NodeJS.Architecture,
+): string | undefined {
+  switch (`${platform}-${arch}`) {
+    case "darwin-arm64":
+      return "darwin-arm64";
+    case "darwin-x64":
+      return "darwin-x64";
+    default:
+      return undefined;
+  }
+}
+
+function unavailable(reason: Extract<EditorRuntimeStatus, { status: "unavailable" }>["reason"]): ResolveEditorRuntimeResult {
+  return {
+    status: {
+      status: "unavailable",
+      mode: "server_managed",
+      reason,
+    },
+  };
+}
+
+function ready(
+  manifest: EditorRuntimeManifest,
+  runtime: InstalledEditorRuntime,
+  updated: boolean,
+): ResolveEditorRuntimeResult {
+  return {
+    codeServerBin: runtime.codeServerBin,
+    runtime,
+    status: {
+      status: "ready",
+      mode: "server_managed",
+      version: manifest.version,
+      platform: manifest.platform,
+      archiveSha256: manifest.archiveSha256,
+      codeServerVersion: manifest.codeServerVersion,
+      codeServerBin: runtime.codeServerBin,
+      updated,
+    },
+  };
+}
+
+async function fetchApprovedManifest(args: {
+  readonly kandanUrl: string;
+  readonly token: string;
+  readonly platform: string;
+  readonly fetchImpl: typeof fetch;
+}): Promise<
+  | { readonly ok: true; readonly manifest: EditorRuntimeManifest }
+  | { readonly ok: false }
+> {
+  const url = new URL(
+    `/api/v2/local-codex-runner/editor-runtime/${encodeURIComponent(args.platform)}/manifest`,
+    kandanHttpBaseUrl(args.kandanUrl),
+  );
+  const response = await args.fetchImpl(url, {
+    headers: { authorization: `Bearer ${args.token}` },
+  }).catch(() => undefined);
+
+  if (response === undefined) {
+    return { ok: false };
+  }
+
+  if (response.status !== 200) {
+    return { ok: false };
+  }
+
+  const body: unknown = await response.json();
+
+  if (!isJsonObject(body) || body.ok !== true || !isJsonObject(body.runtime)) {
+    return { ok: false };
+  }
+
+  return normalizeManifest(body.runtime);
+}
+
+function normalizeManifest(value: JsonObject):
+  | { readonly ok: true; readonly manifest: EditorRuntimeManifest }
+  | { readonly ok: false } {
+  const version = nonEmptyString(value.version);
+  const platform = nonEmptyString(value.platform);
+  const archiveUrl = nonEmptyString(value.archiveUrl);
+  const archiveSha256 = sha256String(value.archiveSha256);
+  const codeServerVersion = nonEmptyString(value.codeServerVersion);
+  const codeServerBinPath = nonEmptyString(value.codeServerBinPath) ?? "bin/code-server";
+  const manifestPath = nonEmptyString(value.manifestPath) ?? "linzumi-editor-runtime.json";
+  const assets = Array.isArray(value.assets) && value.assets.every(isJsonObject)
+    ? value.assets
+    : [];
+
+  if (
+    version === undefined ||
+    platform === undefined ||
+    archiveUrl === undefined ||
+    archiveSha256 === undefined ||
+    codeServerVersion === undefined
+  ) {
+    return { ok: false };
+  }
+
+  return {
+    ok: true,
+    manifest: {
+      version,
+      platform,
+      archiveUrl,
+      archiveSha256,
+      codeServerVersion,
+      codeServerBinPath,
+      manifestPath,
+      assets,
+    },
+  };
+}
+
+function installedRuntime(
+  cacheRoot: string,
+  manifest: EditorRuntimeManifest,
+): { readonly ok: true; readonly runtime: InstalledEditorRuntime } | { readonly ok: false } {
+  const runtimeRoot = runtimeInstallRoot(cacheRoot, manifest);
+  const manifestPath = join(runtimeRoot, manifest.manifestPath);
+  const codeServerBin = join(runtimeRoot, manifest.codeServerBinPath);
+  const assets = verifiedRuntimeAssetPaths(runtimeRoot, manifest);
+
+  if (!existsSync(manifestPath) || !existsSync(codeServerBin) || assets === undefined) {
+    return { ok: false };
+  }
+
+  try {
+    const installed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+    if (
+      isJsonObject(installed) &&
+      installed.version === manifest.version &&
+      installed.platform === manifest.platform &&
+      (installed.archiveSha256 === undefined ||
+        installed.archiveSha256 === manifest.archiveSha256)
+    ) {
+      return {
+        ok: true,
+        runtime: {
+          mode: "server_managed",
+          root: runtimeRoot,
+          codeServerBin,
+          assets,
+        },
+      };
+    }
+  } catch (_error) {
+    return { ok: false };
+  }
+
+  return { ok: false };
+}
+
+async function installRuntime(args: {
+  readonly kandanUrl: string;
+  readonly token: string;
+  readonly manifest: EditorRuntimeManifest;
+  readonly cacheRoot: string;
+  readonly fetchImpl: typeof fetch;
+  readonly extractArchive: (archivePath: string, destination: string) => Promise<boolean>;
+}): Promise<
+  | { readonly ok: true; readonly runtime: InstalledEditorRuntime }
+  | { readonly ok: false; readonly reason: Extract<EditorRuntimeStatus, { status: "unavailable" }>["reason"] }
+> {
+  mkdirSync(args.cacheRoot, { recursive: true });
+
+  const tempRoot = mkdtempSync(join(tmpdir(), "linzumi-editor-runtime-install-"));
+  const archivePath = join(tempRoot, "runtime.tar.gz");
+  const extractRoot = join(tempRoot, "runtime");
+
+  try {
+    const downloaded = await downloadArchive({
+      kandanUrl: args.kandanUrl,
+      token: args.token,
+      manifest: args.manifest,
+      archivePath,
+      fetchImpl: args.fetchImpl,
+    });
+
+    if (!downloaded.ok) {
+      return downloaded;
+    }
+
+    mkdirSync(extractRoot, { recursive: true });
+
+    if (!(await args.extractArchive(archivePath, extractRoot))) {
+      return { ok: false, reason: "archive_extract_failed" };
+    }
+
+    const manifestPath = join(extractRoot, args.manifest.manifestPath);
+    const codeServerBin = join(extractRoot, args.manifest.codeServerBinPath);
+    const assets = verifiedRuntimeAssetPaths(extractRoot, args.manifest);
+
+    if (!existsSync(manifestPath) || !existsSync(codeServerBin) || assets === undefined) {
+      return { ok: false, reason: "invalid_archive" };
+    }
+
+    const installed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+    if (
+      !isJsonObject(installed) ||
+      installed.version !== args.manifest.version ||
+      installed.platform !== args.manifest.platform ||
+      (installed.archiveSha256 !== undefined &&
+        installed.archiveSha256 !== args.manifest.archiveSha256)
+    ) {
+      return { ok: false, reason: "invalid_archive" };
+    }
+
+    writeFileSync(
+      manifestPath,
+      JSON.stringify(
+        {
+          ...installed,
+          archiveSha256: args.manifest.archiveSha256,
+          codeServerVersion: args.manifest.codeServerVersion,
+        },
+        null,
+        2,
+      ),
+    );
+
+    const targetRoot = runtimeInstallRoot(args.cacheRoot, args.manifest);
+    rmSync(targetRoot, { recursive: true, force: true });
+    mkdirSync(dirname(targetRoot), { recursive: true });
+    renameSync(extractRoot, targetRoot);
+
+    return {
+      ok: true,
+      runtime: {
+        mode: "server_managed",
+        root: targetRoot,
+        codeServerBin: join(targetRoot, args.manifest.codeServerBinPath),
+        assets: {
+          collaborationExtensionTarball: join(
+            targetRoot,
+            "kandan",
+            "editor_extensions",
+            "typefox.open-collaboration-tools.tar.gz",
+          ),
+          collaborationServerTarball: join(
+            targetRoot,
+            "kandan",
+            "editor_servers",
+            "open-collaboration-server.tar.gz",
+          ),
+          documentStateExtensionDir: join(
+            targetRoot,
+            "kandan",
+            "editor_extensions",
+            "kandan.document-state-telemetry",
+          ),
+        },
+      },
+    };
+  } catch (_error) {
+    return { ok: false, reason: "install_failed" };
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function downloadArchive(args: {
+  readonly kandanUrl: string;
+  readonly token: string;
+  readonly manifest: EditorRuntimeManifest;
+  readonly archivePath: string;
+  readonly fetchImpl: typeof fetch;
+}): Promise<
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: "download_failed" | "checksum_mismatch" }
+> {
+  const url = new URL(args.manifest.archiveUrl, kandanHttpBaseUrl(args.kandanUrl));
+  const response = await args.fetchImpl(url, {
+    headers: { authorization: `Bearer ${args.token}` },
+  });
+
+  if (response.status !== 200 || response.body === null) {
+    return { ok: false, reason: "download_failed" };
+  }
+
+  await pipeline(
+    Readable.fromWeb(response.body),
+    createWriteStream(args.archivePath),
+  );
+
+  const sha256 = await fileSha256(args.archivePath);
+
+  if (sha256 !== args.manifest.archiveSha256) {
+    return { ok: false, reason: "checksum_mismatch" };
+  }
+
+  return { ok: true };
+}
+
+function extractTarGz(archivePath: string, destination: string): Promise<boolean> {
+  return new Promise((resolveExtract) => {
+    const child = spawn("tar", ["-xzf", archivePath, "-C", destination], {
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+
+    child.on("error", () => resolveExtract(false));
+    child.on("exit", (code) => resolveExtract(code === 0));
+  });
+}
+
+function fileSha256(path: string): Promise<string> {
+  return new Promise((resolveHash, rejectHash) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path);
+
+    stream.on("error", rejectHash);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolveHash(hash.digest("hex")));
+  });
+}
+
+function runtimeInstallRoot(
+  cacheRoot: string,
+  manifest: EditorRuntimeManifest,
+): string {
+  return resolve(cacheRoot, manifest.platform, manifest.archiveSha256);
+}
+
+function verifiedRuntimeAssetPaths(
+  runtimeRoot: string,
+  manifest: EditorRuntimeManifest,
+): InstalledEditorRuntime["assets"] | undefined {
+  const collaborationExtensionTarball = join(
+    runtimeRoot,
+    "kandan",
+    "editor_extensions",
+    "typefox.open-collaboration-tools.tar.gz",
+  );
+  const collaborationServerTarball = join(
+    runtimeRoot,
+    "kandan",
+    "editor_servers",
+    "open-collaboration-server.tar.gz",
+  );
+  const documentStateExtensionDir = join(
+    runtimeRoot,
+    "kandan",
+    "editor_extensions",
+    "kandan.document-state-telemetry",
+  );
+
+  const requiredPaths = [
+    manifest.codeServerBinPath,
+    "lib/vscode/node_modules/vsda/rust/web/vsda.js",
+    "lib/vscode/node_modules/vsda/rust/web/vsda_bg.wasm",
+    "kandan/editor_extensions/typefox.open-collaboration-tools.tar.gz",
+    "kandan/editor_servers/open-collaboration-server.tar.gz",
+    "kandan/editor_extensions/kandan.document-state-telemetry/package.json",
+    "kandan/editor_extensions/kandan.document-state-telemetry/out/extension.js",
+  ];
+  const assetChecksums = manifestAssetChecksums(manifest.assets);
+
+  for (const relativePath of requiredPaths) {
+    const expectedSha256 = assetChecksums.get(relativePath);
+
+    if (expectedSha256 === undefined) {
+      return undefined;
+    }
+
+    const absolutePath = join(runtimeRoot, relativePath);
+
+    if (!existsSync(absolutePath) || fileSha256Sync(absolutePath) !== expectedSha256) {
+      return undefined;
+    }
+  }
+
+  if (!existsSync(collaborationExtensionTarball) || !existsSync(collaborationServerTarball)) {
+    return undefined;
+  }
+
+  return {
+    collaborationExtensionTarball,
+    collaborationServerTarball,
+    documentStateExtensionDir,
+  };
+}
+
+function manifestAssetChecksums(assets: readonly JsonObject[]): Map<string, string> {
+  const checksums = new Map<string, string>();
+
+  for (const asset of assets) {
+    const path = nonEmptyString(asset.path);
+    const sha256 = sha256String(asset.sha256);
+
+    if (path !== undefined && sha256 !== undefined) {
+      checksums.set(path, sha256);
+    }
+  }
+
+  return checksums;
+}
+
+function fileSha256Sync(path: string): string {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function defaultEditorRuntimeCacheRoot(): string {
+  return join(homedir(), ".linzumi", "editor-runtimes");
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== ""
+    ? value.trim()
+    : undefined;
+}
+
+function sha256String(value: unknown): string | undefined {
+  const normalized = nonEmptyString(value);
+
+  return normalized !== undefined && /^[a-f0-9]{64}$/i.test(normalized)
+    ? normalized.toLowerCase()
+    : undefined;
+}