@izykitten/ce 0.0.1

package/README.md

@@ -0,0 +1,50 @@
+# @izykitten/ce
+
+Container engine wrapper for CI: registry login (including Forgejo OIDC), tag and cache rewriting for `docker`, `podman` and `buildah`, and a Docker credential helper that refreshes the Forgejo token.
+
+A Bun port of the Python `ce` script from the `code.izy.sh/library/runner` image. Same commands, flags, environment variables, messages, exit codes and on-disk files, so a workflow only has to swap `ce` for `bunx`. Any job with Bun and an engine CLI can use it; it no longer needs the runner image.
+
+## Usage
+
+```sh
+bunx @izykitten/ce login
+bunx @izykitten/ce docker buildx build --push --cache type=gha,mode=max -t "$SERVER/$REPO:$REF,latest" .
+```
+
+When installed as a dependency, call it as `ce` (`bunx ce …`). Run `ce` with no arguments for the full help, including every environment variable `login` reads.
+
+In a Forgejo workflow:
+
+```yaml
+- uses: oven-sh/setup-bun@v2
+- name: Log in to Registry
+  env:
+    REGISTRY_USER: ${{ forgejo.actor }}
+    REGISTRY_PASSWORD: ${{ secrets.REGISTRY_TOKEN }}
+    REGISTRY_HOST: ${{ forgejo.server_url }}
+  run: bunx @izykitten/ce login
+- name: Container Build & Push
+  run: bunx @izykitten/ce docker buildx build --push -t ${{ forgejo.server_url }}/${{ forgejo.repository }}:${{ forgejo.ref_name }} .
+```
+
+## The credential helper
+
+With `AUD` set (and `enable-openid-connect: true` on the job), `ce login` logs in to the Forgejo registry with a short-lived OIDC token. It then writes `"credHelpers": {"<host>": "ce-forgejo"}` to the Docker config. From then on, Docker gets credentials for that host by running `docker-credential-ce-forgejo get`, which returns the saved token or fetches a fresh one when it is within five minutes of expiry. That is what lets a long build still push.
+
+The package installs `docker-credential-ce-forgejo` next to `ce`. `ce` puts that directory on `PATH` for the engines it starts, so `ce docker …` finds the helper. A plain `docker` command in a later step does not get that `PATH`, so run pushes to an OIDC registry through `ce`.
+
+## Differences from the Python version
+
+- Replacing the process with the engine (`execvp`) and the state-file lock (`flock`) go through `bun:ffi` to libc, since Bun has no API for either. Tested on glibc (Debian) and musl (Alpine). It takes the same kernel lock as the Python version, so both can share a Docker config.
+- The `Usage:` line shows the absolute path of the script, because Bun reports it that way.
+- Error text that comes from the system, network or JSON parser is Bun's wording, not Python's (for example `ENOENT: no such file or directory` rather than `[Errno 2] No such file or directory`). Messages written by `ce` itself are unchanged.
+- `docker-credential-ce-forgejo` runs the helper code directly instead of `exec ce credential-helper`, so `ce` does not have to be on `PATH`.
+- JSON files keep the same structure and sorted keys. Numbers are written as JavaScript writes them (`4102444800` rather than `4102444800.0`), and non-ASCII characters are not `\u`-escaped.
+
+## Development
+
+```sh
+bun install
+bun test          # the ported test_ce.py suite plus process tests for exec and flock
+bun check
+```

package/bin/ce

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+import path from "node:path";
+import { entry } from "../src/ce.ts";
+
+// The wrapper is only meaningful when invoked as `ce`; reject any other basename.
+const self = path.basename(process.argv[1] ?? "");
+if (self !== "ce") {
+  process.stderr.write(`Unknown wrapper name: ${self}\n`);
+  process.exit(1);
+}
+
+await entry(process.argv.slice(2));

package/bin/docker-credential-ce-forgejo

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// Docker runs `docker-credential-<suffix>` for `"credHelpers": {"<host>": "ce-forgejo"}`.
+import { entry } from "../src/ce.ts";
+
+await entry(["credential-helper", ...process.argv.slice(2)]);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@izykitten/ce",
+  "version": "0.0.1",
+  "description": "Container engine wrapper: tag/cache rewriting for docker, podman and buildah, registry login, and a Forgejo OIDC Docker credential helper",
+  "type": "module",
+  "license": "UNLICENSED",
+  "public": true,
+  "bin": {
+    "ce": "bin/ce",
+    "docker-credential-ce-forgejo": "bin/docker-credential-ce-forgejo"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "devDependencies": {
+    "@types/bun": "1.4.3"
+  }
+}

