@wix/himalaya-cli 0.925.0 → 0.927.0

package/dist/cli.mjs

@@ -50982,6 +50982,48 @@ var ServeCliClient = class {
   setAppConfig(app, patch) {
     return this.request("control", "POST", "/v1/admin/app-config", { body: { app, patch }, headers: this.ctrlHeaders() });
   }
+  // ---- flags (RFC 0013) ----
+  //
+  // ALL FOUR ARE ON THE CONTROL PLANE, the read included, and that is not an oversight about
+  // which door a device uses. `/v1/flags/{app}` is implemented in serve-control; the deployed
+  // artifact happens to answer it on the serve origin too, because one process hosts both
+  // (`isControlPath` in packages/serve/src/index.ts). Locally they are two processes, and the
+  // one on the serve port answers `/v1/flags/` with a STUB — `{definitions: {}}`, unconditional
+  // 200, documented as such in core/serve/src/run-handler.ts. So reading "the device door" from
+  // the serve base is right on prod and silently wrong everywhere else: the list comes back
+  // empty and every write reports that it is not being served.
+  //
+  // The read is still the point of the pairing: it is the same handler and the same file the
+  // write touched, which is what makes it able to contradict a 200.
+  /** Flag definitions as the plane would serve them (GET /v1/flags/{app}). No credential. */
+  flags(app) {
+    return this.request("control", "GET", `/v1/flags/${encodeURIComponent(app)}`);
+  }
+  /** Create or replace one flag definition (POST /v1/admin/flags). */
+  setFlag(app, key2, definition) {
+    return this.request("control", "POST", "/v1/admin/flags", { body: { app, key: key2, definition }, headers: this.ctrlHeaders() });
+  }
+  /** Ramp or kill a flag in place (POST /v1/admin/flags/ramp) — 404s an unknown key. */
+  rampFlag(app, key2, change) {
+    return this.request("control", "POST", "/v1/admin/flags/ramp", {
+      body: {
+        app,
+        key: key2,
+        // Spread-if-present, never `rolloutPercentage: change.rolloutPercentage`: the route reads
+        // `typeof === "number"`, so an explicit `undefined` is harmless — but `enabled` is read as
+        // `typeof === "boolean"`, and sending `{enabled: undefined}` in JSON drops the key anyway.
+        // Being explicit here keeps the wire body equal to what the caller asked for, so a ramp
+        // that only sets a percentage cannot also be read as "and leave enabled alone" by luck.
+        ...typeof change.rolloutPercentage === "number" ? { rolloutPercentage: change.rolloutPercentage } : {},
+        ...typeof change.enabled === "boolean" ? { enabled: change.enabled } : {}
+      },
+      headers: this.ctrlHeaders()
+    });
+  }
+  /** Delete one flag definition (POST /v1/admin/flags/remove); echoes the definition it removed. */
+  removeFlag(app, key2) {
+    return this.request("control", "POST", "/v1/admin/flags/remove", { body: { app, key: key2 }, headers: this.ctrlHeaders() });
+  }
   /** Write-through a design-tokens patch (POST /v1/admin/tokens). */
   setTokens(app, tokens, kit) {
     return this.request("control", "POST", "/v1/admin/tokens", { body: { app, tokens, ...kit ? { kit } : {} }, headers: this.ctrlHeaders() });
@@ -54384,6 +54426,9 @@ var USAGE = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                            plane, no dev-server. With no argument it packs the current
                                            content package first \u2014 edit, run, look at it.
                                            Blocks until Ctrl-C.
+  himi flags list|set|ramp|rm [<key>] [--app <a>]
+                                           read/change operational flags (RFC 0013); writes report
+                                           servedNow from the device door, never just ok
   himi visibility [public|unlisted] [--app <a>]
                                            read (no value) or set whether the public registry lists the app
   himi preview --app <app> --release <id> [--screen <id>] [--surface <id>] [--preview-token <token>]
@@ -54714,6 +54759,7 @@ var COMMANDS = [
   { name: "logs", summary: "worker console read-back (GET /v1/telemetry/logs); --follow tails via the seq cursor", required: "--app [--release] [--screen] [--level] [--follow]" },
   { name: "promote", summary: "flip a stored draft LIVE (POST /v1/admin/release/activate); --ring also points a rollout ring at it in the same command (POST /v1/admin/promote), which ring-based clients need in order to resolve at all \u2014 without it they stay unresolved and the warning goes to stderr; --percent sets that ring's rollout share; a release pushed past errors needs an explicit --force override", required: "--app --release [--ring <ring>] [--percent 0-100] [--force] (--control-token)" },
   { name: "patch", summary: 'change ONE item of a published app \u2014 a screen descriptor, a Tier-5 bundle, tokens, or the app-config baseline \u2014 from a RAW FILE, with no content package and no build. The low-level door: it does not lint your package, because there is no package here; `himi push --only <selector>` is the same edit with the full build + lint gate and is what to reach for when the package is in hand. Derives a new release from the app\'s current LIVE release, or from `--from-release <id>`. An explicit `--draft` or `--live` is REQUIRED \u2014 a patch has no default blast radius \u2014 and `--notes` is required with `--live` on a screen or app-config patch, because off-repo `gitSha` is "dev" and the ledger notes are then the only durable record of bytes that correspond to no commit. A branch does not merge: activating one derived from an older release reverts every item the patch does not move, so that case is refused until `--accept-regressions`. A bundle patch must repoint a screen (`--for-screen`) or the bytes land under a manifest key nothing reads. It cannot ADD a screen (screens are git-only, RFC 0012), never claims a slug \u2014 the app must already be published \u2014 and carries no attestation, source archive, assets, icon or minBinaryVersion, each named in the output.', required: "screen <id> --file <descriptor.json> [--bundle <sha256|none>] | bundle --file <bundle.js> (--for-screen <id>[,<id>] | --no-rebind) | tokens --file <tokens.json> | app-config --file <app-config.json> ; (--draft|--live) --app <a> [--from-release <id>] [--accept-regressions] [--label <n>] [--notes <t>] [--force] [--target <t>] (--control-token)" },
+  { name: "flags", summary: "read and change the app's OPERATIONAL flags (RFC 0013) \u2014 `list` prints what the DEVICE door serves, `set <key> --definition` creates or replaces one, `ramp <key>` moves its rollout share or kills it, `rm <key>` deletes it and echoes the definition back so the removal is reversible. Every write is followed by a read of the same door the device uses, and the answer is reported as `servedNow`: flags are stored in the app's git-committed flags.json, so a control plane with no checkout accepts a write it will never serve.", required: "list|set|ramp|rm [<key>] [--definition <json|@file>] [--percent 0-100] [--enabled true|false] [--app <a>] (--control-token)" },
   { name: "visibility", summary: "read (no value) or set whether the public registry (/v1/apps + the Himi Player picker) LISTS the app. `public` lists it for everyone; `unlisted` hides it from listings while direct reads by app id \u2014 deep links, previews \u2014 keep working. App from --app or the content dir. Setting it needs no republish.", required: "[public|unlisted] [--app <a>] [--content <dir>] (--control-token)" },
   { name: "dist", summary: "build an INSTALLABLE QA binary (signed IPA / APK) on the Wix Job Service Mac pool and return an install link \u2014 the serve plane brokers the job, the pool builds it. WAITS for the build by default (~4 min) and prints the install link; `--no-wait` returns a jobId immediately instead. Omitting `--release` builds whatever is LIVE for the app. A named draft is refused unless `--allow-draft` makes that exceptional build explicit. `status <jobId>` / `watch <jobId>` / `list --app <a>` / `cancel <jobId>` inspect and stop builds (`watch` reports up front whether the job mints its own signing identity or borrows one, so a doomed iOS build is cancellable in seconds rather than after the archive). Off-repo, name a target \u2014 `--target wix` for a self-serve Wix login or `--target bo` for the internal employee path (the in-repo default is a local dev plane that isn't reachable off-repo); self-serve callers may build their OWN apps under a tighter budget (2 in flight / 5 per 24h), while a manage-only owner-role credential is refused. `--shell` picks the native host to sign into (branded-lite | owner-lite | player | demo-app). `--signing` defaults to `wix-managed` \u2014 the Wix Apple account mints a per-app signing identity for the build, so the caller provisions no Apple credentials of their own; `--signing byo` (sign with your own Apple account) is reserved and 501s. `--android-signing` is the Android counterpart and a SEPARATE axis (a keystore, not an Apple account): `qa-keystore` (default \u2014 the repo's committed QA key, identical on every pool machine, so a build installs over the previous one), `wix-keystore` (the Wix key the pool machine carries; the build FAILS naming the paths searched if it carries none, rather than quietly signing with something else), or `debug` (the old per-machine key \u2014 QA must uninstall any previous build first). NOT the normal way to ship: screens, Tier-5 bundles, tokens and app-config all go over the air with `himi push` in seconds \u2014 a binary trip is only needed for a NATIVE delta (a new SDUI component, a new declared capability/entitlement, a new bundle id, or a minBinaryVersion floor bump). Refuses to build an app whose launcher icon is missing, a placeholder, or one a store would reject \u2014 the one thing a binary carries that no later OTA push can fix; `--force` builds anyway", required: "[--app <a>] [--platform ios,android] [--release <id>] [--allow-draft] [--target <t>] [--shell branded-lite|owner-lite|player|demo-app] [--signing wix-managed|byo] [--android-signing qa-keystore|wix-keystore|debug] [--borrow-ios-id <bundleId>] [--no-wait] [--force] | status <jobId> [--target <t>] | watch <jobId> [--target <t>] [--interval <ms>] | list --app <a> [--target <t>] | cancel <jobId> [--target <t>]" },
   { name: "testflight", summary: 'build, sign and upload an app to TestFlight (internal testers \u2014 no Beta App Review), then WAIT until App Store Connect finishes processing it. Sugar for `store upload --track testflight`. Prompts first: a build number is consumed permanently on a real Apple account and cannot be reused \u2014 `--yes` for CI, `--dry-run` to see the plan without touching anything. The wait is the real check, not a nicety: fastlane prints "Successfully uploaded" for a binary App Store Connect then rejects in processing, and a rejected binary leaves NO build record at all (the reason is emailed). Public App Store review is deliberately NOT automatable here \u2014 `--track appstore` is refused; use /submit-ios-app when you mean to go public', required: "<app> [--track testflight|internal] [--profile <name>] [--yes] [--dry-run] [--skip-build] [--no-wait] [--json]" },
@@ -54888,6 +54934,12 @@ function diagnoseBody(body) {
   if (emptied.length) out.foldedIntoFindings = emptied;
   return out;
 }
+var GIT_FLAG_STORE_NOTE = "the plane accepted the write but is not serving it. Operational flags live in the app's git-committed flags.json (RFC 0013), so a control plane with no checkout \u2014 a hosted pod \u2014 writes to a filesystem that is not read back and is lost on restart. Commit the change to the app's flags.json, or point this command at a control plane that has the repo.";
+function servesAll(served, asked) {
+  const stable = (v) => JSON.stringify(v, (_k, x) => x && typeof x === "object" && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => a.localeCompare(b))) : x);
+  return Object.entries(asked).every(([k, v]) => stable(served[k]) === stable(v));
+}
+var GIT_FLAG_STORE_HALF_WRITE_NOTE = "the plane reported a failure, but this store writes flags.json BEFORE it commits \u2014 so the change may already be on the pod that served this request, uncommitted and lost on its next restart. servedNow says what that pod answers now; other pods may differ.";
 var PREVIEW_TOKEN_NOTE = "the preview link carries a bearer with a limited lifetime, and this call has no usable expiry for it \u2014 the plane stated none, or the one it stated is unreadable, already past, or beyond the hour this CLI will reason about. Run the `previewRenew` command printed beside this note \u2014 from the same plane and credentials as this call (any `--serve-url`/`--control-url`/token flags you passed) \u2014 for a fresh one.";
 function previewTokenNote(expiresAt, now = Date.now()) {
   const at = expiresAt ? Date.parse(expiresAt) : NaN;
@@ -54987,9 +55039,9 @@ function isPublicTarget(target, control) {
   }
   return isPublicServeOrigin(url ?? "");
 }
-function serveUnreachableError(target, base, cause) {
+function serveUnreachableError(target, base, cause, plane = "serve") {
   return {
-    error: `cannot reach the serve plane for target "${target}" (${base || "no serve url"}): ${cause}. ${serveUnreachableHint(target)}`,
+    error: `cannot reach the ${plane} plane for target "${target}" (${base || `no ${plane} url`}): ${cause}. ${serveUnreachableHint(target)}`,
     code: "needs_vpn",
     target
   };
@@ -55750,6 +55802,7 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
     })
   );
   const serveBase = () => resolveTarget({ target: str5(flags.target), defaultTarget: contextualDefaultTarget, serveUrl: str5(flags["serve-url"]) }).serve;
