@akanjs/cli 3.1.0-rc.1 → 3.1.0-rc.3

package/{pipeline.command-d0v38572.js → pipeline.command-r5t30py6.js}

@@ -4,7 +4,7 @@ import {
   runner,
   script,
   command
-} from "./index-6jjtnhkw.js";
+} from "./index-3x7yeecy.js";
 import {
   FileSys2
 } from "./index-52w0fvh8.js";
@@ -12,7 +12,7 @@ import {
   AkanAppConfig,
   AkanWorkspaceConfig,
   AppExecutor
-} from "./index-55mynnqs.js";
+} from "./index-bv210r6t.js";
 import {
   resolveMobileTargets
 } from "./index-q958tqqg.js";
@@ -31,13 +31,16 @@ import {
   pipelineActions,
   pipelineMilestones as pipelineMilestones2,
   pipelineOtaPlatforms as pipelineOtaPlatforms2,
-  pipelinePlanVersion
+  pipelinePlanLimits as pipelinePlanLimits2,
+  pipelinePlanVersion,
+  toError
 } from "akanjs/common";
 
 // pkgs/@akanjs/devkit/pipeline/PipelineInputReader.ts
 import {
   PipelineNames,
   PipelinePattern,
+  PipelineValueReader,
   pipelineActionNames,
   pipelineMilestones,
   pipelineOtaPlatforms,
@@ -47,15 +50,31 @@ import {
 
 class PipelineInputReader {
   static #futureKeys = ["cache", "artifacts", "input", "image", "services", "notify"];
+  static #stageKeys = ["id", "name", "description", "milestone", "when", "timeout", "allowFailure"];
+  static #shellKeys = [...PipelineInputReader.#stageKeys, "sh", "steps", "env", "secrets", "retry"];
+  static #postResults = ["success", "failure", "canceled", "always"];
   static #durationPattern = /^(\d+)(s|m|h)$/;
+  static #trailingHighSurrogate = /[\uD800-\uDBFF]$/;
   static #stepNameChars = 80;
+  static #shownChars = 80;
+  static clip(text, max) {
+    if (text.length <= max)
+      return text;
+    const cut = text.slice(0, max - 1);
+    return `${PipelineInputReader.#trailingHighSurrogate.test(cut) ? cut.slice(0, -1) : cut}\u2026`;
+  }
   diagnostics = [];
   #file;
+  #read = new PipelineValueReader("config", (path, ...problems) => {
+    for (const problem of problems)
+      this.#problem(path, problem);
+    return null;
+  });
   constructor(file) {
     this.#file = file;
   }
   workspace(value) {
-    const input = this.#object(value, "pipeline", ["schemaVersion", "env", "timeout", "before", "after", "post"]);
+    const input = this.#read.object(value, "pipeline", ["schemaVersion", "env", "timeout", "before", "after", "post"]);
     if (!input)
       return null;
     this.#schemaVersion(input.schemaVersion, "pipeline.schemaVersion");
@@ -75,7 +94,7 @@ class PipelineInputReader {
     };
   }
   app(value) {
-    const input = this.#object(value, "pipeline", ["schemaVersion", "stages", "env", "after"]);
+    const input = this.#read.object(value, "pipeline", ["schemaVersion", "stages", "env", "after"]);
     if (!input)
       return null;
     this.#schemaVersion(input.schemaVersion, "pipeline.schemaVersion");
@@ -95,53 +114,51 @@ class PipelineInputReader {
     };
   }
   #workspaceStage(value, path) {
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw)
       return null;
-    if ("use" in raw) {
+    if (this.#declares(raw, "use")) {
       this.#report("pipeline.schema.invalid", "built-in actions are declared per app, in apps/<app>/akan.config.ts", `${path}.use`);
       return null;
     }
-    if ("parallel" in raw)
+    if (this.#declares(raw, "parallel"))
       return this.#parallelStage(raw, path);
-    if ("matrix" in raw)
+    if (this.#declares(raw, "matrix"))
       return this.#matrixStage(raw, path);
-    return this.#shellStage(raw, path, "workspace");
+    return this.#shellStage(raw, path);
   }
   #appStage(value, path) {
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw)
       return null;
-    if ("parallel" in raw || "matrix" in raw) {
-      this.#report("pipeline.schema.invalid", `an app's own stage takes no \`${"parallel" in raw ? "parallel" : "matrix"}\`: it is already that app's, and parallel or per-app copies belong to the workspace root akan.config.ts`, path);
+    const workspaceKey = this.#declares(raw, "parallel") ? "parallel" : this.#declares(raw, "matrix") ? "matrix" : null;
+    if (workspaceKey) {
+      this.#report("pipeline.schema.invalid", `an app's own stage takes no \`${workspaceKey}\`: it is already that app's, and parallel or per-app copies belong to the workspace root akan.config.ts`, path);
       return null;
     }
-    if ("use" in raw)
+    if (this.#declares(raw, "use"))
       return this.#actionStage(raw, path);
-    return this.#shellStage(raw, path, "app");
+    return this.#shellStage(raw, path);
+  }
+  #declares(raw, key) {
+    return raw[key] !== undefined || key in raw && raw.sh === undefined && raw.steps === undefined;
   }
   #actionStage(raw, path) {
-    if (!this.#keys(raw, path, [
+    if (!this.#read.keys(raw, path, [
       "use",
-      "id",
-      "name",
-      "description",
-      "milestone",
-      "when",
-      "timeout",
-      "allowFailure",
+      ...PipelineInputReader.#stageKeys,
       "retry",
       ...raw.use === "ota" ? ["targets", "platforms"] : []
     ]))
       return null;