package/src/ce.ts

@@ -0,0 +1,1189 @@
+/**
+ * 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);
+  }
+}

package/src/libc.ts

@@ -0,0 +1,104 @@
+// The two libc calls Bun has no API for: flock(2) and execve(2).
+//
+// - flock: the Python `ce` serializes credential-helper state with
+//   `fcntl.flock(<state>.lock, LOCK_EX)`. Taking the very same kernel lock (not
+//   a lockfile scheme) keeps this port mutually exclusive with a Python `ce`
+//   sharing the same ~/.docker, and the kernel drops it when a holder dies.
+// - execve: the Python `ce` ends with `os.execvp`, replacing itself with the
+//   engine so it keeps the PID, signals, TTY and exit status. A real execve does
+//   the same here, with no signal-forwarding or exit-code-relaying layer.
+//
+// libc is opened lazily so commands that never lock or exec (help, argument
+// errors) do not depend on bun:ffi.
+
+import { dlopen, FFIType, ptr, read } from "bun:ffi";
+
+const LIBC_CANDIDATES: Record<string, string[]> = {
+  // musl resolves these reserved names to its built-in libc as well.
+  linux: ["libc.so.6", "libc.so", "libc.musl-x86_64.so.1", "libc.musl-aarch64.so.1"],
+  darwin: ["libc.dylib", "/usr/lib/libSystem.B.dylib"],
+};
+
+const symbols = {
+  flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+  execve: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+  strerror: { args: [FFIType.i32], returns: FFIType.cstring },
+} as const;
+
+type Libc = ReturnType<typeof dlopen<typeof symbols>>["symbols"] & {
+  errnoLocation: () => number | null;
+};
+
+let cached: Libc | undefined;
+
+function libc(): Libc {
+  if (cached) return cached;
+  const errnoSymbol = process.platform === "darwin" ? "__error" : "__errno_location";
+  const errors: string[] = [];
+  for (const name of LIBC_CANDIDATES[process.platform] ?? ["libc.so.6"]) {
+    try {
+      const lib = dlopen(name, {
+        ...symbols,
+        [errnoSymbol]: { args: [], returns: FFIType.ptr },
+      });
+      const s = lib.symbols as unknown as Record<string, (...a: unknown[]) => unknown>;
+      cached = {
+        ...(lib.symbols as unknown as Libc),
+        errnoLocation: s[errnoSymbol] as () => number | null,
+      };
+      return cached;
+    } catch (exc) {
+      errors.push(`${name}: ${(exc as Error).message}`);
+    }
+  }
+  throw new Error(`ce: cannot load libc via bun:ffi (${errors.join("; ")})`);
+}
+
+/** The calling thread's errno, read right after a failed libc call. */
+export function errno(): number {
+  const location = libc().errnoLocation();
+  return location ? read.i32(location, 0) : 0;
+}
+
+/** strerror(3) text, as Python puts in "[Errno N] <text>". */
+export function strerror(code: number): string {
+  try {
+    return String(libc().strerror(code));
+  } catch {
+    return `Unknown error ${code}`;
+  }
+}
+
+export const LOCK_EX = 2;
+export const EINTR = 4;
+
+/** Blocking flock(2). Returns 0 or the failing errno (EINTR is retried, as Python's PEP 475 does). */
+export function flock(fd: number, operation: number): number {
+  for (;;) {
+    if (libc().flock(fd, operation) === 0) return 0;
+    const code = errno();
+    if (code !== EINTR) return code;
+  }
+}
+
+function cString(value: string): Buffer {
+  return Buffer.from(`${value}\0`, "utf8");
+}
+
+/**
+ * execve(2). Only returns on failure, with the errno. The buffers stay
+ * referenced until the call returns, so the pointers handed to libc are valid.
+ */
+export function execve(path: string, argv: string[], env: Record<string, string | undefined>): number {
+  const pathBuf = cString(path);
+  const argBufs = argv.map(cString);
+  const envBufs = Object.entries(env)
+    .filter((entry): entry is [string, string] => entry[1] !== undefined)
+    .map(([key, value]) => cString(`${key}=${value}`));
+  const argPtrs = new BigUint64Array(argBufs.length + 1);
+  argBufs.forEach((buf, i) => (argPtrs[i] = BigInt(ptr(buf))));
+  const envPtrs = new BigUint64Array(envBufs.length + 1);
+  envBufs.forEach((buf, i) => (envPtrs[i] = BigInt(ptr(buf))));
+  libc().execve(pathBuf, argPtrs, envPtrs);
+  return errno();
+}