@wix/himalaya-cli 0.1245.0 → 0.1247.0

package/dist/cli.mjs

@@ -132925,6 +132925,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, {
@@ -163741,11 +163807,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 };
@@ -164295,6 +164361,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,
@@ -164315,7 +164384,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) {
@@ -164342,11 +164411,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) => {
@@ -164359,33 +164428,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",
@@ -164397,14 +164466,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",
@@ -164414,25 +164483,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) {
@@ -164498,17 +164567,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;
@@ -166687,15 +166756,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 [
@@ -166703,12 +166772,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;
@@ -166727,14 +166796,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) ?? {});
@@ -166762,7 +166831,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);
@@ -166781,28 +166850,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, {
@@ -166872,21 +166941,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",
@@ -166896,7 +166965,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;
@@ -166913,22 +166982,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, {
@@ -166940,7 +167009,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,
@@ -166958,7 +167027,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);
@@ -166969,7 +167038,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 = {
@@ -166988,7 +167057,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,
@@ -166997,7 +167066,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);
@@ -167008,14 +167077,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 }));
@@ -167036,16 +167105,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;
@@ -170282,15 +170351,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/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.1245.0",
+  "version": "0.1247.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": "09f05672ac223575259bf3c6b41d9dbdb7ad92bd5de82076c956864c"
+  "falconPackageHash": "ba75b3fdbeb557376aad2c794b64762b5e246a1c72a94d970720534c"
 }