@izykitten/ce 0.0.1 → 0.0.2

package/dist/ce.js

@@ -0,0 +1,946 @@
+// src/errors.ts
+class CeError extends Error {
+  name = "CeError";
+}
+function isErrno(exc, code) {
+  if (!(exc instanceof Error))
+    return false;
+  const actual = exc.code;
+  return typeof actual === "string" && (code === undefined || actual === code);
+}
+function errorMessage(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+
+// src/system.ts
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { setTimeout } from "node:timers/promises";
+var io = {
+  stdout: (text) => void fs.writeSync(1, text),
+  stderr: (text) => void fs.writeSync(2, text),
+  stdin: () => fs.readFileSync(0, "utf8"),
+  argv0: () => process.argv[1] ?? "ce"
+};
+function log(line) {
+  io.stdout(`${line}
+`);
+}
+function logError(line) {
+  io.stderr(`${line}
+`);
+}
+function childEnv() {
+  return Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+}
+function which(command) {
+  const candidates = command.includes("/") ? [command] : (process.env.PATH ?? "").split(path.delimiter).filter(Boolean).map((dir) => path.join(dir, command));
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      if (fs.statSync(candidate).isFile())
+        return candidate;
+    } catch {}
+  }
+  return null;
+}
+var system = {
+  which,
+  run(argv, input) {
+    const result = spawnSync(argv[0], argv.slice(1), {
+      input,
+      stdio: [input === undefined ? "ignore" : "pipe", "ignore", "pipe"],
+      env: childEnv(),
+      encoding: "utf8",
+      maxBuffer: Infinity
+    });
+    if (result.error)
+      throw result.error;
+    return { status: result.status ?? 1, stderr: result.stderr ?? "" };
+  },
+  sleep: (ms) => setTimeout(ms),
+  exec(file, argv) {
+    const resolved = system.which(file);
+    if (!resolved) {
+      logError(`ce: ${file} not found on PATH`);
+      return 1;
+    }
+    process.execve(resolved, argv, childEnv());
+    throw new Error(`execve returned for ${file}`);
+  }
+};
+function binDir() {
+  return fs.realpathSync(path.join(import.meta.dirname, "..", "bin"));
+}
+function ensureHelperOnPath() {
+  const dir = binDir();
+  const parts = (process.env.PATH ?? "").split(path.delimiter);
+  if (!parts.includes(dir))
+    process.env.PATH = [dir, ...parts].join(path.delimiter);
+}
+
+// src/tags.ts
+var INVALID_TAG_CHARS = /[^A-Za-z0-9_.\-]/gu;
+var INVALID_SCOPE_CHARS = /[^A-Za-z0-9_.:/\-]/gu;
+var RENOVATE_RE = /^(.*)\/renovate_(.*)$/u;
+var GHA_RE = /^type=gha(,mode=max)?(?:,scope=(.*))?$/u;
+var SEPARATORS = "-_.";
+function sanitizeChars(value, charRegex) {
+  return value.replace(charRegex, "_");
+}
+function assertAscii(label, value) {
+  for (const ch of value) {
+    const code = ch.codePointAt(0);
+    if (code >= 128) {
+      const hex = code.toString(16).toUpperCase().padStart(4, "0");
+      throw new CeError(`ce: refusing to sanitize non-ASCII character ${JSON.stringify(ch)} ` + `(U+${hex}) in ${label} ${JSON.stringify(value)} — rename the ref ` + `or pass an explicit ASCII tag.`);
+    }
+  }
+}
+function stripProto(value) {
+  return value.replace(/^https?:\/\//u, "");
+}
+function splitOnce(value, sep) {
+  const i = value.indexOf(sep);
+  return i < 0 ? [value, ""] : [value.slice(0, i), value.slice(i + sep.length)];
+}
+function sanitizeTag(value) {
+  assertAscii("tag", value);
+  value = stripProto(value);
+  let out = value;
+  if (value.includes(":")) {
+    const [repo, tag] = splitOnce(value, ":");
+    if (tag.includes("/")) {
+      const [first, rest] = splitOnce(tag, "/");
+      out = `${repo}/${sanitizeChars(first, INVALID_TAG_CHARS)}:${sanitizeChars(rest, INVALID_TAG_CHARS)}`;
+    } else {
+      out = `${repo}:${sanitizeChars(tag, INVALID_TAG_CHARS)}`;
+    }
+  }
+  const m = RENOVATE_RE.exec(out);
+  return m ? `${m[1]}/renovate:${m[2]}` : out;
+}
+function computeSafePrefix(prefix) {
+  assertAscii("tag prefix", prefix);
+  const p = sanitizeChars(prefix, INVALID_TAG_CHARS);
+  return p && !SEPARATORS.includes(p.at(-1)) ? `${p}-` : p;
+}
+function rewriteTagValue(value, tagPrefix) {
+  const v = stripProto(value);
+  if (!v.includes(":")) {
+    assertAscii("tag", v);
+    return [v];
+  }
+  const [repo, tags] = splitOnce(v, ":");
+  const safePrefix = computeSafePrefix(tagPrefix);
+  return tags.split(/[,\s]+/u).filter(Boolean).map((tag) => sanitizeTag(`${repo}:${safePrefix}${tag}`)).filter(Boolean);
+}
+function cacheScopeName(value) {
+  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);
+}
+function normalizeCacheScope(value, cachePrefix) {
+  const m = GHA_RE.exec(value);
+  if (!m)
+    return value;
+  if (!cachePrefix)
+    return value;
+  assertAscii("cache prefix", cachePrefix);
+  const prefix = sanitizeChars(cachePrefix, INVALID_TAG_CHARS);
+  let scope = splitOnce(cacheScopeName(value), ",")[0];
+  if (!scope) {
+    scope = prefix.replace(/[-_.]+$/u, "");
+  } else if (prefix) {
+    scope = SEPARATORS.includes(prefix.at(-1)) ? `${prefix}${scope}` : `${prefix}-${scope}`;
+  }
+  return m[1] ? `type=gha,mode=max,scope=${scope}` : `type=gha,scope=${scope}`;
+}
+
+// src/build-args.ts
+function consumeValue(argv, flag) {
+  if (argv.length === 0)
+    throw new CeError(`ce: ${flag} requires a value but none was provided.`);
+  const v = argv[0];
+  if (v.length > 1 && v.startsWith("-")) {
+    throw new CeError(`ce: ${flag} requires a value but the next token ${JSON.stringify(v)} looks like a flag.`);
+  }
+  return [v, argv.slice(1)];
+}
+var SUMMARIZED = {
+  "-f": "dockerfile",
+  "--file": "dockerfile",
+  "--target": "target",
+  "--platform": "platform",
+  "--build-arg": "buildArgs"
+};
+function parseBuildArgs(argv, tagPrefix, cachePrefix) {
+  const args = [];
+  const rawCacheFrom = [];
+  const rawCacheTo = [];
+  const summary = {
+    tags: [],
+    cacheFrom: [],
+    cacheTo: [],
+    buildArgs: [],
+    dockerfile: "",
+    target: "",
+    platform: "",
+    context: ""
+  };
+  const addTags = (value, flag) => {
+    const refs = rewriteTagValue(value, tagPrefix);
+    for (const ref of refs)
+      args.push(`${flag}${ref}`);
+    summary.tags.push(...refs);
+  };
+  const summarize = (flag, value) => {
+    const field = SUMMARIZED[flag];
+    if (field === "buildArgs")
+      summary.buildArgs.push(value);
+    else
+      summary[field] = value;
+  };
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    const [name, attached] = arg.startsWith("--") && arg.includes("=") ? splitAt(arg, "=") : [arg, undefined];
+    const next = () => consumeValue(argv.slice(++i), arg)[0];
+    if (arg === "-t")
+      addTags(next(), "-t");
+    else if (arg === "--tag")
+      addTags(next(), "--tag=");
+    else if (arg.startsWith("-t"))
+      addTags(arg.slice(2), "-t");
+    else if (name === "--tag")
+      addTags(attached, "--tag=");
+    else if (name === "--cache-from")
+      rawCacheFrom.push(attached ?? next());
+    else if (name === "--cache-to")
+      rawCacheTo.push(attached ?? next());
+    else if (name === "--cache") {
+      const v = attached ?? next();
+      rawCacheFrom.push(v);
+      rawCacheTo.push(v);
+    } else if (Object.hasOwn(SUMMARIZED, name)) {
+      const flag = name;
+      if (attached === undefined) {
+        const v = next();
+        args.push(arg, v);
+        summarize(flag, v);
+      } else {
+        args.push(arg);
+        summarize(flag, attached);
+      }
+    } else if (arg.startsWith("-f") && arg.length > 2) {
+      args.push(arg);
+      summary.dockerfile = arg.slice(2);
+    } else {
+      args.push(arg);
+      if (!arg.startsWith("-"))
+        summary.context = arg;
+    }
+  }
+  const toNames = new Set(rawCacheTo.map(cacheScopeName));
+  for (const c of rawCacheFrom) {
+    const rewritten = toNames.has(cacheScopeName(c)) ? normalizeCacheScope(c, cachePrefix) : c;
+    args.push(`--cache-from=${rewritten}`);
+    summary.cacheFrom.push(rewritten);
+  }
+  for (const c of rawCacheTo) {
+    const rewritten = normalizeCacheScope(c, cachePrefix);
+    args.push(`--cache-to=${rewritten}`);
+    summary.cacheTo.push(rewritten);
+  }
+  return { args, summary };
+}
+function splitAt(value, sep) {
+  const i = value.indexOf(sep);
+  return [value.slice(0, i), value.slice(i + 1)];
+}
+function printBuildSummary(engine, args, summary) {
+  const subcommand = args.find((arg) => !arg.startsWith("-") && arg !== "buildx");
+  if (subcommand !== "build" && subcommand !== "bud")
+    return;
+  const out = ["[ce] build summary:", `  engine: ${engine}`, `  subcommand: ${subcommand}`];
+  const list = (title, items) => {
+    if (items.length)
+      out.push(`  ${title}:`, ...items.map((item) => `    - ${item}`));
+  };
+  list("tags", summary.tags);
+  list("cache-from", summary.cacheFrom);
+  list("cache-to", summary.cacheTo);
+  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.buildArgs);
+  if (summary.context)
+    out.push(`  context: ${summary.context}`);
+  io.stderr(`${out.join(`
+`)}
+
+`);
+}
+
+// src/json.ts
+import { randomUUID } from "node:crypto";
+import fs2 from "node:fs";
+import path2 from "node:path";
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJsonFile(file, fallback) {
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(fs2.readFileSync(file)));
+  } catch (exc) {
+    if (isErrno(exc, "ENOENT"))
+      return fallback;
+    throw new CeError(`cannot read JSON file ${JSON.stringify(file)}: ${errorMessage(exc)}`);
+  }
+}
+function dumpJson(payload) {
+  return JSON.stringify(payload, (_key, value) => isObject(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : value);
+}
+function writePrivateJson(file, payload) {
+  const directory = path2.dirname(file);
+  fs2.mkdirSync(directory, { recursive: true, mode: 448 });
+  const temporary = path2.join(directory, `.ce-forgejo-${randomUUID().slice(0, 8)}`);
+  const fd = fs2.openSync(temporary, "wx", 384);
+  try {
+    try {
+      fs2.fchmodSync(fd, 384);
+      fs2.writeSync(fd, `${dumpJson(payload)}
+`);
+      fs2.fsyncSync(fd);
+    } finally {
+      fs2.closeSync(fd);
+    }
+    fs2.renameSync(temporary, file);
+  } finally {
+    fs2.rmSync(temporary, { force: true });
+  }
+}
+
+// src/url.ts
+function sameAuthority(a, b) {
+  return a[0] === b[0] && a[1] === b[1];
+}
+var SCHEME_RE = /^[a-z][a-z\d+.-]*:\/\//iu;
+function parseHttpUrl(value) {
+  const raw = value.trim();
+  if (!raw)
+    throw new CeError("empty URL or host");
+  let url;
+  try {
+    url = new URL(SCHEME_RE.test(raw) ? raw : `https://${raw}`);
+  } catch {
+    throw new CeError(`invalid URL or host ${JSON.stringify(value)}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new CeError(`unsupported URL scheme ${JSON.stringify(url.protocol.slice(0, -1))}`);
+  }
+  if (!url.hostname)
+    throw new CeError(`missing hostname in ${JSON.stringify(value)}`);
+  return url;
+}
+function urlAuthority(value) {
+  const url = parseHttpUrl(value);
+  const port = url.port ? Number(url.port) : url.protocol === "http:" ? 80 : 443;
+  return [url.hostname.replace(/^\[(.*)\]$/u, "$1"), port];
+}
+function assertAbsoluteHttpUrl(value, error) {
+  try {
+    if (!SCHEME_RE.test(value.trim()))
+      throw new CeError(error);
+    parseHttpUrl(value);
+  } catch {
+    throw new CeError(error);
+  }
+}
+function registryServer(value) {
+  const url = parseHttpUrl(value);
+  const authority = value.trim().replace(SCHEME_RE, "").split(/[/\\?#]/u, 1)[0].split("@").at(-1);
+  const port = url.port || /:(\d+)$/u.exec(authority)?.[1];
+  return port ? `${url.hostname}:${Number(port)}` : url.hostname;
+}
+function registryKey(value) {
+  return registryServer(value).toLowerCase();
+}
+
+// src/oidc.ts
+var REFRESH_WINDOW_S = 5 * 60;
+var REQUEST_TIMEOUT_MS = 30000;
+var decodeUtf8 = (bytes) => new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+async function forgejoOidcJwt(audience, requestUrl, requestToken) {
+  assertAbsoluteHttpUrl(requestUrl, "token request URL must be an absolute HTTP(S) URL");
+  let tokenUrl;
+  let headers;
+  try {
+    const url = new URL(requestUrl);
+    if (url.username || url.password)
+      throw new Error("credentials in URL");
+    url.searchParams.set("audience", audience);
+    tokenUrl = url.href;
+    headers = { Accept: "application/json", Authorization: `bearer ${requestToken}` };
+    new Headers(headers);
+  } catch {
+    throw new CeError("token request URL or headers are invalid");
+  }
+  let body;
+  try {
+    const response = await fetch(tokenUrl, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (!response.ok)
+      throw new Error(`HTTP ${response.status} ${response.statusText}`);
+    body = await response.arrayBuffer();
+  } catch (exc) {
+    throw new CeError(`token request failed: ${errorMessage(exc)}`);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(decodeUtf8(body));
+  } catch {
+    throw new CeError("token response is not valid UTF-8 JSON");
+  }
+  if (!isObject(payload))
+    throw new CeError("token response is not a JSON object");
+  const jwt = payload.value;
+  if (typeof jwt !== "string" || !jwt.trim()) {
+    throw new CeError("token response has no non-empty string 'value'");
+  }
+  return jwt.trim();
+}
+function jwtExpiry(jwt) {
+  const parts = jwt.split(".");
+  if (parts.length !== 3)
+    throw new CeError("OIDC token is not a three-part JWT");
+  let payload;
+  try {
+    payload = JSON.parse(decodeUtf8(Buffer.from(parts[1], "base64url")));
+  } catch {
+    throw new CeError("OIDC token has an invalid JWT payload");
+  }
+  const expiry = isObject(payload) ? payload.exp : undefined;
+  if (typeof expiry !== "number")
+    throw new CeError("OIDC token has no numeric 'exp' claim");
+  return expiry;
+}
+function needsRefresh(expiry) {
+  return expiry <= Date.now() / 1000 + REFRESH_WINDOW_S;
+}
+
+// src/state.ts
+import fs4 from "node:fs";
+import { homedir } from "node:os";
+import path3 from "node:path";
+
+// src/lock.ts
+import fs3 from "node:fs";
+import { hostname } from "node:os";
+import { setTimeout as setTimeout2 } from "node:timers/promises";
+var STALE_AFTER_MS = 120000;
+var POLL_MS = 50;
+function snapshot(lockPath) {
+  try {
+    const { ino, mtimeMs } = fs3.statSync(lockPath);
+    return { ino, mtimeMs, owner: fs3.readFileSync(lockPath, "utf8").trim() };
+  } catch (exc) {
+    if (isErrno(exc, "ENOENT"))
+      return null;
+    throw exc;
+  }
+}
+function isStale({ mtimeMs, owner }) {
+  if (Date.now() - mtimeMs > STALE_AFTER_MS)
+    return true;
+  const match = /^(\d+)@(.*)$/u.exec(owner);
+  if (!match || match[2] !== hostname())
+    return false;
+  try {
+    process.kill(Number(match[1]), 0);
+    return false;
+  } catch (exc) {
+    return !isErrno(exc, "EPERM");
+  }
+}
+function breakIfStale(lockPath) {
+  const stale = snapshot(lockPath);
+  if (!stale || !isStale(stale))
+    return;
+  const guard = `${lockPath}.break`;
+  try {
+    fs3.writeFileSync(guard, "", { flag: "wx", mode: 384 });
+  } catch (exc) {
+    if (!isErrno(exc, "EEXIST"))
+      throw exc;
+    const held = snapshot(guard);
+    if (held && Date.now() - held.mtimeMs > STALE_AFTER_MS) {
+      throw new CeError(`stale lock guard ${JSON.stringify(guard)}: remove it if no ce is running`);
+    }
+    return;
+  }
+  try {
+    const current = snapshot(lockPath);
+    if (current && current.ino === stale.ino && current.mtimeMs === stale.mtimeMs && current.owner === stale.owner) {
+      fs3.rmSync(lockPath, { force: true });
+    }
+  } finally {
+    fs3.rmSync(guard, { force: true });
+  }
+}
+async function withFileLock(lockPath, fn) {
+  const owner = `${process.pid}@${hostname()}`;
+  let ino;
+  for (;; ) {
+    let fd;
+    try {
+      fd = fs3.openSync(lockPath, "wx", 384);
+    } catch (exc) {
+      if (!isErrno(exc, "EEXIST"))
+        throw exc;
+      breakIfStale(lockPath);
+      await setTimeout2(POLL_MS);
+      continue;
+    }
+    try {
+      fs3.writeSync(fd, `${owner}
+`);
+      ino = fs3.fstatSync(fd).ino;
+    } finally {
+      fs3.closeSync(fd);
+    }
+    break;
+  }
+  try {
+    return await fn();
+  } finally {
+    const current = snapshot(lockPath);
+    if (current?.ino === ino && current.owner === owner)
+      fs3.rmSync(lockPath, { force: true });
+  }
+}
+
+// src/state.ts
+var HELPER_SUFFIX = "ce-forgejo";
+var STATE_FILE = "ce-forgejo-credentials.json";
+function dockerConfigDir() {
+  const configured = process.env.DOCKER_CONFIG;
+  if (!configured)
+    return path3.join(homedir(), ".docker");
+  const expanded = configured === "~" || configured.startsWith("~/") ? path3.join(homedir(), configured.slice(1)) : configured;
+  return path3.resolve(expanded);
+}
+function helperStatePath() {
+  return path3.join(dockerConfigDir(), STATE_FILE);
+}
+async function withHelperState(fn) {
+  const statePath = helperStatePath();
+  fs4.mkdirSync(path3.dirname(statePath), { recursive: true, mode: 448 });
+  return withFileLock(`${statePath}.pidlock`, async () => {
+    const state = readJsonFile(statePath, { version: 1, registries: {} });
+    if (!isObject(state) || !isObject(state.registries)) {
+      throw new CeError("Forgejo credential-helper state is invalid");
+    }
+    const before = JSON.stringify(state);
+    const result = await fn(state);
+    if (JSON.stringify(state) !== before)
+      writePrivateJson(statePath, state);
+    return result;
+  });
+}
+async function saveHelperState(registry, username, audience, authority, jwt) {
+  const expiry = jwtExpiry(jwt);
+  if (needsRefresh(expiry))
+    throw new CeError("OIDC token expires within the five-minute refresh window");
+  await withHelperState((state) => {
+    state.registries[registryKey(registry)] = {
+      audience,
+      authority: [authority[0], authority[1]],
+      expires_at: expiry,
+      token: jwt,
+      username
+    };
+  });
+}
+async function configureDockerCredentialHelper(registry, username, audience, authority, jwt) {
+  await saveHelperState(registry, username, audience, authority, jwt);
+  const configPath = path3.join(dockerConfigDir(), "config.json");
+  const config = readJsonFile(configPath, {});
+  if (!isObject(config))
+    throw new CeError("Docker config is not a JSON object");
+  config.credHelpers ??= {};
+  const helpers = config.credHelpers;
+  if (!isObject(helpers))
+    throw new CeError("Docker config 'credHelpers' is not a JSON object");
+  helpers[registry] = HELPER_SUFFIX;
+  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);
+}
+
+// src/credential-helper.ts
+async function helperGet(registry) {
+  const key = registryKey(registry);
+  return withHelperState(async (state) => {
+    const entry = state.registries[key];
+    if (!isObject(entry)) {
+      throw new CeError(`no Forgejo OIDC credentials configured for ${JSON.stringify(registry)}`);
+    }
+    const { username, token, expires_at: expiry } = entry;
+    if (typeof username !== "string" || !username) {
+      throw new CeError("Forgejo credential-helper username is missing");
+    }
+    if (typeof token !== "string" || typeof expiry !== "number") {
+      throw new CeError("Forgejo credential-helper token state is invalid");
+    }
+    if (!needsRefresh(expiry))
+      return { Username: username, Secret: token };
+    const { audience, authority } = 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 CeError("Forgejo credential-helper audience is missing");
+    }
+    if (!(requestUrl && requestToken)) {
+      throw new CeError("OIDC refresh requires ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN");
+    }
+    const [host, port] = urlAuthority(requestUrl);
+    if (!Array.isArray(authority) || authority.length !== 2 || authority[0] !== host || authority[1] !== port) {
+      throw new CeError("OIDC token-request host does not match the registry");
+    }
+    const refreshed = await forgejoOidcJwt(audience, requestUrl, requestToken);
+    const refreshedExpiry = jwtExpiry(refreshed);
+    if (needsRefresh(refreshedExpiry)) {
+      throw new CeError("refreshed OIDC token expires within the five-minute window");
+    }
+    entry.token = refreshed;
+    entry.expires_at = refreshedExpiry;
+    return { Username: username, Secret: refreshed };
+  });
+}
+async function helperStore(input) {
+  const payload = JSON.parse(input);
+  if (!isObject(payload))
+    throw new CeError("credential-helper store payload is invalid");
+  const { ServerURL: registry, Username: username, Secret: secret } = payload;
+  const filled = (value) => typeof value === "string" && value !== "";
+  if (!(filled(registry) && filled(username) && filled(secret))) {
+    throw new CeError("credential-helper store fields are incomplete");
+  }
+  const expiry = jwtExpiry(secret);
+  await withHelperState((state) => {
+    const entry = state.registries[registryKey(registry)] ??= {};
+    Object.assign(entry, { expires_at: expiry, token: secret, username });
+  });
+}
+async function credentialHelper(argv) {
+  const [command] = argv;
+  if (argv.length !== 1 || !["get", "store", "erase", "list"].includes(command)) {
+    logError("ce: credential-helper requires get|store|erase|list");
+    return 1;
+  }
+  try {
+    if (command === "get") {
+      io.stdout(`${JSON.stringify(await helperGet(io.stdin().trim()))}
+`);
+    } else if (command === "store") {
+      await helperStore(io.stdin());
+    } else if (command === "erase") {
+      const key = registryKey(io.stdin().trim());
+      await withHelperState((state) => void delete state.registries[key]);
+    } else {
+      const entries = await withHelperState((state) => Object.fromEntries(Object.entries(state.registries).filter(([, entry]) => isObject(entry)).map(([key, entry]) => [key, entry.username ?? ""])));
+      io.stdout(`${JSON.stringify(entries)}
+`);
+    }
+    return 0;
+  } catch (exc) {
+    if (!(exc instanceof CeError || exc instanceof SyntaxError || isErrno(exc)))
+      throw exc;
+    logError(`ce: Forgejo credential helper: ${errorMessage(exc)}`);
+    return 1;
+  }
+}
+
+// src/engine.ts
+var isEngine = (value) => ["docker", "podman", "buildah"].includes(value);
+var WAIT_ATTEMPTS = 30;
+async function waitForEngine(engine) {
+  if (engine === "buildah")
+    return true;
+  for (let attempt = 1;attempt <= WAIT_ATTEMPTS; attempt++) {
+    if (system.run([engine, "info"]).status === 0)
+      return true;
+    logError(`waiting for ${engine}... (${attempt}/${WAIT_ATTEMPTS})`);
+    await system.sleep(1000);
+  }
+  logError(`no engine available: ${engine}`);
+  return false;
+}
+async function runEngine(engine, argv, tagPrefix, cachePrefix) {
+  const { args, summary } = parseBuildArgs(argv, tagPrefix, cachePrefix);
+  ensureHelperOnPath();
+  if (!system.which(engine)) {
+    logError(`Engine not found: ${engine}`);
+    return 1;
+  }
+  if (!await waitForEngine(engine))
+    return 1;
+  printBuildSummary(engine, args, summary);
+  if (engine === "docker")
+    return system.exec("docker", ["docker", ...args]);
+  if (system.which("gosu")) {
+    const user = process.env.USER ?? "";
+    if (!user) {
+      logError("ce: gosu is available but USER is not set; cannot drop privileges. Set USER or remove gosu from PATH.");
+      return 1;
+    }
+    return system.exec("gosu", ["gosu", user, engine, ...args]);
+  }
+  return system.exec(engine, [engine, ...args]);
+}
+
+// src/login.ts
+var ENGINES = ["docker", "podman", "buildah"];
+function registryGroups() {
+  const prefix = "REGISTRY_HOST__";
+  const suffixed = Object.keys(process.env).filter((name) => name.startsWith(prefix) && name.length > prefix.length).sort().map((name) => name.slice(prefix.length));
+  return [...process.env.REGISTRY_HOST ? [""] : [], ...suffixed];
+}
+function oidcConfig() {
+  const audience = process.env.AUD ?? "";
+  if (!audience)
+    return null;
+  const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL ?? "";
+  const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN ?? "";
+  if (!(requestUrl && requestToken)) {
+    return "Forgejo OIDC login config is incomplete: AUD requires ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN";
+  }
+  try {
+    assertAbsoluteHttpUrl(requestUrl, "must be an absolute HTTP(S) URL");
+    return { audience, requestUrl, requestToken, authority: urlAuthority(requestUrl) };
+  } catch (exc) {
+    if (!(exc instanceof CeError))
+      throw exc;
+    return `Invalid ACTIONS_ID_TOKEN_REQUEST_URL: ${exc.message}`;
+  }
+}
+function loginWithEngines(target, password) {
+  for (const engine of ENGINES) {
+    if (!system.which(engine))
+      continue;
+    let result;
+    try {
+      result = system.run([engine, "login", "-u", target.user, "--password-stdin", target.registry], `${password}
+`);
+    } catch (exc) {
+      if (isErrno(exc, "ENOENT"))
+        continue;
+      throw exc;
+    }
+    if (result.status === 0)
+      return engine;
+    logError(`${engine} login failed for '${target.label}' (${target.registry}):`);
+    io.stderr(result.stderr);
+  }
+  return null;
+}
+async function login() {
+  ensureHelperOnPath();
+  const groups = registryGroups();
+  if (groups.length === 0) {
+    log("Skipping login: no REGISTRY_HOST env vars set");
+    return 0;
+  }
+  const oidc = oidcConfig();
+  if (typeof oidc === "string") {
+    logError(oidc);
+    return 1;
+  }
+  const targets = [];
+  let failed = false;
+  for (const group of groups) {
+    const suffix = group ? `__${group}` : "";
+    const host = process.env[`REGISTRY_HOST${suffix}`] ?? "";
+    const user = process.env[`REGISTRY_USER${suffix}`] ?? "";
+    const password = process.env[`REGISTRY_PASSWORD${suffix}`] ?? "";
+    const label = group || "default";
+    const incomplete = `Login config for '${label}' is incomplete: host/user/password not all set`;
+    if (!(host && user)) {
+      logError(incomplete);
+      failed = true;
+      continue;
+    }
+    for (const rawRegistry of host.split(/\s+/u).filter(Boolean)) {
+      let authority;
+      let registry;
+      try {
+        authority = urlAuthority(rawRegistry);
+        registry = registryServer(rawRegistry);
+      } catch (exc) {
+        if (!(exc instanceof CeError))
+          throw exc;
+        logError(`Invalid registry host for '${label}' (${rawRegistry}): ${exc.message}`);
+        failed = true;
+        continue;
+      }
+      const useOidc = oidc !== null && sameAuthority(authority, oidc.authority);
+      if (!useOidc && !password) {
+        logError(incomplete);
+        failed = true;
+        continue;
+      }
+      targets.push({ registry, label, user, password, useOidc });
+    }
+  }
+  let jwt = null;
+  if (oidc && targets.some((target) => target.useOidc)) {
+    try {
+      jwt = await forgejoOidcJwt(oidc.audience, oidc.requestUrl, oidc.requestToken);
+    } catch (exc) {
+      if (!(exc instanceof CeError))
+        throw exc;
+      logError(`Failed to fetch Forgejo OIDC JWT: ${exc.message}`);
+      return 1;
+    }
+  }
+  for (const target of targets) {
+    const { registry, label } = target;
+    const password = target.useOidc ? jwt : target.password;
+    if (password === null) {
+      logError(`Forgejo OIDC JWT unavailable for '${label}' (${registry})`);
+      failed = true;
+      continue;
+    }
+    log(`Logging in to ${registry} (${label})...`);
+    const engine = loginWithEngines(target, password);
+    if (!engine) {
+      logError(`Login failed for '${label}' (${registry})`);
+      failed = true;
+      continue;
+    }
+    log(`Logged in to ${registry} (${label}) via ${engine} ` + `(and all engines at or below it: docker < podman < buildah share credentials)`);
+    if (target.useOidc && oidc && jwt) {
+      try {
+        await configureDockerCredentialHelper(registry, target.user, oidc.audience, oidc.authority, jwt);
+      } catch (exc) {
+        if (!(exc instanceof CeError || isErrno(exc)))
+          throw exc;
+        logError(`Failed to configure Forgejo credential helper for '${label}' (${registry}): ${errorMessage(exc)}`);
+        failed = true;
+      }
+    }
+  }
+  return failed ? 1 : 0;
+}
+
+// src/cli.ts
+function helpText() {
+  return `Usage: ${io.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.
+`;
+}
+async function main(argv) {
+  let tagPrefix = process.env.TAG_PREFIX ?? "";
+  let cachePrefix = process.env.CACHE_PREFIX ?? process.env.TAG_PREFIX ?? "";
+  for (;; ) {
+    const a = argv[0];
+    if (a === "--tag-prefix")
+      [tagPrefix, argv] = consumeValue(argv.slice(1), a);
+    else if (a?.startsWith("--tag-prefix="))
+      [tagPrefix, argv] = [a.slice("--tag-prefix=".length), argv.slice(1)];
+    else if (a === "--cache-prefix")
+      [cachePrefix, argv] = consumeValue(argv.slice(1), a);
+    else if (a?.startsWith("--cache-prefix="))
+      [cachePrefix, argv] = [a.slice("--cache-prefix=".length), argv.slice(1)];
+    else
+      break;
+  }
+  const [command, ...rest] = argv;
+  if (command === undefined) {
+    io.stderr(helpText());
+    return 0;
+  }
+  if (command === "login")
+    return login();
+  if (command === "credential-helper")
+    return credentialHelper(rest);
+  if (isEngine(command))
+    return runEngine(command, rest, tagPrefix, cachePrefix);
+  io.stderr(helpText());
+  return 1;
+}
+async function entry(argv) {
+  try {
+    process.exit(await main(argv));
+  } catch (exc) {
+    if (!(exc instanceof CeError))
+      throw exc;
+    logError(exc.message);
+    process.exit(2);
+  }
+}
+export {
+  entry,
+  helpText,
+  main
+};