@moondeck/station 0.0.1 → 1.0.0

package/lib/standard-image-pin.ts

@@ -0,0 +1,207 @@
+/**
+ * ADR-114: the standard image is prebuilt in CI and pulled by digest.
+ *
+ * This module is the shared identity/grammar core, deliberately free of any
+ * host runtime import so the release-side identity script and the unit tests
+ * can load it without dragging the container-runtime graph along. Everything
+ * here is consumed from three places:
+ *
+ *   - CI (`host-agent/scripts/release/standard-image-identity.ts`) computes
+ *     the superset context hash and the registry tag to build/push.
+ *   - Release packaging (`scripts/host-runtime/stage.mjs`) embeds a validated
+ *     pin file in the signed payload (its .mjs copy of the grammar cites this
+ *     module as authoritative).
+ *   - The host (`standard-image.ts`) reads the packaged pin and pulls by
+ *     digest instead of building, falling back to the local build.
+ */
+
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Image label carrying the build-context content hash (rebuild trigger). */
+export const CONTEXT_HASH_LABEL = "com.runuai.context-hash";
+
+/** The public registry repository CI publishes the prebuilt image to. The
+ * GitHub org was renamed runuai → moondeckio on 2026-10-20; GHCR, unlike
+ * github.com, does not redirect the old owner (pushes fail "owner not
+ * found", pulls 404). */
+export const STANDARD_IMAGE_RELEASE_REF = "ghcr.io/moondeckio/uai-standard";
+
+/** Pin file basename; packaged at `agent/images/<basename>` in the payload,
+ * one directory above the build context so it never perturbs the hash. */
+export const STANDARD_IMAGE_PIN_BASENAME = "standard-image.pin.json";
+
+/**
+ * The prebuilt image is the SUPERSET: every optional engine baked in. The
+ * layers are additive and non-fatal, a disabled engine is simply never
+ * invoked, and superset-vs-config means one published image serves every
+ * host — and toggling an engine on stops forcing a host-side rebuild.
+ */
+export const STANDARD_IMAGE_SUPERSET_EXTRA =
+  "kimi=1;grok=1;cursor=1;opencode=1";
+
+export const STANDARD_IMAGE_SUPERSET_BUILD_ARGS: readonly string[] = [
+  "INSTALL_KIMI=1",
+  "INSTALL_GROK=1",
+  "INSTALL_CURSOR=1",
+  "INSTALL_OPENCODE=1",
+];
+
+export interface StandardImagePin {
+  readonly ref: string;
+  readonly digest: string;
+  readonly contextHash: string;
+  /**
+   * Per-architecture image digests. A host pulls ITS OWN architecture's
+   * digest — pulling the manifest-list digest stores a two-variant image on
+   * the Apple runtime, and task-up's apple guard refuses any task image with
+   * more than one variant (found live on the Air's first task, 2026-08-20).
+   * Optional so a list-only pin still works on Docker via `digest`.
+   */
+  readonly platforms?: { readonly arm64?: string; readonly x64?: string };
+}
+
+// The pin arrives inside a signature-verified payload; this grammar is
+// defense-in-depth so no parsed field can smuggle registry ports, tags,
+// or shell-significant bytes into an engine command line.
+const REF_PATTERN = /^[a-z0-9]+(?:[a-z0-9._-]*[a-z0-9])?(?:\/[a-z0-9]+(?:[a-z0-9._-]*[a-z0-9])?)+$/;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const CONTEXT_HASH_PATTERN = /^[a-f0-9]{32}$/;
+
+/** Strict parse of a pin document; null on ANY deviation. */
+export function parseStandardImagePin(raw: string): StandardImagePin | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const { ref, digest, contextHash, platforms } = parsed as Record<
+    string,
+    unknown
+  >;
+  if (
+    typeof ref !== "string" ||
+    typeof digest !== "string" ||
+    typeof contextHash !== "string" ||
+    !REF_PATTERN.test(ref) ||
+    !DIGEST_PATTERN.test(digest) ||
+    !CONTEXT_HASH_PATTERN.test(contextHash)
+  ) {
+    return null;
+  }
+  let parsedPlatforms: { arm64?: string; x64?: string } | undefined;
+  if (platforms !== undefined) {
+    if (typeof platforms !== "object" || platforms === null) return null;
+    parsedPlatforms = {};
+    for (const arch of ["arm64", "x64"] as const) {
+      const value = (platforms as Record<string, unknown>)[arch];
+      if (value === undefined) continue;
+      if (typeof value !== "string" || !DIGEST_PATTERN.test(value)) return null;
+      parsedPlatforms[arch] = value;
+    }
+  }
+  return {
+    ref,
+    digest,
+    contextHash,
+    ...(parsedPlatforms ? { platforms: parsedPlatforms } : {}),
+  };
+}
+
+/**
+ * The digest a given host should pull: its own architecture's single-variant
+ * image when the pin carries one, else the manifest list. Docker resolves a
+ * list to the native variant; the Apple runtime stores the whole index, which
+ * task-up's one-variant guard then refuses — so arch digests win.
+ */
+export function standardImagePullDigest(
+  pin: StandardImagePin,
+  arch: string = process.arch,
+): string {
+  if (arch === "arm64" || arch === "x64") {
+    const platformDigest = pin.platforms?.[arch];
+    if (platformDigest !== undefined) return platformDigest;
+  }
+  return pin.digest;
+}
+
+/** The exact engine argv for pulling and tagging the pinned image. Docker
+ * and the Apple `container` CLI differ only in the `image` subcommand prefix. */
+export function standardImagePullCommands(
+  pin: StandardImagePin,
+  targetTag: string,
+  apple: boolean,
+  arch: string = process.arch,
+): { pull: string[]; tag: string[] } {
+  const source = `${pin.ref}@${standardImagePullDigest(pin, arch)}`;
+  return apple
+    ? {
+        pull: ["image", "pull", source],
+        tag: ["image", "tag", source, targetTag],
+      }
+    : { pull: ["pull", source], tag: ["tag", source, targetTag] };
+}
+
+/**
+ * Content-hash a standard-image build context: every file under the context
+ * dir, sorted by relative path, plus an `extra` string carrying the build-arg
+ * configuration (part of the image identity). Null when the context can't be
+ * read — callers keep whatever image exists.
+ */
+export async function hashStandardImageContext(
+  contextDir: string,
+  extra = "",
+): Promise<string | null> {
+  try {
+    const files: string[] = [];
+    const walk = async (dir: string, prefix: string): Promise<void> => {
+      for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) await walk(join(dir, entry.name), rel);
+        else files.push(rel);
+      }
+    };
+    await walk(contextDir, "");
+    files.sort();
+    const hash = createHash("sha256");
+    for (const rel of files) {
+      hash.update(rel);
+      hash.update("\0");
+      hash.update(await readFile(join(contextDir, rel)));
+      hash.update("\0");
+    }
+    hash.update(extra);
+    hash.update("\0");
+    return hash.digest("hex").slice(0, 32);
+  } catch {
+    return null;
+  }
+}
+
+/** Everything CI needs to build/push/pin one release image, or null when the
+ * context is unreadable (a broken checkout must fail the release loudly). */
+export async function standardImageReleaseIdentity(
+  contextDir: string,
+): Promise<{
+  ref: string;
+  tag: string;
+  contextHash: string;
+  label: string;
+  buildArgs: readonly string[];
+} | null> {
+  const contextHash = await hashStandardImageContext(
+    contextDir,
+    STANDARD_IMAGE_SUPERSET_EXTRA,
+  );
+  if (contextHash === null) return null;
+  return {
+    ref: STANDARD_IMAGE_RELEASE_REF,
+    tag: `ctx-${contextHash}`,
+    contextHash,
+    label: `${CONTEXT_HASH_LABEL}=${contextHash}`,
+    buildArgs: STANDARD_IMAGE_SUPERSET_BUILD_ARGS,
+  };
+}