@izykitten/ce 0.0.3-dev.5 → 0.0.3-dev.7

package/README.md

@@ -24,9 +24,13 @@ 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 '{image}:{ref},{?default}latest' .
+  run: >
+    bunx @izykitten/ce docker buildx build --push
+    -t '{image}:{ref},{?version}{version},{?stable}{major}.{minor},{?stable}{major},{?stable}latest' .
 ```
 
+[Recommended tags](#recommended-tags) says which tags that gives, and how to pick what `latest` follows.
+
 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
@@ -53,9 +57,9 @@ Prefixes can use guards too. A guard that does not pass leaves the prefix empty,
 
 Guards decide from the run's metadata, so they need it too: outside a Forgejo Actions run, `{?default}` fails like `{default}` would. Only `{env.NAME}` and `{arg.NAME}` work everywhere. A guard that does not pass decides on its own, though: a tag with one is left out, and a prefix with one is empty, even if another guard in it could not be worked out, so `{?default}{?env.X}` outside a run with `X` empty is simply left out. To tell whether a branch is the default one, ce reads `repository.default_branch` from the event file, or `DEFAULT_BRANCH` when the event has none, as on a scheduled run; set `DEFAULT_BRANCH: main` in such a workflow. Pull requests and tags are never the default branch, so they need neither.
 
-Put templates in single quotes: `?` is a glob character in zsh.
+Quote a template in a workflow's `env:`: YAML reads `CACHE_PREFIX: {ref}` as a mapping, and `{?pr}pr-{pr}` not at all.
 
-A branch, PR and default-branch build:
+A branch, PR and default-branch build, for an image deployed from its default branch with no releases yet, so `latest` follows that branch:
 
 ```yaml
 - name: Container Build & Push
@@ -73,13 +77,41 @@ The same can be written by hand, since ce only prefixes a `--cache-from` whose s
 
 The `--cache-from` that `--cache` makes leaves out a gha `mode=`, which only applies to export, and a `--cache-from` given twice, as the default branch's own scope is on the default branch, is passed once.
 
-A release on a SemVer tag, with the version aliases only for stable releases:
+### Recommended tags
+
+For an image others pull by version:
 
 ```sh
--t '{image}:{ref},{?version}{version},{?stable}{major}.{minor},{?stable}{major},sha-{sha}'
+-t '{image}:{ref},{?version}{version},{?stable}{major}.{minor},{?stable}{major},{?stable}latest'
 ```
 
-`{stable}` does not mean newest: rebuilding an older release moves its aliases back to it.
+| Build             | Tags                                    |
+| ----------------- | --------------------------------------- |
+| branch `main`     | `main`                                  |
+| branch `ci/fix`   | `ci-fix`                                |
+| pull request 3    | `pr-3`                                  |
+| tag `v1.2.3`      | `v1.2.3`, `1.2.3`, `1.2`, `1`, `latest` |
+| tag `v1.3.0-rc.1` | `v1.3.0-rc.1`, `1.3.0-rc.1`             |
+| tag `v0.3.1`      | `v0.3.1`, `0.3.1`, `0.3`, `0`, `latest` |
+
+- `{ref}` names every build after what was pushed, so a branch or pull request can be pulled to try it, and a release keeps its git tag's name, `v` included.
+- `{?version}{version}` adds the version without the `v`, as most images are tagged, for pre-releases too.
+- `1.2` and `1` follow the newest stable release in their line, for those who want fixes but not the next major version. Before 1.0, SemVer lets any minor release break things, so `0` can move from 0.3 to a 0.4 that does; pin `0.3` to avoid that.
+- `latest` is the newest stable release, as on most images. A repository with no release tag yet has no `latest`: deploy `main` instead, or use `{?default}latest` until the first release.
+
+The guard on `latest` picks what it follows:
+
+| Tag                   | `latest` follows                          |
+| --------------------- | ----------------------------------------- |
+| `{?stable}latest`     | stable releases                           |
+| `{?version}latest`    | every SemVer tag, pre-releases included   |
+| `{?tag}latest`        | every tag                                 |
+| `{?default}latest`    | the default branch                        |
+| `{?env.LATEST}latest` | builds where an earlier step set `LATEST` |
+
+Guards go by the build, not by what is in the registry: `latest` and the version aliases move to the last build whose guards pass. A `v1.2.4` fix pushed after `v2.0.0`, or a rebuild of an older release, moves them back to it. For a rule such as "only the highest version" or "the default branch until the first release", have an earlier step check the registry and set the variable an `{?env.NAME}` guard reads.
+
+`{ref}` moves with each push. To also keep every branch and pull request build under a name of its own, add `{?branch}{ref}-{sha},{?pr}{ref}-{sha}`, which gives `main-0123456` and `pr-3-0123456`.
 
 ### Build args and the Containerfile
 
@@ -109,25 +141,25 @@ RUN xcaddy build v${CADDY_VERSION}
 - **The file:** the `-f` file (with Docker, the last one), else the context's `Dockerfile` (or `dockerfile`); podman and buildah look for `Containerfile` first.
 - **The stage:** the one being built, `--target`'s or else the last. Other stages do not matter, unless this one is built `FROM` one of them, which it then starts from.
 - **The default:** the stage's own `ARG NAME=…`, the last one winning, or that of the stage it is built from; else the global `ARG NAME=…` before the first `FROM`, which a bare `ARG NAME` in the stage, or a `FROM` line, also gets. No default anywhere, or an empty one, is no value, and a guard leaves its tag out.
-- **`$` in a default:** worked out as the engine does, from the `ARG`s, `--build-arg`s and `ENV`s before it, with `$NAME`, `${NAME}`, `${NAME:-x}` and `${NAME:+x}` (and with Docker, `${NAME-x}` and `${NAME+x}`). With Docker, in a stage from `scratch`, a name nothing sets is empty, but for `PATH`.
-- **Builtins** such as `TARGETPLATFORM`, and `SOURCE_DATE_EPOCH` and proxies such as `HTTP_PROXY`, which the engine may set itself, are the builder's, unless a `--build-arg` sets them. Docker also takes a builtin's own `ARG` default, and works out a `SOURCE_DATE_EPOCH` that is not a plain number such as `1700000000` itself.
-- **podman and buildah** differ inside a stage: an `ENV`, the base image's too, wins over an `ARG`, so ce only works out a reference to a name an `ENV` there sets. A stage gets the `ARG`s of the stage its `FROM` names as written, so none through `FROM $BASE`. `TARGETPLATFORM` is always the platform they build.
+- **`$` in a default:** worked out as the engine does, from the `ARG`s, `--build-arg`s and `ENV`s before it, with `$NAME`, `${NAME}`, `${NAME:-x}` and `${NAME:+x}` (and with Docker, `${NAME-x}` and `${NAME+x}`). In a stage from `scratch`, a name nothing sets is empty, and `PATH` is the engines' `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`, which with podman and buildah is an `ENV`, so it wins over an `ARG PATH`.
+- **Builtins** such as `TARGETPLATFORM`, and `SOURCE_DATE_EPOCH` and proxies such as `HTTP_PROXY`, which the engine may set itself, are the builder's, unless a `--build-arg` sets them. podman and buildah pass their environment's proxies only to `RUN`, so with them a proxy is like any other name. With a `--platform` such as `linux/arm/v7`, the `TARGET` ones are that platform's, as the engine normalizes it: `linux/arm` is `linux/arm/v7`, `linux/aarch64` is `linux/arm64`, a bare architecture such as `arm64` is for Linux when ce runs on Linux, and with Docker `linux/arm64/v8` is `linux/arm64`. With several, in one `--platform` such as `linux/amd64,linux/arm64` or in several, each is built on its own and every one gets the same tags, so ce works the value out for each: one they share is used, and one that differs is refused, naming two platforms it differs between. podman and buildah set them as ce works them out from podman 5.2 and buildah 1.37, so ce asks the engine its version (`podman info`, which with `--remote` is the server's); older ones let a `--build-arg TARGETPLATFORM` win, and podman 3.4 and buildah 1.23 ignore `--platform`. Docker also takes a builtin's own `ARG` default, and works out a `SOURCE_DATE_EPOCH` that is not a plain number such as `1700000000` itself.
+- **podman and buildah** differ inside a stage: an `ENV`, the base image's too, wins over an `ARG`, so on a base image ce only works out a reference to a name an `ENV` there sets; from `scratch`, the stage's `ARG`s count too. `--env` sets an `ENV` at the start of every stage (`--env NAME` and `--env NAME*` from the environment), and `--unsetenv` drops the base image's. `--from` replaces the first `FROM`'s image, so that stage is on a base image even when its `FROM` is `scratch`. A stage gets the `ARG`s of the stage its `FROM` names as written, so none through `FROM $BASE`. `TARGETPLATFORM` is always the platform they build, and before the first `FROM` the builtins are not the `--platform`'s, but the machine's, or empty before podman 5.7 and buildah 1.42.
 
 **What ce refuses**, with exit 2 and the reason:
 
 - **The file is not there to read:** `-f -`, a `-f` URL or a remote context; with podman or buildah, several `-f` files or a `.in` one for `cpp`.
 - **Another frontend:** a `# syntax=` directive or `BUILDKIT_SYNTAX` naming anything but `docker/dockerfile` untagged, `:1`, or `:1.21` and later, which may be pinned by a digest.
