@camstack/system 1.2.81 → 1.2.82

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM$1, r as __exportAll, t as __commonJSMin$1 } from "./chunk-CNf5ZN-e.mjs";
-import { $ as objectInputDeclaresAddonId, At as emitDownForOwnedCaps, B as isArrayOutputSchema, Bt as scopeKey, Ct as ReadinessRegistry, Dt as asNumber, Et as asJsonObject$1, G as kebabToCamel, H as isObjectInput, Ht as EventCategory$1, It as parseJsonObject, K as lifecycleJobSchema, Lt as parseJsonUnknown$1, Mt as expandCapMethods, Ot as asString$1, R as extractNestedAddonId, Rt as readinessKey, V as isCollectionArrayMethod, W as isVoidInput, X as looseSchema, Y as logLevelAtMost, _t as DATAPLANE_SECRET_HEADER$1, d as METHOD_ACCESS_MAP, f as RUNTIME_DEFAULTS, ht as errMsg$1, it as scopesAllowDeviceCap, kt as createEvent, nt as procedureAuthKey, rt as scopesAllowAddon, t as ALL_CAPABILITY_DEFINITIONS, vt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, wt as ReadinessTimeoutError, y as addonSettingsCapability, yt as DEVICE_STATUS_METHOD, zt as resolveCapMount } from "./dist-DZOZtn-0.mjs";
+import { $ as objectInputDeclaresAddonId, At as emitDownForOwnedCaps, B as isArrayOutputSchema, Bt as scopeKey, Ct as ReadinessRegistry, Dt as asNumber, Et as asJsonObject$1, G as kebabToCamel, H as isObjectInput, Ht as EventCategory$1, It as parseJsonObject, K as lifecycleJobSchema, Lt as parseJsonUnknown$1, Mt as expandCapMethods, Ot as asString$1, R as extractNestedAddonId, Rt as readinessKey, V as isCollectionArrayMethod, W as isVoidInput, X as looseSchema, Y as logLevelAtMost, _t as DATAPLANE_SECRET_HEADER$1, d as METHOD_ACCESS_MAP, f as RUNTIME_DEFAULTS, ht as errMsg$1, it as scopesAllowDeviceCap, kt as createEvent, nt as procedureAuthKey, rt as scopesAllowAddon, t as ALL_CAPABILITY_DEFINITIONS, vt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, wt as ReadinessTimeoutError, y as addonSettingsCapability, yt as DEVICE_STATUS_METHOD, zt as resolveCapMount } from "./dist-DpL4mUA4.mjs";
 import { AlertCenterAddon } from "./builtins/alerts/alerts.addon.mjs";
 import "./builtins/alerts/index.mjs";
 import { t as formatLogLine } from "./formatter-B7qW8bPJ.mjs";
