@izykitten/ce 0.0.3-dev.1 → 0.0.3-dev.3

package/README.md

@@ -43,12 +43,23 @@ Tags and the `TAG_PREFIX`/`CACHE_PREFIX` values can use placeholders, filled fro
 | `{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 |
+| `{arg.NAME}` | the build arg `NAME` from this command's `--build-arg`, the value the build gets |
 
 `{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.
+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.
 
-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}` works everywhere. 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.
+Prefixes can use guards too. A guard that does not pass leaves the prefix empty, since a prefix cannot be left out, and the prefix's other values are then not needed. `CACHE_PREFIX='{?pr}pr-{pr}'` gives each pull request a cache of its own (`pr-3`) and leaves every other build sharing the unprefixed one; with `CACHE_FROM_DEFAULT`, a PR also reads that shared one, as the prefix is empty on the default branch. The image name cannot use guards.
+
+`{arg.NAME}` takes the value from `--build-arg NAME=value`, or from the environment for `--build-arg NAME`, as the engine does, so a tag can name a value worked out on the command line:
+
+```sh
+ce docker build --build-arg VERSION="$(cat VERSION)" -t '{image}:{arg.VERSION}' .
+```
+
+The last `--build-arg NAME` wins. One whose variable is not set is passed over by Docker, which keeps an earlier value, while podman and buildah drop the value for the Containerfile's default. Where the build would use the Containerfile's default, which ce does not read, `{arg.NAME}` is an error, guarded or not, unless another guard beside it does not pass. An empty value (`--build-arg NAME=`) is no value. With podman's `--build-arg-file`, which ce does not read either, `{arg.NAME}` needs a `--build-arg NAME` of its own.
+
+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.
 
@@ -64,13 +75,11 @@ A branch, PR and default-branch build:
     -t '{image}:{ref},{?default}latest,{?default}caddy-{env.CADDY_VERSION}' .
 ```
 
-With `CACHE_PREFIX='{ref}'`, each branch and pull request gets a gha cache of its own, so a new one starts cold. To also read the default branch's cache, add it as a `--cache-from`. ce only prefixes a `--cache-from` whose scope matches a `--cache-to`, so this one is passed on unchanged and only read:
+With `CACHE_PREFIX='{ref}'`, each branch and pull request gets a gha cache of its own, so a new one starts cold. With `CACHE_FROM_DEFAULT=true`, or `--cache-from-default` before the engine, each gha `--cache-to` is also read from its scope on the default branch: ce expands the cache prefix as it would be there, so PR 3 reads `pr-3` and `main` and writes only `pr-3`, and with `scope=js` it reads `main-js`. The default branch comes from the event file or `DEFAULT_BRANCH`, as for `{default}`. A prefix that needs `{sha}` or `{revision}` there cannot be worked out for it, and is an error; one whose guards leave it empty there, like `{?pr}{sha}`, does not need them. This only picks what is read: whether it hits depends on what the default branch last wrote.
 
-```sh
---cache type=gha,mode=max --cache-from type=gha,scope=main
-```
+The same can be written by hand, since ce only prefixes a `--cache-from` whose scope matches a `--cache-to` and passes any other on unchanged: `--cache type=gha,mode=max --cache-from type=gha,scope=main`.
 
-PR 3 then reads `pr-3` and `main` and writes only `pr-3`; main reads its own cache a second time. With a scope of its own, such as `--cache type=gha,mode=max,scope=js`, the cache to read is `main-js`. This only picks what is read: whether it hits depends on what main last wrote.
+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:
 
@@ -80,6 +89,15 @@ A release on a SemVer tag, with the version aliases only for stable releases:
 
 `{stable}` does not mean newest: rebuilding an older release moves its aliases back to it.
 
+### 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:
+
+```sh
+GITHUB_REF=refs/tags/v1.2.3 GITHUB_SERVER_URL=https://code.example GITHUB_REPOSITORY=org/app \
+  ce --dry-run docker buildx build -t '{image}:{ref},{?stable}{major}.{minor}' .
+```
+
 ### 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.
@@ -92,7 +110,7 @@ The package installs `docker-credential-ce-forgejo` next to `ce`. `ce` puts that
 
 ## Compatibility
 
