@izykitten/ce 0.0.1 → 0.0.3-dev.0

package/src/ce.ts

@@ -1,1189 +0,0 @@
-/**
- * Container engine wrapper.
- *
- * A python -> Bun port of the `ce` script. `ce` with no args prints help and
- * exits 0; otherwise `ce [--tag-prefix=<p>] [--cache-prefix=<p>] <command|engine>
- * [args...]`.
- *
- * For engine passthrough, the wrapper rewrites:
- *   - `-t`/`--tag` values: strip https://, sanitize, move leading path
- *     segments to the repo side, and rewrite "<path>/renovate_<x>" to
- *     "<path>/renovate:<x>". Each tag gets the sanitized `--tag-prefix`
- *     prepended.
- *   - `--cache-from`/`--cache-to` (and the `--cache` shorthand): gha cache
- *     scopes get the sanitized `--cache-prefix` prepended; cache-from values
- *     that match a cache-to value are namespaced, unmatched cache-from
- *     values pass through unchanged so reads from a shared cache still work.
- *
- * The final engine invocation uses execve(2) so the wrapper is replaced in
- * place; docker/podman/buildah inherits the same PID, signals, TTY and exit
- * code. `login` spawns the engines because it loops and must continue on
- * partial failure.
- */
-
-import fs from "node:fs";
-import { homedir } from "node:os";
-import path from "node:path";
-import { execve, flock, LOCK_EX, strerror } from "./libc.ts";
-
-export const SELF = "ce";
-
-const FORGEJO_HELPER_SUFFIX = "ce-forgejo";
-const FORGEJO_STATE_FILE = "ce-forgejo-credentials.json";
-const FORGEJO_REFRESH_WINDOW = 5 * 60;
-
-/** Raised for bad input; the entry point prints it and exits 2. */
-export class ValueError extends Error {
-  override name = "ValueError";
-}
-
-function isOSError(exc: unknown): exc is Error & { code: string } {
-  return exc instanceof Error && typeof (exc as { code?: unknown }).code === "string";
-}
-
-function message(exc: unknown): string {
-  return exc instanceof Error ? exc.message : String(exc);
-}
-
-/** Python-style repr() of a string, used in the messages carried over from `ce`. */
-function repr(value: string): string {
-  const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
-  const body = value
-    .replaceAll("\\", "\\\\")
-    .replaceAll(quote, `\\${quote}`)
-    .replaceAll("\n", "\\n")
-    .replaceAll("\r", "\\r")
-    .replaceAll("\t", "\\t");
-  return `${quote}${body}${quote}`;
-}
-
-export interface Writer {
-  write(text: string): void;
-}
-
-/**
- * Process I/O. Writes are synchronous so nothing is lost when the process is
- * replaced by execve. Tests swap these members out.
- */
-export const sys = {
-  stdout: { write: (text: string) => void fs.writeSync(1, text) } as Writer,
-  stderr: { write: (text: string) => void fs.writeSync(2, text) } as Writer,
-  stdin: { read: (): string => fs.readFileSync(0, "utf8") },
-  argv0: (): string => process.argv[1] ?? SELF,
-};
-
-function print(text: string, stream: Writer = sys.stdout): void {
-  stream.write(`${text}\n`);
-}
-
-function env(): Record<string, string> {
-  return Object.fromEntries(
-    Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined),
-  );
-}
-
-export interface RunResult {
-  returncode: number;
-  stderr: Uint8Array;
-}
-
-/** Calls out to the system. Tests swap these members out. */
-export const os = {
-  which: (command: string): string | null => Bun.which(command, { PATH: process.env.PATH ?? "" }),
-
-  /** Run with `input` on stdin, stdout discarded, stderr captured. Throws ENOENT if missing. */
-  run: (argv: string[], input: Uint8Array): RunResult => {
-    const result = Bun.spawnSync(argv, { stdin: input, stdout: "ignore", stderr: "pipe", env: env() });
-    return { returncode: result.exitCode ?? 1, stderr: result.stderr ?? new Uint8Array() };
-  },
-
-  /** Run with stdout/stderr discarded and return the exit code. */
-  call: (argv: string[]): number =>
-    Bun.spawnSync(argv, { stdin: "ignore", stdout: "ignore", stderr: "ignore", env: env() }).exitCode ?? 1,
-
-  sleep: (seconds: number): void => Bun.sleepSync(seconds * 1000),
-
-  urlopen: (url: string, headers: Record<string, string>, timeout: number): Promise<Response> =>
-    fetch(url, { headers, signal: AbortSignal.timeout(timeout * 1000) }),
-
-  /** Replace this process with `file` looked up on PATH. Only returns by throwing. */
-  execvp: (file: string, argv: string[]): never => {
-    const resolved = file.includes("/") ? file : os.which(file);
-    if (!resolved) {
-      throw Object.assign(new Error(`[Errno 2] No such file or directory: ${repr(file)}`), { code: "ENOENT" });
-    }
-    const code = execve(resolved, argv, env());
-    throw new Error(`[Errno ${code}] ${strerror(code)}: ${repr(file)}`);
-  },
-};
-
-/**
- * Build the usage help string lazily from the current invocation name, so the
- * `Usage:` line reflects how `ce` was actually invoked.
- */
-export function helpText(): string {
-  return `Usage: ${sys.argv0()} [--tag-prefix=<prefix>] [--cache-prefix=<prefix>] [command|engine] [args]
-
-Options:
-    --tag-prefix=<prefix>
-                      Prepend <prefix> to every tag passed via -t/--tag.
-                      A trailing "-" is appended automatically if the prefix
-                      does not already end with "-", "_", or ".".
-                      Also available via TAG_PREFIX environment variable.
-    --cache-prefix=<prefix>
-                      Prepend <prefix> to every gha cache scope passed via
-                      --cache-from/--cache-to. Defaults to the tag prefix
-                      (TAG_PREFIX); set to "" to keep cache scopes shared.
-                      Also available via CACHE_PREFIX environment variable.
-    --cache=<spec>    Shorthand for passing <spec> to both --cache-from and
-                      --cache-to. Supports the same forms as --cache-from/--cache-to.
-
-Commands:
-    login             Log in to all available engines
-
-Engines:
-    docker [args]     Passthrough to docker
-    podman [args]     Passthrough to podman (via gosu if available)
-    buildah [args]    Passthrough to buildah (via gosu if available)
-
-Environment variables (used by login):
-    Each registry is a "group". The default group uses the bare variables
-    below; additional registries use a __<name> suffix that ties the three
-    variables together.
-        REGISTRY_USER[__<name>]     username
-        REGISTRY_PASSWORD[__<name>] password
-        REGISTRY_HOST[__<name>]     registry host(s) (https:// stripped);
-                                   whitespace-separated list logs in to each
-                                   with the same creds, e.g. "docker.io dhi.io"
-        AUD                         Forgejo Authorized Integration audience.
-                                   When set, the registry matching the Forgejo
-                                   Actions token-request host uses a short-lived
-                                   OIDC JWT instead of REGISTRY_PASSWORD.
-                                   Docker uses a per-host credential helper that
-                                   refreshes the JWT five minutes before expiry.
-                                   Requires ACTIONS_ID_TOKEN_REQUEST_URL and
-                                   ACTIONS_ID_TOKEN_REQUEST_TOKEN from a job
-                                   with enable-openid-connect: true.
-    Defining REGISTRY_HOST__<name> adds a group; its creds come from
-    REGISTRY_USER__<name> and REGISTRY_PASSWORD__<name>. Example:
-    REGISTRY_HOST__DOCKER="docker.io dhi.io" + REGISTRY_USER__DOCKER +
-    REGISTRY_PASSWORD__DOCKER logs in to both Docker Hub and dhi.io with one
-    set of creds, alongside the default registry. The bare (unsuffixed)
-    variables are the default group — no suffix needed for the primary
-    registry.
-`;
-}
-
-export const INVALID_TAG_CHARS = /[^A-Za-z0-9_.\-]/gu;
-export const INVALID_SCOPE_CHARS = /[^A-Za-z0-9_.:/\-]/gu;
-
-// Rewrite "<path>/renovate_<suffix>" to "<path>/renovate:<suffix>" so the
-// dependency/version lands on the tag side under a renovate repo namespace.
-const RENOVATE_RE = /^(.*)\/renovate_(.*)$/u;
-
-// Matches a gha cache value of the form `type=gha[,mode=max][,scope=<rest>]`.
-// Group 1 is ",mode=max" when mode=max is present. Group 2 is the raw scope
-// (possibly empty) when scope= is present. A bare `type=gha` or
-// `type=gha,mode=max` (no scope=) is matched and treated as an empty scope;
-// buildx would otherwise default it to the shared "buildkit" scope, bypassing
-// the cache prefix namespacing.
-const GHA_RE = /^type=gha(,mode=max)?(?:,scope=(.*))?$/u;
-
-export function sanitizeChars(value: string, charRegex: RegExp): string {
-  return value.replace(charRegex, "_");
-}
-
-/**
- * Reject non-ASCII characters rather than silently replacing them.
- *
- * ASCII characters outside the safe set are still sanitized to '_' (that is
- * the documented branch-name -> tag contract), but a non-ASCII character would
- * silently change the published image name, so we fail loud and name the
- * offending character instead of mangling it.
- */
-export function assertAscii(label: string, value: string): void {
-  for (const ch of value) {
-    const code = ch.codePointAt(0)!;
-    if (code >= 0x80) {
-      const hex = code.toString(16).toUpperCase().padStart(4, "0");
-      throw new ValueError(
-        `ce: refusing to sanitize non-ASCII character ${repr(ch)} ` +
-          `(U+${hex}) in ${label} ${repr(value)} — rename the ref ` +
-          `or pass an explicit ASCII tag.`,
-      );
-    }
-  }
-}
-
-function stripProto(value: string): string {
-  for (const proto of ["https://", "http://"]) {
-    if (value.startsWith(proto)) return value.slice(proto.length);
-  }
-  return value;
-}
-
-/** str.partition(sep): split at the first `sep`. */
-function partition(value: string, sep: string): [string, string] {
-  const i = value.indexOf(sep);
-  return i < 0 ? [value, ""] : [value.slice(0, i), value.slice(i + sep.length)];
-}
-
-/**
- * Sanitize a tag reference.
- *
- * Strip a leading https:// or http://, then in the tag portion (after the
- * first ":") replace any character not in [A-Za-z0-9_.-] with "_". If a "/"
- * appears in the tag, move it (and any subsequent path segments) to the repo
- * side. Finally, rewrite a "<path>/renovate_<suffix>" prefix to
- * "<path>/renovate:<suffix>".
- *
- * e.g. code.izy.sh/templates/preact/renovate_typescript-native-preview-7.x
- *   -> code.izy.sh/templates/preact/renovate:typescript-native-preview-7.x
- */
-export function sanitizeTag(value: string): string {
-  assertAscii("tag", value);
-  value = stripProto(value);
-  let out: string;
-  if (value.includes(":")) {
-    const [repo, tag] = partition(value, ":");
-    if (tag.includes("/")) {
-      const [first, rest] = partition(tag, "/");
-      out = `${repo}/${sanitizeChars(first, INVALID_TAG_CHARS)}:${sanitizeChars(rest, INVALID_TAG_CHARS)}`;
-    } else {
-      out = `${repo}:${sanitizeChars(tag, INVALID_TAG_CHARS)}`;
-    }
-  } else {
-    out = value;
-  }
-  const m = RENOVATE_RE.exec(out);
-  if (m) out = `${m[1]}/renovate:${m[2]}`;
-  return out;
-}
-
-/**
- * Sanitize a prefix value, appending a "-" separator unless it already ends
- * with one of [-_.]. Empty input yields empty output.
- */
-export function computeSafePrefix(prefix: string): string {
-  assertAscii("tag prefix", prefix);
-  let p = sanitizeChars(prefix, INVALID_TAG_CHARS);
-  if (p && !"-_.".includes(p.at(-1)!)) p += "-";
-  return p;
-}
-
-/**
- * Extract the scope name from a gha cache value, ignoring type/mode wrappers.
- * Non-gha values are returned unchanged. A bare gha value with no scope=
- * yields an empty scope name so it can be matched against a namespaced
- * cache-to. The scope name is sanitized to a safe character set; ":" and "/"
- * are kept because they appear in common scope conventions.
- */
-export function cacheScopeName(value: string): string {
-  const m = GHA_RE.exec(value);
-  if (!m) return value;
-  const scope = m[2];
-  if (scope === undefined) return "";
-  assertAscii("cache scope", scope);
-  return sanitizeChars(scope, INVALID_SCOPE_CHARS);
-}
-
-/**
- * Prepend the sanitized cache prefix to gha cache scope values.
- *
- * A bare gha value with no scope= is treated as an empty scope so the prefix
- * is used as the scope, preventing the buildx default "buildkit" scope from
- * leaking through. If the scope value is empty, the prefix is used alone with
- * no trailing separator. If the prefix does not end with one of [-_.], a "-"
- * is inserted between prefix and scope. Non-gha values are returned unchanged.
- */
-export function normalizeCacheScope(value: string, cachePrefix: string): string {
-  const m = GHA_RE.exec(value);
-  if (!m) return value;
-
-  // Nothing to namespace onto: leave the value (and any buildx-default
-  // scope) untouched.
-  if (!cachePrefix) return value;
-
-  assertAscii("cache prefix", cachePrefix);
-  const prefix = sanitizeChars(cachePrefix, INVALID_TAG_CHARS);
-  // Drop any further ",..." wrapper suffix the scope may carry.
-  let scope = partition(cacheScopeName(value), ",")[0];
-
-  if (!scope) {
-    scope = prefix.replace(/[-_.]+$/u, "");
-  } else if (prefix) {
-    scope = "-_.".includes(prefix.at(-1)!) ? `${prefix}${scope}` : `${prefix}-${scope}`;
-  }
-
-  return m[1] ? `type=gha,mode=max,scope=${scope}` : `type=gha,scope=${scope}`;
-}
-
-/** Wait for an engine to be ready. Returns true once any engine responds. */
-export function doWait(engines: string[]): boolean {
-  for (let i = 1; i <= 30; i++) {
-    for (const engine of engines) {
-      // buildah has no daemon — always considered ready.
-      if (engine === "buildah") return true;
-      if (os.call([engine, "info"]) === 0) return true;
-    }
-    print(`waiting for ${engines.join(" ")}... (${i}/30)`, sys.stderr);
-    os.sleep(1);
-  }
-  print(`no engine available: ${engines.join(" ")}`, sys.stderr);
-  return false;
-}
-
-interface Authority {
-  scheme: string;
-  hostname: string | null;
-  port: number | null;
-}
-
-/**
- * Split "[scheme://]host[:port][/path]" into its parts, the way urlsplit does
- * for the registry and token-request values `ce` handles. The hostname is
- * lowercased and IPv6 brackets are removed.
- */
-function splitAuthority(raw: string): Authority {
-  let scheme = "";
-  let rest = raw;
-  const sep = raw.indexOf("://");
-  if (sep >= 0) {
-    scheme = raw.slice(0, sep).toLowerCase();
-    rest = raw.slice(sep + 3);
-  }
-  let netloc = rest.split(/[/?#]/u, 1)[0]!;
-  netloc = netloc.slice(netloc.lastIndexOf("@") + 1);
-  let host = netloc;
-  let portText: string | null = null;
-  if (netloc.startsWith("[")) {
-    const end = netloc.indexOf("]");
-    if (end < 0) throw new ValueError("Invalid IPv6 URL");
-    host = netloc.slice(1, end);
-    const after = netloc.slice(end + 1);
-    if (after.startsWith(":")) portText = after.slice(1);
-  } else if (netloc.includes(":")) {
-    [host, portText] = [netloc.slice(0, netloc.lastIndexOf(":")), netloc.slice(netloc.lastIndexOf(":") + 1)];
-  }
-  let port: number | null = null;
-  if (portText) {
-    port = /^\d+$/u.test(portText) ? Number(portText) : NaN;
-    if (!(port >= 0 && port <= 65535)) {
-      throw new ValueError(`Port could not be cast to integer value as ${repr(portText)}`);
-    }
-  }
-  return { scheme, hostname: host ? host.toLowerCase() : null, port };
-}
-
-/**
- * Return a normalized [hostname, effectivePort] for a URL/host.
- *
- * Registry entries commonly omit their scheme while Forgejo's Actions token
- * request URL includes one and may include a path. Comparing normalized
- * authorities lets those forms match without treating a service on another
- * port as the same registry and leaking the JWT to it.
- */
-export function urlAuthority(value: string, defaultScheme = "https"): [string, number] {
-  const raw = value.trim();
-  if (!raw) throw new ValueError("empty URL or host");
-
-  const parsed = splitAuthority(raw);
-  const scheme = parsed.scheme || defaultScheme;
-  if (scheme !== "http" && scheme !== "https") {
-    throw new ValueError(`unsupported URL scheme ${repr(scheme)}`);
-  }
-  if (!parsed.hostname) throw new ValueError(`missing hostname in ${repr(value)}`);
-  let port = parsed.port;
-  if (port === null) port = scheme === "http" ? 80 : 443;
-  return [parsed.hostname, port];
-}
-
-/** Validate that `value` is an absolute HTTP(S) URL with a hostname. */
-function assertAbsoluteHttpUrl(value: string, error: string): void {
-  if (!value.includes("://")) throw new ValueError(error);
-  const parsed = splitAuthority(value);
-  if ((parsed.scheme !== "http" && parsed.scheme !== "https") || !parsed.hostname) {
-    throw new ValueError(error);
-  }
-}
-
-/** Fetch a Forgejo Actions OIDC JWT for an Authorized Integration. */
-export async function forgejoOidcJwt(audience: string, requestUrl: string, requestToken: string): Promise<string> {
-  assertAbsoluteHttpUrl(requestUrl, "token request URL must be an absolute HTTP(S) URL");
-
-  let tokenUrl: string;
-  let headers: Record<string, string>;
-  try {
-    const url = new URL(requestUrl);
-    // Replace, rather than duplicate, an audience supplied by a caller.
-    url.searchParams.delete("audience");
-    url.searchParams.append("audience", audience);
-    tokenUrl = url.href;
-    headers = { Accept: "application/json", Authorization: `bearer ${requestToken}` };
-    new Headers(headers);
-  } catch {
-    // Some URL/header errors include their raw input in the exception.
-    // Avoid reflecting the request credential into workflow logs.
-    throw new ValueError("token request URL or headers are invalid");
-  }
-
-  let body: Uint8Array;
-  try {
-    const response = await os.urlopen(tokenUrl, headers, 30);
-    if (!response.ok) throw new Error(`HTTP Error ${response.status}: ${response.statusText}`);
-    body = new Uint8Array(await response.arrayBuffer());
-  } catch (exc) {
-    throw new ValueError(`token request failed: ${message(exc)}`);
-  }
-
-  let text: string;
-  try {
-    text = new TextDecoder("utf-8", { fatal: true }).decode(body);
-  } catch {
-    throw new ValueError("token response is not valid UTF-8 JSON");
-  }
-  let payload: unknown;
-  try {
-    payload = JSON.parse(text);
-  } catch {
-    throw new ValueError("token response is not valid JSON");
-  }
-
-  if (!isObject(payload)) throw new ValueError("token response is not a JSON object");
-  const jwt = payload.value;
-  if (typeof jwt !== "string" || !jwt.trim()) {
-    throw new ValueError("token response has no non-empty string 'value'");
-  }
-  return jwt.trim();
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** Read the numeric `exp` claim without treating it as validation. */
-export function jwtExpiry(jwt: string): number {
-  const parts = jwt.split(".");
-  if (parts.length !== 3) throw new ValueError("OIDC token is not a three-part JWT");
-  let payload: unknown;
-  try {
-    const bytes = Buffer.from(parts[1]!, "base64url");
-    payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
-  } catch {
-    throw new ValueError("OIDC token has an invalid JWT payload");
-  }
-  const expiry = isObject(payload) ? payload.exp : undefined;
-  if (typeof expiry !== "number") throw new ValueError("OIDC token has no numeric 'exp' claim");
-  return expiry;
-}
-
-/**
- * The directory holding the installed `ce` and `docker-credential-ce-forgejo`
- * executables (the package's bin/), wherever bunx or an install put it.
- */
-export function scriptDir(): string {
-  return fs.realpathSync(path.join(import.meta.dir, "..", "bin"));
-}
-
-/** Make the installed script directory visible to Docker. */
-export function ensureHelperOnPath(): void {
-  const dir = scriptDir();
-  const parts = (process.env.PATH ?? "").split(path.delimiter);
-  if (!parts.includes(dir)) process.env.PATH = [dir, ...parts].join(path.delimiter);
-}
-
-function expandUser(value: string): string {
-  if (value === "~" || value.startsWith("~/")) return path.join(homeDir(), value.slice(1));
-  return value;
-}
-
-function homeDir(): string {
-  return homedir();
-}
-
-export function dockerConfigDir(): string {
-  const configured = process.env.DOCKER_CONFIG;
-  if (configured) return path.resolve(expandUser(configured));
-  return path.join(homeDir(), ".docker");
-}
-
-export function forgejoStatePath(): string {
-  return path.join(dockerConfigDir(), FORGEJO_STATE_FILE);
-}
-
-/** Return the Docker registry server name, excluding scheme and path. */
-export function registryServer(value: string): string {
-  const parsed = splitAuthority(value.trim());
-  if (!parsed.hostname) throw new ValueError(`missing hostname in ${repr(value)}`);
-  let hostname = parsed.hostname;
-  if (hostname.includes(":")) hostname = `[${hostname}]`;
-  return parsed.port !== null ? `${hostname}:${parsed.port}` : hostname;
-}
-
-function registryKey(value: string): string {
-  return registryServer(value).toLowerCase();
-}
-
-export function readJsonFile(file: string, fallback: unknown): unknown {
-  try {
-    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(fs.readFileSync(file)));
-  } catch (exc) {
-    if (isOSError(exc) && exc.code === "ENOENT") return fallback;
-    throw new ValueError(`cannot read JSON file ${repr(file)}: ${message(exc)}`);
-  }
-}
-
-/** JSON with sorted keys and compact separators, as `ce` has always written it. */
-function dumpJson(payload: unknown): string {
-  return JSON.stringify(payload, (_key, value: unknown) =>
-    isObject(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : value,
-  );
-}
-
-export function writePrivateJson(file: string, payload: unknown): void {
-  const directory = path.dirname(file);
-  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-  const temporary = path.join(directory, `.ce-forgejo-${crypto.randomUUID().slice(0, 8)}`);
-  const fd = fs.openSync(temporary, "wx", 0o600);
-  try {
-    try {
-      fs.fchmodSync(fd, 0o600);
-      fs.writeSync(fd, `${dumpJson(payload)}\n`);
-      fs.fsyncSync(fd);
-    } finally {
-      fs.closeSync(fd);
-    }
-    fs.renameSync(temporary, file);
-  } finally {
-    fs.rmSync(temporary, { force: true });
-  }
-}
-
-interface HelperState {
-  version?: number;
-  registries: Record<string, Record<string, unknown>>;
-}
-
-type LockCallback<T> = (state: HelperState) => [T, boolean] | Promise<[T, boolean]>;
-
-/** Run `callback(state)` under the helper's cross-process lock. */
-export async function withForgejoStateLock<T>(callback: LockCallback<T>): Promise<T> {
-  const statePath = forgejoStatePath();
-  fs.mkdirSync(path.dirname(statePath), { recursive: true, mode: 0o700 });
-  const lockPath = `${statePath}.lock`;
-  const lock = fs.openSync(lockPath, "a+");
-  try {
-    fs.chmodSync(lockPath, 0o600);
-    const code = flock(lock, LOCK_EX);
-    if (code !== 0) {
-      throw Object.assign(new Error(`[Errno ${code}] ${strerror(code)}: ${repr(lockPath)}`), { code: "EFLOCK" });
-    }
-    const state = readJsonFile(statePath, { version: 1, registries: {} });
-    if (!isObject(state) || !isObject(state.registries)) {
-      throw new ValueError("Forgejo credential-helper state is invalid");
-    }
-    const [result, changed] = await callback(state as unknown as HelperState);
-    if (changed) writePrivateJson(statePath, state);
-    return result;
-  } finally {
-    fs.closeSync(lock);
-  }
-}
-
-export async function saveForgejoHelperState(
-  registry: string,
-  username: string,
-  audience: string,
-  authority: [string, number],
-  jwt: string,
-): Promise<void> {
-  const expiry = jwtExpiry(jwt);
-  if (expiry <= Date.now() / 1000 + FORGEJO_REFRESH_WINDOW) {
-    throw new ValueError("OIDC token expires within the five-minute refresh window");
-  }
-  await withForgejoStateLock((state) => {
-    state.registries[registryKey(registry)] = {
-      audience,
-      authority: [authority[0], authority[1]],
-      expires_at: expiry,
-      token: jwt,
-      username,
-    };
-    return [undefined, true];
-  });
-}
-
-/** Atomically register the per-host helper after a successful login. */
-export async function configureDockerCredentialHelper(
-  registry: string,
-  username: string,
-  audience: string,
-  authority: [string, number],
-  jwt: string,
-): Promise<void> {
-  await saveForgejoHelperState(registry, username, audience, authority, jwt);
-
-  const configPath = path.join(dockerConfigDir(), "config.json");
-  const config = readJsonFile(configPath, {});
-  if (!isObject(config)) throw new ValueError("Docker config is not a JSON object");
-  config.credHelpers ??= {};
-  const helpers = config.credHelpers;
-  if (!isObject(helpers)) throw new ValueError("Docker config 'credHelpers' is not a JSON object");
-  helpers[registry] = FORGEJO_HELPER_SUFFIX;
-
-  // A helper takes precedence, but remove the now-stale plaintext copy so the
-  // JWT has one source of truth and cannot be used after helper-state expiry.
-  const auths = config.auths;
-  if (isObject(auths)) {
-    for (const key of Object.keys(auths)) {
-      if (registryKey(key) === registryKey(registry)) delete auths[key];
-    }
-  }
-  writePrivateJson(configPath, config);
-}
-
-export async function helperGet(registry: string): Promise<{ Username: string; Secret: string }> {
-  const key = registryKey(registry);
-
-  return withForgejoStateLock(async (state) => {
-    const entry = state.registries[key];
-    if (!isObject(entry)) throw new ValueError(`no Forgejo OIDC credentials configured for ${repr(registry)}`);
-    const { username, token, expires_at: expiry } = entry;
-    if (typeof username !== "string" || !username) {
-      throw new ValueError("Forgejo credential-helper username is missing");
-    }
-    if (typeof token !== "string" || typeof expiry !== "number") {
-      throw new ValueError("Forgejo credential-helper token state is invalid");
-    }
-    if (expiry > Date.now() / 1000 + FORGEJO_REFRESH_WINDOW) {
-      return [{ Username: username, Secret: token }, false];
-    }
-
-    const { audience, authority: storedAuthority } = entry;
-    const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL ?? "";
-    const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN ?? "";
-    if (typeof audience !== "string" || !audience) {
-      throw new ValueError("Forgejo credential-helper audience is missing");
-    }
-    if (!(requestUrl && requestToken)) {
-      throw new ValueError("OIDC refresh requires ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN");
-    }
-    const [host, port] = urlAuthority(requestUrl);
-    if (!Array.isArray(storedAuthority) || storedAuthority.length !== 2 || storedAuthority[0] !== host || storedAuthority[1] !== port) {
-      throw new ValueError("OIDC token-request host does not match the registry");
-    }
-
-    const refreshed = await forgejoOidcJwt(audience, requestUrl, requestToken);
-    const refreshedExpiry = jwtExpiry(refreshed);
-    if (refreshedExpiry <= Date.now() / 1000 + FORGEJO_REFRESH_WINDOW) {
-      throw new ValueError("refreshed OIDC token expires within the five-minute window");
-    }
-    entry.token = refreshed;
-    entry.expires_at = refreshedExpiry;
-    return [{ Username: username, Secret: refreshed }, true];
-  });
-}
-
-/** Implement Docker's credential-helper protocol for Forgejo OIDC. */
-export async function cmdCredentialHelper(argv: string[]): Promise<number> {
-  const command = argv[0];
-  if (argv.length !== 1 || !["get", "store", "erase", "list"].includes(command!)) {
-    print("ce: credential-helper requires get|store|erase|list", sys.stderr);
-    return 1;
-  }
-  try {
-    if (command === "get") {
-      const result = await helperGet(sys.stdin.read().trim());
-      sys.stdout.write(`${JSON.stringify(result)}\n`);
-      return 0;
-    }
-
-    if (command === "store") {
-      const payload: unknown = JSON.parse(sys.stdin.read());
-      if (!isObject(payload)) throw new ValueError("credential-helper store payload is invalid");
-      const { ServerURL: registry, Username: username, Secret: secret } = payload;
-      if (![registry, username, secret].every((v) => typeof v === "string" && v)) {
-        throw new ValueError("credential-helper store fields are incomplete");
-      }
-      const expiry = jwtExpiry(secret as string);
-      await withForgejoStateLock((state) => {
-        const entry = (state.registries[registryKey(registry as string)] ??= {});
-        Object.assign(entry, { expires_at: expiry, token: secret, username });
-        return [undefined, true];
-      });
-      return 0;
-    }
-
-    if (command === "erase") {
-      const registry = sys.stdin.read().trim();
-      await withForgejoStateLock((state) => {
-        const key = registryKey(registry);
-        const removed = key in state.registries;
-        delete state.registries[key];
-        return [undefined, removed];
-      });
-      return 0;
-    }
-
-    const result = await withForgejoStateLock((state) => {
-      const entries: Record<string, unknown> = {};
-      for (const [key, value] of Object.entries(state.registries)) {
-        if (isObject(value)) entries[key] = value.username ?? "";
-      }
-      return [entries, false];
-    });
-    sys.stdout.write(`${JSON.stringify(result)}\n`);
-    return 0;
-  } catch (exc) {
-    if (!(exc instanceof ValueError || exc instanceof SyntaxError || isOSError(exc))) throw exc;
-    print(`ce: Forgejo credential helper: ${message(exc)}`, sys.stderr);
-    return 1;
-  }
-}
-
-/**
- * Log in to every available engine for each registry group.
- *
- * Groups are processed in sorted order (default group first, then
- * REGISTRY_HOST__<suffix> groups alphabetically by suffix) so that the order
- * is deterministic and derivable from the variable names. This matters when
- * two groups target the same registry with different credentials: the
- * credential stores are last-write-wins, so the final group wins.
- */
-export async function cmdLogin(): Promise<number> {
-  ensureHelperOnPath();
-  const environ = process.env;
-  const groups: string[] = [];
-  if (environ.REGISTRY_HOST) groups.push("");
-  for (const name of Object.keys(environ).sort()) {
-    if (name.startsWith("REGISTRY_HOST__")) {
-      const suffix = name.slice("REGISTRY_HOST__".length);
-      if (suffix) groups.push(suffix);
-    }
-  }
-
-  if (groups.length === 0) {
-    print("Skipping login: no REGISTRY_HOST env vars set");
-    return 0;
-  }
-
-  const audience = environ.AUD ?? "";
-  let oidcAuthority: [string, number] | null = null;
-  let oidcRequestUrl = "";
-  let oidcRequestToken = "";
-  if (audience) {
-    oidcRequestUrl = environ.ACTIONS_ID_TOKEN_REQUEST_URL ?? "";
-    oidcRequestToken = environ.ACTIONS_ID_TOKEN_REQUEST_TOKEN ?? "";
-    if (!(oidcRequestUrl && oidcRequestToken)) {
-      print(
-        "Forgejo OIDC login config is incomplete: AUD requires " +
-          "ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN",
-        sys.stderr,
-      );
-      return 1;
-    }
-    try {
-      assertAbsoluteHttpUrl(oidcRequestUrl, "must be an absolute HTTP(S) URL");
-      oidcAuthority = urlAuthority(oidcRequestUrl);
-    } catch (exc) {
-      if (!(exc instanceof ValueError)) throw exc;
-      print(`Invalid ACTIONS_ID_TOKEN_REQUEST_URL: ${exc.message}`, sys.stderr);
-      return 1;
-    }
-  }
-
-  // Resolve and validate every target before logging in. In particular, this
-  // lets an OIDC fetch failure stop the operation before any engine receives
-  // credentials.
-  const targets: { registry: string; label: string; user: string; pwd: string; useOidc: boolean }[] = [];
-  let failed = 0;
-  for (const group of groups) {
-    const suffix = group ? `__${group}` : "";
-    const host = environ[`REGISTRY_HOST${suffix}`] ?? "";
-    const user = environ[`REGISTRY_USER${suffix}`] ?? "";
-    const pwd = environ[`REGISTRY_PASSWORD${suffix}`] ?? "";
-    const label = group || "default";
-
-    if (!(host && user)) {
-      print(`Login config for '${label}' is incomplete: host/user/password not all set`, sys.stderr);
-      failed = 1;
-      continue;
-    }
-
-    // A group's host may list multiple registries separated by whitespace;
-    // log in to each with the same creds.
-    for (const rawRegistry of host.split(/\s+/u).filter(Boolean)) {
-      let authority: [string, number];
-      let registry: string;
-      try {
-        authority = urlAuthority(rawRegistry);
-        registry = registryServer(rawRegistry);
-      } catch (exc) {
-        if (!(exc instanceof ValueError)) throw exc;
-        print(`Invalid registry host for '${label}' (${rawRegistry}): ${exc.message}`, sys.stderr);
-        failed = 1;
-        continue;
-      }
-      const useOidc = oidcAuthority !== null && authority[0] === oidcAuthority[0] && authority[1] === oidcAuthority[1];
-      if (!useOidc && !pwd) {
-        print(`Login config for '${label}' is incomplete: host/user/password not all set`, sys.stderr);
-        failed = 1;
-        continue;
-      }
-      targets.push({ registry, label, user, pwd, useOidc });
-    }
-  }
-
-  let oidcJwt: string | null = null;
-  if (targets.some((t) => t.useOidc)) {
-    try {
-      oidcJwt = await forgejoOidcJwt(audience, oidcRequestUrl, oidcRequestToken);
-    } catch (exc) {
-      if (!(exc instanceof ValueError)) throw exc;
-      print(`Failed to fetch Forgejo OIDC JWT: ${exc.message}`, sys.stderr);
-      return 1;
-    }
-  }
-
-  for (const { registry, label, user, pwd, useOidc } of targets) {
-    const password = useOidc ? oidcJwt : pwd;
-    // oidcJwt is guaranteed above for OIDC targets. Keep this guard so a
-    // future refactor cannot accidentally fall back to a static pwd.
-    if (password === null) {
-      print(`Forgejo OIDC JWT unavailable for '${label}' (${registry})`, sys.stderr);
-      failed = 1;
-      continue;
-    }
-    print(`Logging in to ${registry} (${label})...`);
-    let loggedIn: string | null = null;
-    for (const engine of ["docker", "podman", "buildah"]) {
-      if (!os.which(engine)) continue;
-      let result: RunResult;
-      try {
-        result = os.run([engine, "login", "-u", user, "--password-stdin", registry], Buffer.from(`${password}\n`));
-      } catch (exc) {
-        if (isOSError(exc) && exc.code === "ENOENT") continue;
-        throw exc;
-      }
-      if (result.returncode === 0) {
-        loggedIn = engine;
-        break;
-      }
-      print(`${engine} login failed for '${label}' (${registry}):`, sys.stderr);
-      sys.stderr.write(new TextDecoder().decode(result.stderr));
-    }
-    if (loggedIn) {
-      print(
-        `Logged in to ${registry} (${label}) via ${loggedIn} ` +
-          `(and all engines at or below it: docker < podman < buildah share credentials)`,
-      );
-      if (useOidc) {
-        try {
-          if (oidcAuthority === null || oidcJwt === null) throw new ValueError("OIDC helper state is unavailable");
-          await configureDockerCredentialHelper(registry, user, audience, oidcAuthority, oidcJwt);
-        } catch (exc) {
-          if (!(exc instanceof ValueError || isOSError(exc))) throw exc;
-          print(`Failed to configure Forgejo credential helper for '${label}' (${registry}): ${message(exc)}`, sys.stderr);
-          failed = 1;
-        }
-      }
-    } else {
-      print(`Login failed for '${label}' (${registry})`, sys.stderr);
-      failed = 1;
-    }
-  }
-  return failed;
-}
-
-/**
- * Return the rewritten tag refs for a -t/--tag value (no flag prefix).
- *
- * Strips a leading https:// or http://, splits comma/whitespace-separated
- * tags, prepends the sanitized tagPrefix, sanitizes each, and returns the
- * list of refs. Bare refs (no colon) pass through unchanged.
- */
-export function rewriteTagValue(value: string, tagPrefix: string): string[] {
-  const v = stripProto(value);
-  const refs: string[] = [];
-  if (v.includes(":")) {
-    const [repo, tags] = partition(v, ":");
-    const safePrefix = computeSafePrefix(tagPrefix);
-    // Run each through sanitizeTag so "/" in a tag gets moved to the repo.
-    for (const tag of tags.split(/[,\s]+/u)) {
-      if (!tag) continue;
-      const ref = sanitizeTag(`${repo}:${safePrefix}${tag}`);
-      if (ref) refs.push(ref);
-    }
-  } else {
-    assertAscii("tag", v);
-    refs.push(v);
-  }
-  return refs;
-}
-
-/**
- * Consume the next token of `argv` as the value for `flag`. Errors if `argv`
- * is empty or the next token looks like another flag (starts with '-' and
- * isn't a bare '-'). A bare '-' is allowed (e.g. `docker build -f -`).
- */
-export function consumeValue(argv: string[], flag: string): [string, string[]] {
-  if (argv.length === 0) throw new ValueError(`ce: ${flag} requires a value but none was provided.`);
-  const v = argv[0]!;
-  if (v.length > 1 && v.startsWith("-")) {
-    throw new ValueError(`ce: ${flag} requires a value but the next token ${repr(v)} looks like a flag.`);
-  }
-  return [v, argv.slice(1)];
-}
-
-/** Return [value, nextIndex] for a flag that takes a separate value. */
-export function nextValue(argv: string[], i: number, flag: string): [string, number] {
-  return [consumeValue(argv.slice(i + 1), flag)[0], i + 1];
-}
-
-export interface BuildSummary {
-  tags: string[];
-  cache_from: string[];
-  cache_to: string[];
-  build_args: string[];
-  dockerfile: string;
-  target: string;
-  platform: string;
-  context: string;
-}
-
-/**
- * Parse a build/bud argv once into exec args + a summary record.
- *
- * Returns [execArgs, summary] where execArgs is the ordered argument list to
- * pass to the engine (tags inline, cache-from/cache-to appended at the end)
- * and summary holds display fields with already-rewritten tag/cache values.
- * The context is the last non-flag positional.
- */
-export function parseBuildArgs(argv: string[], tagPrefix: string, cachePrefix: string): [string[], BuildSummary] {
-  const execArgs: string[] = [];
-  const rawCacheFrom: string[] = [];
-  const rawCacheTo: string[] = [];
-  const summary: BuildSummary = {
-    tags: [],
-    cache_from: [],
-    cache_to: [],
-    build_args: [],
-    dockerfile: "",
-    target: "",
-    platform: "",
-    context: "",
-  };
-  const addTags = (value: string, flag: "-t" | "--tag=") => {
-    const refs = rewriteTagValue(value, tagPrefix);
-    for (const ref of refs) execArgs.push(`${flag}${ref}`);
-    summary.tags.push(...refs);
-  };
-
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]!;
-    let v: string;
-    if (arg === "-t") {
-      [v, i] = nextValue(argv, i, "-t");
-      addTags(v, "-t");
-    } else if (arg === "--tag") {
-      [v, i] = nextValue(argv, i, "--tag");
-      addTags(v, "--tag=");
-    } else if (arg.startsWith("-t") && arg.length > 2) {
-      addTags(arg.slice(2), "-t");
-    } else if (arg.startsWith("--tag=")) {
-      addTags(arg.slice("--tag=".length), "--tag=");
-    } else if (arg === "--cache-from") {
-      [v, i] = nextValue(argv, i, "--cache-from");
-      rawCacheFrom.push(v);
-    } else if (arg === "--cache-to") {
-      [v, i] = nextValue(argv, i, "--cache-to");
-      rawCacheTo.push(v);
-    } else if (arg.startsWith("--cache-from=")) {
-      rawCacheFrom.push(arg.slice("--cache-from=".length));
-    } else if (arg.startsWith("--cache-to=")) {
-      rawCacheTo.push(arg.slice("--cache-to=".length));
-    } else if (arg === "--cache") {
-      [v, i] = nextValue(argv, i, "--cache");
-      rawCacheFrom.push(v);
-      rawCacheTo.push(v);
-    } else if (arg.startsWith("--cache=")) {
-      v = arg.slice("--cache=".length);
-      rawCacheFrom.push(v);
-      rawCacheTo.push(v);
-    } else if (arg === "-f" || arg === "--file") {
-      [v, i] = nextValue(argv, i, arg);
-      execArgs.push(arg, v);
-      summary.dockerfile = v;
-    } else if (arg.startsWith("-f") && arg.length > 2) {
-      execArgs.push(arg);
-      summary.dockerfile = arg.slice(2);
-    } else if (arg.startsWith("--file=")) {
-      execArgs.push(arg);
-      summary.dockerfile = arg.slice("--file=".length);
-    } else if (arg === "--target") {
-      [v, i] = nextValue(argv, i, "--target");
-      execArgs.push(arg, v);
-      summary.target = v;
-    } else if (arg.startsWith("--target=")) {
-      execArgs.push(arg);
-      summary.target = arg.slice("--target=".length);
-    } else if (arg === "--platform") {
-      [v, i] = nextValue(argv, i, "--platform");
-      execArgs.push(arg, v);
-      summary.platform = v;
-    } else if (arg.startsWith("--platform=")) {
-      execArgs.push(arg);
-      summary.platform = arg.slice("--platform=".length);
-    } else if (arg === "--build-arg") {
-      [v, i] = nextValue(argv, i, "--build-arg");
-      execArgs.push(arg, v);
-      summary.build_args.push(v);
-    } else if (arg.startsWith("--build-arg=")) {
-      execArgs.push(arg);
-      summary.build_args.push(arg.slice("--build-arg=".length));
-    } else if (arg.startsWith("-")) {
-      execArgs.push(arg);
-    } else {
-      execArgs.push(arg);
-      summary.context = arg; // last non-flag positional wins
-    }
-  }
-
-  // Scopes matching a cache-to get the cache prefix applied so reads and
-  // writes target the same namespaced scope. Unmatched cache-from values pass
-  // through unchanged so they can read from a shared cache.
-  const toNames = new Set(rawCacheTo.map(cacheScopeName));
-  for (const c of rawCacheFrom) {
-    const rewritten = toNames.has(cacheScopeName(c)) ? normalizeCacheScope(c, cachePrefix) : c;
-    execArgs.push(`--cache-from=${rewritten}`);
-    summary.cache_from.push(rewritten);
-  }
-  for (const c of rawCacheTo) {
-    const rewritten = normalizeCacheScope(c, cachePrefix);
-    execArgs.push(`--cache-to=${rewritten}`);
-    summary.cache_to.push(rewritten);
-  }
-
-  return [execArgs, summary];
-}
-
-/** Print a build/bud summary to stderr. Only for build-like subcommands. */
-export function formatBuildSummary(engine: string, execArgs: string[], summary: BuildSummary): void {
-  // Skip leading flags and an optional "buildx" to find a build|bud
-  // subcommand; do not summarize other subcommands (e.g. push, pull).
-  let subcommand = "";
-  for (const arg of execArgs) {
-    if (arg.startsWith("-") || arg === "buildx") continue;
-    if (arg === "build" || arg === "bud") subcommand = arg;
-    break;
-  }
-  if (!subcommand) return;
-
-  const out = [`[${SELF}] build summary:`, `  engine: ${engine}`, `  subcommand: ${subcommand}`];
-  const list = (title: string, items: string[]) => {
-    if (items.length) out.push(`  ${title}:`, ...items.map((item) => `    - ${item}`));
-  };
-  list("tags", summary.tags);
-  list("cache-from", summary.cache_from);
-  list("cache-to", summary.cache_to);
-  if (summary.dockerfile) out.push(`  dockerfile: ${summary.dockerfile}`);
-  if (summary.target) out.push(`  target: ${summary.target}`);
-  if (summary.platform) out.push(`  platform: ${summary.platform}`);
-  list("build args", summary.build_args);
-  if (summary.context) out.push(`  context: ${summary.context}`);
-  out.push("");
-  sys.stderr.write(`${out.join("\n")}\n`);
-}
-
-/**
- * Rewrite args and exec the engine in place.
- *
- * Tag refs and cache scopes are normalized, then the wrapper is replaced by
- * the engine via execve so it inherits PID/exit code/signals.
- */
-export function enginePassthrough(engine: string, argv: string[], tagPrefix: string, cachePrefix: string): number {
-  // Validate/rewrite args first so input errors (bad tag, --cache with no
-  // value, non-ASCII) surface as exit 2 even when the engine binary is not
-  // installed.
-  const [execArgs, summary] = parseBuildArgs(argv, tagPrefix, cachePrefix);
-
-  ensureHelperOnPath();
-  if (!os.which(engine)) {
-    print(`Engine not found: ${engine}`, sys.stderr);
-    return 1;
-  }
-  if (!doWait([engine])) return 1;
-
-  formatBuildSummary(engine, execArgs, summary);
-
-  if (engine === "docker") os.execvp("docker", ["docker", ...execArgs]);
-  // podman / buildah: prefer gosu if present so we drop privileges first.
-  if (os.which("gosu")) {
-    const user = process.env.USER ?? "";
-    if (!user) {
-      print(
-        "ce: gosu is available but USER is not set; cannot drop privileges. Set USER or remove gosu from PATH.",
-        sys.stderr,
-      );
-      return 1;
-    }
-    os.execvp("gosu", ["gosu", user, engine, ...execArgs]);
-  }
-  return os.execvp(engine, [engine, ...execArgs]);
-}
-
-export async function main(argv: string[]): Promise<number> {
-  if (argv.length === 0) {
-    sys.stderr.write(helpText());
-    return 0;
-  }
-
-  let tagPrefix = process.env.TAG_PREFIX ?? "";
-  // Honor an explicitly empty CACHE_PREFIX rather than falling back to TAG_PREFIX.
-  let cachePrefix = process.env.CACHE_PREFIX ?? process.env.TAG_PREFIX ?? "";
-
-  while (argv.length) {
-    const a = argv[0]!;
-    if (a === "--tag-prefix") {
-      [tagPrefix, argv] = consumeValue(argv.slice(1), "--tag-prefix");
-    } else if (a.startsWith("--tag-prefix=")) {
-      tagPrefix = a.slice("--tag-prefix=".length);
-      argv = argv.slice(1);
-    } else if (a === "--cache-prefix") {
-      [cachePrefix, argv] = consumeValue(argv.slice(1), "--cache-prefix");
-    } else if (a.startsWith("--cache-prefix=")) {
-      cachePrefix = a.slice("--cache-prefix=".length);
-      argv = argv.slice(1);
-    } else {
-      break;
-    }
-  }
-
-  if (argv.length === 0) {
-    sys.stderr.write(helpText());
-    return 0;
-  }
-
-  const [command, ...rest] = argv as [string, ...string[]];
-  if (command === "login") return cmdLogin();
-  if (command === "credential-helper") return cmdCredentialHelper(rest);
-  if (command === "docker" || command === "podman" || command === "buildah") {
-    return enginePassthrough(command, rest, tagPrefix, cachePrefix);
-  }
-
-  sys.stderr.write(helpText());
-  return 1;
-}
-
-/** Entry point for the bin scripts: run `main` and exit with its status. */
-export async function entry(argv: string[]): Promise<never> {
-  try {
-    process.exit(await main(argv));
-  } catch (exc) {
-    // ValueErrors carry a clear message; surface it cleanly instead of as a
-    // stack trace.
-    if (!(exc instanceof ValueError)) throw exc;
-    print(exc.message, sys.stderr);
-    process.exit(2);
-  }
-}