@caelo-cms/shared 0.10.44 → 0.10.46

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from "./plugin-preview.js";
 export * from "./preview-compose.js";
 export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
+export * from "./provisioning-command.js";
 export * from "./redirect-target.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
@@ -52,5 +53,5 @@ export * from "./theme-render.js";
 export * from "./themes.js";
 export * from "./themes-errors.js";
 export * from "./url.js";
-export { CAELO_VERSION, CALEO_VERSION, type CaeloVersion, parseVersion } from "./version.js";
+export { CAELO_VERSION, CALEO_VERSION, type CaeloVersion, isNewerVersion, parseVersion, } from "./version.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,UAAU,EACV,aAAa,EACb,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,UAAU,EACV,aAAa,EACb,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,YAAY,EACjB,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -27,6 +27,7 @@ export * from "./plugin-preview.js";
 export * from "./preview-compose.js";
 export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
+export * from "./provisioning-command.js";
 export * from "./redirect-target.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
@@ -53,5 +54,5 @@ export * from "./theme-render.js";
 export * from "./themes.js";
 export * from "./themes-errors.js";
 export * from "./url.js";
-export { CAELO_VERSION, CALEO_VERSION, parseVersion } from "./version.js";
+export { CAELO_VERSION, CALEO_VERSION, isNewerVersion, parseVersion, } from "./version.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAKL,UAAU,EACV,aAAa,EACb,MAAM,GAGP,MAAM,aAAa,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAqB,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAKL,UAAU,EACV,aAAa,EACb,MAAM,GAGP,MAAM,aAAa,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,aAAa,EACb,aAAa,EAEb,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/provisioning-command.d.ts

@@ -0,0 +1,40 @@
+/** npm name of the provisioning CLI. */
+export declare const PROVISIONING_PACKAGE = "@caelo-cms/provisioning";
+/**
+ * `bunx @caelo-cms/provisioning@<version> <args>`.
+ *
+ * @param version an exact release (`0.10.44`, a leading `v` is dropped);
+ *   throws on anything that is not a version, so a tag like `latest` can
+ *   never slip into a printed command.
+ * @param args the CLI arguments, already split.
+ * @example provisioningCommand("0.10.44", ["status"])
+ *   // → "bunx @caelo-cms/provisioning@0.10.44 status"
+ */
+export declare function provisioningCommand(version: string, args?: readonly string[]): string;
+/**
+ * The upgrade command for one install, pinned twice: the CLI runs as the
+ * target release (its upgrade logic matches the release it installs) and
+ * `--version` makes it roll exactly that release, even if a newer one ships
+ * before the operator runs it (without the flag, `upgrade` rolls the
+ * registry's `latest` tag).
+ *
+ * @param args.version the release to install.
+ * @param args.install the install's domain (or install id); `upgrade`
+ *   matches either against `~/.caelo-<id>/install.json`.
+ * @example provisioningUpgradeCommand({ version: "0.10.44", install: "example.com" })
+ *   // → "bunx @caelo-cms/provisioning@0.10.44 upgrade --version 0.10.44 --install example.com"
+ */
+export declare function provisioningUpgradeCommand(args: {
+    version: string;
+    install: string;
+}): string;
+/**
+ * The `--install` value for the install whose public site is `siteUrl`
+ * (the admin's `CAELO_SITE_URL`, which the stacks set to
+ * `https://<domain>` — the same domain `install.json` records).
+ *
+ * @returns the lower-cased hostname, or null when `siteUrl` is not a URL
+ *   or its host is not a plain domain (an IP literal with a port, say).
+ */
+export declare function installHintFromSiteUrl(siteUrl: string): string | null;
+//# sourceMappingURL=provisioning-command.d.ts.map

package/dist/provisioning-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning-command.d.ts","sourceRoot":"","sources":["../src/provisioning-command.ts"],"names":[],"mappings":"AAiBA,wCAAwC;AACxC,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AAS9D;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAGzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAM7F;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE"}