-- **A value ce cannot know:** a reference to a builtin, or to a name the base image's `ENV` may set; a form like `${NAME#x}`; with podman or buildah, `--env` or `--unsetenv` changing a name it refers to.
+- **A value ce cannot know:** a reference to a name the base image's `ENV` may set; a builtin of the machine that builds, such as `BUILDARCH`; a `TARGET` one without a `--platform`, with one ce does not read (such as `linux` alone, or an empty one in a list, which podman and buildah build for the machine), with one that differs between the platforms, with podman before 5.2 or buildah before 1.37, or with podman's `--arch`, `--os`, `--variant` or `--all-platforms`; a form like `${NAME#x}`; with podman or buildah, a `$` in a `--env` value, which they expand, or a character they escape there, such as a line end or a tab, and quotes in a `--unsetenv`.
 - **Instructions ce does not read:** an `ARG` or `ENV` name with something to expand, such as `ENV $NAME=x`, or with flags.
 - **Characters other than ASCII's:** letters in an instruction, a stage name or a name after a `$`; space in an `ARG`, `ENV` or `FROM` line or a heredoc's line. Also a line ending in more than one carriage return.
 - **Heredocs ce cannot place:** a delimiter that is not a word, which may be quoted; on its line, a `${}` with space or quotes in its word outside double quotes, or with quotes, `$` or `<` in it anywhere.
-- **Stages that change under it:** a `--build-context` replacing a stage the built one comes from (with podman and buildah, what a `FROM` names); with podman or buildah, a stage built from one with an `ONBUILD ARG` or `ONBUILD ENV`, which they run only for some image formats.
+- **Stages that change under it:** a `--build-context` replacing a stage the built one comes from (with podman and buildah, what a `FROM` names); with podman or buildah, a stage built from one with an `ONBUILD ARG` or `ONBUILD ENV`, which they run only with the `docker` image format, unless `--format` or `BUILDAH_FORMAT` says which (`containers.conf` may change the default).
 
 Two places always need a `--build-arg NAME`: a `{arg.NAME}` in the cache prefix with `CACHE_FROM_DEFAULT`, as the default branch may have another Containerfile; and with podman's `--build-arg-file`, which ce does not read. ce does not see a base image's own `ONBUILD` lines, and does not model Docker's legacy builder (`DOCKER_BUILDKIT=0`). Every rule here has a test in `test/containerfile.test.ts`.
 
 ### Checking a template
 
-`--dry-run` before the engine, or `CE_DRY_RUN=true`, prints the build summary and the engine command ce would run, and exits 0 without running it or waiting for the engine. A template that fails still exits 2, so it also works as a check before pushing a workflow. It checks the templates, not the engine: if the engine is not on `PATH`, it warns and still exits 0, so it works on a machine without one:
+`--dry-run` before the engine, or `CE_DRY_RUN=true`, prints the build summary and the engine command ce would run, and exits 0 without running it or waiting for the engine. A template that fails still exits 2, so it also works as a check before pushing a workflow. It checks the templates, not the engine: if the engine is not on `PATH`, it warns and still exits 0, so it works on a machine without one. The one exception is a `TARGET` arg from `--platform` with podman or buildah, which needs the engine's version: ce asks it, waiting for podman as a build does, and without an answer refuses the value, so the dry run exits 2:
 
 ```sh
 GITHUB_REF=refs/tags/v1.2.3 GITHUB_SERVER_URL=https://code.example GITHUB_REPOSITORY=org/app \
@@ -136,7 +168,30 @@ GITHUB_REF=refs/tags/v1.2.3 GITHUB_SERVER_URL=https://code.example GITHUB_REPOSI
 
 ### 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.
+Builds in a run get these `org.opencontainers.image.` labels, and the same keys as annotations:
+
+| Key           | Value                                                                                  |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `source`      | the repository's page, `{server}/{owner}/{repo}`                                       |
+| `url`         | the repository's website from the event, or else its page                              |
+| `revision`    | the commit, `GITHUB_SHA`                                                               |
+| `version`     | the tag's version, such as `1.2.3`, or else the ref's name (`pr-N` for a pull request) |
+| `title`       | the repository's name                                                                  |
+| `description` | the repository's description from the event                                            |
+| `created`     | when ce started the build, to the second, or the time `SOURCE_DATE_EPOCH` gives        |
+
+Keys the run cannot tell are left out, and outside a run there are none, `created` included. `OCI_LABELS=false`, or `--no-oci-labels` before the engine (`ce --no-oci-labels docker buildx build …`, like the prefix options), turns them off. The labels override a Dockerfile `LABEL` with the same key, and a `--label` you pass for a key wins over ce's label for it, an `--annotation` over its annotation. Labels and annotations are applied after the `RUN` steps, so `created` does not change their cache, but each build's image differs. For one that does not, set the epoch: `created` follows it as the engine does. With Docker, that is a `--build-arg SOURCE_DATE_EPOCH`, or else the environment's `SOURCE_DATE_EPOCH`, or else the default of a global `ARG SOURCE_DATE_EPOCH` before the first `FROM`, which ce reads from the Dockerfile. With podman and buildah, it is `--timestamp`, which they refuse beside any of the others, or else `--source-date-epoch`, or else the environment's `SOURCE_DATE_EPOCH`, or else the build arg. Each is read as the engine reads it: a whole number of seconds, which may be negative, and for `--timestamp` also in Go's other bases, such as `0x10` or `010` (8). An epoch ce cannot read, such as `1.5` or a `SOURCE_DATE_EPOCH` the environment gives that is not a number, leaves `created` out, as do a podman or buildah `--build-arg-file` with none of the others, as the file may set it, and with Docker a global default with a `$` or a Dockerfile ce cannot read, such as a remote context's.
+
+podman and buildah expand a `$NAME` in a `--label`'s value from the build args, and make one that is not a build arg empty, with no way to escape the `$`. They also write a label's value as Go's `%q` does, so a line end becomes `\n`, as do a tab and other characters Go escapes. So with them, a label whose value has a `$`, such as a description that mentions `$HOME`, or a character they escape, is left out; its annotation, which they keep as it is, stays.
+
+With Docker, a build for two or more platforms gets the annotations on the image index too (`manifest,index:`). BuildKit refuses index annotations for one platform, so a build for one gets them on its manifest only. `DOCKER_BUILDKIT=0` gets the labels only, as the legacy builder it picks has no `--annotation`; `docker buildx build` ignores it and always uses BuildKit. podman and buildah put them on the image's manifest, not on a `--manifest` list. With the `docker` image format they drop them, as that format has no annotations.
+
+### SBOM
+
+`SBOM` adds a software bill of materials to builds. `true` (or `spdx`) gives SPDX on every engine, and `cyclonedx` gives CycloneDX with podman and buildah. It is off when unset, empty or `false`; it also takes `yes`, `no`, `1` and `0`, in any case, and any other value exits 2.
+
+- **Docker:** `--sbom=true`, BuildKit's SBOM attestation, unless you pass `--sbom` or an `--attest type=sbom`. [It is always SPDX](https://docs.docker.com/build/metadata/attestations/sbom/), so `SBOM=cyclonedx` exits 2 before the build, unless your own flag means ce adds none. With `--load`, Docker's classic image store refuses the attestation and says what to switch to: another driver, or the containerd image store.
+- **podman and buildah:** `--sbom=syft-spdx`, or `--sbom=syft-cyclonedx` for `SBOM=cyclonedx`, unless you pass a `--sbom` preset. (buildah's plain `syft` preset is CycloneDX, so ce names the format.) The SBOM is written into the image as `/root/buildinfo/content_manifests/sbom.spdx.json`, or `sbom.cdx.json` for a CycloneDX preset. A `--sbom` you pass without an `--sbom-output`, `--sbom-image-output`, `--sbom-purl-output` or `--sbom-image-purl-output` is written there too, even without `SBOM`. The scanner runs from an image, which the engine pulls if it is missing.
 
 ## The credential helper
 
@@ -156,7 +211,7 @@ These behave the same under Node and Bun, and [test/contract.test.ts](test/contr
 
 The wording of messages is not part of that and may change.
 
-In 0.0.3, the `--cache-from` that `--cache` makes no longer has a gha `mode=`, which only applies to export, and a `--cache-from` given twice is passed once. podman and buildah are no longer run through `gosu` as `$USER` when it is on `PATH`: ce runs every engine directly, as the user ce runs as, so to drop root, run ce itself as another user, e.g. with a `USER` line in the image.
+In 0.0.3, builds in a run get the OCI labels, and annotations, by default; `OCI_LABELS=false` or `--no-oci-labels` turns them off. The `--cache-from` that `--cache` makes no longer has a gha `mode=`, which only applies to export, and a `--cache-from` given twice is passed once. podman and buildah are no longer run through `gosu` as `$USER` when it is on `PATH`: ce runs every engine directly, as the user ce runs as, so to drop root, run ce itself as another user, e.g. with a `USER` line in the image.
 
 Compared with the Python version:
 
@@ -175,3 +230,5 @@ bun test          # builds dist/, then unit tests plus the contract and process
 bun check
 bun run build     # dist/ce.js, which the bin scripts load; npm pack runs it
 ```