@@ -3064,6 +3064,74 @@ function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
+* How far up from the entry file to look for the owning `package.json`
+* (`<pkg>/dist/chunks/x.js` → 3 hops). Bounded so a loose module outside a
+* package can't walk to the filesystem root.
+*/
+var PACKAGE_JSON_LOOKUP_DEPTH = 4;
+/** Version from the `package.json` that owns `entryPath`, or null. */
+function readOwningPackageVersion(entryPath) {
+	let dir = path$39.dirname(entryPath);
+	for (let hop = 0; hop < PACKAGE_JSON_LOOKUP_DEPTH; hop++) {
+		try {
+			const version = asJsonObject$1(parseJsonUnknown$1(fs$17.readFileSync(path$39.join(dir, "package.json"), "utf-8")))?.["version"];
+			if (typeof version === "string" && version.length > 0) return version;
+		} catch {}
+		const parent = path$39.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* Cache-bust key for an addon entry module: the `?v=` query that makes each
+* on-disk REVISION of `entryPath` a distinct ESM module URL. Returns null when
+* the entry cannot be stat'd — the caller then does a plain import.
+*
+* The key is `<version>-<content hash>`, and BOTH halves are load-bearing
+* because each on its own has a documented way of not changing across a real
+* redeploy:
+*
+*  - **mtime does not change.** `npm pack` normalises every file's mtime in the
+*    tarball to 499162500000 (1985-10-26); every install path here extracts
+*    such a tarball, so the entry file of v1.0.0 and of v1.0.99 carry the same
+*    mtime. An mtime-only key (what this used to be) is a NO-OP — it produced
+*    one byte-identical URL for every version of every addon ever installed.
+*  - **the version does not change** on a `camstack deploy` of an unbumped
+*    workspace package — the whole dev loop.
+*  - **the entry hash does not change** when a multi-chunk dist alters a chunk
+*    the entry only re-exports; the version bump covers that case.
+*
+* Hashing the entry costs one extra read of an already-read file (~1.5 MB for
+* the largest addon bundle, single-digit ms) once per addon load. Cheap against
+* what a stale key costs: hub-main keeps validating `addons.custom` input
+* against the OLD `customActions` schema — silently STRIPPING newly-added
+* fields — and, worse, Node caches a load that THREW as a rejected module and
+* replays that rejection for every later retry at the same URL. On 2026-08-12
+* `@camstack/addon-export-hap` burned 126 identical failed load retries over
+* 10.5h, none of which could have succeeded: the fixed bytes on disk were never
+* read.
+*
+* Never throws: an unreadable version degrades to the mtime, an unreadable body
+* to mtime+size.
+*/
+function addonModuleCacheKey(entryPath) {
+	let stat;
+	try {
+		stat = fs$17.statSync(entryPath);
+	} catch {
+		return null;
+	}
+	const version = readOwningPackageVersion(entryPath) ?? `m${stat.mtimeMs}`;
+	let content;
+	try {
+		content = createHash("sha1").update(fs$17.readFileSync(entryPath)).digest("hex").slice(0, 16);
+	} catch {
+		content = `m${stat.mtimeMs}s${stat.size}`;
+	}
+	return `${version}-${content}`;
+}
+/**
 * Import an addon entry module FRESH on every load, defeating Node's
 * per-URL ESM module cache.
 *
@@ -3072,23 +3140,15 @@ function isRecord$1(value) {
 * redeploy returns the STALE previously-cached module. The addon RUNNER child
 * is a fresh process so it reloads correctly — but hub-main also imports the
 * module to read its static catalog (`customActions` Zod schemas, addon class)
-* for the `addons.custom` "validate on the way in" guard. Without cache-busting
-* that guard keeps validating against the OLD schema, silently STRIPPING any
-* newly-added custom-action input field until a full hub restart (observed:
-* benchmark `deviceKey`/multi-device fan-out fields dropped after redeploy).
+* for the `addons.custom` "validate on the way in" guard.
 *
-* Appending a `?v=<mtimeMs>` query makes each on-disk version a distinct module
-* URL, so a redeploy (new mtime) loads the fresh module. Falls back to a plain
-* import if the file can't be stat'd.
+* The distinguishing key is {@link addonModuleCacheKey}; a plain import is the
+* fallback when the entry cannot be stat'd.
 */
 async function importAddonModuleFresh(entryPath) {
-	let bust;
-	try {
-		bust = fs$17.statSync(entryPath).mtimeMs;
-	} catch {
-		return import(entryPath);
-	}
-	return import(`${pathToFileURL(entryPath).href}?v=${bust}`);
+	const bust = addonModuleCacheKey(entryPath);
+	if (bust === null) return import(entryPath);
+	return import(`${pathToFileURL(entryPath).href}?v=${encodeURIComponent(bust)}`);
 }
 /**
 * Package.json manifest boundary: the `camstack` field is authored by third-party
@@ -4510,6 +4570,79 @@ var AddonInstaller = class AddonInstaller {
 			force: true
 		}).catch(() => void 0)));
 	}
+	/**
+	* Make `pkgDir` (an addon tree that has NOT been swapped in yet) runnable:
+	* strip the host-provided deps from its manifest, then `npm install` whatever
+	* survives.
+	*
+	* ONE implementation for every path that materialises an addon tree —
+	* `installFromTgz` (deploy/upload) and `applyUpdateFromStaged` (OTA). The OTA
+	* path did not have it, and that is a whole outage class: an addon declaring
+	* `camstack.runtimeDependencies` was broken by its FIRST OTA update, its dist
+	* landing without `node_modules`. Every load then threw `Cannot find module`
+	* and the retry loop replayed it — `@camstack/addon-export-hap`, 126 failed
+	* load retries over 10.5h on 2026-08-12; `@camstack/addon-remote-storage`
+	* (`@aws-sdk/*`, `webdav`) is the same landmine.
+	*
+	* **Strip.** `@camstack/*` are host-provided system packages that resolve via
+	* the host's node_modules (Node walks up from the installed addon dir). Left
+	* in, this `npm install` pulls the LAST PUBLISHED `@camstack/types` (etc.)
+	* into the addon's OWN node_modules where it SHADOWS the host's fresh copy —
+	* local additions to a system package silently never reach the deployed
+	* addon. Addon dists are self-contained besides, so `stripBundledDeps` keeps
+	* only what the manifest explicitly declares in
+	* `camstack.runtimeDependencies` (see fs-utils / ADR-0027). Nothing left to
+	* install is the COMMON case: skip npm rather than pay an empty round-trip.
+	*
+	* **Failure is FATAL.** This used to warn-and-continue on the tgz path ("the
+	* addon may still load if imports are lazy") — live cost: a host with no npm
+	* (packaged Electron Mac agent) installed every runtime-dep addon WITHOUT its
+	* node_modules for DAYS; each reported "running" while its entry failed at
+	* import (`Cannot find module 'sharp'`), the detection group ran 1/3 members,
+	* and the node silently dropped out of the balancer. Throwing here is what
+	* keeps the PREVIOUS install intact: every caller builds the tree before it
+	* swaps, so an abort simply means the swap never happens.
+	*
+	* A missing/unreadable manifest is NOT fatal — it is logged and skipped. The
+	* callers validate the tree themselves, and a tree with no readable
+	* package.json has no declared deps to install (the loader will skip the
+	* package entirely).
+	*/
+	async installRuntimeDependencies(pkgDir, packageName) {
+		const pkgJsonPath = path$39.join(pkgDir, "package.json");
+		const pkgView = readPackageJson(pkgJsonPath);
+		if (pkgView == null) {
+			this.logger.error(`${packageName} — no readable package.json in the prepared tree; runtime dependencies NOT installed`, { meta: { pkgJsonPath } });
+			return;
+		}
+		const strippedManifest = stripBundledDeps(pkgView.raw);
+		await fs$17.promises.writeFile(pkgJsonPath, JSON.stringify(strippedManifest, null, 2));
+		const deps = asJsonObject$1(strippedManifest["dependencies"]);
+		const depNames = deps ? Object.keys(deps) : [];
+		if (depNames.length === 0) return;
+		this.logger.info(`${packageName} — installing runtime dependencies`, { meta: {
+			stagingDir: pkgDir,
+			dependencies: depNames
+		} });
+		try {
+			await runNpm([
+				"install",
+				"--omit=dev",
+				"--omit=peer",
+				"--no-audit",
+				"--no-fund",
+				"--no-package-lock",
+				...this.registry ? ["--registry", this.registry] : []
+			], this.npmRunOptions(pkgDir, 24e4));
+		} catch (err) {
+			this.logger.error(`${packageName} — runtime dependency install FAILED; update ABORTED (a swapped-in copy would fail every load with "Cannot find module")`, { meta: {
+				pkgDir,
+				dependencies: depNames,
+				error: errMsg$1(err)
+			} });
+			throw new Error(`${packageName} — runtime dependency install failed: ${errMsg$1(err)}`, { cause: err });
+		}
+	}
 	/** Install addon from a tgz file (uploaded or downloaded) */
 	async installFromTgz(tgzPath) {
 		const stagingRoot = path$39.join(this.addonsDir, ".staging");
@@ -4533,25 +4666,7 @@ var AddonInstaller = class AddonInstaller {
 			if (!pkgView) throw new Error(`Invalid package.json at ${pkgJsonPath}`);
 			if (!pkgView.camstackAddons) throw new Error(`Package ${pkgView.name} has no camstack.addons manifest`);
 			const targetDir = path$39.join(this.addonsDir, pkgView.name);
-			const strippedManifest = stripBundledDeps(pkgView.raw);
-			await fs$17.promises.writeFile(pkgJsonPath, JSON.stringify(strippedManifest, null, 2));
-			const strippedRuntimeDeps = strippedManifest["dependencies"];
-			if (strippedRuntimeDeps != null && typeof strippedRuntimeDeps === "object" && Object.keys(strippedRuntimeDeps).length > 0) {
-				this.logger.info(`${pkgView.name} — installing runtime dependencies`, { meta: { stagingDir: pkgDir } });
-				try {
-					await runNpm([
-						"install",
-						"--omit=dev",
-						"--omit=peer",
-						"--no-audit",
-						"--no-fund",
-						"--no-package-lock",
-						...this.registry ? ["--registry", this.registry] : []
-					], this.npmRunOptions(pkgDir, 24e4));
-				} catch (err) {
-					throw new Error(`${pkgView.name} — runtime dependency install failed: ${errMsg$1(err)}`, { cause: err });
-				}
-			}
+			await this.installRuntimeDependencies(pkgDir, pkgView.name);
 			try {
 				await installManifestNativeDeps(pkgDir, pkgView.raw, this.logger, this.registry, this.npmCacheDir);
 			} catch (nativeErr) {
@@ -4663,18 +4778,32 @@ var AddonInstaller = class AddonInstaller {
 	* replaces step 2 ("install new version") with an atomic directory
 	* move of `stagedPath` into `addonDir`.
 	*
+	* "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
+	* tree is the raw unpacked tarball, so the addon's own
+	* `camstack.runtimeDependencies` still have to be installed into it, exactly
+	* as `installFromTgz` does. Skipping that is what broke every runtime-dep
+	* addon on its first OTA update — see {@link installRuntimeDependencies}.
+	*
+	* Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
+	* the live install is only then backed up and replaced. So the addon keeps
+	* serving the old version for the whole (minutes-long) npm install, the swap
+	* window stays two renames wide, and a dependency failure aborts with the
+	* previous version untouched instead of leaving a dependency-less copy live.
+	*
 	* On cross-device move (EXDEV) falls back to a recursive copy followed
 	* by removal of the staged directory. On any swap failure the backup is
 	* restored and the error is rethrown — identical recovery to `applyUpdate`.
 	*
-	* Throws if the package is not tracked in the manifest or if `addonDir`
-	* is missing (same preconditions as `applyUpdate`).
+	* Throws if the package is not tracked in the manifest, if `addonDir`
+	* is missing (same preconditions as `applyUpdate`), or if the runtime-dep
+	* install fails.
 	*/
 	async applyUpdateFromStaged(packageName, version, stagedPath) {
 		const current = this.manifest.get(packageName);
 		if (current == null) throw new Error(`Cannot update ${packageName}: not currently tracked in manifest`);
 		const addonDir = path$39.join(this.addonsDir, packageName);
 		if (!fs$17.existsSync(addonDir)) throw new Error(`Cannot update ${packageName}: install dir ${addonDir} missing`);
+		await this.installRuntimeDependencies(stagedPath, packageName);
 		const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 		const backupRoot = path$39.join(this.addonsDir, ".backups", packageName);
 		ensureDir(backupRoot);

package/dist/kernel/addon-installer.d.ts

@@ -302,6 +302,45 @@ export declare class AddonInstaller {
     private sweepStagingResidue;
     /** Best-effort removal of leftover `.evicting/*` dirs from earlier deploys. */
     private sweepGraveyard;
+    /**
+     * Make `pkgDir` (an addon tree that has NOT been swapped in yet) runnable:
+     * strip the host-provided deps from its manifest, then `npm install` whatever
+     * survives.
+     *
+     * ONE implementation for every path that materialises an addon tree —
+     * `installFromTgz` (deploy/upload) and `applyUpdateFromStaged` (OTA). The OTA
+     * path did not have it, and that is a whole outage class: an addon declaring
+     * `camstack.runtimeDependencies` was broken by its FIRST OTA update, its dist
+     * landing without `node_modules`. Every load then threw `Cannot find module`
+     * and the retry loop replayed it — `@camstack/addon-export-hap`, 126 failed
+     * load retries over 10.5h on 2026-08-12; `@camstack/addon-remote-storage`
+     * (`@aws-sdk/*`, `webdav`) is the same landmine.
+     *
+     * **Strip.** `@camstack/*` are host-provided system packages that resolve via
+     * the host's node_modules (Node walks up from the installed addon dir). Left
+     * in, this `npm install` pulls the LAST PUBLISHED `@camstack/types` (etc.)
+     * into the addon's OWN node_modules where it SHADOWS the host's fresh copy —
+     * local additions to a system package silently never reach the deployed
+     * addon. Addon dists are self-contained besides, so `stripBundledDeps` keeps
+     * only what the manifest explicitly declares in
+     * `camstack.runtimeDependencies` (see fs-utils / ADR-0027). Nothing left to
+     * install is the COMMON case: skip npm rather than pay an empty round-trip.
+     *
+     * **Failure is FATAL.** This used to warn-and-continue on the tgz path ("the
+     * addon may still load if imports are lazy") — live cost: a host with no npm
+     * (packaged Electron Mac agent) installed every runtime-dep addon WITHOUT its
+     * node_modules for DAYS; each reported "running" while its entry failed at
+     * import (`Cannot find module 'sharp'`), the detection group ran 1/3 members,
+     * and the node silently dropped out of the balancer. Throwing here is what
+     * keeps the PREVIOUS install intact: every caller builds the tree before it
+     * swaps, so an abort simply means the swap never happens.
+     *
+     * A missing/unreadable manifest is NOT fatal — it is logged and skipped. The
+     * callers validate the tree themselves, and a tree with no readable
+     * package.json has no declared deps to install (the loader will skip the
+     * package entirely).
+     */
+    private installRuntimeDependencies;
     /** Install addon from a tgz file (uploaded or downloaded) */
     installFromTgz(tgzPath: string): Promise<{
         name: string;
@@ -340,12 +379,25 @@ export declare class AddonInstaller {
      * replaces step 2 ("install new version") with an atomic directory
      * move of `stagedPath` into `addonDir`.
      *
+     * "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
+     * tree is the raw unpacked tarball, so the addon's own
+     * `camstack.runtimeDependencies` still have to be installed into it, exactly
+     * as `installFromTgz` does. Skipping that is what broke every runtime-dep
+     * addon on its first OTA update — see {@link installRuntimeDependencies}.
+     *
+     * Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
+     * the live install is only then backed up and replaced. So the addon keeps
+     * serving the old version for the whole (minutes-long) npm install, the swap
+     * window stays two renames wide, and a dependency failure aborts with the
+     * previous version untouched instead of leaving a dependency-less copy live.
+     *
      * On cross-device move (EXDEV) falls back to a recursive copy followed
      * by removal of the staged directory. On any swap failure the backup is
      * restored and the error is rethrown — identical recovery to `applyUpdate`.
      *
-     * Throws if the package is not tracked in the manifest or if `addonDir`
-     * is missing (same preconditions as `applyUpdate`).
+     * Throws if the package is not tracked in the manifest, if `addonDir`
+     * is missing (same preconditions as `applyUpdate`), or if the runtime-dep
+     * install fails.
      */
     applyUpdateFromStaged(packageName: string, version: string, stagedPath: string): Promise<{
         name: string;

package/dist/kernel/addon-loader.d.ts

@@ -1,4 +1,37 @@
 import { AddonDeclaration, ICamstackAddon, IScopedLogger, StorageLocationDeclaration } from '@camstack/types';
+/**
+ * Cache-bust key for an addon entry module: the `?v=` query that makes each
+ * on-disk REVISION of `entryPath` a distinct ESM module URL. Returns null when
+ * the entry cannot be stat'd — the caller then does a plain import.
+ *
+ * The key is `<version>-<content hash>`, and BOTH halves are load-bearing
+ * because each on its own has a documented way of not changing across a real
+ * redeploy:
+ *
+ *  - **mtime does not change.** `npm pack` normalises every file's mtime in the
+ *    tarball to 499162500000 (1985-10-26); every install path here extracts
+ *    such a tarball, so the entry file of v1.0.0 and of v1.0.99 carry the same
+ *    mtime. An mtime-only key (what this used to be) is a NO-OP — it produced
+ *    one byte-identical URL for every version of every addon ever installed.
+ *  - **the version does not change** on a `camstack deploy` of an unbumped
+ *    workspace package — the whole dev loop.
+ *  - **the entry hash does not change** when a multi-chunk dist alters a chunk
+ *    the entry only re-exports; the version bump covers that case.
+ *
+ * Hashing the entry costs one extra read of an already-read file (~1.5 MB for
+ * the largest addon bundle, single-digit ms) once per addon load. Cheap against
+ * what a stale key costs: hub-main keeps validating `addons.custom` input
+ * against the OLD `customActions` schema — silently STRIPPING newly-added
+ * fields — and, worse, Node caches a load that THREW as a rejected module and
+ * replays that rejection for every later retry at the same URL. On 2026-08-12
+ * `@camstack/addon-export-hap` burned 126 identical failed load retries over
+ * 10.5h, none of which could have succeeded: the fixed bytes on disk were never
+ * read.
+ *
+ * Never throws: an unreadable version degrades to the mtime, an unreadable body
+ * to mtime+size.
+ */
+export declare function addonModuleCacheKey(entryPath: string): string | null;
 export interface RegisteredAddon {
     readonly declaration: AddonDeclaration;
     readonly packageName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.81",
+  "version": "1.2.82",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",