-    const action = this.#oneOf(raw.use, `${path}.use`, pipelineActionNames);
+    const action = this.#read.oneOf(raw.use, `${path}.use`, pipelineActionNames);
     if (!action)
       return null;
-    const name = raw.name === undefined ? null : this.#text(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
+    const name = raw.name === undefined ? null : this.#read.string(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
     const id = raw.id === undefined ? action : this.#id(raw.id, `${path}.id`);
     if (!id)
       return null;
-    const attempts = raw.retry === undefined ? null : this.#int(raw.retry, `${path}.retry`, 1, pipelinePlanLimits.retryAttempts);
+    const attempts = raw.retry === undefined ? null : this.#read.int(raw.retry, `${path}.retry`, 1, pipelinePlanLimits.retryAttempts);
     return {
       kind: "action",
       action,
@@ -150,13 +167,13 @@ class PipelineInputReader {
       named: name !== null,
       description: this.#description(raw.description, `${path}.description`),
       milestone: this.#milestone(raw.milestone, `${path}.milestone`),
-      when: this.#when(raw.when, `${path}.when`, false),
+      when: this.#when(raw.when, `${path}.when`),
       timeoutSeconds: this.#duration(raw.timeout, `${path}.timeout`),
       allowFailure: this.#boolean(raw.allowFailure, `${path}.allowFailure`),
       retry: attempts === null ? null : { attempts, delaySeconds: 0 },
       targets: raw.targets === undefined ? null : this.#nonEmptySet(this.#strings(raw.targets, `${path}.targets`), `${path}.targets`),
       platforms: raw.platforms === undefined ? null : this.#nonEmptySet(this.#list(raw.platforms, `${path}.platforms`).flatMap((platform, idx) => {
-        const parsed = this.#oneOf(platform, `${path}.platforms[${idx}]`, pipelineOtaPlatforms);
+        const parsed = this.#read.oneOf(platform, `${path}.platforms[${idx}]`, pipelineOtaPlatforms);
         return parsed ? [parsed] : [];
       }), `${path}.platforms`),
       path
@@ -169,53 +186,23 @@ class PipelineInputReader {
     }
     return [...new Set(items)];
   }
