@wix/himalaya-cli 0.1246.0 → 0.1248.0

package/dist/cli.mjs

@@ -13465,7 +13465,6 @@ function resolveIdiom(tokens2, ctx = {}) {
 var IDIOM_CONTEXTS, UNSAFE_KEYS;
 var init_idiom = __esm({
   "../../core/ts/src/idiom.ts"() {
-    "use strict";
     IDIOM_CONTEXTS = {
       ios: { native: ["ios"] },
       android: { native: ["material"] },
@@ -25749,6 +25748,7 @@ function shouldRevealError(args) {
 var EMAIL_RE, URL_HOST_RE, INTEGER_RE, NUMBER_RE;
 var init_validation = __esm({
   "../../core/ts/src/validation.ts"() {
+    "use strict";
     EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
     URL_HOST_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$/;
     INTEGER_RE = /^[+-]?[0-9]+$/;
@@ -26408,6 +26408,7 @@ function validateWorkerSubtree(raw, slotId, policy, actionCatalog) {
 var WORKER_SUBTREE_CEILINGS, ID_PART, ACTION_ID;
 var init_worker_subtree = __esm({
   "../../core/ts/src/worker-subtree.ts"() {
+    "use strict";
     init_worker_subtree_safe_types_generated();
     WORKER_SUBTREE_CEILINGS = Object.freeze({
       maxEncodedBytes: 65536,
@@ -132926,6 +132927,72 @@ var init_studio = __esm({
   }
 });
 
+// src/push-errors.ts
+var push_errors_exports = {};
+__export(push_errors_exports, {
+  PUSH_FAILURE_CODES: () => PUSH_FAILURE_CODES,
+  pushFailure: () => pushFailure,
+  uxEvidenceCode: () => uxEvidenceCode
+});
+function pushFailure(code, fields) {
+  return { ...fields, ok: false, code };
+}
+function uxEvidenceCode(state) {
+  return UX_CODES[state];
+}
+var PUSH_FAILURE_CODES, UX_CODES;
+var init_push_errors = __esm({
+  "src/push-errors.ts"() {
+    PUSH_FAILURE_CODES = [
+      "attestation_history_corrupt",
+      "attestation_stale",
+      "headless_run_failed",
+      "ux_evidence_absent",
+      "ux_evidence_unrecorded",
+      "ux_evidence_stale",
+      "ux_evidence_outdated",
+      "ux_evidence_failed",
+      "ux_evidence_inherited_screens",
+      "ux_evidence_unreadable",
+      "lint_errors",
+      "control_token_expired",
+      "app_source_contains_secrets",
+      "app_source_too_large",
+      "publish_body_too_large",
+      "needs_vpn",
+      "serve_unreachable",
+      "no_serve_plane",
+      "upload_http_error",
+      "claim_failed",
+      "invalid_flag_value",
+      "invalid_selector",
+      "duplicate_only",
+      "incompatible_push_flags",
+      "from_release_needs_a_value",
+      "conflicting_blast_radius",
+      "no_blast_radius",
+      "invalid_visibility",
+      "release_read_failed",
+      "base_not_found",
+      "no_live_release",
+      "invalid_patch",
+      "would_regress",
+      "not_carried_by_patch",
+      "authoring_unavailable",
+      "push_failed"
+    ];
+    UX_CODES = {
+      absent: "ux_evidence_absent",
+      unrecorded: "ux_evidence_unrecorded",
+      stale: "ux_evidence_stale",
+      outdated: "ux_evidence_outdated",
+      failed: "ux_evidence_failed",
+      "inherited-screens": "ux_evidence_inherited_screens",
+      unreadable: "ux_evidence_unreadable"
+    };
+  }
+});
+
 // src/release-patch.ts
 var release_patch_exports = {};
 __export(release_patch_exports, {
@@ -143740,23 +143807,23 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/index-CCVohdaU.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1194284, sha256: "60579d944c7c43f8809233a2156473912f13308a6013a0c2e8b3dee36b91abf8" },
-      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/octet-stream", offset: 1194292, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
-      { key: "assets/pdfDocument-lN1LAubz.js", contentType: "application/javascript; charset=utf-8", offset: 2511326, length: 489166, sha256: "3b61b9d31976437476b3e8e34999f82c9b14fea30155d98c30ee92135ff23573" },
-      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3000492, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
-      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3005102, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3493686, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3584610, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3675594, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3766574, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 3857446, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 3948426, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4057062, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4166146, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4275194, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4382894, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4471002, length: 4947, sha256: "d4e51bbbba0a856f8060f0b9268c9efd0a7da047d82048d722cf8bcb9b326b01" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4475949, length: 17344, sha256: "d057298d75e7373e5e2c4d11b7d1bcbea88e03af555ba63d97641c78509c58e4" }
+      { key: "assets/index-C_dUZJT0.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1194463, sha256: "6640d516f6b59bacd5f71dbcb264dbdc9aeef5502fb284d0680d91ae40ea141a" },
+      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/octet-stream", offset: 1194471, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
+      { key: "assets/pdfDocument-sHOpLp0o.js", contentType: "application/javascript; charset=utf-8", offset: 2511505, length: 489166, sha256: "57445251df98761d808381a823b3f01c948f41faeae9e61d1bcd9ab8ef1eadc3" },
+      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3000671, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
+      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3005281, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3493865, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3584789, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3675773, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3766753, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 3857625, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 3948605, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4057241, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4166325, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4275373, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4383073, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4471181, length: 4947, sha256: "cecdf774237e111e8306c71e372f32f6fdad1f8ac7c0d7736723bf79fea24503" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4476128, length: 17344, sha256: "d057298d75e7373e5e2c4d11b7d1bcbea88e03af555ba63d97641c78509c58e4" }
     ];
   }
 });
@@ -163742,11 +163809,11 @@ async function contentVisibility(dir) {
   }
   return void 0;
 }
-function visibilityFlag(flags, io2) {
+function visibilityFlag(flags, io2, failure = (fields) => fields) {
   if (flags.visibility === void 0) return {};
   const v2 = str9(flags.visibility);
   if (v2 !== "public" && v2 !== "unlisted") {
-    io2.error(JSON.stringify({ error: `--visibility must be public or unlisted (got "${v2 ?? ""}")` }));
+    io2.error(JSON.stringify(failure({ error: `--visibility must be public or unlisted (got "${v2 ?? ""}")` })));
     return null;
   }
   return { value: v2 };
@@ -164296,6 +164363,9 @@ async function runCommand(argv, io2, deps) {
   const { _: pos, flags } = parseFlags(argv);
   const flagErrors = switchFlagErrors(argv);
   const command = pos[0];
+  const pushErrors = command === "push" ? await Promise.resolve().then(() => (init_push_errors(), push_errors_exports)) : void 0;
+  const uxEvidenceCode2 = (state) => pushErrors?.uxEvidenceCode(state) ?? "ux_evidence_absent";
+  const pushFailure2 = command === "push" ? pushErrors.pushFailure : (_code, fields) => fields;
   let updateNotice;
   const print = (o2) => io2.log(JSON.stringify(
     o2 && typeof o2 === "object" && !Array.isArray(o2) ? tailLast(updateNotice ? { ...o2, upgrade: upgradeEnvelope(updateNotice) } : o2) : o2,
@@ -164316,7 +164386,7 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
     return command === "help" || flags.help ? 0 : 2;
   }
   if (flagErrors.length > 0 && flags.help !== true) {
-    io2.error(JSON.stringify({ ok: false, error: "invalid_flag_value", problems: flagErrors, hint: "run `himi help` for the flag grammar." }));
+    io2.error(JSON.stringify(pushFailure2("invalid_flag_value", { ok: false, error: "invalid_flag_value", problems: flagErrors, hint: "run `himi help` for the flag grammar." })));
     return 2;
   }
   if (flags["skip-version-check"] !== true) {
@@ -164343,11 +164413,11 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
     const base = serveBase();
     if (!isLoopbackBase(base)) return null;
     if (await servePlaneAnswers(() => client2().health("serve"))) return null;
-    io2.error(JSON.stringify(foreignPlaneError(targetName(), base)));
+    io2.error(JSON.stringify(pushFailure2("no_serve_plane", foreignPlaneError(targetName(), base))));
     return 1;
   };
   const printServeFailure = (r2, extra) => {
-    print({ ok: false, ...extra, status: r2.status, body: r2.json ?? r2.text });
+    print(pushFailure2("upload_http_error", { ok: false, ...extra, status: r2.status, body: r2.json ?? r2.text }));
     return 1;
   };
   const serveFailure = async (r2, extra) => {
@@ -164360,33 +164430,33 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
     const target = targetName();
     const baseFound = await fetchReleaseManifest(client2, app, opts.fromRelease);
     if ("error" in baseFound) {
-      io2.error(JSON.stringify(baseFound));
+      io2.error(JSON.stringify(pushFailure2("release_read_failed", baseFound)));
       return 1;
     }
     const base = baseFound.manifest;
     if (!base) {
-      io2.error(JSON.stringify({
+      io2.error(JSON.stringify(pushFailure2(opts.explicitBase ? "base_not_found" : "no_live_release", {
         ok: false,
         error: opts.explicitBase ? "base_not_found" : "no_live_release",
         app,
         ...opts.explicitBase ? { releaseId: opts.fromRelease } : {},
         message: opts.explicitBase ? `no release ${opts.fromRelease} for ${app}. Retention keeps the current release plus roughly the newest 20 ledger entries.` : `${app} has no live release to derive from. A patch changes part of an existing release; there is nothing here to be part of.`,
         hint: opts.explicitBase ? `list what exists: \`himi context --app ${app} --target ${target}\`` : "publish the whole app first: `himi push --draft` then `himi promote`."
-      }));
+      })));
       return 1;
     }
     let regressions = [];
     {
       const liveFound = await fetchReleaseManifest(client2, app);
       if ("error" in liveFound) {
-        io2.error(JSON.stringify(liveFound));
+        io2.error(JSON.stringify(pushFailure2("release_read_failed", liveFound)));
         return 1;
       }
       const live3 = liveFound.manifest;
       if (live3 && live3.releaseId !== base.releaseId) {
         regressions = regressionDiff2(base, live3, plan.touched);
         if (regressions.length > 0 && !opts.acceptRegressions) {
-          io2.error(JSON.stringify({
+          io2.error(JSON.stringify(pushFailure2("would_regress", {
             ok: false,
             patched: false,
             error: "would_regress",
@@ -164398,14 +164468,14 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
             moves: plan.touched,
             hint: opts.explicitBase ? `patch the live release instead (drop --from-release), widen the patch to cover them, or re-run with --accept-regressions if reverting those ${regressions.length} item(s) is what you mean.` : `${app} was published again while this patch was being prepared, so the base it was planned against is no longer live. Re-run to plan against the new release, or pass --accept-regressions to derive from the older one anyway.`,
             proof: "core/serve-control/tests/routes-release-branch-patch.test.ts:126"
-          }, null, 2));
+          }), null, 2));
           return 1;
         }
       }
     }
     const notCarried = opts.notCarried ?? [];
     if (notCarried.length > 0 && !opts.acceptPartial) {
-      io2.error(JSON.stringify({
+      io2.error(JSON.stringify(pushFailure2("not_carried_by_patch", {
         ok: false,
         patched: false,
         error: "not_carried_by_patch",
@@ -164415,25 +164485,25 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
         notCarried,
         carriedByPatch: ["screens", "bundles", "tokens", "appConfig"],
         hint: "run a full `himi push` \u2014 it publishes assets, the icon, the surface envelope and minBinaryVersion. Re-run with --accept-partial only if you know those devices are already covered."
-      }, null, 2));
+      }), null, 2));
       return 1;
     }
     if (opts.ux?.evidence && opts.ux.evidence.state !== "recorded" && !opts.force) {
-      print({
+      print(pushFailure2(uxEvidenceCode2(opts.ux.evidence.state), {
         ok: false,
         patched: false,
         pushed: false,
         uxEvidence: opts.ux.evidence,
         releaseId: opts.ux.ctx.releaseId,
         hint: uxHandoverHint(opts.ux.evidence, opts.ux.ctx)
-      });
+      }));
       return 1;
     }
     let r2;
     try {
       r2 = await client2().releasePatch(app, base.releaseId, plan.patch, draft, opts.meta, opts.force);
     } catch (e2) {
-      io2.error(JSON.stringify({ ok: false, patched: false, error: "serve_unreachable", app, message: e2.message }));
+      io2.error(JSON.stringify(pushFailure2("serve_unreachable", { ok: false, patched: false, error: "serve_unreachable", app, message: e2.message })));
       return 1;
     }
     if (!r2.ok) {
@@ -164499,17 +164569,17 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
     const wantDraft = flags.draft === true;
     const wantLive = flags.live === true;
     if (wantDraft && wantLive) {
-      io2.error(JSON.stringify({ ok: false, error: "conflicting_blast_radius", message: "--draft and --live are mutually exclusive; pass exactly one." }));
+      io2.error(JSON.stringify(pushFailure2("conflicting_blast_radius", { ok: false, error: "conflicting_blast_radius", message: "--draft and --live are mutually exclusive; pass exactly one." })));
       return null;
     }
     if (!wantDraft && !wantLive) {
-      io2.error(JSON.stringify({
+      io2.error(JSON.stringify(pushFailure2("no_blast_radius", {
         ok: false,
         error: "no_blast_radius",
         message: "a patch must say where it lands: --draft (nothing changes on any device) or --live (every device, immediately).",
         hint: "`himi push` defaults to --draft because it publishes a whole release you then promote. A patch has no default, because the two outcomes are not comparable.",
         usage
-      }));
+      })));
       return null;
     }
     return wantDraft;
@@ -166688,15 +166758,15 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
         if (flags.only !== void 0) {
           onlyRaw = str9(flags.only);
           if (!onlyRaw) {
-            io2.error(JSON.stringify({ error: "--only needs a selector", usage: ONLY_USAGE }));
+            io2.error(JSON.stringify(pushFailure2("invalid_selector", { error: "--only needs a selector", usage: ONLY_USAGE })));
             return 2;
           }
           if (argv.filter((a2) => a2 === "--only" || a2.startsWith("--only=")).length > 1) {
-            io2.error(JSON.stringify({
+            io2.error(JSON.stringify(pushFailure2("duplicate_only", {
               error: "duplicate_only",
               usage: ONLY_USAGE,
               message: "--only was passed more than once, and only the last would have taken effect. Comma-separate the selectors instead: --only screen:a,screen:b"
-            }));
+            })));
             return 2;
           }
           for (const [flag, why] of [
@@ -166704,12 +166774,12 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
             ["visibility", "the patch route does not stamp visibility; set it with `himi visibility` instead"]
           ]) {
             if (flags[flag] !== void 0) {
-              io2.error(JSON.stringify({ error: `--${flag} is not meaningful with --only`, message: why, usage: ONLY_USAGE }));
+              io2.error(JSON.stringify(pushFailure2("incompatible_push_flags", { error: `--${flag} is not meaningful with --only`, message: why, usage: ONLY_USAGE })));
               return 2;
             }
           }
           if (flags["from-release"] !== void 0 && !str9(flags["from-release"])) {
-            io2.error(JSON.stringify({ ok: false, error: "from_release_needs_a_value", message: "--from-release takes a release id to branch from. Omit the flag entirely to patch the live release.", usage: ONLY_USAGE }));
+            io2.error(JSON.stringify(pushFailure2("from_release_needs_a_value", { ok: false, error: "from_release_needs_a_value", message: "--from-release takes a release id to branch from. Omit the flag entirely to patch the live release.", usage: ONLY_USAGE })));
             return 2;
           }
           if (patchBlastRadius(ONLY_USAGE) === null) return 2;
@@ -166728,14 +166798,14 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           const { loadTargetsFile: loadTargetsFile2 } = await Promise.resolve().then(() => (init_config(), config_exports));
           const configured = loadTargetsFile2();
           const usable = Object.keys(configured.targets ?? {}).filter((n2) => n2 !== pushTarget).filter((n2) => inspectControlToken(configured.targets?.[n2]?.controlToken).valid).sort().map((n2) => ({ target: n2, control: configured.targets?.[n2]?.control }));
-          io2.error(JSON.stringify({
+          io2.error(JSON.stringify(pushFailure2("control_token_expired", {
             ok: false,
             pushed: false,
             error: "control_token_expired",
             target: pushTarget,
             ...usable.length ? { usableTargets: usable } : {},
             hint: `${pushAuthHint(401, pushToken, pushTarget, !!ownerIssue)}` + (usable.length ? ` \u2014 you are also logged in for ${usable.map((u2) => `${u2.target}${u2.control ? ` (${u2.control})` : ""}`).join(", ")}, but check the plane before switching: a different target publishes somewhere else and claims the slug there.` : "")
-          }));
+          })));
           return 1;
         }
         let app = resolveAppSlug(declared, (pushToken ? decodeControlTokenClaims(pushToken) : null) ?? {});
@@ -166763,7 +166833,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           ...await navIssues2(dir, strict)
         ]);
         if (hasErrors && !force) {
-          print({ ...report3, pushed: false, hint: "lint found errors \u2014 fix them, or re-run `himi push --force` to publish anyway" });
+          print(pushFailure2("lint_errors", { ...report3, pushed: false, hint: "lint found errors \u2014 fix them, or re-run `himi push --force` to publish anyway" }));
           return 1;
         }
         const declaredData = await loadDataResourcesQuietly(dir);
@@ -166782,28 +166852,28 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
             bundles: Object.keys(manifest.bundles ?? {})
           });
           if (!parsed.ok) {
-            io2.error(JSON.stringify(parsed.error, null, 2));
+            io2.error(JSON.stringify(pushFailure2("invalid_selector", parsed.error), null, 2));
             return 2;
           }
           const fromRelease = str9(flags["from-release"]);
           const baseForPlan = await fetchReleaseManifest(client2, app, fromRelease);
           if ("error" in baseForPlan) {
-            io2.error(JSON.stringify(baseForPlan));
+            io2.error(JSON.stringify(pushFailure2("release_read_failed", baseForPlan)));
             return 1;
           }
           if (!baseForPlan.manifest) {
-            io2.error(JSON.stringify({
+            io2.error(JSON.stringify(pushFailure2(fromRelease ? "base_not_found" : "no_live_release", {
               ok: false,
               error: fromRelease ? "base_not_found" : "no_live_release",
               app,
               message: fromRelease ? `no release ${fromRelease} for ${app}.` : `no published release for "${app}" to patch \u2014 run \`himi push\` first.`,
               hint: "if this app is registered under a different slug, pass --app <slug>."
-            }));
+            })));
             return 1;
           }
           const planned = planFromPayload2(payload, baseForPlan.manifest, parsed.selectors);
           if (!planned.ok) {
-            io2.error(JSON.stringify(planned.error, null, 2));
+            io2.error(JSON.stringify(pushFailure2("invalid_patch", planned.error), null, 2));
             return 1;
           }
           const patchUxEvidence = handoverUxEvidence(dir, {
@@ -166873,21 +166943,21 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           const collected = collectAppSource2(dir);
           const findings = secretFindings2(collected.entries);
           if (findings.length > 0) {
-            io2.error(JSON.stringify({
+            io2.error(JSON.stringify(pushFailure2("app_source_contains_secrets", {
               ok: false,
               pushed: false,
               error: `refusing to archive the source: ${findings[0].path} looks like it contains ${findings[0].reason}`,
               file: findings[0].path,
               found: findings.map((f2) => f2.path),
               hint: "move it out of the content package (or into .himi/, .env, or a *.pem/*.p8 file, which are never archived), or push with --no-source"
-            }));
+            })));
             return 1;
           }
           const zip = zipAppSource2(collected.entries);
           const encoded2 = zip.toString("base64");
           if (encoded2.length > MAX_APP_SOURCE_BYTES2) {
             const largest = largestEntries2(collected.entries);
-            io2.error(JSON.stringify({
+            io2.error(JSON.stringify(pushFailure2("app_source_too_large", {
               ok: false,
               pushed: false,
               error: "app_source_too_large",
@@ -166897,7 +166967,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
               files: collected.entries.length,
               largest,
               hint: `trim the content package \u2014 the largest entries are ${largest.map((e2) => `${e2.path} (${Math.round(e2.compressed / 1024)} KB compressed)`).join(", ")}. Sizes are COMPRESSED, because the cap is measured on the deflated archive \u2014 a big but compressible source file is rarely what costs you it. Build output, dependencies, native shells and tooling output (.himi/, and shots/ + evidence/ at the package root) are already excluded. \`--no-source\` publishes without the archive, but then \`himi pull\` cannot restore this release.`
-            }));
+            })));
             return 1;
           }
           appSourceB64 = encoded2;
@@ -166914,22 +166984,22 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
         if (attestationErrors.length > 0 && !force) {
           const remedy = `\`himi test --content ${contentArg2}\` (or \`himi render <screenId> --content ${contentArg2}\`)`;
           const corrupted = evidence.historyErrors.length > 0;
-          print({
+          print(pushFailure2(corrupted ? "attestation_history_corrupt" : "attestation_stale", {
             ok: false,
             pushed: false,
             errors: attestationErrors,
             hint: corrupted ? `attestation history in .himi/attestations/ is corrupt, so the retained runs cannot be trusted \u2014 a fresh run does not remove the bad entry. Delete .himi/attestations/, re-attest with ${remedy}, then re-run \`himi push\`. Only if you intend to publish WITHOUT that evidence, \`himi push --force\`.` : `no retained attestation for this release passed live verification${drifting.length ? `. ${releaseDriftCause(drifting, "Re-attesting", "an attestation")}, then re-attest` : " \u2014 runs recorded at this commit before your latest edits describe a tree that no longer exists. Re-attest"} the CURRENT release with ${remedy}, then re-run \`himi push\`. Only if you intend to publish WITHOUT that evidence, \`himi push --force\`.`
-          });
+          }));
           return 1;
         }
         const attestation = evidence.selected ? summaryOf(evidence.selected) : void 0;
         if (attestation?.report.ok === false && !force) {
-          print({
+          print(pushFailure2("headless_run_failed", {
             ok: false,
             pushed: false,
             attestation,
             hint: "the latest verified headless run failed \u2014 fix it and rerun the tool, or re-run `himi push --force` to publish anyway"
-          });
+          }));
           return 1;
         }
         const uxEvidence = handoverUxEvidence(dir, {
@@ -166941,7 +167011,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           inheritedScreens: []
         });
         if (uxEvidence && uxEvidence.state !== "recorded" && !force) {
-          print({
+          print(pushFailure2(uxEvidenceCode2(uxEvidence.state), {
             ok: false,
             pushed: false,
             uxEvidence,
@@ -166959,7 +167029,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
               // `inherited-screens` and has no base to restore.
               nondeterministicWorkers: drifting
             })
-          });
+          }));
           return 1;
         }
         const forcedPastErrors = force && (hasErrors || attestation?.report.ok === false || attestationErrors.length > 0);
@@ -166970,7 +167040,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           bakedBytes: assetRecords.filter(([, a2]) => a2.baked).reduce((n2, [, a2]) => n2 + a2.bytes, 0),
           otaOnly: assetRecords.filter(([, a2]) => !a2.baked).map(([name]) => name)
         } : null;
-        const visArg = visibilityFlag(flags, io2);
+        const visArg = visibilityFlag(flags, io2, (fields) => pushFailure2("invalid_visibility", fields));
         if (!visArg) return 2;
         const visibility = visArg.value ?? await contentVisibility(dir);
         const meta = {
@@ -166989,7 +167059,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
         const publishBodyBytesFor = (slug) => publishReleaseBodyBytes(publishBodyFor(slug), meta, draft);
         const refuseOversizedBody = (slug, bodyBytes) => {
           const withoutSource = appSourceB64 ? bodyBytes - appSourceB64.length : bodyBytes;
-          io2.error(JSON.stringify({
+          io2.error(JSON.stringify(pushFailure2("publish_body_too_large", {
             ok: false,
             app: slug,
             pushed: false,
@@ -166998,7 +167068,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
             limit: MAX_PUBLISH_BODY_BYTES,
             ...appSourceB64 ? { appSourceBytes: appSourceB64.length } : {},
             hint: appSourceB64 && withoutSource <= MAX_PUBLISH_BODY_BYTES ? "push with --no-source to publish without the source archive (this release then cannot be restored with `himi pull`), or trim the app's assets and bundles" : "trim the app's assets and bundles \u2014 this release is over the limit even without the source archive, so --no-source would not help"
-          }));
+          })));
           return 1;
         };
         const composedBodyBytes = publishBodyBytesFor(app);
@@ -167009,14 +167079,14 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           if (ownerIssue && pushToken && !tokenCoversApp(pushToken, app)) {
             const claim = await autoClaimSlug({ ownerIssue, controlToken: pushToken, app, accountId: str9(flags["account-id"]) });
             if (claim.fatal) {
-              io2.error(JSON.stringify({
+              io2.error(JSON.stringify(pushFailure2("claim_failed", {
                 ok: false,
                 app,
                 pushed: false,
                 status: claim.fatal.status,
                 ...claim.fatal.body,
                 ...claimHint(claim.fatal.status, claim.fatal.error)
-              }));
+              })));
               return 1;
             }
             if (claim.refusal) io2.error(JSON.stringify({ warning: claim.refusal.error, hint: claim.refusal.hint }));
@@ -167037,16 +167107,16 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           r2 = await client2().publishRelease(publishPayload, meta, draft);
         } catch (e2) {
           const target = targetName();
-          io2.error(JSON.stringify({
+          io2.error(JSON.stringify(pushFailure2("needs_vpn", {
             ...serveUnreachableError(target, serveBase(), e2.message),
             version: cliVersion()
-          }));
+          })));
           return 1;
         }
         if (!r2.ok) {
           const authHint = pushAuthHint(r2.status, pushToken, pushTarget, !!ownerIssue);
           const hint = authHint ?? releaseIdExistsHint(r2.status, r2.json);
-          print({ ok: false, status: r2.status, body: r2.json ?? r2.text, ...hint ? { hint } : {} });
+          print(pushFailure2("upload_http_error", { ok: false, status: r2.status, body: r2.json ?? r2.text, ...hint ? { hint } : {} }));
           return 1;
         }
         const release = r2.json?.releaseId ?? manifest.releaseId;
@@ -170283,15 +170353,15 @@ Code: ${userCode}`);
     }
   } catch (err) {
     if (err instanceof AuthoringUnavailable) {
-      io2.error(JSON.stringify({
+      io2.error(JSON.stringify(pushFailure2("authoring_unavailable", {
         error: `the himi authoring runtime failed to load (himi v${cliVersion()}). Off-repo this almost always means an out-of-date CLI, NOT a platform limitation \u2014 upgrade: \`npm i -g @wix/himalaya-cli@latest\`. If you meant to run in-repo, run from a monorepo checkout.`,
         version: cliVersion(),
         upgrade: "npm i -g @wix/himalaya-cli@latest",
         portal: DEVELOPER_PORTAL_URL
-      }));
+      })));
       return 1;
     }
-    io2.error(JSON.stringify({ error: err.message }));
+    io2.error(JSON.stringify(pushFailure2("push_failed", { error: err.message })));
     const code = err.exitCode;
     return code === 2 ? 2 : 1;
   }

package/guides/designing-himi-screens.md

@@ -278,6 +278,7 @@ Concrete patterns lifted from real usage:
 - **Screen root** — `withModifiers(root, { padding: { leading: 16, trailing: 16, top: 16, bottom: 40 }, background: { token: "surfacePrimary" } })`. Consistent gutter, comfortable bottom inset.
 - **Row with a leading label and trailing detail** — `hstack({ spacing: 8, children: [ icon, text, spacer(), trailingText ] })`. The `spacer()` does the push; don't hand-pad.
 - **Fill-width controls share a row** — put fill-width controls in **one** `HStack` and let them share it (weight/flex), rather than stacking `fillMaxWidth` elements. This is a real iOS↔Android parity requirement, not a preference — a full-width control alone in an HStack renders differently across platforms.
+- **A screen that owns its top bar (search beside back)** — set `topBar: { leading: "none" }` and put the row in `stickyHeader`: `hstack([ iconButton({ icon: "arrow_left", accessibilityLabel: "Back", action: { actionId: "nav.back", presentation: "back" } }), withModifiers(textField({ placeholder: "Search", … }), { weight: 1 }) ])`. With **both** set, every shell draws no bar and no back control of its own (iOS hides the system bar, Android floats no chevron and reserves no band, web hides its bar on every look), so the row is the only top bar. `leading: "none"` without a `stickyHeader` keeps the bar's title and trailing actions but drops the back control (and the hamburger, for that screen). System back — hardware, gesture, edge swipe, browser — still pops. Any other `leading` value keeps today's chrome (#3486; demo: `gallery_search_topbar`, linked from the gallery's "Lists & data").
 - **Cell list** — `card([ vstack({ spacing: 0, alignment: "leading", children: [ …ListItem cells… ] }) ])`. `spacing: 0` because the cells own their own dividers/padding.
 - **Overlay** — `zstack({ alignment: "center", children: [ backdropImage(cornerRadius 12), withModifiers(label, { padding, background: { token: "accentPrimary" }, cornerRadius: 10 }) ] })`.
 - **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for 1-up on phone / 2-up on tablet; `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.

package/guides/headless-loop.md

@@ -3,6 +3,10 @@
 Author a Himi app from your own machine, push it to the production serve as a **draft**,
 preview it, read the worker's logs, then promote it live. Nothing is live until you promote.
 
+For machine consumers, `himi push` failures carry a stable top-level `code`.
+See [JSON failure codes](himi-json-output.md) (`himi docs himi-json-output`);
+branch on that code rather than human prose or envelope shape.
+
 ## 1. Get the CLI
 
 ```sh

package/guides/himi-json-output.md

@@ -0,0 +1,84 @@
+# himi JSON failure contract
+
+Every `ok: false` JSON envelope must carry a top-level `code`: a stable, typed
+snake_case identifier for consumers to branch on. Codes are never renamed or
+repurposed when human wording changes. New codes may be added; consumers must
+handle an unknown code as a failure, without parsing prose.
+
+**Rollout:** this contract is enforced for **`himi push`**, including `--only`,
+first. Other subcommands still have legacy failures without codes and are a
+follow-up migration. This is an additive change: existing `error`, `errors`,
+`message`, `hint`, status, body, and gate-specific fields stay as they were.
+Some legacy envelopes have no singular `error` or `hint`; consumers must not
+require those fields. Existing error-only push refusals now also carry `ok: false`.
+Output channels and process exit codes are unchanged. Read JSON failures on both
+stdout and stderr; progress/warnings are not failure envelopes.
+
+`code` is the machine contract. `error`/`errors`/`message` describe the failure for
+people and `hint`, when present, suggests recovery. Neither their wording nor the
+presence of one of those legacy shapes identifies the failure class. The complete
+push code vocabulary is listed below.
+
+For example, an attestation that no longer describes the content being published
+keeps its existing fields and adds the code:
+
+```json
+{
+  "ok": false,
+  "pushed": false,
+  "errors": ["2 retained attestation(s) were recorded at this commit, but none describes the content being published"],
+  "hint": "…",
+  "code": "attestation_stale"
+}
+```
+
+## Push codes
+
+| Code | Meaning |
+| --- | --- |
+| `attestation_history_corrupt` | Retained attestation history failed integrity checks. Takes precedence if stale runs are also present. |
+| `attestation_stale` | Retained runs at this commit do not describe the current release. |
+| `headless_run_failed` | A verified headless run failed. |
+| `ux_evidence_absent` | No UX evidence artifact exists. |
+| `ux_evidence_unrecorded` | No usable native UX drive was recorded. |
+| `ux_evidence_stale` | UX evidence belongs to a different release/commit. |
+| `ux_evidence_outdated` | UX evidence predates edits at this commit. |
+| `ux_evidence_failed` | A matching UX drive failed. |
+| `ux_evidence_inherited_screens` | A partial push inherits screens not covered by local UX evidence. |
+| `ux_evidence_unreadable` | The UX evidence artifact cannot be read. |
+| `lint_errors` | Build/lint validation found errors. |
+| `control_token_expired` | The selected control token has expired. |
+| `app_source_contains_secrets` | Source archiving detected a possible credential. |
+| `app_source_too_large` | The encoded source archive exceeds its limit. |
+| `publish_body_too_large` | The complete publish request exceeds its limit. |
+| `needs_vpn` | Full-push request to the publishing service could not complete (existing reachability code). This is not proof that VPN is the cause; read the target-aware error. |
+| `serve_unreachable` | A partial-push upload could not reach the publishing service. |
+| `no_serve_plane` | A loopback service answering a partial push is not a himi publishing service. |
+| `upload_http_error` | The upload returned a non-success HTTP status. `status` and the original `body` remain available; server errors never replace this CLI code. |
+| `claim_failed` | Auto-claim returned a fatal refusal. Existing server fields and `status` remain available. |
+| `invalid_flag_value` | A flag violates the CLI flag grammar. |
+| `invalid_selector` | `--only` is missing a selector or its selector syntax is invalid. |
+| `duplicate_only` | `--only` was repeated. |
+| `incompatible_push_flags` | A flag cannot be combined with `--only`. |
+| `from_release_needs_a_value` | `--from-release` has no value. |
+| `conflicting_blast_radius` | A partial push supplied both `--draft` and `--live`. |
+| `no_blast_radius` | A partial push supplied neither `--draft` nor `--live`. |
+| `invalid_visibility` | The visibility value is invalid. |
+| `release_read_failed` | A partial push could not read the base/live release. |
+| `base_not_found` | The explicitly selected base has no manifest. |
+| `no_live_release` | There is no live release to patch. |
+| `invalid_patch` | The selection cannot produce a valid patch. The existing `error` and plan details are preserved. |
+| `would_regress` | A partial push would revert unselected live changes. |
+| `not_carried_by_patch` | The package changed dependencies that a partial push cannot carry. |
+| `authoring_unavailable` | The bundled authoring runtime failed to load. |
+| `push_failed` | An otherwise unclassified exception stopped push (for example unreadable content). The original error is preserved. |
+
+The `ux_evidence_*` codes map to the existing typed `uxEvidence.state`; a successful
+`recorded` state has no refusal code. Successful pushes and warnings do not gain
+failure codes. A forced push still follows the existing override rules.
+
+## Follow-ups
+
+- Migrate failure envelopes in subcommands other than `push`, keeping this contract.
+- Review/reword human messages separately; no message rewrite is part of this change.
+- Review exit-code conventions separately; no exit code changes are part of this change.

package/guides/index.json

@@ -53,6 +53,12 @@
       "category": "CLI & Loop",
       "file": "headless-loop.md"
     },
+    {
+      "id": "himi-json-output",
+      "title": "JSON failures — stable error codes",
+      "category": "CLI & Loop",
+      "file": "himi-json-output.md"
+    },
     {
       "id": "himi-mcp",
       "title": "himi in your coding agent (MCP)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1246.0",
+  "version": "0.1248.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "5e90fa27e7fc17c28b74ef6630a0742b66132390f44c0270ca325392"
+  "falconPackageHash": "c3978ffa25b74036a72561b7d81106fb8230ea398edab38ac57b4270"
 }