+
+`bun run check-engines` builds each case in [scripts/engine-cases.ts](scripts/engine-cases.ts) with real Docker, podman and buildah, and compares the build arg each build gets with the one ce works out. It fails if ce would tag with a wrong value. podman and buildah run in a privileged container each, from `quay.io/podman/stable` and `quay.io/buildah/stable` unless `PODMAN_IMAGE` or `BUILDAH_IMAGE` names another, such as an older version's; `bun run check-engines docker` checks Docker alone. Run it after changing how ce reads a Containerfile.

package/dist/ce.js

@@ -104,20 +104,31 @@ var COMMANDS = {
 };
 function findBuildCommand(engine, argv) {
   const words = [];
+  const options = [];
+  let global = 0;
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--")
       return null;
     if (arg.startsWith("-")) {
-      if (takesNext(engine, arg))
-        i++;
+      options.push(arg);
+      if (takesNext(engine, arg) && i + 1 < argv.length)
+        options.push(argv[++i]);
       continue;
     }
+    if (!words.length)
+      global = options.length;
     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 };
+      return {
+        start: i + 1,
+        name: arg,
+        tagsOnly: match.tagsOnly ?? false,
+        engineOptions: engine === "docker" ? options.slice(0, global) : options,
+        buildx: words[0] === "buildx"
+      };
     if (!candidates.length)
       return null;
   }
@@ -143,8 +154,11 @@ function errorMessage(exc) {
 }
 
 // src/containerfile.ts
+var engineEscapes = (value) => /[^\p{L}\p{M}\p{N}\p{P}\p{S} ]/u.test(value);
+
 class Unreadable extends Error {
   located = false;
+  hint = "";
 }
 var fail = (message) => {
   throw new Unreadable(message);
@@ -491,6 +505,7 @@ class Unknown {
   }
 }
 var BASE_ENV = new Unknown("base");