-  #shellStage(raw, path, scope) {
-    const keys = [
-      "id",
-      "name",
-      "description",
-      "milestone",
-      "when",
-      "timeout",
-      "allowFailure",
-      "sh",
-      "steps",
-      "env",
-      "secrets",
-      "retry"
-    ];
-    if (!this.#keys(raw, path, keys))
+  #shellStage(raw, path) {
+    if (!this.#read.keys(raw, path, PipelineInputReader.#shellKeys))
       return null;
-    const head = this.#stageHead(raw, path, scope === "workspace" ? "workspace" : "app");
+    const head = this.#stageHead(raw, path);
     if (!head)
       return null;
     const steps = this.#stageSteps(raw, path);
     return steps ? { kind: "sh", ...head, steps } : null;
   }
   #matrixStage(raw, path) {
-    const keys = [
-      "id",
-      "name",
-      "description",
-      "milestone",
-      "when",
-      "timeout",
-      "allowFailure",
-      "sh",
-      "steps",
-      "env",
-      "secrets",
-      "retry",
-      "matrix",
-      "maxParallel"
-    ];
-    if (!this.#keys(raw, path, keys))
+    if (!this.#read.keys(raw, path, [...PipelineInputReader.#shellKeys, "matrix", "maxParallel"]))
       return null;
     if (raw.matrix !== "apps") {
-      this.#report("pipeline.schema.invalid", `${JSON.stringify(raw.matrix)} is not a matrix axis: only "apps"`, `${path}.matrix`);
+      this.#report("pipeline.schema.invalid", `${PipelineInputReader.#show(raw.matrix)} is not a matrix axis: only "apps"`, `${path}.matrix`);
       return null;
     }
-    const head = this.#stageHead(raw, path, "matrix");
+    const head = this.#stageHead(raw, path, { allowApp: true });
     if (!head)
       return null;
     const steps = this.#stageSteps(raw, path);
@@ -224,23 +211,10 @@ class PipelineInputReader {
     return { kind: "matrix", ...head, maxParallel: this.#maxParallel(raw.maxParallel, `${path}.maxParallel`), steps };
   }
   #parallelStage(raw, path) {
-    const keys = [
-      "id",
-      "name",
-      "description",
-      "milestone",
-      "when",
-      "timeout",
-      "allowFailure",
-      "parallel",
-      "maxParallel",
-      "failFast",
-      "env",
-      "secrets"
-    ];
-    if (!this.#keys(raw, path, keys))
+    const keys = [...PipelineInputReader.#stageKeys, "parallel", "maxParallel", "failFast", "env", "secrets"];
+    if (!this.#read.keys(raw, path, keys))
       return null;
-    const head = this.#stageHead(raw, path, "workspace");
+    const head = this.#stageHead(raw, path);
     if (!head)
       return null;
     const env = this.#env(raw.env, `${path}.env`);
@@ -248,20 +222,22 @@ class PipelineInputReader {
     const ids = new Set;
     const branches = this.#list(raw.parallel, `${path}.parallel`).flatMap((branch, idx) => {
       const branchPath = `${path}.parallel[${idx}]`;
-      const branchRaw = this.#object(branch, branchPath);
+      const branchRaw = this.#read.object(branch, branchPath);
       if (!branchRaw)
         return [];
-      if ("use" in branchRaw || "parallel" in branchRaw || "matrix" in branchRaw) {
+      if (["use", "parallel", "matrix"].some((key) => this.#declares(branchRaw, key))) {
         this.#report("pipeline.schema.invalid", "a parallel branch is a shell stage", branchPath);
         return [];
       }
-      const rule = this.#shellStage(branchRaw, branchPath, "workspace");
+      const rule = this.#shellStage(branchRaw, branchPath);
       if (!rule)
         return [];
       if (rule.when.changed && head.when.changed) {
         this.#report("pipeline.schema.invalid", "`when.changed` on both a parallel stage and its branch cannot be combined; keep one", `${branchPath}.when.changed`);
         return [];
       }
+      if (head.id === "post" && PipelineInputReader.#postResults.includes(rule.id))
+        this.#report("pipeline.id.reserved", `"post.${rule.id}" is reserved for the steps of post.${rule.id}; give this branch or its parallel stage another \`id\``, `${branchPath}.${branchRaw.id === undefined ? "name" : "id"}`);
       this.#claimId(ids, rule.id, rule.path);
       const steps = rule.steps.map((step) => ({
         ...step,
@@ -270,7 +246,7 @@ class PipelineInputReader {
       }));
       return [{ ...rule, steps }];
     });
-    if (!branches.length && Array.isArray(raw.parallel))
+    if (!branches.length && (raw.parallel === undefined || Array.isArray(raw.parallel)))
       this.#report("pipeline.schema.invalid", "a parallel stage holds at least one branch", `${path}.parallel`);
     return {
       kind: "parallel",
@@ -280,8 +256,8 @@ class PipelineInputReader {
       branches
     };
   }
-  #stageHead(raw, path, whenScope) {
-    const name = this.#text(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
+  #stageHead(raw, path, { allowApp = false } = {}) {
+    const name = this.#read.string(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
     if (name === null)
       return null;
     const id = raw.id === undefined ? this.#slugId(name, `${path}.name`) : this.#id(raw.id, `${path}.id`);
@@ -292,7 +268,7 @@ class PipelineInputReader {
       name,
       description: this.#description(raw.description, `${path}.description`),
       milestone: this.#milestone(raw.milestone, `${path}.milestone`),
-      when: this.#when(raw.when, `${path}.when`, whenScope === "matrix"),
+      when: this.#when(raw.when, `${path}.when`, { allowApp }),
       timeoutSeconds: this.#duration(raw.timeout, `${path}.timeout`),
       allowFailure: this.#boolean(raw.allowFailure, `${path}.allowFailure`),
       path
@@ -330,20 +306,20 @@ class PipelineInputReader {
     });
   }
   #step(value, path, idx) {
-    const raw = typeof value === "string" ? { sh: value } : this.#object(value, path);
+    const raw = typeof value === "string" ? { sh: value } : this.#read.object(value, path);
     if (!raw)
       return null;
     const keys = ["sh", "id", "name", "cwd", "env", "secrets", "timeout", "retry", "allowFailure", "skipExitCodes"];
-    if (!this.#keys(raw, path, keys))
+    if (!this.#read.keys(raw, path, keys))
       return null;
-    const run = this.#text(raw.sh, typeof value === "string" ? path : `${path}.sh`, Number.POSITIVE_INFINITY);
+    const run = this.#read.string(raw.sh, typeof value === "string" ? path : `${path}.sh`, Number.POSITIVE_INFINITY);
     if (run === null)
       return null;
     if (new TextEncoder().encode(run).length > pipelinePlanLimits.shBytes) {
       this.#report("pipeline.limit.exceeded", `a script is at most ${pipelinePlanLimits.shBytes} bytes`, path);
       return null;
     }
-    const name = raw.name === undefined ? PipelineInputReader.#nameOf(run) : this.#text(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
+    const name = raw.name === undefined ? PipelineInputReader.#nameOf(run) : this.#read.string(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
     if (name === null)
       return null;
     const localId = raw.id !== undefined ? this.#id(raw.id, `${path}.id`) : raw.name !== undefined ? this.#slugId(name, `${path}.name`) : String(idx + 1);
@@ -366,11 +342,11 @@ class PipelineInputReader {
     const empty = { success: [], failure: [], canceled: [], always: [] };
     if (value === undefined)
       return empty;
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw)
       return empty;
     for (const key of Object.keys(raw))
-      if (!["success", "failure", "canceled", "always"].includes(key))
+      if (!PipelineInputReader.#postResults.includes(key))
         this.#report("pipeline.schema.unknownKey", key === "unstable" ? "`unstable` is not a result the framework knows: the executor decides which list an allowed failure runs" : `"${key}" is not a post result: success, failure, canceled or always`, `${path}.${key}`);
     const steps = (key) => {
       const ids = new Set;
@@ -388,11 +364,11 @@ class PipelineInputReader {
       always: steps("always")
     };
   }
-  #when(value, path, allowApp) {
+  #when(value, path, { allowApp = false } = {}) {
     const none = { branch: null, trigger: null, changed: null, app: null };
     if (value === undefined)
       return none;
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw)
       return none;
     for (const key of Object.keys(raw)) {
@@ -401,9 +377,11 @@ class PipelineInputReader {
       this.#report("pipeline.schema.unknownKey", key === "app" ? "`when.app` narrows a workspace matrix stage only; an app's own stages are already that app's" : `"${key}" is not a condition: branch, trigger, changed${allowApp ? " or app" : ""}`, `${path}.${key}`);
     }
     const triggers = raw.trigger === undefined ? null : (typeof raw.trigger === "string" ? [raw.trigger] : this.#list(raw.trigger, `${path}.trigger`)).flatMap((trigger, idx) => {
-      const parsed = this.#oneOf(trigger, `${path}.trigger[${idx}]`, pipelineTriggers);
+      const parsed = this.#read.oneOf(trigger, `${path}.trigger[${idx}]`, pipelineTriggers);
       return parsed ? [parsed] : [];
     });
+    if (Array.isArray(raw.trigger) && !raw.trigger.length)
+      this.#report("pipeline.schema.invalid", "a trigger list may not be empty", `${path}.trigger`);
     return {
       branch: this.#patterns(raw.branch, `${path}.branch`),
       trigger: triggers,
@@ -424,12 +402,12 @@ class PipelineInputReader {
   }
   #schemaVersion(value, path) {
     if (value !== undefined && value !== 1)
-      this.#report("pipeline.schema.unsupported", `${JSON.stringify(value)} is not a schemaVersion this CLI reads (1)`, path);
+      this.#report("pipeline.schema.unsupported", `${PipelineInputReader.#show(value)} is not a schemaVersion this CLI reads (1)`, path);
   }
   #env(value, path) {
     if (value === undefined)
       return {};
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw)
       return {};
     const env = {};
@@ -439,6 +417,8 @@ class PipelineInputReader {
         this.#report("pipeline.env.name", problem, `${path}.${name}`);
       else if (typeof entry !== "string")
         this.#report("pipeline.schema.invalid", "must be a string", `${path}.${name}`);
+      else if (entry.length > pipelinePlanLimits.shBytes)
+        this.#report("pipeline.limit.exceeded", `an env value is at most ${pipelinePlanLimits.shBytes} characters`, `${path}.${name}`);
       else
         env[name] = entry;
     }
@@ -446,10 +426,10 @@ class PipelineInputReader {
   }
   #secrets(value, path) {
     const names = value === undefined ? [] : this.#strings(value, path);
-    const valid = names.filter((name) => {
+    const valid = names.filter((name, idx) => {
       const problem = PipelineNames.secretNameError(name);
       if (problem)
-        this.#report("pipeline.secret.name", problem, path);
+        this.#report("pipeline.secret.name", problem, `${path}[${idx}]`);
       return !problem;
     });
     return [...new Set(valid)];
@@ -457,7 +437,7 @@ class PipelineInputReader {
   #cwd(value, path) {
     if (value === undefined)
       return ".";
-    const cwd = this.#text(value, path, 1024);
+    const cwd = this.#read.string(value, path, 1024);
     if (cwd === null)
       return ".";
     if (cwd.startsWith("/") || cwd.startsWith("~") || cwd.includes("\\") || cwd.split("/").includes("..")) {
@@ -470,7 +450,7 @@ class PipelineInputReader {
     if (value === undefined)
       return [];
     const codes = this.#list(value, path).flatMap((code, idx) => {
-      const parsed = this.#int(code, `${path}[${idx}]`, 1, 255);
+      const parsed = this.#read.int(code, `${path}[${idx}]`, 1, 255);
       return parsed === null ? [] : [parsed];
     });
     return [...new Set(codes)];
@@ -479,13 +459,13 @@ class PipelineInputReader {
     if (value === undefined)
       return null;
     if (typeof value === "number") {
-      const attempts = this.#int(value, path, 1, pipelinePlanLimits.retryAttempts);
+      const attempts = this.#read.int(value, path, 1, pipelinePlanLimits.retryAttempts);
       return attempts === null ? null : { attempts, delaySeconds: 0 };
     }
-    const raw = this.#object(value, path);
-    if (!raw || !this.#keys(raw, path, ["attempts", "delay"]))
+    const raw = this.#read.object(value, path);
+    if (!raw || !this.#read.keys(raw, path, ["attempts", "delay"]))
       return null;
-    const attempts = this.#int(raw.attempts, `${path}.attempts`, 1, pipelinePlanLimits.retryAttempts);
+    const attempts = this.#read.int(raw.attempts, `${path}.attempts`, 1, pipelinePlanLimits.retryAttempts);
     const delaySeconds = this.#duration(raw.delay, `${path}.delay`, {
       min: 0,
       max: pipelinePlanLimits.retryDelaySeconds
@@ -498,22 +478,22 @@ class PipelineInputReader {
     const match = typeof value === "string" ? PipelineInputReader.#durationPattern.exec(value) : null;
     const seconds = typeof value === "number" && Number.isInteger(value) ? value : match ? Number(match[1]) * { s: 1, m: 60, h: 3600 }[match[2]] : Number.NaN;
     if (!Number.isInteger(seconds) || seconds < min || seconds > max) {
-      this.#report("pipeline.duration.invalid", `${JSON.stringify(value)} is not a duration between ${min} and ${max} seconds: whole seconds, or "30s", "20m", "1h"`, path);
+      this.#report("pipeline.duration.invalid", `${PipelineInputReader.#show(value)} is not a duration between ${min} and ${max} seconds: whole seconds, or "30s", "20m", "1h"`, path);
       return null;
     }
     return seconds;
   }
   #maxParallel(value, path) {
-    return value === undefined ? null : this.#int(value, path, 1, pipelinePlanLimits.stages);
+    return value === undefined ? null : this.#read.int(value, path, 1, pipelinePlanLimits.stages);
   }
   #milestone(value, path) {
-    return value === undefined ? null : this.#oneOf(value, path, pipelineMilestones);
+    return value === undefined ? null : this.#read.oneOf(value, path, pipelineMilestones);
   }
   #description(value, path) {
-    return value === undefined ? null : this.#text(value, path, pipelinePlanLimits.descriptionChars);
+    return value === undefined ? null : this.#read.string(value, path, pipelinePlanLimits.descriptionChars);
   }
   #id(value, path) {
-    const id = this.#text(value, path, 64);
+    const id = this.#read.string(value, path, 64);
     if (id === null)
       return null;
     const problem = PipelineNames.idError(id);
@@ -539,77 +519,58 @@ class PipelineInputReader {
   static #nameOf(run) {
     const line = run.split(`
 `).map((text) => text.trim()).find(Boolean);
-    const name = line ?? run.trim();
-    return name.length > PipelineInputReader.#stepNameChars ? `${name.slice(0, PipelineInputReader.#stepNameChars - 1)}\u2026` : name;
+    return PipelineInputReader.clip(line ?? run.trim(), PipelineInputReader.#stepNameChars);
   }
-  #keys(raw, path, keys) {
-    let ok = true;
-    for (const key of Object.keys(raw)) {
-      if (keys.includes(key))
-        continue;
-      ok = false;
-      if (PipelineInputReader.#futureKeys.includes(key))
-        this.#report("pipeline.schema.unsupported", `\`${key}\` is not supported in schemaVersion 1`, `${path}.${key}`);
-      else
-        this.#report("pipeline.schema.unknownKey", `"${key}" is not a key here: ${keys.join(", ")}`, `${path}.${key}`);
-    }
-    return ok;
-  }
-  #object(value, path, keys) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-      this.#report("pipeline.schema.invalid", "must be an object", path);
-      return null;
+  static #show(value) {
+    let text;
+    try {
+      text = JSON.stringify(value) ?? String(value);
+    } catch {
+      text = typeof value === "bigint" ? `${value}n` : Object.prototype.toString.call(value);
     }
-    const raw = value;
-    if (keys && !this.#keys(raw, path, keys))
-      return null;
-    return raw;
+    return PipelineInputReader.clip(text, PipelineInputReader.#shownChars);
   }
   #list(value, path) {
-    if (value === undefined)
-      return [];
-    if (!Array.isArray(value)) {
-      this.#report("pipeline.schema.invalid", "must be a list", path);
-      return [];
-    }
-    return value;
+    return value === undefined ? [] : this.#read.list(value, path) ?? [];
   }
   #strings(value, path) {
     return this.#list(value, path).flatMap((item, idx) => {
-      const text = this.#text(item, `${path}[${idx}]`, 1024);
+      const text = this.#read.string(item, `${path}[${idx}]`);
       return text === null ? [] : [text];
     });
   }
-  #text(value, path, max) {
-    if (typeof value !== "string" || !value.trim()) {
-      this.#report("pipeline.schema.invalid", "must be a non-empty string", path);
-      return null;
-    }
-    if (value.length > max) {
-      this.#report("pipeline.schema.invalid", `is longer than ${max} characters`, path);
-      return null;
-    }
-    return value;
-  }
   #boolean(value, path) {
-    if (value === undefined)
-      return false;
-    if (typeof value === "boolean")
-      return value;
-    this.#report("pipeline.schema.invalid", "must be true or false", path);
-    return false;
-  }
-  #int(value, path, min, max) {
-    if (typeof value === "number" && Number.isInteger(value) && value >= min && value <= max)
-      return value;
-    this.#report("pipeline.schema.invalid", `must be a whole number between ${min} and ${max}`, path);
-    return null;
+    return value === undefined ? false : this.#read.boolean(value, path) ?? false;
   }
-  #oneOf(value, path, options) {
-    if (typeof value === "string" && options.includes(value))
-      return value;
-    this.#report("pipeline.schema.invalid", `${JSON.stringify(value)} is not one of ${options.join(", ")}`, path);
-    return null;
+  #problem(path, problem) {
+    if (problem.kind !== "unknownKey")
+      this.#report("pipeline.schema.invalid", PipelineInputReader.#reason(problem), path);
+    else if (PipelineInputReader.#futureKeys.includes(problem.key))
+      this.#report("pipeline.schema.unsupported", `\`${problem.key}\` is not supported in schemaVersion 1`, `${path}.${problem.key}`);
+    else
+      this.#report("pipeline.schema.unknownKey", `"${problem.key}" is not a key here: ${problem.keys.join(", ")}`, `${path}.${problem.key}`);
+  }
+  static #reason(problem) {
+    switch (problem.kind) {
+      case "object":
+        return "must be an object";
+      case "missingKey":
+        return `"${problem.key}" is missing`;
+      case "list":
+        return "must be a list";
+      case "string":
+      case "empty":
+        return "must be a non-empty string";
+      case "length":
+        return `is longer than ${problem.max} characters`;
+      case "boolean":
+        return "must be true or false";
+      case "int":
+      case "range":
+        return `must be a whole number between ${problem.min} and ${problem.max}`;
+      case "oneOf":
+        return `${PipelineInputReader.#show(problem.value)} is not one of ${problem.options.join(", ")}`;
+    }
   }
   #report(code, message, path) {
     this.diagnostics.push({ severity: "error", code, message, file: this.#file, path });
@@ -640,6 +601,7 @@ class PipelineCompiler {
   };
   static #reservedPhaseId = /^(?:build|docker|deploy|ota|(?:before-build|after-build|after-docker|after-deploy|after-ota)(?:-\d+)?)$/;
   static #actionStepNames = { build: "akan build", docker: "image", deploy: "deploy", ota: "ota" };
+  static #reasonChars = 1024;
   static compile(input) {
     return new PipelineCompiler(input).#compile();
   }
@@ -654,13 +616,9 @@ class PipelineCompiler {
     const { context, workspaceApps } = this.#input;
     this.#checkContext();
     const pipelineContext = {
-      branch: context.branch,
-      env: context.env,
+      ...context,
       apps: [...context.apps],
-      workspaceApps: [...workspaceApps],
-      trigger: context.trigger,
-      buildNum: context.buildNum,
-      commit: context.commit
+      workspaceApps: [...workspaceApps]
     };
     const workspace = this.#readWorkspace(pipelineContext);
     const lanes = new Map;
@@ -691,11 +649,18 @@ class PipelineCompiler {
     try {
       PipelinePlanSchema.parse(plan);
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = toError(error).message;
       this.#error(message.includes("at most") ? "pipeline.limit.exceeded" : "pipeline.internal", message, null, null);
       return this.#failed();
     }
-    return { ok: true, plan, diagnostics: this.#diagnostics };
+    const result = { ok: true, plan, diagnostics: this.#diagnostics };
+    const bytes = new TextEncoder().encode(`${JSON.stringify(result, null, 2)}
+`).length;
+    if (bytes > pipelinePlanLimits2.planBytes) {
+      this.#error("pipeline.limit.exceeded", `the plan is ${bytes} bytes as written, and an executor reads at most ${pipelinePlanLimits2.planBytes}`, null, null);
+      return this.#failed();
+    }
+    return result;
   }
   #checkContext() {
     const { context, workspaceApps } = this.#input;
@@ -710,13 +675,13 @@ class PipelineCompiler {
   }
   #readWorkspace(context) {
     const source = this.#input.workspace;
-    if (!source?.pipeline)
+    if (source?.pipeline == null)
       return null;
-    const value = this.#evaluate(source.pipeline, context, source.file);
-    if (value === undefined)
+    const evaluated = this.#evaluate(source.pipeline, context, source.file);
+    if (!evaluated)
       return null;
     const reader = new PipelineInputReader(source.file);
-    const rule = reader.workspace(value);
+    const rule = reader.workspace(evaluated.value);
     this.#diagnostics.push(...reader.diagnostics);
     return rule;
   }
@@ -725,25 +690,38 @@ class PipelineCompiler {
     if (!source)
       return null;
     const appContext = { ...context, app };
-    const value = source.pipeline ? this.#evaluate(source.pipeline, appContext, source.file) : defaultAppPipeline;
-    if (value === undefined)
+    const evaluated = source.pipeline == null ? { value: defaultAppPipeline } : this.#evaluate(source.pipeline, appContext, source.file);
+    if (!evaluated)
       return null;
     const reader = new PipelineInputReader(source.file);
-    const rule = reader.app(value);
+    const rule = reader.app(evaluated.value);
     this.#diagnostics.push(...reader.diagnostics);
     return rule ? this.#lane(app, rule, source.file) : null;
   }
   #evaluate(config, context, file) {
-    if (typeof config !== "function")
-      return config;
-    if (this.#input.sampled)
-      this.#warning("pipeline.function.sampled", "a function form was checked against one sample context; other branches, triggers or apps may differ", file, "pipeline");
-    try {
-      return config(context);
-    } catch (error) {
-      this.#error("pipeline.load.failed", `the pipeline function threw: ${error instanceof Error ? error.message : String(error)}`, file, "pipeline");
-      return;
+    let value = config;
+    if (typeof config === "function") {
+      if (this.#input.sampled)
+        this.#warning("pipeline.function.sampled", "a function form was checked against one sample context; other branches, triggers or apps may differ", file, "pipeline");
+      try {
+        value = config(context);
+      } catch (error) {
+        this.#error("pipeline.load.failed", `the pipeline function threw: ${toError(error).message}`, file, "pipeline");
+        return null;
+      }
+      if (value === undefined) {
+        this.#error("pipeline.schema.invalid", "the pipeline function returned nothing for this run: return a pipeline on every path", file, "pipeline");
+        return null;
+      }
+    }
+    if (typeof value?.then === "function") {
+      Promise.resolve(value).catch(() => {
+        return;
+      });
+      this.#error("pipeline.schema.invalid", "is a Promise, which the planner cannot wait for: return the pipeline itself, not from an async function", file, "pipeline");
+      return null;
     }
+    return { value };
   }
   #lane(app, rule, file) {
     const lane = {
@@ -987,7 +965,7 @@ class PipelineCompiler {
         maxParallel: stage.maxParallel,
         failFast: false,
         timeoutSeconds: stage.timeoutSeconds,
-        stages: apps.map((app) => this.#shellStage(copy, { id: `${stage.id}:${app}`, name: app, app, milestone, env }))
+        stages: apps.map((app) => this.#shellStage(copy, { id: `${stage.id}.apps.${app}`, name: app, app, milestone, env }))
       }
     ];
   }
@@ -1034,10 +1012,11 @@ class PipelineCompiler {
   }
   #skipOf(when) {
     const { branch, trigger } = this.#input.context;
+    const skip = (reason) => ({ reason: PipelineInputReader.clip(reason, PipelineCompiler.#reasonChars) });
     if (when.branch && !PipelinePattern2.matches(when.branch, branch))
-      return { reason: `branch "${branch}" does not match ${when.branch.map((glob) => `"${glob}"`).join(", ")}` };
+      return skip(`branch "${branch}" does not match ${when.branch.map((glob) => `"${glob}"`).join(", ")}`);
     if (when.trigger && !when.trigger.includes(trigger))
-      return { reason: `trigger "${trigger}" is not ${when.trigger.map((name) => `"${name}"`).join(" or ")}` };
+      return skip(`trigger "${trigger}" is not ${when.trigger.map((name) => `"${name}"`).join(" or ")}`);
     return null;
   }
   #sources() {
@@ -1045,7 +1024,7 @@ class PipelineCompiler {
     const sourceOf = (source) => ({
       file: source.file,
       sha256: source.sha256,
-      declared: source.pipeline !== null
+      declared: source.pipeline != null
     });
     return {
       workspace: workspace ? sourceOf(workspace) : null,
@@ -1071,6 +1050,7 @@ class PipelineCompiler {
 // pkgs/@akanjs/devkit/pipeline/PipelineDefinition.ts
 import { readFile } from "fs/promises";
 import path from "path";
+import { toError as toError2 } from "akanjs/common";
 class PipelineDefinition {
   static async load(workspace, apps) {
     const definition = new PipelineDefinition(workspace);
@@ -1099,7 +1079,7 @@ class PipelineDefinition {
     });
   }
   async#load(apps) {
-    this.workspaceApps = (await this.#workspace.getApps()).sort((a, b) => a.localeCompare(b));
+    this.workspaceApps = (await this.#workspace.getApps()).sort();
     this.workspaceSource = await this.#loadWorkspace();
     for (const app of new Set(apps)) {
       if (!this.workspaceApps.includes(app))
@@ -1121,7 +1101,7 @@ class PipelineDefinition {
       const targets = await resolveMobileTargets(AppExecutor.from(this.#workspace, app), "all");
       return { targets: targets.map(({ name, config }) => ({ name, updates: !!config.updates })) };
     } catch (error) {
-      return { error: error instanceof Error ? error.message : String(error) };
+      return { error: toError2(error).message };
     }
   }
   async#loadWorkspace() {
@@ -1155,7 +1135,7 @@ class PipelineDefinition {
     this.diagnostics.push({
       severity: "error",
       code: "pipeline.load.failed",
-      message: `could not load: ${error instanceof Error ? error.message : String(error)}`,
+      message: `could not load: ${toError2(error).message}`,
       file,
       path: null
     });
@@ -1211,7 +1191,7 @@ class PipelineDryRun {
     if (phase.stages.length === 1) {
       const [stage] = phase.stages;
       const command = stage?.steps.map((step) => step.kind === "sh" ? step.name : `action ${step.action}`).join(" \xB7 ");
-      return [labels[0], command].filter((part) => part && part !== stage?.name).join("  ");
+      return [labels[0], command].filter((part) => part && part !== phase.name).join("  ");
     }
     return `\u2016 ${labels.join(" \xB7 ")}`;
   }
@@ -1234,20 +1214,24 @@ class PipelineDryRun {
   }
 }
 // pkgs/@akanjs/cli/pipeline/pipeline.script.ts
-import { Logger } from "akanjs/common";
+import { Logger, toError as toError3 } from "akanjs/common";
 
 // pkgs/@akanjs/cli/pipeline/pipeline.runner.ts
-import { mkdir, open, rename } from "fs/promises";
 import path2 from "path";
 class PipelineRunner extends runner("pipeline") {
+  static #flagChars = 1024;
   async context(workspace, flags) {
-    if (!Number.isInteger(flags.buildNum) || flags.buildNum < 0)
+    if (!Number.isSafeInteger(flags.buildNum) || flags.buildNum < 0)
       throw new Error(`--build-num ${flags.buildNum} is not a whole number of 0 or more`);
-    const branch = flags.branch ?? await PipelineRunner.#git(workspace, ["rev-parse", "--abbrev-ref", "HEAD"]) ?? "main";
+    for (const flag of ["branch", "env", "commit"])
+      PipelineRunner.#assertFlag(flag, flags[flag]);
+    const branch = flags.branch ?? await PipelineRunner.#git(workspace, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (!branch)
+      throw new Error("git names no branch here (a detached HEAD, or no checkout): name it with --branch");
     return {
       branch,
       env: flags.env ?? branch,
-      apps: flags.apps === null ? (await workspace.getApps()).sort((a, b) => a.localeCompare(b)) : flags.apps.split(","),
+      apps: flags.apps === null ? (await workspace.getApps()).sort() : flags.apps.split(",").map((app) => app.trim()).filter(Boolean),
       trigger: flags.trigger,
       buildNum: flags.buildNum,
       commit: flags.commit ?? await PipelineRunner.#git(workspace, ["rev-parse", "HEAD"])
@@ -1257,17 +1241,16 @@ class PipelineRunner extends runner("pipeline") {
     return (await PipelineDefinition.load(workspace, context.apps)).compile(context, { sampled });
   }
   async writeResult(out, result) {
-    const target = path2.resolve(out);
-    await mkdir(path2.dirname(target), { recursive: true });
-    const temp = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
-    const handle = await open(temp, "wx");
-    try {
-      await handle.writeFile(`${JSON.stringify(result, null, 2)}
+    await FileSys2.writeTextAtomic(path2.resolve(out), `${JSON.stringify(result, null, 2)}
 `);
-    } finally {
-      await handle.close();
-    }
-    await rename(temp, target);
+  }
+  static #assertFlag(flag, value) {
+    if (value === null)
+      return;
+    if (!value.trim())
+      throw new Error(`--${flag} is blank`);
+    if (value.length > PipelineRunner.#flagChars)
+      throw new Error(`--${flag} is longer than ${PipelineRunner.#flagChars} characters`);
   }
   static async#git(workspace, args) {
     try {
@@ -1282,6 +1265,15 @@ class PipelineRunner extends runner("pipeline") {
 // pkgs/@akanjs/cli/pipeline/pipeline.script.ts
 class PipelineScript extends script("pipeline", [PipelineRunner]) {
   async run(workspace, action, { flags, out, format }) {
+    const json = format === "json" || action === "plan" && !out;
+    const restoreLogs = json ? PipelineScript.#logToStderr() : null;
+    try {
+      await this.#run(workspace, action, { flags, out, json });
+    } finally {
+      restoreLogs?.();
+    }
+  }
+  async#run(workspace, action, { flags, out, json }) {
     let result;
     try {
       const context = await this.pipelineRunner.context(workspace, flags);
@@ -1289,11 +1281,11 @@ class PipelineScript extends script("pipeline", [PipelineRunner]) {
       if (out)
         await this.pipelineRunner.writeResult(out, result);
     } catch (error) {
-      Logger.rawLog(`akan pipeline ${action}: ${error instanceof Error ? error.message : String(error)}`, undefined, "error");
+      Logger.rawLog(`akan pipeline ${action}: ${toError3(error).message}`, undefined, "error");
       process.exitCode = 2;
       return;
     }
-    if (format === "json" || action === "plan" && !out)
+    if (json)
       process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
     else
@@ -1301,6 +1293,15 @@ class PipelineScript extends script("pipeline", [PipelineRunner]) {
     if (!result.ok)
       process.exitCode = 1;
   }
+  static #logToStderr() {
+    const consoleOutput = Logger.consoleOutput;
+    Logger.consoleOutput = false;
+    const removeSink = Logger.addSink((entry) => void process.stderr.write(entry.message), { minLevel: Logger.level });
+    return () => {
+      removeSink();
+      Logger.consoleOutput = consoleOutput;
+    };
+  }
   static #summary(action, result, out) {
     const head = result.ok ? `${action === "plan" ? "planned" : "valid"}: ${result.plan.phases.length} phases, ${result.plan.phases.reduce((sum, phase) => sum + phase.stages.length, 0)} stages` : `${action === "plan" ? "no plan" : "invalid"}: ${result.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length} error(s)`;
     return [`${head}${out ? ` \u2192 ${out}` : ""}`, ...PipelineDryRun.diagnostics(result.diagnostics)].join(`