@izykitten/ce 0.0.2 → 0.0.3-dev.0

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2026 izy
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -24,9 +24,58 @@ In a Forgejo workflow:
     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 }} .
+  run: bunx @izykitten/ce docker buildx build --push -t '{image}:{ref},{?default}latest' .
 ```
 
+Only build commands are rewritten: `build`, `buildx build` and `image build` for Docker and Podman, `build` and `bud` for Buildah, and the tags of `docker buildx imagetools create`. Everything else, such as `docker run -t`, reaches the engine unchanged.
+
+## Tags from the Forgejo run
+
+Tags and the `TAG_PREFIX`/`CACHE_PREFIX` values can use placeholders, filled from the Forgejo Actions environment and its event file. ce makes no API calls and does not look at the checkout.
+
+| Placeholder | Value |
+|---|---|
+| `{image}` | registry host and repository, lowercased, e.g. `code.izy.sh/library/gateway` |
+| `{ref}` | the branch name, `pr-<number>` for a pull request, or the tag name |
+| `{branch}`, `{pr}`, `{tag}` | the branch, PR number or tag, set only when building that kind of ref |
+| `{default}` | set only when building the default branch, never for a pull request |
+| `{revision}`, `{sha}` | the commit, in full and as its first 7 characters |
+| `{version}`, `{major}`, `{minor}`, `{patch}` | from a SemVer tag such as `v1.2.3` or `1.2.3-rc.1` |
+| `{stable}` | set only for a SemVer tag without a pre-release |
+| `{env.NAME}` | the environment variable `NAME`, e.g. a value from an earlier step |
+
+`{name}` must have a value (an empty variable has none): if it has none in this run, ce fails with exit 2 before anything runs. To leave a tag out instead, guard it with `{?name}`, which expands to nothing and keeps the tag only when `name` has a value. Every guard in a tag has to pass, and a tag's other values are only needed when it is kept. Names are checked in every tag, so a typo fails even in one a guard leaves out. If the guards leave out every tag, ce fails rather than build an untagged image.
+
+Values are made safe for a tag: any ASCII character a tag cannot have becomes `-`, so branch `ci/modernize-build` gives `ci-modernize-build`; a non-ASCII character is an error. A value never adds a tag or changes the image name. Prefixes can use `{name}` but not guards.
+
+Guards decide from the run's metadata, so they need it too: outside a Forgejo Actions run, or with its event file missing `repository.default_branch`, `{?default}` fails like `{default}` would. Only `{env.NAME}` works everywhere.
+
+Put templates in single quotes: `?` is a glob character in zsh.
+
+A branch, PR and default-branch build:
+
+```yaml
+- name: Container Build & Push
+  env:
+    CACHE_PREFIX: '{ref}'
+    CADDY_VERSION: ${{ steps.caddy.outputs.version }}
+  run: >
+    bunx @izykitten/ce docker buildx build --push --cache type=gha,mode=max
+    -t '{image}:{ref},{?default}latest,{?default}caddy-{env.CADDY_VERSION}' .
+```
+
+A release on a SemVer tag, with the version aliases only for stable releases:
+
+```sh
+-t '{image}:{ref},{?version}{version},{?stable}{major}.{minor},{?stable}{major},sha-{sha}'
+```
+
+`{stable}` does not mean newest: rebuilding an older release moves its aliases back to it.
+
+### OCI labels
+
+With `OCI_LABELS=true`, or `--oci-labels` before the engine (`ce --oci-labels docker buildx build …`, like the prefix options), builds get `org.opencontainers.image.source`, `revision`, `version`, `title` and `description` labels from the run. Labels the run cannot tell are left out. They override a Dockerfile `LABEL` with the same key, and a `--label` you pass wins over them. `created` is not set, so the labels do not change the image on every rebuild.
+
 ## 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.

package/dist/ce.js

@@ -1,3 +1,116 @@
+// src/command.ts
+var VALUE_OPTIONS = {
+  docker: {
+    long: new Set(["config", "context", "host", "log-level", "tlscacert", "tlscert", "tlskey", "builder"]),
+    short: "cHl"
+  },
+  podman: {
+    long: new Set([
+      "cdi-spec-dir",
+      "cgroup-manager",
+      "cni-config-dir",
+      "config",
+      "conmon",
+      "connection",
+      "context",
+      "cpu-profile",
+      "db-backend",
+      "default-mounts-file",
+      "events-backend",
+      "hooks-dir",
+      "host",
+      "identity",
+      "imagestore",
+      "log-level",
+      "max-workers",
+      "memory-profile",
+      "module",
+      "namespace",
+      "network-backend",
+      "network-cmd-path",
+      "network-config-dir",
+      "out",
+      "pull-option",
+      "registries-conf",
+      "root",
+      "runroot",
+      "runtime",
+      "runtime-flag",
+      "ssh",
+      "storage-driver",
+      "storage-opt",
+      "tmpdir",
+      "url",
+      "volumepath"
+    ]),
+    short: "cH"
+  },
+  buildah: {
+    long: new Set([
+      "cgroup-manager",
+      "cpu-profile",
+      "default-mounts-file",
+      "experimental-timeout",
+      "imagestore",
+      "log-level",
+      "memory-profile",
+      "registries-conf",
+      "registries-conf-dir",
+      "root",
+      "runroot",
+      "short-name-alias-conf",
+      "storage-driver",
+      "storage-opt",
+      "userns-gid-map",
+      "userns-uid-map"
+    ]),
+    short: ""
+  }
+};
+function takesNext(engine, arg) {
+  const options = VALUE_OPTIONS[engine];
+  if (arg.startsWith("--"))
+    return options.long.has(arg.slice(2));
+  for (let j = 1;j < arg.length; j++) {
+    if (options.short.includes(arg[j]))
+      return j === arg.length - 1;
+  }
+  return false;
+}
+var COMMANDS = {
+  docker: [
+    { words: ["build"] },
+    { words: ["image", "build"] },
+    { words: ["builder", "build"] },
+    { words: ["buildx", "build"] },
+    { words: ["buildx", "b"] },
+    { words: ["buildx", "imagetools", "create"], tagsOnly: true }
+  ],
+  podman: [{ words: ["build"] }, { words: ["image", "build"] }, { words: ["buildx", "build"] }],
+  buildah: [{ words: ["build"] }, { words: ["bud"] }]
+};
+function findBuildCommand(engine, argv) {
+  const words = [];
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--")
+      return null;
+    if (arg.startsWith("-")) {
+      if (takesNext(engine, arg))
+        i++;
+      continue;
+    }
+    words.push(arg);
+    const candidates = COMMANDS[engine].filter((command) => words.every((word, j) => command.words[j] === word));
+    const match = candidates.find((command) => command.words.length === words.length);
+    if (match)
+      return { start: i + 1, name: arg, tagsOnly: match.tagsOnly ?? false };
+    if (!candidates.length)
+      return null;
+  }
+  return null;
+}
+
 // src/errors.ts
 class CeError extends Error {
   name = "CeError";
@@ -12,15 +125,274 @@ function errorMessage(exc) {
   return exc instanceof Error ? exc.message : String(exc);
 }
 
-// src/system.ts
-import { spawnSync } from "node:child_process";
+// src/json.ts
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path 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(fs.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 = path.dirname(file);
+  fs.mkdirSync(directory, { recursive: true, mode: 448 });
+  const temporary = path.join(directory, `.ce-forgejo-${randomUUID().slice(0, 8)}`);
+  const fd = fs.openSync(temporary, "wx", 384);
+  try {
+    try {
+      fs.fchmodSync(fd, 384);
+      fs.writeSync(fd, `${dumpJson(payload)}
+`);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.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/metadata.ts
+var CI_VARIABLES = [
+  "image",
+  "ref",
+  "branch",
+  "pr",
+  "tag",
+  "default",
+  "revision",
+  "sha",
+  "version",
+  "major",
+  "minor",
+  "patch",
+  "stable"
+];
+var ENV_VARIABLE = /^env\.([A-Za-z_][A-Za-z0-9_]*)$/u;
+var SEMVER = /^v?((0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?)$/u;
+var nonEmpty = (value) => value ? value : undefined;
+
+class CiMetadata {
+  #env;
+  #cache = new Map;
+  #ref;
+  #event;
+  constructor(env = process.env) {
+    this.#env = env;
+  }
+  known(name) {
+    return CI_VARIABLES.includes(name) || ENV_VARIABLE.test(name);
+  }
+  get(name) {
+    const envName = ENV_VARIABLE.exec(name)?.[1];
+    if (envName)
+      return nonEmpty(this.#env[envName]);
+    if (!this.#cache.has(name))
+      this.#cache.set(name, this.#resolve(name));
+    return this.#cache.get(name);
+  }
+  labels() {
+    const labels = {};
+    const add = (key, value) => {
+      try {
+        const v = value();
+        if (v)
+          labels[`org.opencontainers.image.${key}`] = v;
+      } catch (exc) {
+        if (!(exc instanceof CeError))
+          throw exc;
+      }
+    };
+    const server = nonEmpty(this.#ciEnv("SERVER_URL"))?.replace(/\/+$/u, "");
+    const repository = nonEmpty(this.#ciEnv("REPOSITORY"));
+    add("source", () => server && repository ? `${server}/${repository}` : undefined);
+    add("revision", () => this.#ciEnv("SHA"));
+    add("version", () => this.get("version") ?? this.#rawRef());
+    add("title", () => repository?.split("/").at(-1));
+    add("description", () => {
+      const repo = this.#payload().repository;
+      return isObject(repo) && typeof repo.description === "string" ? repo.description : undefined;
+    });
+    return labels;
+  }
+  #resolve(name) {
+    switch (name) {
+      case "image": {
+        const server = this.#require("SERVER_URL", "{image}");
+        const repository = this.#require("REPOSITORY", "{image}");
+        return `${registryServer(server)}/${repository}`.toLowerCase();
+      }
+      case "ref":
+        return this.#rawRef();
+      case "branch": {
+        const ref = this.#parsedRef();
+        return ref.kind === "branch" ? ref.name : undefined;
+      }
+      case "tag": {
+        const ref = this.#parsedRef();
+        return ref.kind === "tag" ? ref.name : undefined;
+      }
+      case "pr": {
+        const ref = this.#parsedRef();
+        return ref.kind === "pr" ? ref.number : undefined;
+      }
+      case "default": {
+        const ref = this.#parsedRef();
+        if (ref.kind !== "branch")
+          return;
+        return ref.name === this.#defaultBranch() ? ref.name : undefined;
+      }
+      case "revision":
+        return this.#require("SHA", `{${name}}`);
+      case "sha":
+        return this.#require("SHA", `{${name}}`).slice(0, 7);
+      case "version":
+        return this.#semver()?.[1];
+      case "major":
+        return this.#semver()?.[2];
+      case "minor":
+        return this.#semver()?.[3];
+      case "patch":
+        return this.#semver()?.[4];
+      case "stable": {
+        const semver = this.#semver();
+        return semver && semver[5] === undefined ? semver[1] : undefined;
+      }
+    }
+    throw new CeError(`ce: unknown placeholder {${name}}`);
+  }
+  #ciEnv(name) {
+    return nonEmpty(this.#env[`FORGEJO_${name}`]) ?? nonEmpty(this.#env[`GITHUB_${name}`]);
+  }
+  #require(name, user) {
+    const value = this.#ciEnv(name);
+    if (!value) {
+      throw new CeError(`ce: ${user} needs GITHUB_${name} (or FORGEJO_${name}), which is not set; is this a Forgejo Actions run?`);
+    }
+    return value;
+  }
+  #rawRef() {
+    const ref = this.#parsedRef();
+    return ref.kind === "pr" ? `pr-${ref.number}` : ref.name;
+  }
+  #parsedRef() {
+    if (this.#ref)
+      return this.#ref;
+    const ref = this.#require("REF", "{ref}, {branch}, {tag} or {pr}");
+    const event = this.#ciEnv("EVENT_NAME") ?? "";
+    const pull = /^refs\/pull\/(\d+)\//u.exec(ref);
+    if (event.startsWith("pull_request") || pull) {
+      const payload = pull ? {} : this.#payload();
+      const fromPayload = [isObject(payload.pull_request) && payload.pull_request.number, payload.number].find(Number.isInteger);
+      const number = pull?.[1] ?? (fromPayload === undefined ? undefined : String(fromPayload));
+      if (!number)
+        throw new CeError(`ce: cannot find the pull request number for ${event} on ${ref}`);
+      this.#ref = { kind: "pr", number };
+    } else if (ref.startsWith("refs/heads/")) {
+      this.#ref = { kind: "branch", name: ref.slice("refs/heads/".length) };
+    } else if (ref.startsWith("refs/tags/")) {
+      this.#ref = { kind: "tag", name: ref.slice("refs/tags/".length) };
+    } else {
+      throw new CeError(`ce: cannot tell what ${JSON.stringify(ref)} is: not a branch, tag or pull request`);
+    }
+    return this.#ref;
+  }
+  #semver() {
+    const ref = this.#parsedRef();
+    return ref.kind === "tag" ? SEMVER.exec(ref.name) : null;
+  }
+  #defaultBranch() {
+    const repository = this.#payload().repository;
+    const branch = isObject(repository) ? repository.default_branch : undefined;
+    if (typeof branch !== "string" || !branch) {
+      throw new CeError("ce: {default} needs repository.default_branch in the event file, which it does not have");
+    }
+    return branch;
+  }
+  #payload() {
+    if (this.#event)
+      return this.#event;
+    const file = this.#require("EVENT_PATH", "reading the event file");
+    let payload;
+    try {
+      payload = readJsonFile(file, undefined);
+    } catch (exc) {
+      throw new CeError(`ce: ${errorMessage(exc)}`);
+    }
+    if (!isObject(payload))
+      throw new CeError(`ce: the event file ${JSON.stringify(file)} is missing or not a JSON object`);
+    this.#event = payload;
+    return payload;
+  }
+}
+
+// src/system.ts
+import { spawnSync } from "node:child_process";
+import fs2 from "node:fs";
+import path2 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"),
+  stdout: (text) => void fs2.writeSync(1, text),
+  stderr: (text) => void fs2.writeSync(2, text),
+  stdin: () => fs2.readFileSync(0, "utf8"),
   argv0: () => process.argv[1] ?? "ce"
 };
 function log(line) {
@@ -35,11 +407,11 @@ 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));
+  const candidates = command.includes("/") ? [command] : (process.env.PATH ?? "").split(path2.delimiter).filter(Boolean).map((dir) => path2.join(dir, command));
   for (const candidate of candidates) {
     try {
-      fs.accessSync(candidate, fs.constants.X_OK);
-      if (fs.statSync(candidate).isFile())
+      fs2.accessSync(candidate, fs2.constants.X_OK);
+      if (fs2.statSync(candidate).isFile())
         return candidate;
     } catch {}
   }
@@ -71,20 +443,76 @@ var system = {
   }
 };
 function binDir() {
-  return fs.realpathSync(path.join(import.meta.dirname, "..", "bin"));
+  return fs2.realpathSync(path2.join(import.meta.dirname, "..", "bin"));
 }
 function ensureHelperOnPath() {
   const dir = binDir();
-  const parts = (process.env.PATH ?? "").split(path.delimiter);
+  const parts = (process.env.PATH ?? "").split(path2.delimiter);
   if (!parts.includes(dir))
-    process.env.PATH = [dir, ...parts].join(path.delimiter);
+    process.env.PATH = [dir, ...parts].join(path2.delimiter);
+}
+
+// src/template.ts
+var PLACEHOLDER = /\{([^{}]*)\}/gu;
+function hasPlaceholders(value) {
+  return value.includes("{") || value.includes("}");
+}
+function parse(template, vars) {
+  const parts = [];
+  const text = (value) => {
+    if (hasPlaceholders(value))
+      throw new CeError(`ce: unmatched brace in ${JSON.stringify(template)}`);
+    if (value)
+      parts.push({ text: value });
+  };
+  let last = 0;
+  for (const match of template.matchAll(PLACEHOLDER)) {
+    text(template.slice(last, match.index));
+    last = match.index + match[0].length;
+    const guard = match[1].startsWith("?");
+    const name = guard ? match[1].slice(1) : match[1];
+    if (!vars.known(name))
+      throw new CeError(`ce: unknown placeholder ${match[0]} in ${JSON.stringify(template)}`);
+    parts.push({ name, guard });
+  }
+  text(template.slice(last));
+  return parts;
+}
+function expand(template, vars, encode) {
+  const parts = parse(template, vars);
+  for (const part of parts) {
+    if ("name" in part && part.guard && vars.get(part.name) === undefined)
+      return null;
+  }
+  let out = "";
+  for (const part of parts) {
+    if ("text" in part)
+      out += part.text;
+    else if (!part.guard) {
+      const value = vars.get(part.name);
+      if (value === undefined) {
+        throw new CeError(`ce: {${part.name}} has no value here, in ${JSON.stringify(template)}. ` + `To leave the tag out instead, guard it with {?${part.name}}.`);
+      }
+      out += encode(value);
+    }
+  }
+  return out;
+}
+function checkValue(template, vars, what) {
+  if (parse(template, vars).some((part) => ("guard" in part) && part.guard)) {
+    throw new CeError(`ce: ${what} ${JSON.stringify(template)} cannot use {?guards}; they only apply to tags`);
+  }
+}
+function expandValue(template, vars, encode, what) {
+  checkValue(template, vars, what);
+  return expand(template, vars, encode);
 }
 
 // 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 VALID_TAG = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/u;
+var HOST_PORT = /^([^/:]+):(?:\d|\{[^{}]*\})+\//u;
 var SEPARATORS = "-_.";
 function sanitizeChars(value, charRegex) {
   return value.replace(charRegex, "_");
@@ -105,62 +533,163 @@ 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)}`;
-    }
+function splitRef(value) {
+  const host = HOST_PORT.exec(value);
+  const isHost = host && (host[1].includes(".") || host[1] === "localhost" || value.includes(":", host[0].length));
+  const offset = isHost ? host[0].length : 0;
+  const i = value.indexOf(":", offset);
+  return i < 0 ? null : [value.slice(0, i), value.slice(i + 1)];
+}
+function assertValidTag(repo, tag) {
+  if (!VALID_TAG.test(tag)) {
+    throw new CeError(`ce: invalid tag ${JSON.stringify(tag)} in ${JSON.stringify(`${repo}:${tag}`)}: a tag is up to 128 letters, ` + `digits, "_", "." and "-", and cannot start with "." or "-".`);
   }
-  const m = RENOVATE_RE.exec(out);
-  return m ? `${m[1]}/renovate:${m[2]}` : out;
+  return `${repo}:${tag}`;
+}
+function encodeTagValue(value) {
+  assertAscii("placeholder value", value);
+  return value.replace(INVALID_TAG_CHARS, "-");
+}
+function encodeRepoValue(value) {
+  assertAscii("placeholder value", value);
+  if (/[^A-Za-z0-9._:/-]/u.test(value))
+    throw new CeError(`ce: ${JSON.stringify(value)} cannot go in an image name`);
+  return value;
+}
+function expandImage(template, vars) {
+  const image = expandValue(template, vars, encodeRepoValue, "image name");
+  if (!/^(?:[^/:]+:\d+\/)?[^:]*$/u.test(image)) {
+    throw new CeError(`ce: image name ${JSON.stringify(image)} from ${JSON.stringify(template)} has a ":" that is not a registry port`);
+  }
+  return image;
+}
+function expandPrefix(prefix, vars, what) {
+  return hasPlaceholders(prefix) ? expandValue(prefix, vars, encodeTagValue, what) : prefix;
+}
+function literalRef(repo, tag) {
+  if (tag.includes("/")) {
+    const [first, rest] = splitOnce(tag, "/");
+    return `${repo}/${sanitizeChars(first, INVALID_TAG_CHARS)}:${sanitizeChars(rest, INVALID_TAG_CHARS)}`;
+  }
+  return `${repo}:${sanitizeChars(tag, INVALID_TAG_CHARS)}`;
 }
 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) {
+function rewriteTagValue(value, tagPrefix, vars = new CiMetadata) {
+  assertAscii("tag", value);
   const v = stripProto(value);
-  if (!v.includes(":")) {
-    assertAscii("tag", v);
-    return [v];
+  if (!v)
+    throw new CeError("ce: empty -t/--tag value");
+  const [repoTemplate, tagList] = splitRef(v) ?? [v, undefined];
+  if (hasPlaceholders(repoTemplate))
+    checkValue(repoTemplate, vars, "image name");
+  if (hasPlaceholders(tagPrefix))
+    checkValue(tagPrefix, vars, "tag prefix");
+  let repo;
+  const expandRepo = () => repo ??= hasPlaceholders(repoTemplate) ? expandImage(repoTemplate, vars) : repoTemplate;
+  if (tagList === undefined)
+    return [expandRepo()];
+  const tags = tagList.split(/[,\s]+/u).filter(Boolean);
+  if (!tags.length)
+    throw new CeError(`ce: no tag after the ":" in ${JSON.stringify(value)}`);
+  let safePrefix;
+  const refs = [];
+  for (const tag of tags) {
+    const expanded = hasPlaceholders(tag) ? expand(tag, vars, encodeTagValue) : tag;
+    if (expanded === null)
+      continue;
+    safePrefix ??= computeSafePrefix(expandPrefix(tagPrefix, vars, "tag prefix"));
+    if (hasPlaceholders(tag)) {
+      refs.push(assertValidTag(expandRepo(), `${safePrefix}${sanitizeChars(expanded, INVALID_TAG_CHARS)}`));
+    } else {
+      const ref = literalRef(expandRepo(), `${safePrefix}${tag}`);
+      const i = ref.lastIndexOf(":");
+      refs.push(assertValidTag(ref.slice(0, i), ref.slice(i + 1)));
+    }
+  }
+  return refs;
+}
+function csvFields(value) {
+  value = value.replace(/\r?\n$/u, "");
+  if (!value)
+    return null;
+  const fields = [];
+  let i = 0;
+  for (;; ) {
+    if (value[i] !== '"') {
+      const end = value.indexOf(",", i);
+      const field = end < 0 ? value.slice(i) : value.slice(i, end);
+      if (field.includes('"'))
+        return null;
+      fields.push(field);
+      if (end < 0)
+        return fields;
+      i = end + 1;
+      continue;
+    }
+    let field = "";
+    for (i++;; i++) {
+      const quote = value.indexOf('"', i);
+      if (quote < 0)
+        return null;
+      field += value.slice(i, quote);
+      i = quote + 1;
+      if (value[i] !== '"')
+        break;
+      field += '"';
+    }
+    fields.push(field);
+    if (i === value.length)
+      return fields;
+    if (value[i] !== ",")
+      return null;
+    i++;
   }
-  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 csvJoin(fields) {
+  return fields.map((field) => /^[ \t]|[",\r\n]/u.test(field) ? `"${field.replaceAll('"', '""')}"` : field).join(",");
+}
+var fieldKey = (field) => field.split("=", 1)[0].toLowerCase();
+function ghaFields(value) {
+  const fields = csvFields(value);
+  const type = fields?.findLast((field) => fieldKey(field) === "type");
+  return type?.slice("type=".length) === "gha" ? fields : null;
+}
+var scopeIndex = (fields) => fields.findLastIndex((field) => fieldKey(field) === "scope");
 function cacheScopeName(value) {
-  const m = GHA_RE.exec(value);
-  if (!m)
+  const fields = ghaFields(value);
+  if (!fields)
     return value;
-  const scope = m[2];
-  if (scope === undefined)
+  const i = scopeIndex(fields);
+  if (i < 0)
     return "";
+  const scope = fields[i].slice("scope=".length);
   assertAscii("cache scope", scope);
   return sanitizeChars(scope, INVALID_SCOPE_CHARS);
 }
 function normalizeCacheScope(value, cachePrefix) {
-  const m = GHA_RE.exec(value);
-  if (!m)
+  const fields = ghaFields(value);
+  if (!fields)
     return value;
   if (!cachePrefix)
     return value;
   assertAscii("cache prefix", cachePrefix);
   const prefix = sanitizeChars(cachePrefix, INVALID_TAG_CHARS);
-  let scope = splitOnce(cacheScopeName(value), ",")[0];
+  let scope = cacheScopeName(value);
   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}`;
+  const i = scopeIndex(fields);
+  if (i < 0)
+    fields.push(`scope=${scope}`);
+  else
+    fields[i] = `scope=${scope}`;
+  return csvJoin(fields);
 }
 
 // src/build-args.ts
@@ -178,9 +707,10 @@ var SUMMARIZED = {
   "--file": "dockerfile",
   "--target": "target",
   "--platform": "platform",
-  "--build-arg": "buildArgs"
+  "--build-arg": "buildArgs",
+  "--label": "labels"
 };
-function parseBuildArgs(argv, tagPrefix, cachePrefix) {
+function parseBuildArgs(argv, tagPrefix, cachePrefix, { vars = new CiMetadata, labels = {} } = {}) {
   const args = [];
   const rawCacheFrom = [];
   const rawCacheTo = [];
@@ -189,21 +719,25 @@ function parseBuildArgs(argv, tagPrefix, cachePrefix) {
     cacheFrom: [],
     cacheTo: [],
     buildArgs: [],
+    labels: [],
     dockerfile: "",
     target: "",
     platform: "",
     context: ""
   };
+  let templated = false;
+  let rest = [];
   const addTags = (value, flag) => {
-    const refs = rewriteTagValue(value, tagPrefix);
+    templated ||= hasPlaceholders(value);
+    const refs = rewriteTagValue(value, tagPrefix, vars);
     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);
+    if (field === "buildArgs" || field === "labels")
+      summary[field].push(value);
     else
       summary[field] = value;
   };
@@ -211,7 +745,12 @@ function parseBuildArgs(argv, tagPrefix, cachePrefix) {
     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")
+    if (arg === "--") {
+      rest = argv.slice(i);
+      if (rest.length > 1)
+        summary.context = rest.at(-1);
+      break;
+    } else if (arg === "-t")
       addTags(next(), "-t");
     else if (arg === "--tag")
       addTags(next(), "--tag=");
@@ -246,6 +785,15 @@ function parseBuildArgs(argv, tagPrefix, cachePrefix) {
         summary.context = arg;
     }
   }
+  if (templated && !summary.tags.length) {
+    throw new CeError("ce: the guards in the -t templates left out every tag, so the image would have none");
+  }
+  const ownKeys = new Set(summary.labels.map((label) => label.split("=", 1)[0]));
+  const added = Object.entries(labels).filter(([key]) => !ownKeys.has(key)).map(([key, value]) => `${key}=${value}`);
+  args.unshift(...added.map((label) => `--label=${label}`));
+  summary.labels.unshift(...added);
+  if (rawCacheFrom.length || rawCacheTo.length)
+    cachePrefix = expandPrefix(cachePrefix, vars, "cache prefix");
   const toNames = new Set(rawCacheTo.map(cacheScopeName));
   for (const c of rawCacheFrom) {
     const rewritten = toNames.has(cacheScopeName(c)) ? normalizeCacheScope(c, cachePrefix) : c;
@@ -257,6 +805,7 @@ function parseBuildArgs(argv, tagPrefix, cachePrefix) {
     args.push(`--cache-to=${rewritten}`);
     summary.cacheTo.push(rewritten);
   }
+  args.push(...rest);
   return { args, summary };
 }
 function splitAt(value, sep) {
@@ -264,9 +813,10 @@ function splitAt(value, 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")
+  const command = findBuildCommand(engine, args);
+  if (!command || command.tagsOnly)
     return;
+  const subcommand = command.name;
   const out = ["[ce] build summary:", `  engine: ${engine}`, `  subcommand: ${subcommand}`];
   const list = (title, items) => {
     if (items.length)
@@ -282,6 +832,7 @@ function printBuildSummary(engine, args, summary) {
   if (summary.platform)
     out.push(`  platform: ${summary.platform}`);
   list("build args", summary.buildArgs);
+  list("labels", summary.labels);
   if (summary.context)
     out.push(`  context: ${summary.context}`);
   io.stderr(`${out.join(`
@@ -290,91 +841,6 @@ function printBuildSummary(engine, args, summary) {
 `);
 }
 
-// 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;
@@ -689,8 +1155,25 @@ async function waitForEngine(engine) {
   logError(`no engine available: ${engine}`);
   return false;
 }
-async function runEngine(engine, argv, tagPrefix, cachePrefix) {
-  const { args, summary } = parseBuildArgs(argv, tagPrefix, cachePrefix);
+function envFlag(name) {
+  const value = (process.env[name] ?? "").toLowerCase();
+  if (["", "0", "false", "no"].includes(value))
+    return false;
+  if (["1", "true", "yes"].includes(value))
+    return true;
+  throw new CeError(`ce: ${name} must be true or false, not ${JSON.stringify(process.env[name])}`);
+}
+async function runEngine(engine, argv, tagPrefix, cachePrefix, ociLabels) {
+  const command = findBuildCommand(engine, argv);
+  let args = argv;
+  let summary;
+  if (command) {
+    const vars = new CiMetadata;
+    const labels = !command.tagsOnly && (ociLabels ?? envFlag("OCI_LABELS")) ? vars.labels() : {};
+    const parsed = parseBuildArgs(argv.slice(command.start), tagPrefix, cachePrefix, { vars, labels });
+    args = [...argv.slice(0, command.start), ...parsed.args];
+    summary = parsed.summary;
+  }
   ensureHelperOnPath();
   if (!system.which(engine)) {
     logError(`Engine not found: ${engine}`);
@@ -698,7 +1181,8 @@ async function runEngine(engine, argv, tagPrefix, cachePrefix) {
   }
   if (!await waitForEngine(engine))
     return 1;
-  printBuildSummary(engine, args, summary);
+  if (summary)
+    printBuildSummary(engine, args, summary);
   if (engine === "docker")
     return system.exec("docker", ["docker", ...args]);
   if (system.which("gosu")) {
@@ -848,7 +1332,7 @@ async function login() {
 
 // src/cli.ts
 function helpText() {
-  return `Usage: ${io.argv0()} [--tag-prefix=<prefix>] [--cache-prefix=<prefix>] [command|engine] [args]
+  return `Usage: ${io.argv0()} [--tag-prefix=<prefix>] [--cache-prefix=<prefix>] [--oci-labels] [command|engine] [args]
 
 Options:
     --tag-prefix=<prefix>
@@ -857,12 +1341,35 @@ Options:
                       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
+                      Prepend <prefix> to the gha cache scopes in --cache-to,
+                      and in --cache-from where they match one; other
+                      --cache-from scopes stay shared. 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.
+    --oci-labels      Add org.opencontainers.image.* labels (source, revision,
+                      version, title, description) from the Forgejo Actions
+                      run to builds. A --label with the same key wins.
+                      Also available via OCI_LABELS=true.
+
+Placeholders, in build tags and in the tag and cache prefixes:
+    {name}            The value of name; an error if it has none in this run.
+    {?name}           Expands to nothing; leaves the tag out unless name has
+                      a value. Not allowed in prefixes.
+    {image}           Registry host and repository, lowercased
+    {ref}             Branch name, pr-<number>, or tag name
+    {branch} {pr} {tag}
+                      Set only when building that kind of ref
+    {default}         Set only when building the default branch
+    {revision} {sha}  The commit, in full and as 7 characters
+    {version} {major} {minor} {patch}
+                      From a SemVer tag such as v1.2.3 (v optional)
+    {stable}          Set only for a SemVer tag without a pre-release
+    {env.NAME}        The environment variable NAME
+    Values are made safe for a tag ("ci/x" becomes "ci-x"). Quote templates
+    in single quotes. Example:
+        -t '{image}:{ref},{?default}latest'
 
 Commands:
     login             Log in to all available engines
@@ -900,6 +1407,7 @@ Environment variables (used by login):
 `;
 }
 async function main(argv) {
+  let ociLabels;
   let tagPrefix = process.env.TAG_PREFIX ?? "";
   let cachePrefix = process.env.CACHE_PREFIX ?? process.env.TAG_PREFIX ?? "";
   for (;; ) {
@@ -912,6 +1420,8 @@ async function main(argv) {
       [cachePrefix, argv] = consumeValue(argv.slice(1), a);
     else if (a?.startsWith("--cache-prefix="))
       [cachePrefix, argv] = [a.slice("--cache-prefix=".length), argv.slice(1)];
+    else if (a === "--oci-labels")
+      [ociLabels, argv] = [true, argv.slice(1)];
     else
       break;
   }
@@ -925,7 +1435,7 @@ async function main(argv) {
   if (command === "credential-helper")
     return credentialHelper(rest);
   if (isEngine(command))
-    return runEngine(command, rest, tagPrefix, cachePrefix);
+    return runEngine(command, rest, tagPrefix, cachePrefix, ociLabels);
   io.stderr(helpText());
   return 1;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@izykitten/ce",
-  "version": "0.0.2",
+  "version": "0.0.3-dev.0",
   "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",
+  "license": "BSD-3-Clause",
   "bin": {
     "ce": "bin/ce",
     "docker-credential-ce-forgejo": "bin/docker-credential-ce-forgejo"
@@ -30,4 +30,4 @@
   "devDependencies": {
     "@types/bun": "1.4.3"
   }
-}
+}