+var SCRATCH_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
 var BUILTINS = [
   "BUILDPLATFORM",
   "BUILDOS",
@@ -505,6 +520,7 @@ var BUILTINS = [
   "TARGETSTAGE"
 ];
 var INJECTED = /^(?:SOURCE_DATE_EPOCH|(?:HTTPS?|FTP|NO|ALL)_PROXY)$/iu;
+var INJECTED_IB = /^SOURCE_DATE_EPOCH$/iu;
 var PROXIES = /^(?:(?:HTTPS?|FTP|NO)_PROXY|(?:https?|ftp|no)_proxy)$/u;
 var NON_ENV = ["BUILDKIT_SBOM_SCAN_CONTEXT", "BUILDKIT_SBOM_SCAN_STAGE"];
 function expandWord(word, escape, model, lookup) {
@@ -517,8 +533,11 @@ function expandWord(word, escape, model, lookup) {
       return;
     const v = lookup(name);
     if (v instanceof Unknown) {
-      if (v.why !== "error")
-        fail(`ce cannot tell what $${name} is there`);
+      if (v.why !== "error") {
+        const exc = new Unreadable(`ce cannot tell what $${name} is there`);
+        exc.hint = v.reason;
+        throw exc;
+      }
       const exc = new Unreadable(v.reason);
       exc.located = true;
       throw exc;
@@ -616,7 +635,67 @@ function expandWord(word, escape, model, lookup) {
   };
   return until("");
 }
-function argDefault(parsed, name, target, buildArg, model = "buildkit", { contexts = [], envs = [] } = {}) {
+var VARIANTS = new Map(Object.entries({
+  amd64: { "": "", v1: "", v2: "v2", v3: "v3", v4: "v4" },
+  arm64: { "": "", "8": "v8", v8: "v8", "v8.0": "v8" },
+  arm: {
+    "": "v7",
+    "5": "v5",
+    "6": "v6",
+    "7": "v7",
+    "8": "v8",
+    v5: "v5",
+    v6: "v6",
+    v7: "v7",
+    v8: "v8"
+  },
+  "386": { "": "" },
+  ppc64le: { "": "" },
+  riscv64: { "": "" },
+  s390x: { "": "" }
+}).map(([arch, variants]) => [arch, new Map(Object.entries(variants))]));
+var ARCH_NAMES = new Map([
+  ["aarch64", ["arm64"]],
+  ["x86_64", ["amd64"]],
+  ["x86-64", ["amd64"]],
+  ["i386", ["386", ""]],
+  ["armhf", ["arm", "v7"]],
+  ["armel", ["arm", "v6"]]
+]);
+function platformArgs(platform, model) {
+  const parts = platform.toLowerCase().split("/");
+  const isArch = (name) => VARIANTS.has(name) || ARCH_NAMES.has(name);
+  if (parts.length === 1 && isArch(parts[0]) && process.platform === "linux")
+    parts.unshift("linux");
+  const [os, written = "", given = "", ...rest] = parts;
+  if (os !== "linux" || rest.length)
+    return;
+  const [arch = written, fixed] = ARCH_NAMES.get(written) ?? [];
+  let variant = fixed === undefined ? VARIANTS.get(arch)?.get(given) : given ? undefined : fixed;
+  if (variant === undefined)
+    return;
+  if (arch === "arm64" && model === "buildkit")
+    variant = "";
+  return new Map([
+    ["TARGETPLATFORM", [os, arch, variant].filter(Boolean).join("/")],
+    ["TARGETOS", os],
+    ["TARGETARCH", arch],
+    ["TARGETVARIANT", variant],
+    ["TARGETOSVERSION", ""]
+  ]);
+}
+function normalizePlatform(platform, engine) {
+  return platformArgs(platform, engine === "docker" ? "buildkit" : "imagebuilder")?.get("TARGETPLATFORM");
+}
+function argDefault(parsed, name, target, buildArg, model = "buildkit", {
+  contexts = [],
+  envs = [],
+  env: hostEnv = process.env,
+  platform,
+  platformIgnored,
+  format,
+  from: fromImage
+} = {}) {
   const buildkit = model === "buildkit";
   const escape = buildkit ? parsed.escape : "\\";
   const evaluate = (word, line, lookup) => {
@@ -625,29 +704,41 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
     } catch (exc) {
       if (!(exc instanceof Unreadable))
         throw exc;
-      return new Unknown("error", exc.located ? exc.message : `${exc.message}, on line ${line}`);
+      return new Unknown("error", exc.located ? exc.message : `${exc.message}, on line ${line}${exc.hint && `: ${exc.hint}`}`);
     }
   };
   const isBuiltin = (arg) => BUILTINS.includes(arg);
+  let targets;
+  const builtin = (arg, global) => {
+    if (arg.startsWith("BUILD"))
+      return new Unknown("builtin", "it is the platform of the machine that builds");
+    if (arg === "TARGETSTAGE")
+      return new Unknown("builtin");
+    if (global && !buildkit)
+      return new Unknown("builtin", "podman and buildah do not set it from --platform before the first FROM");
+    targets ??= platformIgnored?.() ?? (platform === undefined ? "it comes from --platform, which the build does not have" : platformArgs(platform, model) ?? `ce does not read the --platform ${JSON.stringify(platform)}`);
+    return typeof targets === "string" ? new Unknown("builtin", targets) : targets.get(arg);
+  };
+  const injected = (arg) => (buildkit ? INJECTED : INJECTED_IB).test(arg);
   const plain = (name) => ![...`$'"`, escape].some((ch) => name.includes(ch));
   const named = (kind, name, line) => plain(name) ? name : fail(`ce cannot tell what name the ${kind} on line ${line} sets`);
   const globals = new Map;
-  for (const builtin of BUILTINS)
-    globals.set(builtin, buildArg(builtin) ?? new Unknown("builtin"));
+  for (const arg of BUILTINS)
+    globals.set(arg, buildArg(arg) ?? builtin(arg, true));
   for (const { pairs, line } of parsed.globals) {
     const before = new Map(globals);
     const seen = (ref) => {
       const known = buildkit ? globals : before;
       if (known.has(ref) || buildkit || !PROXIES.test(ref))
         return known.get(ref);
-      return buildArg(ref) ?? new Unknown("injected");
+      return buildArg(ref);
     };
     for (const { name, value } of pairs) {
       const arg = named("ARG", name, line);
       const given = buildArg(arg);
       if (given !== undefined)
         globals.set(arg, given);
-      else if (INJECTED.test(arg))
+      else if (injected(arg))
         globals.set(arg, new Unknown("injected"));
       else if (value !== undefined && !(isBuiltin(arg) && !buildkit))
         globals.set(arg, evaluate(value, line, seen));
@@ -670,7 +761,7 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
   }
   const source = (index) => {
     const stage = parsed.stages[index];
-    const base = evaluate(stage.base, stage.line, (ref) => globals.get(ref));
+    const base = index === 0 && fromImage !== undefined && !buildkit ? fromImage : evaluate(stage.base, stage.line, (ref) => globals.get(ref));
     let parent = typeof base === "string" ? findStage(base, index) : -1;
     const swapped = buildkit ? parent >= 0 ? replaced(parent) : undefined : contexts.find((c) => c === stage.base || c === base);
     if (swapped !== undefined)
@@ -695,14 +786,14 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
     let triggers = [];
     if (buildkit) {
       if (base instanceof Unknown)
-        state.undeclared = new Unknown("error", `ce cannot tell what the FROM on line ${stage.line} is built from`);
+        state.undeclared = new Unknown("error", `ce cannot tell what the FROM on line ${stage.line} is built from: ${base.reason}`);
       else if (swapped !== undefined)
         state.undeclared = lost(swapped);
       else if (from) {
         state.args = new Map(from.args);
         state.undeclared = from.undeclared;
         for (const [k, v] of from.env)
-          state.env.set(k, from.opaque || k === "PATH" ? BASE_ENV : v);
+          state.env.set(k, from.opaque ? BASE_ENV : k === "PATH" ? SCRATCH_PATH : v);
         for (const [k, v] of from.image)
           state.env.set(k, v);
         triggers = parsed.stages[parent].instructions.filter((i) => i.onbuild);
@@ -710,24 +801,45 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
     } else {
       if (from)
         state.env = new Map(from.env);
-      for (const flag of envs) {
+      const unset = envs.filter((flag) => flag.startsWith("--unsetenv "));
+      for (const flag of unset) {
         const spec = flag.slice(flag.indexOf(" ") + 1);
-        const names = flag.startsWith("--unsetenv ") ? spec.includes('"') ? ["*"] : spec.split(",") : [spec.split("=")[0].replace(/-$/u, "")];
-        const set = (k) => state.env.set(k, new Unknown("error", `${k} may be changed by ${flag}`));
-        for (const env of names) {
-          const prefix = flag.startsWith("--env ") && env.endsWith("*") ? env.slice(0, -1) : "";
-          if (env.includes("*"))
-            [...state.env.keys()].filter((k) => k.startsWith(prefix)).forEach(set);
-          else
-            set(env);
-        }
+        if (/["\r\n]/u.test(spec))
+          for (const k of state.env.keys())
+            state.env.set(k, new Unknown("error", `${k} may be changed by ${/[\r\n]/u.test(spec) ? `--unsetenv ${JSON.stringify(spec)}` : flag}`));
+        else
+          for (const k of spec.split(","))
+            state.env.delete(k);
+      }
+      for (const flag of envs.filter((f) => f.startsWith("--env "))) {
+        const spec = flag.slice(flag.indexOf(" ") + 1);
+        const copied = (k, v) => {
+          const what = v.includes("$") ? "expand the $" : engineEscapes(v) ? "escape the characters podman and buildah escape" : undefined;
+          if (what === undefined)
+            return v;
+          return new Unknown("error", spec.includes("=") ? `ce does not ${what} in --env ${engineEscapes(spec) ? JSON.stringify(spec) : spec}` : `ce does not ${what} in the ${k} that ${flag} copies`);
+        };
+        if (spec.includes("=")) {
+          const k = spec.slice(0, spec.indexOf("="));
+          state.env.set(k, copied(k, spec.slice(k.length + 1)));
+        } else if (spec.endsWith("*") && !spec.slice(0, -1).includes("*")) {
+          for (const [k, v] of Object.entries(hostEnv))
+            if (k.startsWith(spec.slice(0, -1)) && v !== undefined)
+              state.env.set(k, copied(k, v));
+        } else if (spec.includes("*"))
+          fail(`ce does not read ${flag}`);
+        else if (!spec.endsWith("-") && hostEnv[spec] !== undefined)
+          state.env.set(spec, copied(spec, hostEnv[spec]));
       }
       const written = findStage(stage.base, index);
       if (swapped !== undefined)
         state.undeclared = lost(swapped);
       else if (written >= 0)
         state.args = inheritedArgs(written);
-      for (const { kind, pairs, line } of parent >= 0 ? parsed.stages[parent].instructions.filter((i) => i.onbuild) : []) {
+      const onbuilds = parent >= 0 ? parsed.stages[parent].instructions.filter((i) => i.onbuild) : [];
+      if (format === "docker")
+        triggers = onbuilds;
+      for (const { kind, pairs, line } of format ? [] : onbuilds) {
         for (const { name: arg } of pairs) {
           if (!plain(arg))
             fail(`ce cannot tell what name the ONBUILD on line ${line} sets`);
@@ -735,14 +847,15 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
         }
       }
     }
-    const see = (env) => (ref) => env.has(ref) ? env.get(ref) : !buildkit || state.opaque || ref === "PATH" ? BASE_ENV : undefined;
+    const see = (env, args) => (ref) => env.has(ref) ? env.get(ref) : state.opaque ? BASE_ENV : ref === "PATH" ? SCRATCH_PATH : buildkit ? undefined : args.has(ref) ? args.get(ref) : PROXIES.test(ref) ? buildArg(ref) : undefined;
     const own = stage.instructions.filter((i) => !i.onbuild);
     for (const { kind, pairs, line } of [...triggers, ...own]) {
       const before = new Map(state.env);
+      const argsBefore = new Map(state.args);
       for (const { name, value } of pairs) {
         const arg = named(kind, name, line);
         const seen = buildkit && kind === "ARG" ? state.env : before;
-        const evaluated = (word) => evaluate(word, line, see(seen));
+        const evaluated = (word) => evaluate(word, line, see(seen, argsBefore));
         if (kind === "ENV") {
           const v = value === undefined ? new Unknown("error", `ce does not read the ENV ${arg} on line ${line}`) : evaluated(value);
           state.env.set(arg, v);
@@ -753,10 +866,10 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
         let v;
         if (given !== undefined)
           v = given;
-        else if (INJECTED.test(arg))
+        else if (injected(arg))
           v = new Unknown("injected");
         else if (isBuiltin(arg) && (!buildkit || value === undefined))
-          v = globals.get(arg);
+          v = buildkit ? globals.get(arg) : builtin(arg, false);
         else if (value !== undefined)
           v = evaluated(value);
         else if (globals.get(arg) !== undefined)
@@ -792,7 +905,7 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
           const given = buildArg(arg);
           if (given !== undefined)
             args.set(arg, given);
-          else if (INJECTED.test(arg))
+          else if (injected(arg))
             args.set(arg, new Unknown("injected"));
           else if (isBuiltin(arg))
             args.set(arg, globals.get(arg));
@@ -830,10 +943,10 @@ function argDefault(parsed, name, target, buildArg, model = "buildkit", { contex
   for (const i of ancestors)
     run(i);
   const state = run(index);
-  const v = state.args.has(name) ? state.args.get(name) : state.undeclared ?? (!globals.has(name) && INJECTED.test(name) && buildArg(name) === undefined ? new Unknown("injected") : globals.get(name));
+  const v = state.args.has(name) ? state.args.get(name) : state.undeclared ?? (!globals.has(name) && injected(name) && buildArg(name) === undefined ? new Unknown("injected") : globals.get(name));
   if (v instanceof Unknown) {
     if (v.why === "builtin")
-      fail(`${name} is set by the builder`);
+      fail(`${name} is set by the builder${v.reason && `: ${v.reason}`}`);
     if (v.why === "injected")
       fail(`${name} may be set by the builder`);
     fail(v.why === "error" ? v.reason : `ce cannot tell what ${name} is`);
@@ -855,38 +968,64 @@ function readContainerfile(file, model) {
     throw exc;
   }
 }
-function containerfileDefaults(files, buildArg) {
+function loadContainerfile(files, buildArg) {
   const docker = files.engine === "docker";
-  const model = docker ? "buildkit" : "imagebuilder";
+  let file;
+  let parsed;
+  try {
+    file = findContainerfile(files);
+    parsed = readContainerfile(file, docker ? "buildkit" : "imagebuilder");
+  } catch (exc) {
+    if (exc instanceof Unreadable)
+      return { error: exc };
+    throw exc;
+  }
+  const frontend = docker ? buildArg("BUILDKIT_SYNTAX")?.trim().split(" ")[0] ?? parsed.syntax : undefined;
+  if (frontend !== undefined && !STANDARD_SYNTAX.test(frontend))
+    return {
+      file,
+      error: new Unreadable(`it is read by the frontend ${JSON.stringify(frontend)}, which may read it differently`)
+    };
+  return { file, parsed };
+}
+function dockerfileEpoch(files, buildArg) {
   let read;
-  const load = () => {
-    let file;
-    let parsed;
-    try {
-      file = findContainerfile(files);
-      parsed = readContainerfile(file, model);
-    } catch (exc) {
-      if (exc instanceof Unreadable)
-        return { error: exc };
-      throw exc;
-    }
-    const frontend = docker ? buildArg("BUILDKIT_SYNTAX")?.trim().split(" ")[0] ?? parsed.syntax : undefined;
-    if (frontend !== undefined && !STANDARD_SYNTAX.test(frontend))
-      return {
-        file,
-        error: new Unreadable(`it is read by the frontend ${JSON.stringify(frontend)}, which may read it differently`)
-      };
-    return { file, parsed };
-  };
+  try {
+    read = loadContainerfile(files, buildArg);
+  } catch {
+    return "";
+  }
+  if (!read.parsed)
+    return "";
+  const defaults = read.parsed.globals.flatMap(({ pairs }) => pairs).filter(({ name, value }) => name === "SOURCE_DATE_EPOCH" && value !== undefined);
+  if (!defaults.length)
+    return;
+  const value = defaults[0].value;
+  return defaults.length === 1 && !value.includes("$") ? value : "";
+}
+function containerfileDefaults(files, buildArg) {
+  const model = files.engine === "docker" ? "buildkit" : "imagebuilder";
+  let read;
+  const load = () => loadContainerfile(files, buildArg);
+  const platforms = files.platforms?.length ? [...new Set(files.platforms)] : [undefined];
   return (name) => {
     read ??= load();
     try {
       if (read.error)
         throw read.error;
-      return argDefault(read.parsed, name, files.target, buildArg, model, {
+      const values = platforms.map((platform) => argDefault(read.parsed, name, files.target, buildArg, model, {
         contexts: files.contexts ?? [],
-        envs: files.envs ?? []
-      });
+        envs: files.envs ?? [],
+        env: files.env ?? process.env,
+        platform,
+        platformIgnored: files.platformIgnored,
+        format: files.format,
+        from: files.from
+      }));
+      const other = values.findIndex((v) => (v ?? "") !== (values[0] ?? ""));
+      if (other !== -1)
+        fail(`it is ${JSON.stringify(values[0] ?? "")} for ${platforms[0]} but ${JSON.stringify(values[other] ?? "")} for ${platforms[other]}, and every platform gets the same tags`);
+      return values[0];
     } catch (exc) {
       if (!(exc instanceof Unreadable))
         throw exc;
@@ -1000,6 +1139,19 @@ var CI_VARIABLES = [
 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;
+function epochDate(epoch, base = 10) {
+  const match = base === 10 ? /^([+-]?)(\d+)$/u.exec(epoch) : /^([+-]?)(0[xX][0-9a-fA-F]+|0[oO][0-7]+|0[bB][01]+|0[0-7]+|0|[1-9]\d*)$/u.exec(epoch);
+  if (!match)
+    return;
+  const digits = match[2];
+  const magnitude = base === 0 && /^0[0-7]/u.test(digits) ? BigInt(`0o${digits.slice(1)}`) : BigInt(digits);
+  const seconds = match[1] === "-" ? -magnitude : magnitude;
+  if (seconds < -(2n ** 63n) || seconds >= 2n ** 63n)
+    return;
+  const date = new Date(Number(seconds) * 1000);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+var rfc3339 = (date) => date.toISOString().replace(/\.\d{3}Z$/u, "Z");
 
 class CiMetadata {
   #env;
@@ -1020,7 +1172,7 @@ class CiMetadata {
       this.#cache.set(name, this.#resolve(name));
     return this.#cache.get(name);
   }
-  labels() {
+  labels(now = new Date) {
     const labels = {};
     const add = (key, value) => {
       try {
@@ -1034,14 +1186,29 @@ class CiMetadata {
     };
     const server = nonEmpty(this.#ciEnv("SERVER_URL"))?.replace(/\/+$/u, "");
     const repository = nonEmpty(this.#ciEnv("REPOSITORY"));
-    add("source", () => server && repository ? `${server}/${repository}` : undefined);
+    const page = server && repository ? `${server}/${repository}` : undefined;
+    const repo = (key) => {
+      const value = this.#payload().repository;
+      return isObject(value) && typeof value[key] === "string" ? value[key] : undefined;
+    };
+    add("source", () => page);
+    add("url", () => {
+      try {
+        return repo("website") || page;
+      } catch (exc) {
+        if (exc instanceof CeError)
+          return page;
+        throw exc;
+      }
+    });
     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;
-    });
+    add("description", () => repo("description"));
+    const epoch = this.#env.SOURCE_DATE_EPOCH;
+    const time = epoch ? epochDate(epoch) : now;
+    if (Object.keys(labels).length && time)
+      add("created", () => rfc3339(time));
     return labels;
   }
   #resolve(name) {
@@ -1221,7 +1388,20 @@ var system = {
       throw result.error;
     return { status: result.status ?? 1, stderr: result.stderr ?? "" };
   },
+  output(argv) {
+    const result = spawnSync(argv[0], argv.slice(1), {
+      stdio: ["ignore", "pipe", "ignore"],
+      env: childEnv(),
+      encoding: "utf8"
+    });
+    if (result.error)
+      throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+  },
   sleep: (ms) => setTimeout(ms),
+  sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  },
   exec(file, argv) {
     const resolved = system.which(file);
     if (!resolved) {
@@ -1288,15 +1468,17 @@ function expand(template, vars, encode) {
   const parts = parse(template, vars);
   if (!guardsPass(parts, vars))
     return null;
+  return render(parts, vars, encode, (name) => `ce: {${name}} has no value here, in ${JSON.stringify(template)}. ` + `To leave the tag out instead, guard it with {?${name}}.`);
+}
+function render(parts, vars, encode, missing) {
   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}}.`);
-      }
+      if (value === undefined)
+        throw new CeError(missing(part.name));
       out += encode(value);
     }
   }
@@ -1307,19 +1489,14 @@ function checkValue(template, vars, what, guards = false) {
   if (!guards && parts.some((part) => ("guard" in part) && part.guard)) {
     throw new CeError(`ce: ${what} ${JSON.stringify(template)} cannot use {?guards}; they only apply to tags and prefixes`);
   }
+  return parts;
 }
 function expandValue(template, vars, encode, what, guards = false) {
-  checkValue(template, vars, what, guards);
-  const parts = parse(template, vars);
+  const parts = checkValue(template, vars, what, guards);
   if (!guardsPass(parts, vars))
     return "";
-  for (const part of parts) {
-    if ("name" in part && !part.guard && vars.get(part.name) === undefined) {
-      const hint = guards ? ` To leave the ${what} empty instead, guard it with {?${part.name}}.` : "";
-      throw new CeError(`ce: {${part.name}} has no value here, in the ${what} ${JSON.stringify(template)}.${hint}`);
-    }
-  }
-  return expand(template, vars, encode);
+  const hint = (name) => guards ? ` To leave the ${what} empty instead, guard it with {?${name}}.` : "";
+  return render(parts, vars, encode, (name) => `ce: {${name}} has no value here, in the ${what} ${JSON.stringify(template)}.${hint(name)}`);
 }
 
 // src/tags.ts
@@ -1529,9 +1706,23 @@ var SUMMARIZED = {
   "--target": "target",
   "--platform": "platform",
   "--build-arg": "buildArgs",
-  "--label": "labels"
+  "--label": "labels",
+  "--annotation": "annotations"
 };
 var ARG_VARIABLE = /^arg\.([A-Za-z_][A-Za-z0-9_]*)$/u;
+var PLATFORM_FROM = {
+  podman: [5, 2],
+  buildah: [1, 37]
+};
+var PLATFORM_PARTS = [
+  "--arch",
+  "--os",
+  "--variant",
+  "--override-arch",
+  "--override-os",
+  "--os-version",
+  "--os-feature"
+];
 function withBuildArgs(vars, values, argFile, fromFile) {
   return {
     known: (name) => ARG_VARIABLE.test(name) || vars.known(name),
@@ -1556,10 +1747,12 @@ var SHORT_BOOLS = {
 };
 var BUILDX_VALUES = "add-host allow annotation attest build-arg build-context builder cache-from cache-to call cgroup-parent cpu-period cpu-quota cpu-shares cpuset-cpus cpuset-mems file iidfile isolation label memory memory-swap metadata-file network no-cache-filter output platform policy print progress provenance resource sbom secret security-opt shm-size ssh tag target ulimit";
 var BUILDAH_VALUES = "add-host annotation arch authfile blob-cache blob-info-cache-dir build-arg build-arg-file build-context cache-from cache-to cache-ttl cap-add cap-drop cdi-config-dir cert-dir cgroup-parent cgroupns compression-format compression-level cpp-flag cpu-period cpu-quota cpu-shares cpuset-cpus cpuset-mems creds cw decryption-key device dns dns-option dns-search env file format from group-add hooks-dir ignorefile iidfile iidfile-raw ipc isolation jobs label layer-label logfile loglevel manifest memory memory-swap metadata-file mount net network os os-feature os-version output override-arch override-os pid platform progress raw-iidfile retry retry-delay runtime-flag rusage-logfile sbom sbom-image-output sbom-image-purl-output sbom-merge-strategy sbom-output sbom-purl-output sbom-scanner-command sbom-scanner-image secret security-opt shm-size sign-by signature-policy source-date-epoch source-policy-file ssh tag target timestamp ulimit unsetannotation unsetenv unsetlabel userns userns-gid-map userns-gid-map-group userns-uid-map userns-uid-map-user uts variant volume";
+var PODMAN_ROOT_VALUES = "cdi-spec-dir cgroup-manager conmon cpu-profile db-backend default-mounts-file events-backend hooks-dir imagestore log-level max-workers memory-profile namespace network-backend network-cmd-path network-config-dir pull-option registries-conf root runroot runtime runtime-flag storage-driver storage-opt tmpdir volumepath";
+var BUILDAH_ROOT_VALUES = "cgroup-manager cpu-profile default-mounts-file 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";
 var VALUE_FLAGS = {
   docker: new Set(BUILDX_VALUES.split(" ")),
-  podman: new Set(BUILDAH_VALUES.split(" ")),
-  buildah: new Set(BUILDAH_VALUES.split(" "))
+  podman: new Set(`${BUILDAH_VALUES} ${PODMAN_ROOT_VALUES}`.split(" ")),
+  buildah: new Set(`${BUILDAH_VALUES} runtime ${BUILDAH_ROOT_VALUES}`.split(" "))
 };
 var SHORT_VALUES = {
   docker: "cfmot",
@@ -1568,23 +1761,34 @@ var SHORT_VALUES = {
 };
 var takesValue = (arg, engine) => arg.startsWith("--") ? VALUE_FLAGS[engine].has(arg.slice(2)) : arg.length === 2 && SHORT_VALUES[engine].includes(arg[1]);
 function ungroup(argv, engine) {
-  const end = argv.indexOf("--");
-  return argv.flatMap((arg, at) => {
-    if (end >= 0 && at >= end || !/^-[^-]/u.test(arg))
-      return [arg];
+  const out = [];
+  for (let at = 0;at < argv.length; at++) {
+    const arg = argv[at];
+    if (arg === "--") {
+      out.push(...argv.slice(at));
+      break;
+    }
     const split = [];
     let i = 1;
-    while (i < arg.length - 1 && SHORT_BOOLS[engine].includes(arg[i]) && arg[i + 1] !== "=")
-      split.push(`-${arg[i++]}`);
-    return i === 1 ? [arg] : [...split, `-${arg.slice(i)}`];
-  });
+    if (/^-[^-]/u.test(arg))
+      while (i < arg.length - 1 && SHORT_BOOLS[engine].includes(arg[i]) && arg[i + 1] !== "=")
+        split.push(`-${arg[i++]}`);
+    split.push(i === 1 ? arg : `-${arg.slice(i)}`);
+    out.push(...split);
+    if (takesValue(split.at(-1), engine) && at + 1 < argv.length)
+      out.push(argv[++at]);
+  }
+  return out;
 }
 function parseBuildArgs(given, tagPrefix, cachePrefix, {
   vars = new CiMetadata,
   labels = {},
   defaultBranch,
   env = process.env,
-  engine = "docker"
+  engine = "docker",
+  buildx = false,
+  engineVersion,
+  sbom = false
 } = {}) {
   const argv = ungroup(given, engine);
   const parts = [];
@@ -1596,6 +1800,7 @@ function parseBuildArgs(given, tagPrefix, cachePrefix, {
     cacheTo: [],
     buildArgs: [],
     labels: [],
+    annotations: [],
     dockerfile: "",
     target: "",
     platform: "",
@@ -1608,6 +1813,14 @@ function parseBuildArgs(given, tagPrefix, cachePrefix, {
   const positionals = [];
   const contexts = [];
   const envs = [];
+  const platforms = [];
+  let platformParts = false;
+  let fromImage;
+  let format = env["BUILDAH_FORMAT"];
+  const sbomFlags = [];
+  const times = new Map;
+  let epochArg;
+  let allPlatforms = false;
   let rest = [];
   const addTags = (value, flag) => {
     templated ||= hasPlaceholders(value);
@@ -1616,12 +1829,15 @@ function parseBuildArgs(given, tagPrefix, cachePrefix, {
   const summarize = (flag, value) => {
     const field = SUMMARIZED[flag];
     if (field === "buildArgs") {
-      if (value.includes("="))
-        buildArgs.set(...splitAt(value, "="));
-      else if (Object.hasOwn(env, value))
-        buildArgs.set(value, env[value]);
+      const [key, given] = value.includes("=") ? splitAt(value, "=") : [value, Object.hasOwn(env, value) ? env[value] : undefined];
+      if (given !== undefined)
+        buildArgs.set(key, given);
       else if (engine !== "docker")
         buildArgs.set(value, null);
+      if (key === "SOURCE_DATE_EPOCH" && given !== undefined)
+        epochArg = given;
+      else if (key === "SOURCE_DATE_EPOCH" && engine !== "docker")
+        epochArg = undefined;
       if (engine !== "docker" && buildArgs.has("TARGETPLATFORM"))
         buildArgs.set("TARGETPLATFORM", null);
       const epoch = buildArgs.get("SOURCE_DATE_EPOCH");
@@ -1630,7 +1846,10 @@ function parseBuildArgs(given, tagPrefix, cachePrefix, {
     }
     if (field === "dockerfile")
       files.push(value);
-    if (field === "buildArgs" || field === "labels")
+    if (field === "platform") {
+      platforms.push(...value.split(","));
+      summary.platform = platforms.join(",");
+    } else if (field === "buildArgs" || field === "labels" || field === "annotations")
       summary[field].push(value);
     else
       summary[field] = value;
@@ -1640,6 +1859,18 @@ function parseBuildArgs(given, tagPrefix, cachePrefix, {
     const [name, attached] = arg.startsWith("--") && arg.includes("=") ? splitAt(arg, "=") : [arg, undefined];
     const next = () => consumeValue(argv.slice(++i), arg)[0];
     const short = () => arg.slice(arg[2] === "=" ? 3 : 2);
+    if (engine !== "docker" && PLATFORM_PARTS.includes(name))
+      platformParts = true;
+    if (engine !== "docker" && name === "--format")
+      format = attached ?? argv[i + 1];
+    if (engine !== "docker" && name === "--all-platforms")
+      allPlatforms = attached === undefined || !/^(?:0|f|false)$/iu.test(attached);
+    if (engine !== "docker" && name === "--from")
+      fromImage = attached ?? argv[i + 1] ?? "";
+    if (name.startsWith("--sbom") || name === "--attest")
+      sbomFlags.push([name, attached ?? argv[i + 1] ?? ""]);
+    if (engine !== "docker" && (name === "--timestamp" || name === "--source-date-epoch"))
+      times.set(name, attached ?? argv[i + 1] ?? "");
     if (arg === "--") {
       rest = argv.slice(i);
       positionals.push(...rest.slice(1));
@@ -1703,23 +1934,74 @@ function parseBuildArgs(given, tagPrefix, cachePrefix, {
       }
     }
   }
+  const whyIgnored = () => {
+    if (allPlatforms)
+      return `--all-platforms builds for the platforms of the base images, which ce does not read`;
+    if (platformParts)
+      return `${engine}'s --arch, --os or --variant changes the platform, which ce does not follow`;
+    const from = PLATFORM_FROM[engine];
+    if (!from || !platforms.length)
+      return;
+    const since = `ce follows how ${engine} sets it from --platform only from ${from.join(".")}`;
+    const version = engineVersion?.();
+    if (version === undefined)
+      return `${since}, and cannot tell which version builds`;
+    return older(version, from) ? `${since}, and this is ${version}` : undefined;
+  };
+  let ignored;
+  const platformIgnored = () => (ignored ??= { why: whyIgnored() }).why;
   const baseVars = vars;
-  const fromFile = containerfileDefaults({ engine, files, positionals, target: summary.target, contexts, envs }, (arg) => buildArgs.get(arg) ?? undefined);
+  const buildFiles = {
+    engine,
+    files,
+    positionals,
+    target: summary.target,
+    contexts,
+    envs,
+    env,
+    platforms,
+    platformIgnored,
+    format: format === "oci" || format === "docker" ? format : undefined,
+    from: fromImage
+  };
+  const buildArg = (arg) => buildArgs.get(arg) ?? undefined;
+  const fromFile = containerfileDefaults(buildFiles, buildArg);
   vars = withBuildArgs(baseVars, buildArgs, argFile, fromFile);
   const args = parts.flatMap((part) => {
     if (typeof part === "string")
       return [part];
-    const refs = rewriteTagValue(part.tags, tagPrefix, vars);
+    const refs = [
+      ...new Set(rewriteTagValue(part.tags, tagPrefix, vars))
+    ].filter((ref) => !summary.tags.includes(ref));
     summary.tags.push(...refs);
     return refs.map((ref) => `${part.flag}${ref}`);
   });
   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);
+  const CREATED = "org.opencontainers.image.created";
+  const timestamp = times.get("--timestamp");
+  const flagEpoch = timestamp ?? times.get("--source-date-epoch");
+  let epoch;
+  if (engine === "docker")
+    epoch = epochArg ?? (env["SOURCE_DATE_EPOCH"] || !labels[CREATED] ? undefined : dockerfileEpoch(buildFiles, buildArg));
+  else if (flagEpoch !== undefined || env["SOURCE_DATE_EPOCH"])
+    epoch = flagEpoch;
+  else
+    epoch = epochArg ?? (argFile ? "" : undefined);
+  const time = epoch === undefined ? undefined : epochDate(epoch, timestamp === undefined ? 10 : 0);
+  const metadata = Object.entries(labels).filter(([key]) => key !== CREATED || epoch === undefined || time).map(([key, value]) => [
+    key,
+    time && key === CREATED ? rfc3339(time) : value
+  ]);
+  const ownLabels = new Set(summary.labels.map((label) => label.split("=", 1)[0]));
+  const ownAnnotations = new Set(summary.annotations.map((annotation) => annotationKey(annotation, engine)));
+  const addedLabels = metadata.filter(([key, value]) => !ownLabels.has(key) && (engine === "docker" || !(value.includes("$") || engineEscapes(value)))).map(([key, value]) => `${key}=${value}`);
+  const level = engine === "docker" && indexed(platforms) ? "manifest,index:" : "";
+  const addedAnnotations = annotates(engine, env, buildx) ? metadata.filter(([key]) => !ownAnnotations.has(key)).map(([key, value]) => `${level}${key}=${value}`) : [];
+  args.unshift(...addedLabels.map((label) => `--label=${label}`), ...addedAnnotations.map((annotation) => `--annotation=${annotation}`), ...sbomArgs(engine, sbom, sbomFlags));
+  summary.labels.unshift(...addedLabels);
+  summary.annotations.unshift(...addedAnnotations);
   const prefixTemplate = cachePrefix;
   if (rawCacheFrom.length || rawCacheTo.length)
     cachePrefix = expandPrefix(cachePrefix, vars, "cache prefix");
@@ -1744,7 +2026,48 @@ function parseBuildArgs(given, tagPrefix, cachePrefix, {
     summary.cacheTo.push(rewritten);
   }
   args.push(...rest);
-  return { args, summary };
+  return { args, summary, vars };
+}
+function annotationKey(annotation, engine) {
+  const key = annotation.split("=", 1)[0];
+  return engine === "docker" ? key.replace(/^[a-z-]+(?:\[[^\]]*\])?(?:,[a-z-]+(?:\[[^\]]*\])?)*:/u, "") : key;
+}
+var annotates = (engine, env, buildx) => engine !== "docker" || buildx || !["0", "f", "false"].includes((env["DOCKER_BUILDKIT"] ?? "").toLowerCase());
+function indexed(platforms) {
+  const normalized = platforms.map((p) => normalizePlatform(p, "docker"));
+  return normalized.every((p) => p !== undefined) && new Set(normalized).size > 1;
+}
+var SBOM_PATH = "/root/buildinfo/content_manifests/sbom";
+function sbomArgs(engine, sbom, flags) {
+  if (engine === "docker") {
+    const asked = flags.some(([name, value]) => name === "--sbom" || name === "--attest" && csvFields(value)?.findLast((field) => fieldKey(field) === "type")?.slice("type=".length) === "sbom");
+    if (!sbom || asked)
+      return [];
+    if (sbom === "cyclonedx")
+      throw new CeError("ce: SBOM=cyclonedx is not supported by Docker's BuildKit SBOM attestation; use SBOM=spdx or SBOM=true");
+    return ["--sbom=true"];
+  }
+  const preset = flags.findLast(([name]) => name === "--sbom")?.[1];
+  const output = flags.some(([name]) => [
+    "--sbom-output",
+    "--sbom-image-output",
+    "--sbom-purl-output",
+    "--sbom-image-purl-output"
+  ].includes(name));
+  const used = preset ?? (sbom ? `syft-${sbom === "cyclonedx" ? "cyclonedx" : "spdx"}` : undefined);
+  if (used === undefined)
+    return [];
+  const args = preset === undefined ? [`--sbom=${used}`] : [];
+  if (!output)
+    args.push(`--sbom-image-output=${SBOM_PATH}${used.endsWith("-spdx") ? ".spdx.json" : ".cdx.json"}`);
+  return args;
+}
+function older(version, than) {
+  const parts = /^(\d+)\.(\d+)/u.exec(version)?.slice(1).map(Number);
+  if (!parts)
+    return true;
+  const i = parts.findIndex((n, j) => n !== than[j]);
+  return i !== -1 && parts[i] < than[i];
 }
 function splitAt(value, sep) {
   const i = value.indexOf(sep);
@@ -1775,6 +2098,7 @@ function printBuildSummary(engine, args, summary) {
     out.push(`  platform: ${summary.platform}`);
   list("build args", summary.buildArgs);
   list("labels", summary.labels);
+  list("annotations", summary.annotations);
   if (summary.context)
     out.push(`  context: ${summary.context}`);
   io.stderr(`${out.join(`
@@ -2091,28 +2415,60 @@ async function credentialHelper(argv) {
 // src/engine.ts
 var isEngine = (value) => ["docker", "podman", "buildah"].includes(value);
 var WAIT_ATTEMPTS = 30;
-async function waitForEngine(engine) {
+async function waitForEngine(engine, options = []) {
   if (engine === "buildah")
     return true;
+  const argv = [engine, ...options, "info"];
+  let stderr = "";
   for (let attempt = 1;attempt <= WAIT_ATTEMPTS; attempt++) {
-    if (system.run([engine, "info"]).status === 0)
+    const result = system.run(argv);
+    if (result.status === 0)
       return true;
+    stderr = result.stderr.trim();
     logError(`waiting for ${engine}... (${attempt}/${WAIT_ATTEMPTS})`);
     await system.sleep(1000);
   }
   logError(`no engine available: ${engine}`);
+  if (stderr)
+    logError(`${argv.map(shellQuote).join(" ")} last said:
+${stderr}`);
   return false;
 }
-function envFlag(name) {
+function engineVersion(engine, options = []) {
+  const argv = engine === "podman" ? ["podman", ...options, "info", "--format", "{{.Version.Version}}"] : ["buildah", "--version"];
+  for (let attempt = 1;; attempt++) {
+    let result;
+    try {
+      result = system.output(argv);
+    } catch {
+      return;
+    }
+    if (result.status === 0)
+      return /^(?:buildah version )?(\d+\.\d+\.\d+)\b/u.exec(result.stdout.trim())?.[1];
+    if (engine === "buildah" || attempt === WAIT_ATTEMPTS)
+      return;
+    logError(`waiting for ${engine}... (${attempt}/${WAIT_ATTEMPTS})`);
+    system.sleepSync(1000);
+  }
+}
+function envFlag(name, unset = false, allowed = "true or false") {
   const value = (process.env[name] ?? "").toLowerCase();
-  if (["", "0", "false", "no"].includes(value))
+  if (value === "")
+    return unset;
+  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])}`);
+  throw new CeError(`ce: ${name} must be ${allowed}, not ${JSON.stringify(process.env[name])}`);
+}
+function sbomOption() {
+  const value = (process.env["SBOM"] ?? "").toLowerCase();
+  if (value === "spdx" || value === "cyclonedx")
+    return value;
+  return envFlag("SBOM", false, "true, false, spdx or cyclonedx");
 }
 function shellQuote(arg) {
-  return /^[A-Za-z0-9_@%+:,./-][A-Za-z0-9_@%+=:,./-]*$/u.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+  return /^[A-Za-z0-9_@%+=:,./-]+$/u.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
 }
 async function runEngine(engine, argv, tagPrefix, cachePrefix, options = {}) {
   const dryRun = options.dryRun ?? envFlag("CE_DRY_RUN");
@@ -2122,13 +2478,17 @@ async function runEngine(engine, argv, tagPrefix, cachePrefix, options = {}) {
   let summary;
   if (command) {
     const vars = new CiMetadata;
-    const labels = !command.tagsOnly && (options.ociLabels ?? envFlag("OCI_LABELS")) ? vars.labels() : {};
+    const labels = !command.tagsOnly && (options.ociLabels ?? envFlag("OCI_LABELS", true)) ? vars.labels() : {};
+    const sbom = !command.tagsOnly && sbomOption();
     const fromDefault = !command.tagsOnly && (options.cacheFromDefault ?? envFlag("CACHE_FROM_DEFAULT"));
     const parsed = parseBuildArgs(argv.slice(command.start), tagPrefix, cachePrefix, {
       engine,
+      buildx: command.buildx,
       vars,
       labels,
-      defaultBranch: fromDefault ? () => vars.defaultBranch() : undefined
+      sbom,
+      defaultBranch: fromDefault ? () => vars.defaultBranch() : undefined,
+      engineVersion: engine === "docker" ? undefined : () => engineVersion(engine, command.engineOptions)
     });
     args = [...argv.slice(0, command.start), ...parsed.args];
     summary = parsed.summary;
@@ -2146,7 +2506,7 @@ async function runEngine(engine, argv, tagPrefix, cachePrefix, options = {}) {
     logError(`Engine not found: ${engine}`);
     return 1;
   }
-  if (!await waitForEngine(engine))
+  if (!await waitForEngine(engine, command?.engineOptions))
     return 1;
   if (summary)
     printBuildSummary(engine, args, summary);
@@ -2321,7 +2681,7 @@ async function login() {
 
 // src/cli.ts
 function helpText() {
-  return `Usage: ${io.argv0()} [--tag-prefix=<prefix>] [--cache-prefix=<prefix>] [--oci-labels]
+  return `Usage: ${io.argv0()} [--tag-prefix=<prefix>] [--cache-prefix=<prefix>] [--no-oci-labels]
           [--cache-from-default] [--dry-run] [command|engine] [args]
 
 Options:
@@ -2346,10 +2706,12 @@ Options:
                       default branch, from the cache prefix as it is there,
                       so a new branch or PR starts from its cache.
                       Also available via CACHE_FROM_DEFAULT=true.
-    --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.
+    --no-oci-labels   Do not add the org.opencontainers.image.* labels and
+                      annotations (source, url, revision, version, title,
+                      description, created) that builds in a Forgejo Actions
+                      run otherwise get. A --label or --annotation with the
+                      same key wins over them.
+                      Also available via OCI_LABELS=false.
     --dry-run         Print the build summary and the engine command, and
                       exit without running it. Template errors still exit 2;
                       a missing engine is only a warning.
@@ -2387,6 +2749,17 @@ Engines:
     podman [args]     Passthrough to podman
     buildah [args]    Passthrough to buildah
 
+Environment variables (used by builds):
+    SBOM=true         Add an SBOM: with Docker, BuildKit's attestation; with
+                      podman and buildah, syft's SPDX, written into the image
+                      at /root/buildinfo/content_manifests/sbom.spdx.json.
+                      SBOM=spdx selects the same format. SBOM=cyclonedx uses
+                      syft's CycloneDX with podman and buildah, written as
+                      sbom.cdx.json in that directory. Docker refuses it.
+                      An engine SBOM option you pass takes precedence.
+                      A podman or buildah --sbom with no output gets an image
+                      path matching its preset.
+
 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
@@ -2430,6 +2803,8 @@ async function main(argv) {
       [cachePrefix, argv] = [a.slice("--cache-prefix=".length), argv.slice(1)];
     else if (a === "--oci-labels")
       [options.ociLabels, argv] = [true, argv.slice(1)];
+    else if (a === "--no-oci-labels")
+      [options.ociLabels, argv] = [false, argv.slice(1)];
     else if (a === "--cache-from-default")
       [options.cacheFromDefault, argv] = [true, argv.slice(1)];
     else if (a === "--dry-run")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izykitten/ce",
-  "version": "0.0.3-dev.5",
+  "version": "0.0.3-dev.7",
   "description": "Container engine wrapper: tag/cache rewriting for docker, podman and buildah, registry login, and a Forgejo OIDC Docker credential helper",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -14,7 +14,8 @@
   ],
   "scripts": {
     "build": "bun build src/cli.ts --target=node --outfile=dist/ce.js",
-    "prepack": "bun run build"
+    "prepack": "bun run build",
+    "check-engines": "bun scripts/check-engines.ts"
   },
   "engines": {
     "node": ">=22.15.0",