package/dist/provisioning-command.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The `bunx @caelo-cms/provisioning …` commands Caelo prints — in the CLI's
+ * own next-step hints, `status`, and the admin's Settings → Updates page
+ * (issue #696 Phase 0).
+ *
+ * Every command names an exact package version. Without one, `bunx` reuses
+ * whatever copy of the CLI it cached first and never looks again, so an
+ * operator who installed months ago would upgrade with months-old upgrade
+ * logic (the same trap #552 fixed for the MCP shim). The version is always
+ * one the caller knows for certain: the running CLI's own, or the release
+ * the release check reported — never "whatever is newest".
+ */
+import { parseVersion } from "./version.js";
+/** npm name of the provisioning CLI. */
+export const PROVISIONING_PACKAGE = "@caelo-cms/provisioning";
+/**
+ * A hostname the `--install` flag can carry into a copy-pasted shell
+ * command: letters, digits, dots and hyphens only, so nothing in it can be
+ * read by the shell.
+ */
+const SAFE_INSTALL_HINT = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
+/**
+ * `bunx @caelo-cms/provisioning@<version> <args>`.
+ *
+ * @param version an exact release (`0.10.44`, a leading `v` is dropped);
+ *   throws on anything that is not a version, so a tag like `latest` can
+ *   never slip into a printed command.
+ * @param args the CLI arguments, already split.
+ * @example provisioningCommand("0.10.44", ["status"])
+ *   // → "bunx @caelo-cms/provisioning@0.10.44 status"
+ */
+export function provisioningCommand(version, args = []) {
+    const exact = parseVersion(version.replace(/^v/, "")).raw;
+    return [`bunx ${PROVISIONING_PACKAGE}@${exact}`, ...args].join(" ");
+}
+/**
+ * The upgrade command for one install, pinned twice: the CLI runs as the
+ * target release (its upgrade logic matches the release it installs) and
+ * `--version` makes it roll exactly that release, even if a newer one ships
+ * before the operator runs it (without the flag, `upgrade` rolls the
+ * registry's `latest` tag).
+ *
+ * @param args.version the release to install.
+ * @param args.install the install's domain (or install id); `upgrade`
+ *   matches either against `~/.caelo-<id>/install.json`.
+ * @example provisioningUpgradeCommand({ version: "0.10.44", install: "example.com" })
+ *   // → "bunx @caelo-cms/provisioning@0.10.44 upgrade --version 0.10.44 --install example.com"
+ */
+export function provisioningUpgradeCommand(args) {
+    const version = parseVersion(args.version.replace(/^v/, "")).raw;
+    if (!SAFE_INSTALL_HINT.test(args.install)) {
+        throw new Error(`not a domain or install id: ${JSON.stringify(args.install)}`);
+    }
+    return provisioningCommand(version, ["upgrade", "--version", version, "--install", args.install]);
+}
+/**
+ * The `--install` value for the install whose public site is `siteUrl`
+ * (the admin's `CAELO_SITE_URL`, which the stacks set to
+ * `https://<domain>` — the same domain `install.json` records).
+ *
+ * @returns the lower-cased hostname, or null when `siteUrl` is not a URL
+ *   or its host is not a plain domain (an IP literal with a port, say).
+ */
+export function installHintFromSiteUrl(siteUrl) {
+    let host;
+    try {
+        host = new URL(siteUrl).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+    return SAFE_INSTALL_HINT.test(host) ? host : null;
+}
+//# sourceMappingURL=provisioning-command.js.map

package/dist/provisioning-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning-command.js","sourceRoot":"","sources":["../src/provisioning-command.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,wCAAwC;AACxC,MAAM,CAAC,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,yEAAyE,CAAC;AAEpG;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,OAA0B,EAAE;IAC/E,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1D,OAAO,CAAC,QAAQ,oBAAoB,IAAI,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAA0C;IACnF,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACjE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,mBAAmB,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC"}

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.10.44";
+export declare const CAELO_VERSION = "0.10.46";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.10.44";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.10.44";
+export declare const CALEO_VERSION = "0.10.46";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —
@@ -46,4 +46,15 @@ export interface CaeloVersion {
     readonly raw: string;
 }
 export declare function parseVersion(raw?: string): CaeloVersion;
+/**
+ * True when release `latest` is newer than `current` (both SemVer
+ * `X.Y.Z[-pre]`; a leading `v` is ignored). A pre-release sorts before the
+ * same X.Y.Z stable; two pre-releases of one X.Y.Z compare as strings.
+ * Mirrors the ordering in scripts/release.ts so the "update available"
+ * notice agrees with the release pipeline. A string that is not a version
+ * is never newer.
+ *
+ * @example isNewerVersion("0.10.44", "0.10.43") // → true
+ */
+export declare function isNewerVersion(latest: string, current: string): boolean;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,YAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAsB,GAAG,YAAY,CAYtE"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,YAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAsB,GAAG,YAAY,CAYtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAkBvE"}

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.10.44";
+export const CAELO_VERSION = "0.10.46";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -46,4 +46,39 @@ export function parseVersion(raw = CAELO_VERSION) {
         raw,
     };
 }
+/**
+ * True when release `latest` is newer than `current` (both SemVer
+ * `X.Y.Z[-pre]`; a leading `v` is ignored). A pre-release sorts before the
+ * same X.Y.Z stable; two pre-releases of one X.Y.Z compare as strings.
+ * Mirrors the ordering in scripts/release.ts so the "update available"
+ * notice agrees with the release pipeline. A string that is not a version
+ * is never newer.
+ *
+ * @example isNewerVersion("0.10.44", "0.10.43") // → true
+ */
+export function isNewerVersion(latest, current) {
+    const parse = (v) => {
+        try {
+            return parseVersion(v.replace(/^v/, ""));
+        }
+        catch {
+            return null;
+        }
+    };
+    const a = parse(latest);
+    const b = parse(current);
+    if (!a || !b)
+        return false;
+    for (const k of ["major", "minor", "patch"]) {
+        if (a[k] !== b[k])
+            return a[k] > b[k];
+    }
+    if (a.preRelease && !b.preRelease)
+        return false;
+    if (!a.preRelease && b.preRelease)
+        return true;
+    if (a.preRelease && b.preRelease)
+        return a.preRelease > b.preRelease;
+    return false;
+}
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAgB3C,MAAM,UAAU,YAAY,CAAC,MAAc,aAAa;IACtD,MAAM,CAAC,GAAG,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI;QACxB,GAAG;KACJ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAgB3C,MAAM,UAAU,YAAY,CAAC,MAAc,aAAa;IACtD,MAAM,CAAC,GAAG,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI;QACxB,GAAG;KACJ,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,OAAe;IAC5D,MAAM,KAAK,GAAG,CAAC,CAAS,EAAuB,EAAE;QAC/C,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IACF,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAU,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IACrE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.10.44",
+  "version": "0.10.46",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/index.ts

@@ -39,6 +39,7 @@ export * from "./plugin-preview.js";
 export * from "./preview-compose.js";
 export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
+export * from "./provisioning-command.js";
 export * from "./redirect-target.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
@@ -65,4 +66,10 @@ export * from "./theme-render.js";
 export * from "./themes.js";
 export * from "./themes-errors.js";
 export * from "./url.js";
-export { CAELO_VERSION, CALEO_VERSION, type CaeloVersion, parseVersion } from "./version.js";
+export {
+  CAELO_VERSION,
+  CALEO_VERSION,
+  type CaeloVersion,
+  isNewerVersion,
+  parseVersion,
+} from "./version.js";

package/src/provisioning-command.test.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  installHintFromSiteUrl,
+  provisioningCommand,
+  provisioningUpgradeCommand,
+} from "./provisioning-command.js";
+import { isNewerVersion } from "./version.js";
+
+describe("provisioningCommand", () => {
+  it("pins the package to an exact version", () => {
+    expect(provisioningCommand("0.10.44", ["status"])).toBe(
+      "bunx @caelo-cms/provisioning@0.10.44 status",
+    );
+    expect(provisioningCommand("v0.10.44")).toBe("bunx @caelo-cms/provisioning@0.10.44");
+  });
+
+  it("refuses a tag or anything else that is not a version", () => {
+    expect(() => provisioningCommand("latest")).toThrow(/invalid Caelo version/);
+    expect(() => provisioningCommand("0.10")).toThrow(/invalid Caelo version/);
+  });
+});
+
+describe("provisioningUpgradeCommand", () => {
+  it("runs the target release's CLI, rolls exactly that release, on exactly this install", () => {
+    expect(provisioningUpgradeCommand({ version: "0.10.44", install: "example.com" })).toBe(
+      "bunx @caelo-cms/provisioning@0.10.44 upgrade --version 0.10.44 --install example.com",
+    );
+  });
+
+  it("accepts a v-prefixed tag and a pre-release", () => {
+    expect(provisioningUpgradeCommand({ version: "v0.11.0-rc.1", install: "gcp-acme" })).toBe(
+      "bunx @caelo-cms/provisioning@0.11.0-rc.1 upgrade --version 0.11.0-rc.1 --install gcp-acme",
+    );
+  });
+
+  it("refuses an install hint the shell could interpret", () => {
+    for (const install of ["example.com; rm -rf ~", "$(id)", "a b", "", "Example.com"]) {
+      expect(() => provisioningUpgradeCommand({ version: "0.10.44", install })).toThrow(
+        /not a domain/,
+      );
+    }
+  });
+});
+
+describe("installHintFromSiteUrl", () => {
+  it("names the install by its site's domain", () => {
+    expect(installHintFromSiteUrl("https://Example.com")).toBe("example.com");
+    expect(installHintFromSiteUrl("https://www.example.co.uk/")).toBe("www.example.co.uk");
+  });
+
+  it("returns null for something that is not a URL", () => {
+    expect(installHintFromSiteUrl("example.com")).toBeNull();
+    expect(installHintFromSiteUrl("")).toBeNull();
+  });
+});
+
+describe("isNewerVersion", () => {
+  it("orders by major, minor, patch", () => {
+    expect(isNewerVersion("0.10.44", "0.10.43")).toBe(true);
+    expect(isNewerVersion("0.11.0", "0.10.99")).toBe(true);
+    expect(isNewerVersion("1.0.0", "0.99.99")).toBe(true);
+    expect(isNewerVersion("0.10.43", "0.10.43")).toBe(false);
+    expect(isNewerVersion("0.10.42", "0.10.43")).toBe(false);
+  });
+
+  it("sorts a pre-release before its stable", () => {
+    expect(isNewerVersion("0.11.0-rc.1", "0.11.0")).toBe(false);
+    expect(isNewerVersion("0.11.0", "0.11.0-rc.1")).toBe(true);
+    expect(isNewerVersion("0.11.0-rc.2", "0.11.0-rc.1")).toBe(true);
+  });
+
+  it("ignores a leading v and treats a non-version as never newer", () => {
+    expect(isNewerVersion("v0.10.44", "0.10.43")).toBe(true);
+    expect(isNewerVersion("nightly", "0.10.43")).toBe(false);
+  });
+});