-These stay the same from release to release, and [test/contract.test.ts](test/contract.test.ts) checks them by running the built package under Node and Bun:
+These behave the same under Node and Bun, and [test/contract.test.ts](test/contract.test.ts) checks them by running the built package under both. A release that changes one says so here:
 
 - commands, flags and the environment variables `login` reads;
 - the arguments the engine receives after tag and cache rewriting, and its exit code, signals and PID (`ce` replaces itself with the engine);
@@ -102,6 +120,8 @@ These stay the same from release to release, and [test/contract.test.ts](test/co
 
 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.
+
 Compared with the Python version:
 
 - The state file is locked with `ce-forgejo-credentials.json.pidlock`, holding the holder's PID and hostname, rather than `flock`, which Node does not have. A lock whose holder died is broken right away if the PID is gone on the same host, otherwise after two minutes. It does not exclude a Python `ce` using the same Docker config at the same moment.

package/dist/ce.js

@@ -244,7 +244,7 @@ class CiMetadata {
   get(name) {
     const envName = ENV_VARIABLE.exec(name)?.[1];
     if (envName)
-      return nonEmpty(this.#env[envName]);
+      return Object.hasOwn(this.#env, envName) ? nonEmpty(this.#env[envName]) : undefined;
     if (!this.#cache.has(name))
       this.#cache.set(name, this.#resolve(name));
     return this.#cache.get(name);
@@ -298,7 +298,7 @@ class CiMetadata {
         const ref = this.#parsedRef();
         if (ref.kind !== "branch")
           return;
-        return ref.name === this.#defaultBranch() ? ref.name : undefined;
+        return ref.name === this.defaultBranch() ? ref.name : undefined;
       }
       case "revision":
         return this.#require("SHA", `{${name}}`);
@@ -359,7 +359,7 @@ class CiMetadata {
     const ref = this.#parsedRef();
     return ref.kind === "tag" ? SEMVER.exec(ref.name) : null;
   }
-  #defaultBranch() {
+  defaultBranch() {
     const repository = this.#ciEnv("EVENT_PATH") ? this.#payload().repository : undefined;
     const fromEvent = isObject(repository) ? repository.default_branch : undefined;
     const branch = typeof fromEvent === "string" && fromEvent || nonEmpty(this.#env.DEFAULT_BRANCH);
@@ -384,6 +384,21 @@ class CiMetadata {
     return payload;
   }
 }
+var ON_DEFAULT_BRANCH = new Set(["ref", "branch", "default"]);
+var UNKNOWN_ON_DEFAULT_BRANCH = new Set(["revision", "sha"]);
+function onDefaultBranch(vars, branch) {
+  return {
+    known: (name) => vars.known(name),
+    get(name) {
+      if (ON_DEFAULT_BRANCH.has(name))
+        return branch;
+      if (UNKNOWN_ON_DEFAULT_BRANCH.has(name)) {
+        throw new CeError(`ce: the default branch's cache scope cannot use {${name}}: this run does not know its commit`);
+      }
+      return name === "image" || name.startsWith("env.") || name.startsWith("arg.") ? vars.get(name) : undefined;
+    }
+  };
+}
 
 // src/system.ts
 import { spawnSync } from "node:child_process";
@@ -479,12 +494,26 @@ function parse(template, vars) {
   text(template.slice(last));
   return parts;
 }
-function expand(template, vars, encode) {
-  const parts = parse(template, vars);
+function guardsPass(parts, vars) {
+  let unknown;
   for (const part of parts) {
-    if ("name" in part && part.guard && vars.get(part.name) === undefined)
-      return null;
+    if (!("name" in part) || !part.guard)
+      continue;
+    try {
+      if (vars.get(part.name) === undefined)
+        return false;
+    } catch (exc) {
+      unknown ??= exc;
+    }
   }
+  if (unknown !== undefined)
+    throw unknown;
+  return true;
+}
+function expand(template, vars, encode) {
+  const parts = parse(template, vars);
+  if (!guardsPass(parts, vars))
+    return null;
   let out = "";
   for (const part of parts) {
     if ("text" in part)
@@ -499,16 +528,21 @@ function expand(template, vars, encode) {
   }
   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 checkValue(template, vars, what, guards = false) {
+  const parts = parse(template, vars);
+  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`);
   }
 }
-function expandValue(template, vars, encode, what) {
-  checkValue(template, vars, what);
-  for (const part of parse(template, vars)) {
-    if ("name" in part && vars.get(part.name) === undefined) {
-      throw new CeError(`ce: {${part.name}} has no value here, in the ${what} ${JSON.stringify(template)}`);
+function expandValue(template, vars, encode, what, guards = false) {
+  checkValue(template, vars, what, guards);
+  const parts = parse(template, vars);
+  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);
@@ -570,7 +604,7 @@ function expandImage(template, vars) {
   return image;
 }
 function expandPrefix(prefix, vars, what) {
-  return hasPlaceholders(prefix) ? expandValue(prefix, vars, encodeTagValue, what) : prefix;
+  return hasPlaceholders(prefix) ? expandValue(prefix, vars, encodeTagValue, what, true) : prefix;
 }
 function literalRef(repo, tag) {
   if (tag.includes("/")) {
@@ -593,7 +627,7 @@ function rewriteTagValue(value, tagPrefix, vars = new CiMetadata) {
   if (hasPlaceholders(repoTemplate))
     checkValue(repoTemplate, vars, "image name");
   if (hasPlaceholders(tagPrefix))
-    checkValue(tagPrefix, vars, "tag prefix");
+    checkValue(tagPrefix, vars, "tag prefix", true);
   let repo;
   const expandRepo = () => repo ??= hasPlaceholders(repoTemplate) ? expandImage(repoTemplate, vars) : repoTemplate;
   if (tagList === undefined)
@@ -664,6 +698,7 @@ function ghaFields(value) {
   const type = fields?.findLast((field) => fieldKey(field) === "type");
   return type?.slice("type=".length) === "gha" ? fields : null;
 }
+var isGhaCache = (value) => ghaFields(value) !== null;
 var scopeIndex = (fields) => fields.findLastIndex((field) => fieldKey(field) === "scope");
 function cacheScopeName(value) {
   const fields = ghaFields(value);
@@ -697,6 +732,12 @@ function normalizeCacheScope(value, cachePrefix) {
     fields[i] = `scope=${scope}`;
   return csvJoin(fields);
 }
+function withoutCacheMode(value) {
+  const fields = ghaFields(value);
+  if (!fields?.some((field) => fieldKey(field) === "mode"))
+    return value;
+  return csvJoin(fields.filter((field) => fieldKey(field) !== "mode"));
+}
 
 // src/build-args.ts
 function consumeValue(argv, flag) {
@@ -716,8 +757,27 @@ var SUMMARIZED = {
   "--build-arg": "buildArgs",
   "--label": "labels"
 };
-function parseBuildArgs(argv, tagPrefix, cachePrefix, { vars = new CiMetadata, labels = {} } = {}) {
-  const args = [];
+var ARG_VARIABLE = /^arg\.([A-Za-z_][A-Za-z0-9_]*)$/u;
+function withBuildArgs(vars, values, argFile) {
+  return {
+    known: (name) => ARG_VARIABLE.test(name) || vars.known(name),
+    get(name) {
+      const arg = ARG_VARIABLE.exec(name)?.[1];
+      if (arg === undefined)
+        return vars.get(name);
+      const value = values.get(arg);
+      if (value === undefined && argFile) {
+        throw new CeError(`ce: {${name}} needs --build-arg ${arg} on this command, as ce does not read --build-arg-file`);
+      }
+      if (value == null) {
+        throw new CeError(`ce: {${name}} needs --build-arg ${arg}=<value> on this command, or --build-arg ${arg} with ${arg} set; ` + "ce does not read defaults from the Containerfile");
+      }
+      return value || undefined;
+    }
+  };
+}
+function parseBuildArgs(argv, tagPrefix, cachePrefix, { vars = new CiMetadata, labels = {}, defaultBranch, env = process.env, engine = "docker" } = {}) {
+  const parts = [];
   const rawCacheFrom = [];
   const rawCacheTo = [];
   const summary = {
@@ -732,16 +792,23 @@ function parseBuildArgs(argv, tagPrefix, cachePrefix, { vars = new CiMetadata, l
     context: ""
   };
   let templated = false;
+  const buildArgs = new Map;
+  let argFile = false;
   let rest = [];
   const addTags = (value, flag) => {
     templated ||= hasPlaceholders(value);
-    const refs = rewriteTagValue(value, tagPrefix, vars);
-    for (const ref of refs)
-      args.push(`${flag}${ref}`);
-    summary.tags.push(...refs);
+    parts.push({ tags: value, flag });
   };
   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]);
+      else if (engine !== "docker")
+        buildArgs.set(value, null);
+    }
     if (field === "buildArgs" || field === "labels")
       summary[field].push(value);
     else
@@ -770,27 +837,40 @@ function parseBuildArgs(argv, tagPrefix, cachePrefix, { vars = new CiMetadata, l
       rawCacheTo.push(attached ?? next());
     else if (name === "--cache") {
       const v = attached ?? next();
-      rawCacheFrom.push(v);
+      rawCacheFrom.push(withoutCacheMode(v));
       rawCacheTo.push(v);
     } else if (Object.hasOwn(SUMMARIZED, name)) {
       const flag = name;
       if (attached === undefined) {
         const v = next();
-        args.push(arg, v);
+        parts.push(arg, v);
         summarize(flag, v);
       } else {
-        args.push(arg);
+        parts.push(arg);
         summarize(flag, attached);
       }
+    } else if (name === "--build-arg-file") {
+      argFile = true;
+      parts.push(arg);
+      if (attached === undefined)
+        parts.push(next());
     } else if (arg.startsWith("-f") && arg.length > 2) {
-      args.push(arg);
+      parts.push(arg);
       summary.dockerfile = arg.slice(2);
     } else {
-      args.push(arg);
+      parts.push(arg);
       if (!arg.startsWith("-"))
         summary.context = arg;
     }
   }
+  vars = withBuildArgs(vars, buildArgs, argFile);
+  const args = parts.flatMap((part) => {
+    if (typeof part === "string")
+      return [part];
+    const refs = rewriteTagValue(part.tags, tagPrefix, vars);
+    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");
   }
@@ -798,11 +878,17 @@ function parseBuildArgs(argv, tagPrefix, cachePrefix, { vars = new CiMetadata, l
   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 prefixTemplate = cachePrefix;
   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;
+  const cacheFrom = rawCacheFrom.map((c) => toNames.has(cacheScopeName(c)) ? normalizeCacheScope(c, cachePrefix) : c);
+  const ghaTo = rawCacheTo.filter(isGhaCache);
+  if (defaultBranch && ghaTo.length) {
+    const prefix = expandPrefix(prefixTemplate, onDefaultBranch(vars, defaultBranch()), "cache prefix");
+    cacheFrom.push(...ghaTo.map((c) => normalizeCacheScope(withoutCacheMode(c), prefix)));
+  }
+  for (const rewritten of new Set(cacheFrom)) {
     args.push(`--cache-from=${rewritten}`);
     summary.cacheFrom.push(rewritten);
   }
@@ -1169,18 +1255,50 @@ function envFlag(name) {
     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) {
+function shellQuote(arg) {
+  return /^[A-Za-z0-9_@%+:,./-][A-Za-z0-9_@%+=:,./-]*$/u.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+}
+function engineCommand(engine, args) {
+  if (engine === "docker" || !system.which("gosu"))
+    return [engine, ...args];
+  const user = process.env.USER ?? "";
+  if (!user) {
+    logError("ce: gosu is available but USER is not set; cannot drop privileges. Set USER or remove gosu from PATH.");
+    return null;
+  }
+  return ["gosu", user, engine, ...args];
+}
+async function runEngine(engine, argv, tagPrefix, cachePrefix, options = {}) {
+  const dryRun = options.dryRun ?? envFlag("CE_DRY_RUN");
+  ensureHelperOnPath();
   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 });
+    const labels = !command.tagsOnly && (options.ociLabels ?? envFlag("OCI_LABELS")) ? vars.labels() : {};
+    const fromDefault = !command.tagsOnly && (options.cacheFromDefault ?? envFlag("CACHE_FROM_DEFAULT"));
+    const parsed = parseBuildArgs(argv.slice(command.start), tagPrefix, cachePrefix, {
+      engine,
+      vars,
+      labels,
+      defaultBranch: fromDefault ? () => vars.defaultBranch() : undefined
+    });
     args = [...argv.slice(0, command.start), ...parsed.args];
     summary = parsed.summary;
   }
-  ensureHelperOnPath();
+  if (dryRun) {
+    const run = engineCommand(engine, args);
+    if (!run)
+      return 1;
+    if (summary)
+      printBuildSummary(engine, args, summary);
+    if (!system.which(engine))
+      logError(`ce: warning: ${engine} is not on PATH, so running this here would fail`);
+    io.stdout(`${run.map(shellQuote).join(" ")}
+`);
+    return 0;
+  }
   if (!system.which(engine)) {
     logError(`Engine not found: ${engine}`);
     return 1;
@@ -1189,17 +1307,8 @@ async function runEngine(engine, argv, tagPrefix, cachePrefix, ociLabels) {
     return 1;
   if (summary)
     printBuildSummary(engine, args, summary);
-  if (engine === "docker")
-    return system.exec("docker", ["docker", ...args]);
-  if (system.which("gosu")) {
-    const user = process.env.USER ?? "";
-    if (!user) {
-      logError("ce: gosu is available but USER is not set; cannot drop privileges. Set USER or remove gosu from PATH.");
-      return 1;
-    }
-    return system.exec("gosu", ["gosu", user, engine, ...args]);
-  }
-  return system.exec(engine, [engine, ...args]);
+  const run = engineCommand(engine, args);
+  return run ? system.exec(run[0], run) : 1;
 }
 
 // src/login.ts
@@ -1352,7 +1461,8 @@ async function login() {
 
 // src/cli.ts
 function helpText() {
-  return `Usage: ${io.argv0()} [--tag-prefix=<prefix>] [--cache-prefix=<prefix>] [--oci-labels] [command|engine] [args]
+  return `Usage: ${io.argv0()} [--tag-prefix=<prefix>] [--cache-prefix=<prefix>] [--oci-labels]
+          [--cache-from-default] [--dry-run] [command|engine] [args]
 
 Options:
     --tag-prefix=<prefix>
@@ -1368,15 +1478,27 @@ Options:
                       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.
+                      A gha cache-from made this way leaves out mode=, which
+                      only applies to export. The same cache-from given twice
+                      is passed once.
+    --cache-from-default
+                      Also read each gha --cache-to from its scope on the
+                      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.
+    --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.
+                      Also available via CE_DRY_RUN=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.
+                      a value. In a prefix, leaves the prefix empty instead.
     {image}           Registry host and repository, lowercased
     {ref}             Branch name, pr-<number>, or tag name
     {branch} {pr} {tag}
@@ -1388,6 +1510,11 @@ Placeholders, in build tags and in the tag and cache prefixes:
                       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
+    {arg.NAME}        The build arg NAME from this command's --build-arg;
+                      an error without one, even guarded, as ce does not
+                      read Containerfiles
+    A guard that does not pass leaves its tag out or its prefix empty even if
+    another guard there cannot be worked out.
     Values are made safe for a tag ("ci/x" becomes "ci-x"). Quote templates
     in single quotes. Example:
         -t '{image}:{ref},{?default}latest'
@@ -1428,7 +1555,7 @@ Environment variables (used by login):
 `;
 }
 async function main(argv) {
-  let ociLabels;
+  const options = {};
   let tagPrefix = process.env.TAG_PREFIX ?? "";
   let cachePrefix = process.env.CACHE_PREFIX ?? process.env.TAG_PREFIX ?? "";
   for (;; ) {
@@ -1442,7 +1569,11 @@ async function main(argv) {
     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)];
+      [options.ociLabels, argv] = [true, argv.slice(1)];
+    else if (a === "--cache-from-default")
+      [options.cacheFromDefault, argv] = [true, argv.slice(1)];
+    else if (a === "--dry-run")
+      [options.dryRun, argv] = [true, argv.slice(1)];
     else
       break;
   }
@@ -1456,7 +1587,7 @@ async function main(argv) {
   if (command === "credential-helper")
     return credentialHelper(rest);
   if (isEngine(command))
-    return runEngine(command, rest, tagPrefix, cachePrefix, ociLabels);
+    return runEngine(command, rest, tagPrefix, cachePrefix, options);
   io.stderr(helpText());
   return 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izykitten/ce",
-  "version": "0.0.3-dev.1",
+  "version": "0.0.3-dev.3",
   "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",