+  const controlBase = () => resolveTarget({ target: str5(flags.target), defaultTarget: contextualDefaultTarget, controlUrl: str5(flags["control-url"]) }).control ?? "";
   const foreignPlaneRefusal = async () => {
     const base = serveBase();
     if (!isLoopbackBase(base)) return null;
@@ -58953,6 +59006,184 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           extra: { kind, file: { path: file, bytes: bytes2.length, sha256: sha } }
         });
       }
+      // OPERATIONAL FLAGS (RFC 0013) — the surface the admin portal's FlagsPanel used to own.
+      //
+      // The panel is going; this is what replaces it, and it is deliberately not a port. The panel
+      // wrote `flags.json` into a pod filesystem and reported success, which is why "flags don't
+      // work in production" was true and invisible for so long. Every write here is followed by a
+      // READ of the device-facing door, and what that read says is what gets printed.
+      case "flags": {
+        const sub = pos[1];
+        const app = str5(flags.app) ?? await appId(contentDir(flags));
+        const usage = "usage: himi flags list | set <key> --definition <json|@file> | ramp <key> [--percent 0-100] [--enabled true|false] | rm <key>";
+        if (sub !== "list" && sub !== "set" && sub !== "ramp" && sub !== "rm") {
+          io.error(JSON.stringify({ error: `unknown flags subcommand: ${sub ?? "(none)"}`, hint: usage }));
+          return 2;
+        }
+        const servedDefs = async () => {
+          try {
+            const r = await client2().flags(app);
+            if (!r.ok) return null;
+            const defs = r.json?.definitions;
+            return Array.isArray(defs) ? defs : null;
+          } catch {
+            return null;
+          }
+        };
+        if (sub === "list") {
+          let r;
+          try {
+            r = await client2().flags(app);
+          } catch (e) {
+            io.error(JSON.stringify({
+              ...serveUnreachableError(targetName(), controlBase(), e.message, "control"),
+              // The deployed artifact answers control routes on its public serve origin too
+              // (one process, `isControlPath`), so a reader who cannot reach the control host has
+              // somewhere to point. Said as an override rather than done automatically: the local
+              // serve port answers /v1/flags/ with a stub, and silently reading that is the
+              // failure this whole command is built to avoid.
+              hint: `flag routes live on the control plane; on a deployed target the same route is answered by the serve origin, so \`--control-url <serve origin>\` is the read-only way round a control host you cannot reach`
+            }));
+            return 1;
+          }
+          if (!r.ok) {
+            print({ ok: false, status: r.status, body: r.json ?? r.text });
+            return 1;
+          }
+          const defs = r.json?.definitions ?? [];
+          print({ ok: true, app, count: defs.length, definitions: defs });
+          return 0;
+        }
+        const key2 = pos[2];
+        if (!key2) {
+          io.error(JSON.stringify({ error: `flags ${sub} needs a key`, hint: usage }));
+          return 2;
+        }
+        if (sub === "set") {
+          const arg = str5(flags.definition);
+          if (!arg) {
+            io.error(JSON.stringify({ error: "flags set needs --definition <json|@file>", hint: usage }));
+            return 2;
+          }
+          let def;
+          try {
+            const parsed = JSON.parse(arg.startsWith("@") ? readFileSync64(arg.slice(1), "utf8") : arg);
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+              io.error(JSON.stringify({ error: "invalid_definition", problems: [`--definition must be a JSON object, got ${Array.isArray(parsed) ? "an array" : parsed === null ? "null" : typeof parsed}`] }));
+              return 2;
+            }
+            def = parsed;
+          } catch (e) {
+            io.error(JSON.stringify({ error: "invalid_definition_json", detail: e.message }));
+            return 2;
+          }
+          if (typeof def.key === "string" && def.key !== key2) {
+            io.error(JSON.stringify({
+              error: "definition_key_mismatch",
+              key: key2,
+              definitionKey: def.key,
+              hint: `the stored flag takes its key from the command, so this would save "${def.key}"'s definition under "${key2}"`
+            }));
+            return 2;
+          }
+          const problems = [];
+          if (typeof def.enabled !== "boolean") problems.push("enabled must be true or false");
+          const variants = Array.isArray(def.variants) ? def.variants : null;
+          if (!variants || variants.length === 0) problems.push("variants must be a non-empty array");
+          if (def.rolloutPercentage !== void 0 && (typeof def.rolloutPercentage !== "number" || def.rolloutPercentage < 0 || def.rolloutPercentage > 100)) {
+            problems.push(`rolloutPercentage must be 0..100, got ${JSON.stringify(def.rolloutPercentage)}`);
+          }
+          if (typeof def.defaultVariant !== "string") problems.push("defaultVariant must name a variant");
+          else if (variants && variants.length > 0 && !variants.some((v) => v?.key === def.defaultVariant)) {
+            problems.push(`defaultVariant "${def.defaultVariant}" is not one of the variants`);
+          }
+          if (problems.length > 0) {
+            io.error(JSON.stringify({ error: "invalid_definition", problems, hint: 'e.g. {"enabled":true,"variants":[{"key":"on","weight":100},{"key":"off","weight":0}],"defaultVariant":"off"}' }));
+            return 2;
+          }
+          const sent = { ...def, key: key2 };
+          return await writeFlag(() => client2().setFlag(app, key2, sent), (now) => !!now && servesAll(now, sent));
+        }
+        if (sub === "ramp") {
+          const percentGiven = flags.percent !== void 0;
+          const percent = num(flags.percent);
+          if (percentGiven && (percent === void 0 || percent < 0 || percent > 100)) {
+            io.error(JSON.stringify({ error: `--percent must be 0..100, got ${String(flags.percent)}` }));
+            return 2;
+          }
+          const enabledGiven = flags.enabled !== void 0;
+          const enabledRaw = flags.enabled === true ? "true" : str5(flags.enabled);
+          if (enabledGiven && enabledRaw !== "true" && enabledRaw !== "false") {
+            io.error(JSON.stringify({ error: `--enabled must be true or false, got ${String(flags.enabled)}` }));
+            return 2;
+          }
+          if (!percentGiven && !enabledGiven) {
+            io.error(JSON.stringify({ error: "flags ramp needs --percent and/or --enabled", hint: usage }));
+            return 2;
+          }
+          const change = {
+            ...percentGiven ? { rolloutPercentage: percent } : {},
+            ...enabledGiven ? { enabled: enabledRaw === "true" } : {}
+          };
+          return await writeFlag(() => client2().rampFlag(app, key2, change), (now) => !!now && servesAll(now, change));
+        }
+        const removedBefore = (await servedDefs())?.find((d) => d?.key === key2);
+        return await writeFlag(() => client2().removeFlag(app, key2), (now) => now === void 0, removedBefore);
+        async function writeFlag(send2, expected, undoCopy) {
+          let r;
+          try {
+            r = await send2();
+          } catch (e) {
+            io.error(JSON.stringify(serveUnreachableError(targetName(), controlBase(), e.message, "control")));
+            return 1;
+          }
+          if (!r.ok) {
+            const served2 = r.status >= 500 ? await servedDefs() : null;
+            const now2 = served2?.find((d) => d?.key === key2);
+            const removed = r.json?.removed ?? (r.status >= 500 ? undoCopy : void 0);
+            print({
+              ok: false,
+              status: r.status,
+              app,
+              key: key2,
+              body: r.json ?? r.text,
+              ...removed !== void 0 ? { removed } : {},
+              ...r.status >= 500 ? {
+                // The same two fields the success path prints, for the same reason: presence
+                // alone would call a 500 that left the OLD definition in place "served".
+                servedNow: served2 === null ? null : !!now2,
+                asRequested: served2 === null ? null : expected(now2),
+                warning: GIT_FLAG_STORE_HALF_WRITE_NOTE,
+                hint: `check what is actually served: himi flags list --app ${app} --target ${targetName()}`
+              } : {}
+            });
+            return 1;
+          }
+          const served = await servedDefs();
+          const now = served?.find((d) => d?.key === key2);
+          const wanted = expected(now);
+          print({
+            ok: true,
+            app,
+            key: key2,
+            ...r.json ?? {},
+            // A plane too old to echo what it deleted still leaves the caller with the copy this
+            // command read before writing — otherwise `rm` succeeds against it and prints nothing
+            // to paste back, which is the whole reason the pre-read exists.
+            ...undoCopy !== void 0 && r.json?.removed === void 0 ? { removed: undoCopy } : {},
+            // TWO fields, because one boolean cannot carry both facts without meaning different
+            // things per verb. `servedNow` is plain presence — is the door serving this key at
+            // all. `asRequested` is the judgement: does what it serves match what was just asked
+            // for (for `rm`, that the key is gone). A replaced definition the plane kept serving
+            // unchanged is servedNow:true / asRequested:false, which is the case a presence-only
+            // check reported as success.
+            servedNow: served === null ? null : !!now,
+            asRequested: served === null ? null : wanted,
+            ...served === null ? { note: "could not read the device door to confirm; the write was accepted" } : wanted ? {} : { warning: GIT_FLAG_STORE_NOTE, hint: `commit apps/${app}/flags.json instead` }
+          });
+          return 0;
+        }
+      }
       case "visibility": {
         const value = pos[1];
         if (value !== void 0 && value !== "public" && value !== "unlisted") {
@@ -60236,6 +60467,8 @@ if (isMain) {
 }
 export {
   ConfigLoadError,
+  GIT_FLAG_STORE_HALF_WRITE_NOTE,
+  GIT_FLAG_STORE_NOTE,
   PLACEHOLDER_CLIENT_ID,
   PLACEHOLDER_SITE_URL,
   PREVIEW_TOKEN_NOTE,
@@ -60288,6 +60521,7 @@ export {
   servePlaneAnswers,
   serveUnreachableError,
   serveUnreachableHint,
+  servesAll,
   switchFlagErrors,
   templatePreviewAuthError,
   tokenCoversApp,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.925.0",
+  "version": "0.927.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": [
@@ -64,5 +64,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "f7e299bf4530163cb8143700d0c7ad83fed1966b5f6f73a47e960356"
+  "falconPackageHash": "5a9a78922aa072426bb6e4169693f0fdd84817367970c02f4e036483"
 }