package/src/provisioning-command.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The `bunx @caelo-cms/provisioning …` commands Caelo prints — in the CLI's
+ * own next-step hints, `status`, and the admin's Settings → Updates page
+ * (issue #696 Phase 0).
+ *
+ * Every command names an exact package version. Without one, `bunx` reuses
+ * whatever copy of the CLI it cached first and never looks again, so an
+ * operator who installed months ago would upgrade with months-old upgrade
+ * logic (the same trap #552 fixed for the MCP shim). The version is always
+ * one the caller knows for certain: the running CLI's own, or the release
+ * the release check reported — never "whatever is newest".
+ */
+
+import { parseVersion } from "./version.js";
+
+/** npm name of the provisioning CLI. */
+export const PROVISIONING_PACKAGE = "@caelo-cms/provisioning";
+
+/**
+ * A hostname the `--install` flag can carry into a copy-pasted shell
+ * command: letters, digits, dots and hyphens only, so nothing in it can be
+ * read by the shell.
+ */
+const SAFE_INSTALL_HINT = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
+
+/**
+ * `bunx @caelo-cms/provisioning@<version> <args>`.
+ *
+ * @param version an exact release (`0.10.44`, a leading `v` is dropped);
+ *   throws on anything that is not a version, so a tag like `latest` can
+ *   never slip into a printed command.
+ * @param args the CLI arguments, already split.
+ * @example provisioningCommand("0.10.44", ["status"])
+ *   // → "bunx @caelo-cms/provisioning@0.10.44 status"
+ */
+export function provisioningCommand(version: string, args: readonly string[] = []): string {
+  const exact = parseVersion(version.replace(/^v/, "")).raw;
+  return [`bunx ${PROVISIONING_PACKAGE}@${exact}`, ...args].join(" ");
+}
+
+/**
+ * The upgrade command for one install, pinned twice: the CLI runs as the
+ * target release (its upgrade logic matches the release it installs) and
+ * `--version` makes it roll exactly that release, even if a newer one ships
+ * before the operator runs it (without the flag, `upgrade` rolls the
+ * registry's `latest` tag).
+ *
+ * @param args.version the release to install.
+ * @param args.install the install's domain (or install id); `upgrade`
+ *   matches either against `~/.caelo-<id>/install.json`.
+ * @example provisioningUpgradeCommand({ version: "0.10.44", install: "example.com" })
+ *   // → "bunx @caelo-cms/provisioning@0.10.44 upgrade --version 0.10.44 --install example.com"
+ */
+export function provisioningUpgradeCommand(args: { version: string; install: string }): string {
+  const version = parseVersion(args.version.replace(/^v/, "")).raw;
+  if (!SAFE_INSTALL_HINT.test(args.install)) {
+    throw new Error(`not a domain or install id: ${JSON.stringify(args.install)}`);
+  }
+  return provisioningCommand(version, ["upgrade", "--version", version, "--install", args.install]);
+}
+
+/**
+ * The `--install` value for the install whose public site is `siteUrl`
+ * (the admin's `CAELO_SITE_URL`, which the stacks set to
+ * `https://<domain>` — the same domain `install.json` records).
+ *
+ * @returns the lower-cased hostname, or null when `siteUrl` is not a URL
+ *   or its host is not a plain domain (an IP literal with a port, say).
+ */
+export function installHintFromSiteUrl(siteUrl: string): string | null {
+  let host: string;
+  try {
+    host = new URL(siteUrl).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  return SAFE_INSTALL_HINT.test(host) ? host : null;
+}

package/src/version.ts

@@ -22,7 +22,7 @@
  * follow standard SemVer.
  */
 
-export const CAELO_VERSION = "0.10.44";
+export const CAELO_VERSION = "0.10.46";
 
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
@@ -64,3 +64,33 @@ export function parseVersion(raw: string = CAELO_VERSION): CaeloVersion {
     raw,
   };
 }
+
+/**
+ * True when release `latest` is newer than `current` (both SemVer
+ * `X.Y.Z[-pre]`; a leading `v` is ignored). A pre-release sorts before the
+ * same X.Y.Z stable; two pre-releases of one X.Y.Z compare as strings.
+ * Mirrors the ordering in scripts/release.ts so the "update available"
+ * notice agrees with the release pipeline. A string that is not a version
+ * is never newer.
+ *
+ * @example isNewerVersion("0.10.44", "0.10.43") // → true
+ */
+export function isNewerVersion(latest: string, current: string): boolean {
+  const parse = (v: string): CaeloVersion | null => {
+    try {
+      return parseVersion(v.replace(/^v/, ""));
+    } catch {
+      return null;
+    }
+  };
+  const a = parse(latest);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (const k of ["major", "minor", "patch"] as const) {
+    if (a[k] !== b[k]) return a[k] > b[k];
+  }
+  if (a.preRelease && !b.preRelease) return false;
+  if (!a.preRelease && b.preRelease) return true;
+  if (a.preRelease && b.preRelease) return a.preRelease > b.preRelease;
+  return false;
+}