@wix/himalaya-cli 0.973.0 → 0.975.0

package/dist/cli.mjs

@@ -18715,6 +18715,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]+$/;
@@ -22139,6 +22140,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,
@@ -39644,7 +39646,7 @@ async function pinnedFetch(url, init, addresses, maxResponseBytes) {
   const body = init.body === void 0 || init.body === null ? void 0 : new Uint8Array(await new Response(init.body).arrayBuffer());
   const headers2 = Object.fromEntries(new Headers(init.headers).entries());
   const request = url.protocol === "https:" ? httpsRequest : httpRequest;
-  const hostname = url.hostname.replace(/^\[|\]$/g, "");
+  const hostname2 = url.hostname.replace(/^\[|\]$/g, "");
   return await new Promise((resolve43, reject) => {
     let settled = false;
     const finish2 = (fn) => {
@@ -39654,13 +39656,13 @@ async function pinnedFetch(url, init, addresses, maxResponseBytes) {
     };
     const req = request({
       protocol: url.protocol,
-      hostname,
+      hostname: hostname2,
       port: url.port || (url.protocol === "https:" ? 443 : 80),
       path: `${url.pathname}${url.search}`,
       method: init.method ?? "GET",
       headers: headers2,
       lookup: (_hostname, _options, callback) => callback(null, address, isIP(address)),
-      ...url.protocol === "https:" && isIP(hostname) === 0 ? { servername: hostname } : {}
+      ...url.protocol === "https:" && isIP(hostname2) === 0 ? { servername: hostname2 } : {}
     }, (response) => {
       const chunks = [];
       let total = 0;
@@ -48234,9 +48236,9 @@ function isFetchableFontUrl(raw) {
   if (host.includes(":")) return !isPrivateV6(host);
   return true;
 }
-function resolveAll(hostname) {
+function resolveAll(hostname2) {
   return new Promise((resolve43, reject) => {
-    dnsLookup(hostname, { all: true, verbatim: true }, (err, addresses) => {
+    dnsLookup(hostname2, { all: true, verbatim: true }, (err, addresses) => {
       if (err) reject(err);
       else resolve43(addresses);
     });
@@ -51212,9 +51214,9 @@ var init_site_oauth_client = __esm({
 
 // src/cli.ts
 import { mkdtempSync as mkdtempSync4, readFileSync as readFileSync65, mkdirSync as mkdirSync25, writeFileSync as writeFileSync23, existsSync as existsSync54, rmSync as rmSync9, readdirSync as readdirSync25, statSync as statSync12, lstatSync as lstatSync6, accessSync, constants } from "node:fs";
-import { execFileSync as execFileSync7 } from "node:child_process";
-import { createHash as createHash24 } from "node:crypto";
-import { tmpdir as tmpdir5 } from "node:os";
+import { execFileSync as execFileSync7, spawnSync as spawnSync5 } from "node:child_process";
+import { createHash as createHash24, randomUUID as randomUUID3 } from "node:crypto";
+import { tmpdir as tmpdir5, homedir as homedir7, hostname } from "node:os";
 import { join as join51, resolve as resolve42, relative as relative8, basename as basename11, dirname as dirname30 } from "node:path";
 import { fileURLToPath as fileURLToPath24 } from "node:url";
 
@@ -54580,6 +54582,19 @@ ${overview}
 
 ${loop}
 
+## Stay on a current CLI
+
+A stale global install is the single most common cause of "this doesn't work off-repo": the old
+CLI mislabels its own age as a platform limit, and the error it prints sends you hunting the
+wrong thing. himi now notices \u2014 when the running build is over a week old it updates itself and
+re-runs your command (at a terminal it asks first), so in an unattended run this takes care of
+itself. \`himi upgrade\` does it on demand, and \`himi doctor --json\` reports
+\`versions.cli\` \u2014 \`running\`, \`latest\`, \`ageDays\`, \`status\`.
+
+Before concluding that a command is broken or a capability is missing, check you are not on an
+old build. If a \`--json\` envelope carries an \`upgrade\` key, that is himi telling you this
+directly. Set \`HIMI_NO_UPDATE_CHECK=1\` in images that must not self-update.
+
 ## Import paths (in-repo vs off-repo)
 
 Off-repo content packages import \`@wix/himalaya/<pkg>\`. In-repo Himalaya sources import
@@ -55333,6 +55348,12 @@ var USAGE = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                            stored control token). --dpx also runs a live
                                            supported "dpx auth status". --json for agents; an
                                            unreachable internal plane carries code:"needs_vpn".
+  himi upgrade [--json]                    install the newest published CLI and say what moved.
+                                           himi also does this ITSELF when the running build is
+                                           over a week old \u2014 unattended it updates and re-runs
+                                           your command, at a terminal it asks first. Turn that
+                                           off with HIMI_NO_UPDATE_CHECK=1 (or per-run with
+                                           --skip-version-check) and use this command instead.
 
 Learn (works offline \u2014 no serve stack needed):
   himi guide                               feature highlights + the headless dev loop + topics
@@ -55421,6 +55442,7 @@ var COMMANDS = [
   { name: "notify", summary: "send a REAL push notification to registered devices (RFC 0036 WS5) \u2014 APNs .p8 over HTTP/2 for iOS, FCM v1 for Android. `send` targets one device (--token / --device <registry id>) or fans out to the whole app (--all), reporting a per-device result; a token the provider says is uninstalled (APNs 410 Unregistered / FCM UNREGISTERED) is auto-disabled, while a merely wrong one (BadDeviceToken \u2014 usually a sandbox/production mismatch) is recorded and left enabled. `tokens` lists the registry. `doctor` reports which credentials resolve and which sender each platform picks. Talks to the admin-server via --admin-url/HIMALAYA_ADMIN_URL, authenticated with --admin-session/HIMALAYA_ADMIN_SESSION. NOT `himi push`, which publishes a release.", required: "send|tokens|doctor [--app <a>] [--token <t> | --device <id> | --all] [--title <s>] [--body <s>] [--link <url>] [--platform ios|android] [--badge <n>] [--channel <id>] [--silent] [--dry-run] [--json]" },
   { name: "site", summary: "PROVISION a Wix project, then analyze or extend it. `create` is the one door that makes a site instead of adopting one: POST /funnel/projects/v1/create (a WIX site, a HEADLESS backend, a BRANDED_APP, or a VIBE site), and for headless it also mints the OAuth app whose id IS the `WIX_CLIENT_ID` \u2014 with --redirect-uri already registered, because an unregistered redirect makes native signInDirect fail at redirect-session. `--verticals` REQUIRES `--template` and reports only what Wix confirmed: measured, installing onto a project created from the BLANK template returns 200 while the vertical's API answers 428 forever, because there is no site for it to attach to (the install asks for CREATE_SITE). A real template ships its verticals installed and populated, and installing further ones onto it then works. It MUTATES your Wix account and needs --yes; without it you get the payload and nothing is sent. `list` is the read-only site inventory (with each site's premium flag, which is what explains an installed-but-428 vertical). Auth is the account-scoped `wix token` (no --site), falling back to WIX_API_KEY + WIX_ACCOUNT_ID. `client` is the same OAuth step for a site that ALREADY exists \u2014 the one himi adopts rather than makes \u2014 so a clientId no longer means a manual trip to the dashboard: `client ensure` reconciles rather than mints, because a site can already carry a client with NO registered redirect and shipping that one fails signInDirect at runtime; it reuses a client that carries --redirect-uri, PATCHes one that matches --name but lacks it (unioning, so another app's redirect survives), and creates only when there is nothing to reuse (--new forces a fresh one). --name IS the idempotency key. `client` auth is SITE-scoped (`wix token --site <msid>`) because minting is owner-of-that-site, and --yes gates every mutation: a site that already has a usable client resolves WITHOUT it, but --write-provisioning needs --yes even then because it rewrites a manifest on disk (the dry run's planned.provisioning names the file). That query endpoint IGNORES paging (measured: query.paging, cursorPaging and a top-level paging all return the full set at offset 0), so when pagingMetadata reports more clients than came back, `ensure` REFUSES EVERY outcome \u2014 create, patch AND reuse. Reuse is refused too because pickClient breaks ties on the OLDEST createdDate, so an omitted older same-named MOBILE client with the same redirect would win a later complete read and the resolved clientId would MOVE between runs \u2014 and it gets written into provisioning.json; convergence is what makes a stray duplicate untidy rather than harmful. --name cannot narrow the query (no filter is sent; the name is applied to the rows after they arrive), so the recovery is the dashboard; --new skips the query entirely. A `patched` result is verified against what Wix STORED \u2014 the redirect list is read off the PATCH response, and re-read via GET when the response omits it, because falling back to the list himi just sent would make the guard pass vacuously on exactly the silent no-op it exists to catch. `client list` is the read-only inventory of a site's clients: act on its `shippable` column rather than `hasRedirect`, because shippable ALSO requires a MOBILE applicationType and `ensure` refuses a WEB client \u2014 a WEB one carrying your redirect looks right and is not a candidate \u2014 and it sets truncated:true rather than presenting a partial inventory as the whole one. `analyze` reads a site into a business-book folder (REST + Playwright, GET-only); `site function` list/get/put/publish/invokes that site's Velo HTTP functions and is not `himi functions` (serve-plane jobs). `--apply` bakes into a brandable shell; `--shell` takes the same names `himi dist --shell` does and defaults to branded-lite, and a shell that ships no prepare:customer is refused by name rather than half-built. It never overwrites any shell's committed apps/<shell>/provisioning.json.", required: "create <name> [--type wix|headless|branded-app|vibe] [--template <guid>] [--verticals stores,bookings,\u2026] [--folder <guid>] [--redirect-uri <uri>] [--no-oauth-app] [--write-provisioning [path]] [--site-url <url>] [--json] --yes | list | client ensure|list --site <msid> [--name <name>] [--redirect-uri <uri>] [--new] [--write-provisioning [path]] [--site-url <url>] [--json] --yes | analyze --client-id <id> --url <https> [--site <msid>] [--out <dir>] [--redirect-uri <uri>] [--apply] [--shell " + SHELL_ENUM + "] | function list|get|put|publish|invoke [--site <msid>] [--url <https>] [--method GET|POST|PUT|DELETE] [--source <file>] [--body <json>] [--publish] [--invoke]" },
   { name: "doctor", summary: 'off-VPN preflight in one shot: probe the PUBLIC data plane (www.wixapis.com \u2014 reachable off-VPN), the INTERNAL serve/control plane for the selected target (VPN-gated), and report auth state (dpx session on disk + stored control token). --dpx additionally runs a live, EADDRINUSE-safe `dpx whoami`. Machine-readable with --json (an unreachable internal plane carries a stable code:"needs_vpn" so an agent branches on the code, not the prose); human-readable otherwise. Never loads the authoring runtime \u2014 works off-repo.', required: "[--target <t>] [--dpx] [--json] [--data-url <url>] [--timeout <ms>]" },
+  { name: "upgrade", summary: "install the newest published CLI (`npm i -g @wix/himalaya-cli@latest`) and report what moved. This is the explicit door: himi also updates itself when the running build is more than a week old \u2014 unattended it just does it and re-runs your command, at a terminal it asks first \u2014 and `HIMI_NO_UPDATE_CHECK=1` turns that off, leaving this command as the way to catch up. Reports `unchanged` rather than claiming success when npm exits 0 without moving the version, which is what a registry mirror serving its own pinned copy looks like.", required: "[--json]" },
   { name: "push", summary: "lint + build + publish a release (default --draft: servable via ?release= but NOT live). REFUSES to publish on any error unless --force; --strict promotes warnings. Prints preview + agent-context links. The published slug is NAMESPACED per owner \u2014 `<ownerPrefix>.<name>`, composed offline from the control token's ownerPrefix claim, so the CLI and the server derive the identical string and himalaya.content.json is NOT rewritten (a legacy token with no ownerPrefix publishes the declared name unchanged). An app claimed BEFORE namespacing is stored under its FLAT slug, so the claim route answers `alreadyYours` naming that slug and the push adopts it \u2014 reported as `adoptedSlug`, since it is the one case where the published `app` differs from what the declared name composes to. `--no-claim` skips the route that knows this, so a pre-namespacing app pushed with it still fails 403. --visibility public|unlisted decides whether /v1/apps + the Himi Player picker LIST the app (also declarable as `visibility` in himalaya.content.json; omitted, a brand-new app defaults to unlisted \u2014 share by link \u2014 and an existing setting is kept). --account-id names which account owns the app when your Wix session resolves to several (the auto-claim of a brand-new slug cannot guess \u2014 without it a multi-account caller is told to name one). An unforced push of a release that carries SCREENS also refuses when `.himi/ux-audit.json` holds no mobile-UX drive recorded against that release id, or holds one that FAILED (#2955) \u2014 a published draft IS the owner-private preview a customer is handed; `himi ux record` clears it and `--force` overrides it, which the success envelope then says out loud. `--only <selector>` publishes ONLY the named items as a release derived from the app's live release (or `--from-release <id>`), running the identical build + lint gate and simply publishing less; it requires an explicit `--draft` or `--live` because a partial publish has no safe default, never claims a slug, and carries neither attestation nor a source archive (both named in the output). Selectors are comma-separated in ONE `--only`: `changed` (every item whose bytes differ from the base), `screen:<id|glob>`, `bundle:<name>`, `tokens`, `app-config` \u2014 a selected screen drags its logic bundle and a selected bundle drags the screens that reference it, or the bytes land under a key nothing reads.", required: "[--content <dir>] [--draft] [--live] [--force] [--strict] [--label] [--notes] [--visibility public|unlisted] [--no-claim] [--account-id <id>] [--only <selector>] [--from-release <id>] [--accept-regressions] [--accept-partial] [--app <slug>] (--control-token)" },
   { name: "pack", summary: 'write the app as a PORTABLE .himi package \u2014 one self-contained file holding every screen, Tier-5 bundle, token, asset and the app-config. Packages are live by default: they boot bundled content offline, then Himi Player follows its baked-in production ring. `--snapshot` makes a frozen reproducible artifact. Package-supplied origins are never trusted. --format dir writes the same tree unpacked, for static hosting. --release-dir packs a release that is already built on disk (needs --app) instead of rebuilding from source. `--dev` ALSO packs the app\'s own source archive into the container (`source.zip`, header `contents: "dev"`), so the package can be handed to someone who then keeps building \u2014 collected through the same deny-list and secret scan `himi push` uses, and refused if a credential is found. A dev package IS the codebase: it is never the default, it is always labelled in the output, the web host will not open one, and it is archive-only (`--dev --format dir` is refused, because a reader that predates the source entry drops it before hashing a directory and would call the package tampered). Restore one with `himi import`.', required: "[--content <dir>] [--out <file|dir>] [--format zip|dir] [--name <title>] [--snapshot] [--dev] [--strict] [--force] | --release-dir <dir> --app <a>" },
   { name: "import", summary: "turn a `himi pack --dev` package back into an EDITABLE content package \u2014 the file counterpart of `himi pull`, needing no serve plane, no account and no network. Refuses an invalid package before trusting its source (the content hash is recomputed over every entry on open, so the archive is provably the one that was packed), and refuses a RELEASE package by naming the absence \u2014 it carries built output and no source \u2014 rather than reporting a missing file. `--name` re-substitutes the app identity through the same machinery `himi init --template` and `himi pull --name` use, so the restored tree is a NEW app rather than a second copy of the same one, and a name that also appears inside a screen id (`feed` in `feed_home`) is left alone. A non-empty destination needs `--force` and a merge NAMES what it kept (`left: [...]`), the same contract `himi pull --force` has; a shape clash is refused whole before anything is written. There is no `--replace`: a file you were handed is not the plane's per-release archive.", required: "<package.himi> [--out <dir>] [--name <new>] [--force]" },
@@ -55472,6 +55494,56 @@ function compareVersions2(a, b) {
   }
   return 0;
 }
+var PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org";
+var WIX_NPM_MIRROR = "https://npm.dev.wixpress.com";
+var CLI_PACKAGE_PATH = "@wix%2fhimalaya-cli";
+var TRUSTED_REGISTRIES = /* @__PURE__ */ new Set([PUBLIC_NPM_REGISTRY, WIX_NPM_MIRROR]);
+function normalizeRegistry(url) {
+  return url?.trim().replace(/\/+$/, "") || void 0;
+}
+function isTrustedRegistry(url) {
+  const normalized = normalizeRegistry(url);
+  return normalized !== void 0 && TRUSTED_REGISTRIES.has(normalized);
+}
+function trustedConfiguredRegistry(env) {
+  const configured = normalizeRegistry(env.npm_config_registry ?? env.NPM_CONFIG_REGISTRY);
+  return isTrustedRegistry(configured) ? configured : void 0;
+}
+async function fetchPackumentFrom(registry, fetchImpl, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(`${registry.replace(/\/$/, "")}/${CLI_PACKAGE_PATH}`, {
+      headers: { accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) return void 0;
+    const json5 = await response.json();
+    const latest = typeof json5?.["dist-tags"]?.latest === "string" ? json5["dist-tags"].latest : void 0;
+    const time = {};
+    for (const [version, when] of Object.entries(json5?.time ?? {})) if (typeof when === "string") time[version] = when;
+    return latest ? { latest, time, registry: normalizeRegistry(registry) ?? registry } : void 0;
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchCliPackument(fetchImpl = fetch, timeoutMs = DOCTOR_TIMEOUT_MS, env = process.env) {
+  const configured = trustedConfiguredRegistry(env);
+  const candidates = configured && configured !== PUBLIC_NPM_REGISTRY ? [configured, PUBLIC_NPM_REGISTRY] : [PUBLIC_NPM_REGISTRY];
+  for (const registry of candidates) {
+    const packument = await fetchPackumentFrom(registry, fetchImpl, timeoutMs);
+    if (packument) return packument;
+  }
+  return void 0;
+}
+function ageInDays(publishedAt, now = Date.now()) {
+  if (!publishedAt) return void 0;
+  const at = Date.parse(publishedAt);
+  if (!Number.isFinite(at)) return void 0;
+  return Math.max(0, (now - at) / 864e5);
+}
 function packageVersion(path) {
   try {
     const version = JSON.parse(readFileSync65(path, "utf8")).version;
@@ -55501,18 +55573,10 @@ function resolvedSdkVersion(fromDir = process.cwd(), bundledManifest = new URL("
 }
 async function doctorVersionReport(running, fetchImpl = fetch, sdk = resolvedSdkVersion()) {
   const minimumSdk = "0.33.0";
-  const registry = (process.env.npm_config_registry ?? "https://npm.dev.wixpress.com").replace(/\/$/, "");
-  let latest;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), DOCTOR_TIMEOUT_MS);
-  try {
-    const response = await fetchImpl(`${registry}/@wix%2fhimalaya-cli`, { headers: { accept: "application/json" }, signal: controller.signal });
-    const json5 = response.ok ? await response.json() : void 0;
-    latest = typeof json5?.["dist-tags"]?.latest === "string" ? json5["dist-tags"].latest : void 0;
-  } catch {
-  } finally {
-    clearTimeout(timer);
-  }
+  const packument = await fetchCliPackument(fetchImpl);
+  const latest = packument?.latest;
+  const publishedAt = packument?.time[running];
+  const ageDays = ageInDays(publishedAt);
   const cliOutdated = !!latest && compareVersions2(running, latest) < 0;
   const bundled = sdk.source === "bundled";
   const sdkOutdated = !bundled && !!sdk.version && compareVersions2(sdk.version, minimumSdk) < 0;
@@ -55520,6 +55584,8 @@ async function doctorVersionReport(running, fetchImpl = fetch, sdk = resolvedSdk
     cli: {
       running,
       ...latest ? { latest } : {},
+      ...publishedAt ? { publishedAt } : {},
+      ...ageDays === void 0 ? {} : { ageDays: Math.round(ageDays * 10) / 10 },
       status: latest ? cliOutdated ? "outdated" : "current" : "unknown",
       ...cliOutdated ? { hint: "Upgrade: npm i -g @wix/himalaya-cli@latest" } : {}
     },
@@ -55535,6 +55601,329 @@ function formatSdkVersionLine(sdk) {
   if (sdk.source === "bundled") return `sdk: bundled (${sdk.resolved ?? "unknown"})`;
   return `sdk: ${sdk.resolved ?? "not installed"} (minimum ${sdk.minimum}; ${sdk.status})`;
 }
+var CLI_PACKAGE = "@wix/himalaya-cli";
+var UNPUBLISHED_CLI_VERSION = "0.1.0";
+var UPDATE_MAX_AGE_DAYS = 7;
+var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var UPDATE_SNOOZE_MS = 24 * 60 * 60 * 1e3;
+var UPDATE_REEXEC_ENV = "HIMI_UPDATED_ONCE";
+function updateCachePath(env = process.env) {
+  return env.HIMI_UPDATE_CACHE_FILE ?? join51(homedir7(), ".himalaya", "update-check.json");
+}
+function readUpdateCache(path) {
+  try {
+    const parsed = JSON.parse(readFileSync65(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function writeUpdateCache(path, cache) {
+  try {
+    mkdirSync25(dirname30(path), { recursive: true, mode: 448 });
+    writeFileSync23(path, JSON.stringify(cache, null, 2) + "\n", { mode: 384 });
+  } catch {
+  }
+}
+function updateCheckSuppression(running, command, env = process.env, cwd = process.cwd()) {
+  if (env[UPDATE_REEXEC_ENV] === "1") return "already-updated";
+  if (env.HIMI_NO_UPDATE_CHECK === "1") return "opted-out";
+  if (command === "upgrade" || command === "doctor") return "own-command";
+  if (running === UNPUBLISHED_CLI_VERSION) return "unpublished";
+  if (isHimalayaMonorepoCheckout(cwd)) return "monorepo";
+  return void 0;
+}
+function decideUpdateAction(input) {
+  if (!input.latest || compareVersions2(input.running, input.latest) >= 0) return "skip";
+  if (input.ageDays === void 0 || input.ageDays < input.maxAgeDays) return "skip";
+  if (!input.prefixWritable()) return "warn";
+  return input.interactive ? "prompt" : "update";
+}
+function globalNodeModulesRoot() {
+  try {
+    const root = execFileSync7("npm", ["root", "-g"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    return root || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function globalPrefixWritable() {
+  const root = globalNodeModulesRoot();
+  if (!root) return false;
+  try {
+    accessSync(root, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function npmInstallArgs(registry, version) {
+  const pinned = `${normalizeRegistry(registry) ?? registry}/`;
+  return ["i", "-g", `${CLI_PACKAGE}@${version}`, `--registry=${pinned}`, `--@wix:registry=${pinned}`];
+}
+var INSTALLABLE_SPEC = /^(?:latest|\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/;
+function createUpdateRunner(spawn5 = spawnSync5) {
+  return {
+    install: async (registry, version) => {
+      if (!isTrustedRegistry(registry)) return { ok: false, detail: `refusing untrusted registry ${registry}` };
+      if (!INSTALLABLE_SPEC.test(version)) return { ok: false, detail: `refusing install spec ${JSON.stringify(version)}` };
+      const result = spawn5("npm", npmInstallArgs(registry, version), {
+        // npm's stdout goes to OUR stderr: in `himi <cmd> --json | jq` (and `himi upgrade --json`) its
+        // "added 212 packages" would otherwise land in stdout ahead of the envelope and break the
+        // parse — the agent case this whole feature exists for (#2985 review). And no stdin: an
+        // install needs none, and must not consume input piped to the command we are about to re-run.
+        stdio: ["ignore", 2, 2],
+        cwd: homedir7()
+      });
+      if (result.error) return { ok: false, detail: result.error.message };
+      return result.status === 0 ? { ok: true } : { ok: false, detail: `npm exited ${result.status}` };
+    },
+    installedVersion: () => {
+      const root = globalNodeModulesRoot();
+      return root ? packageVersion(join51(root, "@wix", "himalaya-cli", "package.json")) : void 0;
+    },
+    reexec: (argv) => {
+      const root = globalNodeModulesRoot();
+      const entry = root ? join51(root, "@wix", "himalaya-cli", "dist", "cli.mjs") : void 0;
+      if (!entry || !existsSync54(entry)) return void 0;
+      const result = spawnSync5(process.execPath, [entry, ...argv], {
+        // inherit keeps PIPED STDIN working — commands that read stdin must survive a re-exec.
+        stdio: "inherit",
+        env: { ...process.env, [UPDATE_REEXEC_ENV]: "1" }
+      });
+      return result.status ?? 1;
+    },
+    confirm: async (question) => {
+      const { createInterface } = await import("node:readline/promises");
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      try {
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
+      } catch {
+        return false;
+      } finally {
+        rl.close();
+      }
+    }
+  };
+}
+var defaultUpdateRunner = createUpdateRunner();
+var UPDATE_LOCK_REPORT_AFTER_MS = 60 * 60 * 1e3;
+function thisHost() {
+  return hostname().replace(/\s+/g, "_");
+}
+function lockStamp(now) {
+  return `${now} ${process.pid} ${thisHost()} ${randomUUID3()}`;
+}
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function isAbandoned(content) {
+  const [, pid, host] = content.split(" ");
+  const owner = Number.parseInt(pid, 10);
+  return Number.isFinite(owner) && owner > 0 && host === thisHost() && !processAlive(owner);
+}
+function staleUpdateLockFile(cachePath, now) {
+  for (const path of [`${cachePath}.lock.break`, `${cachePath}.lock`]) {
+    let content;
+    try {
+      content = readFileSync65(path, "utf8");
+    } catch {
+      continue;
+    }
+    const stamped = Number.parseInt(content.split(" ")[0], 10);
+    let since = stamped;
+    if (!Number.isFinite(since)) {
+      try {
+        since = statSync12(path).mtimeMs;
+      } catch {
+        continue;
+      }
+    }
+    if (now - since >= UPDATE_LOCK_REPORT_AFTER_MS) return path;
+  }
+  return void 0;
+}
+function acquireUpdateLock(cachePath, now, hooks = {}) {
+  const lockPath = `${cachePath}.lock`;
+  const breakPath = `${cachePath}.lock.break`;
+  const mine = lockStamp(now);
+  const readLock = (path) => {
+    try {
+      return readFileSync65(path, "utf8");
+    } catch {
+      return void 0;
+    }
+  };
+  const tryCreate = (path) => {
+    try {
+      writeFileSync23(path, mine, { flag: "wx", mode: 384 });
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const removeIfMine = (path) => {
+    try {
+      if (readLock(path) === mine) rmSync9(path, { force: true });
+    } catch {
+    }
+  };
+  const release = () => removeIfMine(lockPath);
+  try {
+    mkdirSync25(dirname30(lockPath), { recursive: true, mode: 448 });
+  } catch {
+    return () => {
+    };
+  }
+  try {
+    if (tryCreate(lockPath)) return release;
+    const held = readLock(lockPath);
+    if (held === void 0) return tryCreate(lockPath) ? release : void 0;
+    if (!isAbandoned(held)) return void 0;
+    hooks.beforeBreak?.();
+    if (!tryCreate(breakPath)) return void 0;
+    try {
+      const current = readLock(lockPath);
+      hooks.underBreakLock?.();
+      if (current === void 0) return tryCreate(lockPath) ? release : void 0;
+      if (!isAbandoned(current)) return void 0;
+      rmSync9(lockPath, { force: true });
+      return tryCreate(lockPath) ? release : void 0;
+    } finally {
+      removeIfMine(breakPath);
+    }
+  } catch {
+    return void 0;
+  }
+}
+function formatStaleLine(running, latest, ageDays) {
+  const days = Math.round(ageDays);
+  return `himi v${running} is ${days} day${days === 1 ? "" : "s"} old (latest ${latest})`;
+}
+function upgradeEnvelope(outcome) {
+  return {
+    running: outcome.running,
+    ...outcome.latest ? { latest: outcome.latest } : {},
+    ...outcome.ageDays === void 0 ? {} : { ageDays: outcome.ageDays },
+    action: outcome.action,
+    command: `npm i -g ${CLI_PACKAGE}@latest`,
+    ...outcome.detail ? { detail: outcome.detail } : {}
+  };
+}
+async function maybeSelfUpdate(argv, io, opts = {}) {
+  const env = opts.env ?? process.env;
+  const running = opts.running ?? cliVersion();
+  const command = opts.command ?? "";
+  if (updateCheckSuppression(running, command, env, opts.cwd ?? process.cwd())) return void 0;
+  const now = opts.now ?? Date.now();
+  const cachePath = opts.cachePath ?? updateCachePath(env);
+  const cache = readUpdateCache(cachePath);
+  if (cache.snoozedUntil && Date.parse(cache.snoozedUntil) > now) return void 0;
+  let latest = cache.latest;
+  let runningPublishedAt = cache.runningPublishedAt;
+  const checkedAt = cache.checkedAt ? Date.parse(cache.checkedAt) : Number.NaN;
+  const describesThisBuild = cache.running === running;
+  const fresh = Number.isFinite(checkedAt) && now - checkedAt < UPDATE_CHECK_INTERVAL_MS && describesThisBuild;
+  if (!describesThisBuild) runningPublishedAt = void 0;
+  let answeredBy;
+  let answeredLatest;
+  if (!fresh) {
+    const packument = await fetchCliPackument(opts.fetchImpl ?? fetch, DOCTOR_TIMEOUT_MS, env);
+    if (packument) {
+      latest = packument.latest;
+      runningPublishedAt = packument.time[running];
+      answeredBy = packument.registry;
+      answeredLatest = packument.latest;
+      writeUpdateCache(cachePath, { ...cache, running, checkedAt: new Date(now).toISOString(), latest, runningPublishedAt });
+    }
+  }
+  const ageDays = ageInDays(runningPublishedAt, now);
+  const fromEnv = Number(env.HIMI_UPDATE_MAX_AGE_DAYS);
+  const maxAgeDays = opts.maxAgeDays ?? (fromEnv > 0 ? fromEnv : UPDATE_MAX_AGE_DAYS);
+  const interactive = opts.interactive ?? (io.isTTY === true && process.stdin.isTTY === true);
+  const action = decideUpdateAction({
+    running,
+    latest,
+    ageDays,
+    maxAgeDays,
+    interactive,
+    prefixWritable: opts.prefixWritable ?? globalPrefixWritable
+  });
+  if (action === "skip" || !latest || ageDays === void 0) return void 0;
+  const base = { running, latest, ageDays: Math.round(ageDays * 10) / 10, command };
+  const stale = formatStaleLine(running, latest, ageDays);
+  if (action === "warn") {
+    io.error(`${stale} \u2014 npm i -g ${CLI_PACKAGE}@latest`);
+    return { ...base, action: "warned", detail: "global prefix is not writable" };
+  }
+  const runner2 = opts.runner ?? defaultUpdateRunner;
+  if (action === "prompt") {
+    const yes = await runner2.confirm(`${stale}. Update now? [Y/n] `);
+    if (!yes) {
+      writeUpdateCache(cachePath, {
+        running,
+        latest,
+        runningPublishedAt,
+        checkedAt: new Date(now).toISOString(),
+        snoozedUntil: new Date(now + UPDATE_SNOOZE_MS).toISOString()
+      });
+      return { ...base, action: "declined" };
+    }
+  }
+  const releaseLock = opts.acquireLock === void 0 ? acquireUpdateLock(cachePath, now) : opts.acquireLock();
+  if (!releaseLock) {
+    const blocker = staleUpdateLockFile(cachePath, now);
+    if (blocker) io.error(`${stale}, but self-update has been blocked for over an hour by ${blocker} \u2014 if no himi is running, delete it`);
+    return void 0;
+  }
+  try {
+    if (!answeredBy) {
+      const again = await fetchCliPackument(opts.fetchImpl ?? fetch, DOCTOR_TIMEOUT_MS, env);
+      answeredBy = again?.registry;
+      answeredLatest = again?.latest;
+    }
+    if (!answeredBy || !answeredLatest || compareVersions2(answeredLatest, running) <= 0) {
+      if (answeredBy && answeredLatest) {
+        writeUpdateCache(cachePath, { ...cache, running, latest: answeredLatest, runningPublishedAt, checkedAt: new Date(now).toISOString() });
+      }
+      return void 0;
+    }
+    const installFrom = answeredBy;
+    const target = answeredLatest;
+    io.error(`${stale} \u2014 updating to ${target}\u2026`);
+    const installed = await runner2.install(installFrom, target);
+    if (!installed.ok) {
+      io.error(`  update failed (${installed.detail ?? "unknown error"}) via ${installFrom} \u2014 continuing on v${running}`);
+      return { ...base, action: "failed", detail: installed.detail };
+    }
+    const after = runner2.installedVersion();
+    if (!after || compareVersions2(after, running) <= 0) {
+      io.error(`  npm reported success but v${running} is still installed \u2014 continuing without re-running`);
+      return { ...base, action: "failed", detail: "version did not change" };
+    }
+    writeUpdateCache(cachePath, {
+      running: after,
+      latest: target,
+      checkedAt: new Date(now).toISOString(),
+      ...cache.snoozedUntil ? { snoozedUntil: cache.snoozedUntil } : {}
+    });
+    io.error(`  installed ${after} \u2014 re-running: himi ${argv.join(" ")}`);
+    const exitCode = runner2.reexec(argv);
+    if (exitCode === void 0) {
+      io.error(`  could not locate the new install to re-run \u2014 continuing on v${running}`);
+      return { ...base, action: "failed", detail: "new entry not found" };
+    }
+    return { ...base, latest: after, action: "updated", exitCode };
+  } finally {
+    releaseLock();
+  }
+}
 function helpJson() {
   return {
     cli: "himi",
@@ -56587,11 +56976,16 @@ async function producedWidgetFamilies(dir) {
   }
   return { families, source: "dist/bundles" };
 }
-async function run(argv, io = defaultIO) {
+async function run(argv, io = defaultIO, deps = {}) {
   const { _: pos, flags } = parseFlags(argv);
   const flagErrors = switchFlagErrors(argv);
   const command = pos[0];
-  const print = (o) => io.log(JSON.stringify(o, null, 2));
+  let updateNotice;
+  const print = (o) => io.log(JSON.stringify(
+    updateNotice && o && typeof o === "object" && !Array.isArray(o) ? { ...o, upgrade: upgradeEnvelope(updateNotice) } : o,
+    null,
+    2
+  ));
   if (flags.version === true || command === "version" || pos.includes("-v")) {
     const v = cliVersion();
     io.log(flags.json ? JSON.stringify({ himi: v }, null, 2) : `himi v${v}`);
@@ -56609,6 +57003,11 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
     io.error(JSON.stringify({ ok: false, error: "invalid_flag_value", problems: flagErrors, hint: "run `himi help` for the flag grammar." }));
     return 2;
   }
+  if (flags["skip-version-check"] !== true) {
+    const update = await maybeSelfUpdate(argv, io, { command, ...deps.selfUpdate });
+    if (update?.exitCode !== void 0) return update.exitCode;
+    if (update) updateNotice = update;
+  }
   const contextualDefaultTarget = defaultTargetForCommand(command, contentDir(flags));
   const targetName = () => resolveTargetName({ target: str5(flags.target), defaultTarget: contextualDefaultTarget });
   const client2 = () => new ServeCliClient(
@@ -60967,6 +61366,45 @@ ${label2}`);
         });
         return 0;
       }
+      case "upgrade": {
+        const up = deps.selfUpdate ?? {};
+        const runner2 = up.runner ?? defaultUpdateRunner;
+        const env = up.env ?? process.env;
+        const before = cliVersion();
+        const lockFile = `${up.cachePath ?? updateCachePath(env)}.lock`;
+        const releaseLock = up.acquireLock ? up.acquireLock() : acquireUpdateLock(up.cachePath ?? updateCachePath(env), Date.now());
+        if (!releaseLock) {
+          const hint = `another himi process is updating right now \u2014 try again in a minute. If no himi is running, delete ${lockFile} (and ${lockFile}.break if present)`;
+          if (flags.json) print({ ok: false, error: "update_in_progress", running: before, lock: lockFile, hint });
+          else io.error(hint);
+          return 1;
+        }
+        try {
+          const answered = await fetchCliPackument(up.fetchImpl ?? fetch, DOCTOR_TIMEOUT_MS, env);
+          const registry = answered?.registry ?? trustedConfiguredRegistry(env) ?? PUBLIC_NPM_REGISTRY;
+          if (answered?.latest && compareVersions2(answered.latest, before) <= 0) {
+            if (flags.json) print({ ok: true, running: before, installed: before, changed: false, registry, latest: answered.latest });
+            else io.log(`himi ${before} (unchanged \u2014 ${registry} has nothing newer; its latest is ${answered.latest})`);
+            return 0;
+          }
+          const version = answered?.latest ?? "latest";
+          io.error(`upgrading ${CLI_PACKAGE} (running v${before}) to ${version} from ${registry}\u2026`);
+          const installed = await runner2.install(registry, version);
+          if (!installed.ok) {
+            const detail = installed.detail ?? "unknown error";
+            if (flags.json) print({ ok: false, error: "upgrade_failed", running: before, registry, detail });
+            else io.error(`upgrade failed (${detail}) via ${registry}`);
+            return 1;
+          }
+          const after = runner2.installedVersion();
+          const moved = !!after && compareVersions2(after, before) > 0;
+          if (flags.json) print({ ok: true, running: before, installed: after, changed: moved, registry });
+          else io.log(moved ? `himi ${before} \u2192 ${after}` : `himi ${before} (unchanged \u2014 the registry has nothing newer to install)`);
+          return 0;
+        } finally {
+          releaseLock();
+        }
+      }
       case "doctor": {
         const target = targetName();
         const timeoutMs = Number(str5(flags.timeout)) > 0 ? Number(str5(flags.timeout)) : DOCTOR_TIMEOUT_MS;
@@ -61419,36 +61857,50 @@ if (isMain) {
   });
 }
 export {
+  CLI_PACKAGE,
   ConfigLoadError,
   GIT_FLAG_STORE_HALF_WRITE_NOTE,
   GIT_FLAG_STORE_NOTE,
   PLACEHOLDER_CLIENT_ID,
   PLACEHOLDER_SITE_URL,
   PREVIEW_TOKEN_NOTE,
+  PUBLIC_NPM_REGISTRY,
   PUBLIC_WIX_API_BASE,
+  WIX_NPM_MIRROR,
+  acquireUpdateLock,
+  ageInDays,
   autoClaimSlug,
   buildDoctorReport,
   compareVersions2 as compareVersions,
+  createUpdateRunner,
   credentialKind,
   credentialSwapNotice,
+  decideUpdateAction,
   decodeControlTokenClaims,
   defaultTargetForCommand,
+  defaultUpdateRunner,
   diagnoseBody,
   doctorVersionReport,
   executableOnPath,
+  fetchCliPackument,
   foreignPlaneError,
   formatSdkVersionLine,
+  formatStaleLine,
+  globalPrefixWritable,
   humanDuration,
   inspectControlToken,
   isHimalayaMonorepoCheckout,
   isLoopbackBase,
   isPublicTarget,
+  isTrustedRegistry,
   loginModeMark,
   loginModeReport,
   loopbackTargetWarning,
   materializeForPreview,
+  maybeSelfUpdate,
   nativeConfigAdvisories,
   nativeConfigTokenNotice,
+  npmInstallArgs,
   ownerPlaneHint,
   ownerPlaneIsDark,
   parseFlags,
@@ -61468,6 +61920,7 @@ export {
   probeControlToken,
   probeReachable,
   pushAuthHint,
+  readUpdateCache,
   renderDataSource,
   renderDeviceWidths,
   resolveAppSlug,
@@ -61478,12 +61931,18 @@ export {
   serveUnreachableHint,
   servesAll,
   shellShaDivergenceWarnings,
+  staleUpdateLockFile,
   switchFlagErrors,
   templatePreviewAuthError,
   tokenCoversApp,
+  trustedConfiguredRegistry,
+  updateCachePath,
+  updateCheckSuppression,
+  upgradeEnvelope,
   uxHandoverHint,
   uxHandoverNote,
   uxHandoverOverride,
   wixPlayerTestflightTarget,
-  writePngFile
+  writePngFile,
+  writeUpdateCache
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.973.0",
+  "version": "0.975.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": "555534516afcd5d59dd7e53839ae5548e01ea913dfdd2fd025ff48ec"
+  "falconPackageHash": "ac291974b49df3a7c0844b15d82c21cb6d2af2409ad4d2b53aa35b5b"
 }