@camstack/addon-cloudflare 1.0.2 → 1.0.4

package/dist/{dist-FQAxmoZY.js → dist-BaLJK4dE.js}

@@ -5130,14 +5130,15 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["DeviceSleeping"] = "device.sleeping";
 	EventCategory["RetentionCleanup"] = "retention.cleanup";
 	/**
-	* Progress snapshot emitted by `BulkUpdateCoordinator` on every state
-	* transition (item status change, phase change, completion, cancel).
-	* Payload is `BulkUpdateState`. Admin UI subscribes via `useLiveEvent`
-	* to drive the sticky `BulkUpdateBanner` and per-row `AddonRowBadge`.
-	*
-	* Spec: docs/superpowers/specs/2026-05-21-addons-bulk-update-progress-design.md
+	* Legacy bulk-update progress snapshot (payload `BulkUpdateState`). No longer
+	* emitted — F3 removed the coordinator that produced it; "Update all" now runs
+	* as one lifecycle engine job (`AddonsJobProgress`/`AddonsJobLog`). Retained
+	* (with `BulkUpdateState`) only to avoid regenerating the event maps; removed
+	* in F4 once live bulk progress is re-implemented over the engine events.
 	*/
 	EventCategory["AddonsBulkUpdateProgress"] = "addons.bulk-update-progress";
+	EventCategory["AddonsJobProgress"] = "addons.job-progress";
+	EventCategory["AddonsJobLog"] = "addons.job-log";
 	/**
 	* A container's child visibility toggled (hidden/shown). Emitted by the
 	* `accessories` cap when a child device is hidden or revealed.
@@ -16018,6 +16019,69 @@ method(_void(), array(IntegrationWithStateSchema)), method(object({ id: string()
 	kind: "mutation",
 	auth: "admin"
 });
+var jobKindSchema = _enum([
+	"install",
+	"update",
+	"uninstall",
+	"restart"
+]);
+var taskPhaseSchema = _enum([
+	"queued",
+	"fetching",
+	"staged",
+	"validating",
+	"applying",
+	"restarting",
+	"applied",
+	"done",
+	"failed",
+	"skipped"
+]);
+var taskTargetSchema = _enum(["framework", "addon"]);
+var taskLogEntrySchema = object({
+	tsMs: number(),
+	nodeId: string(),
+	packageName: string(),
+	phase: taskPhaseSchema,
+	message: string()
+});
+var lifecycleTaskSchema = object({
+	taskId: string(),
+	nodeId: string(),
+	packageName: string(),
+	fromVersion: string().nullable(),
+	toVersion: string(),
+	target: taskTargetSchema,
+	phase: taskPhaseSchema,
+	stagedPath: string().nullable(),
+	attempts: number(),
+	steps: array(taskLogEntrySchema),
+	error: string().nullable(),
+	startedAtMs: number().nullable(),
+	finishedAtMs: number().nullable()
+});
+var lifecycleJobStateSchema = _enum([
+	"running",
+	"completed",
+	"failed",
+	"partially-failed",
+	"cancelled"
+]);
+var lifecycleJobScopeSchema = _enum([
+	"single",
+	"bulk",
+	"cluster"
+]);
+var lifecycleJobSchema = object({
+	jobId: string(),
+	kind: jobKindSchema,
+	createdAtMs: number(),
+	createdBy: string(),
+	scope: lifecycleJobScopeSchema,
+	tasks: array(lifecycleTaskSchema),
+	state: lifecycleJobStateSchema,
+	schemaVersion: literal(1)
+});
 /**
 * addons — system-scoped singleton capability for addon package
 * management (install, update, configure, restart) and per-addon log
@@ -16200,7 +16264,7 @@ var BulkUpdatePhaseSchema = _enum([
 	"restarting",
 	"finalizing"
 ]);
-var BulkUpdateStateSchema = object({
+object({
 	id: string(),
 	nodeId: string(),
 	startedAtMs: number(),
@@ -16303,20 +16367,7 @@ method(_void(), array(AddonListItemSchema).readonly()), method(object({
 }), UpdateFrameworkPackageResultSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({
-	nodeId: string(),
-	items: array(object({
-		name: string(),
-		version: string(),
-		isSystem: boolean()
-	})).readonly()
-}), object({ id: string() }), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({ id: string() }), BulkUpdateStateSchema.nullable(), { auth: "admin" }), method(object({ id: string() }), object({ cancelled: boolean() }), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({ nodeId: string().optional() }), array(BulkUpdateStateSchema).readonly(), { auth: "admin" }), method(object({ name: string() }), array(PackageVersionInfoSchema).readonly()), method(object({ addonId: string() }), RestartAddonResultSchema, {
+}), method(object({ name: string() }), array(PackageVersionInfoSchema).readonly()), method(object({ addonId: string() }), RestartAddonResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 }), method(object({ packageName: string() }), object({ success: literal(true) }), {
@@ -16338,6 +16389,24 @@ method(_void(), array(AddonListItemSchema).readonly()), method(object({
 	kind: "mutation",
 	auth: "admin"
 }), method(CustomActionInputSchema, unknown(), { kind: "mutation" }), method(object({
+	kind: _enum([
+		"install",
+		"update",
+		"uninstall",
+		"restart"
+	]),
+	targets: array(object({
+		name: string().min(1),
+		version: string().min(1)
+	})).min(1),
+	nodeIds: array(string()).optional()
+}), object({ jobId: string() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ jobId: string() }), lifecycleJobSchema.nullable(), { auth: "admin" }), method(object({ activeOnly: boolean().optional() }), array(lifecycleJobSchema), { auth: "admin" }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
 	addonId: string(),
 	level: LogLevelSchema$1.optional()
 }), LogStreamEntrySchema, { kind: "subscription" });
@@ -16378,7 +16447,7 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"addons.cancelBulkUpdate": {
+	"addons.cancelJob": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -16408,7 +16477,7 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
-	"addons.getBulkUpdateState": {
+	"addons.getJob": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -16456,19 +16525,19 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
-	"addons.listActiveBulkUpdates": {
+	"addons.listCapabilityProviders": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
-	"addons.listCapabilityProviders": {
+	"addons.listFrameworkPackages": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
-	"addons.listFrameworkPackages": {
+	"addons.listJobs": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -16552,7 +16621,7 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"addons.startBulkUpdate": {
+	"addons.startJob": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -20539,6 +20608,32 @@ Object.freeze({
 	"network-access": "ingress",
 	"smtp-provider": "email"
 });
+var frameworkSwapPackageSchema = object({
+	name: string(),
+	stagedPath: string(),
+	backupPath: string(),
+	toVersion: string(),
+	fromVersion: string().nullable()
+});
+object({
+	jobId: string(),
+	taskId: string(),
+	packages: array(frameworkSwapPackageSchema),
+	requestedAtMs: number(),
+	schemaVersion: literal(1)
+});
+object({
+	jobId: string(),
+	taskId: string(),
+	backups: array(object({
+		name: string(),
+		backupPath: string(),
+		livePath: string()
+	})),
+	appliedAtMs: number(),
+	bootAttempts: number(),
+	schemaVersion: literal(1)
+});
 //#endregion
 Object.defineProperty(exports, "BaseAddon", {
 	enumerable: true,

package/dist/{dist-gS41k7Cx.mjs → dist-COIj-4Zk.mjs}

@@ -5130,14 +5130,15 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["DeviceSleeping"] = "device.sleeping";
 	EventCategory["RetentionCleanup"] = "retention.cleanup";
 	/**
-	* Progress snapshot emitted by `BulkUpdateCoordinator` on every state
-	* transition (item status change, phase change, completion, cancel).
-	* Payload is `BulkUpdateState`. Admin UI subscribes via `useLiveEvent`
-	* to drive the sticky `BulkUpdateBanner` and per-row `AddonRowBadge`.
-	*
-	* Spec: docs/superpowers/specs/2026-05-21-addons-bulk-update-progress-design.md
+	* Legacy bulk-update progress snapshot (payload `BulkUpdateState`). No longer
+	* emitted — F3 removed the coordinator that produced it; "Update all" now runs
+	* as one lifecycle engine job (`AddonsJobProgress`/`AddonsJobLog`). Retained
+	* (with `BulkUpdateState`) only to avoid regenerating the event maps; removed
+	* in F4 once live bulk progress is re-implemented over the engine events.
 	*/
 	EventCategory["AddonsBulkUpdateProgress"] = "addons.bulk-update-progress";
+	EventCategory["AddonsJobProgress"] = "addons.job-progress";
+	EventCategory["AddonsJobLog"] = "addons.job-log";
 	/**
 	* A container's child visibility toggled (hidden/shown). Emitted by the
 	* `accessories` cap when a child device is hidden or revealed.
@@ -16018,6 +16019,69 @@ method(_void(), array(IntegrationWithStateSchema)), method(object({ id: string()
 	kind: "mutation",
 	auth: "admin"
 });
+var jobKindSchema = _enum([
+	"install",
+	"update",
+	"uninstall",
+	"restart"
+]);
+var taskPhaseSchema = _enum([
+	"queued",
+	"fetching",
+	"staged",
+	"validating",
+	"applying",
+	"restarting",
+	"applied",
+	"done",
+	"failed",
+	"skipped"
+]);
+var taskTargetSchema = _enum(["framework", "addon"]);
+var taskLogEntrySchema = object({
+	tsMs: number(),
+	nodeId: string(),
+	packageName: string(),
+	phase: taskPhaseSchema,
+	message: string()
+});
+var lifecycleTaskSchema = object({
+	taskId: string(),
+	nodeId: string(),
+	packageName: string(),
+	fromVersion: string().nullable(),
+	toVersion: string(),
+	target: taskTargetSchema,
+	phase: taskPhaseSchema,
+	stagedPath: string().nullable(),
+	attempts: number(),
+	steps: array(taskLogEntrySchema),
+	error: string().nullable(),
+	startedAtMs: number().nullable(),
+	finishedAtMs: number().nullable()
+});
+var lifecycleJobStateSchema = _enum([
+	"running",
+	"completed",
+	"failed",
+	"partially-failed",
+	"cancelled"
+]);
+var lifecycleJobScopeSchema = _enum([
+	"single",
+	"bulk",
+	"cluster"
+]);
+var lifecycleJobSchema = object({
+	jobId: string(),
+	kind: jobKindSchema,
+	createdAtMs: number(),
+	createdBy: string(),
+	scope: lifecycleJobScopeSchema,
+	tasks: array(lifecycleTaskSchema),
+	state: lifecycleJobStateSchema,
+	schemaVersion: literal(1)
+});
 /**
 * addons — system-scoped singleton capability for addon package
 * management (install, update, configure, restart) and per-addon log
@@ -16200,7 +16264,7 @@ var BulkUpdatePhaseSchema = _enum([
 	"restarting",
 	"finalizing"
 ]);
-var BulkUpdateStateSchema = object({
+object({
 	id: string(),
 	nodeId: string(),
 	startedAtMs: number(),
@@ -16303,20 +16367,7 @@ method(_void(), array(AddonListItemSchema).readonly()), method(object({
 }), UpdateFrameworkPackageResultSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({
-	nodeId: string(),
-	items: array(object({
-		name: string(),
-		version: string(),
-		isSystem: boolean()
-	})).readonly()
-}), object({ id: string() }), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({ id: string() }), BulkUpdateStateSchema.nullable(), { auth: "admin" }), method(object({ id: string() }), object({ cancelled: boolean() }), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({ nodeId: string().optional() }), array(BulkUpdateStateSchema).readonly(), { auth: "admin" }), method(object({ name: string() }), array(PackageVersionInfoSchema).readonly()), method(object({ addonId: string() }), RestartAddonResultSchema, {
+}), method(object({ name: string() }), array(PackageVersionInfoSchema).readonly()), method(object({ addonId: string() }), RestartAddonResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 }), method(object({ packageName: string() }), object({ success: literal(true) }), {
@@ -16338,6 +16389,24 @@ method(_void(), array(AddonListItemSchema).readonly()), method(object({
 	kind: "mutation",
 	auth: "admin"
 }), method(CustomActionInputSchema, unknown(), { kind: "mutation" }), method(object({
+	kind: _enum([
+		"install",
+		"update",
+		"uninstall",
+		"restart"
+	]),
+	targets: array(object({
+		name: string().min(1),
+		version: string().min(1)
+	})).min(1),
+	nodeIds: array(string()).optional()
+}), object({ jobId: string() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ jobId: string() }), lifecycleJobSchema.nullable(), { auth: "admin" }), method(object({ activeOnly: boolean().optional() }), array(lifecycleJobSchema), { auth: "admin" }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
 	addonId: string(),
 	level: LogLevelSchema$1.optional()
 }), LogStreamEntrySchema, { kind: "subscription" });
@@ -16378,7 +16447,7 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"addons.cancelBulkUpdate": {
+	"addons.cancelJob": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -16408,7 +16477,7 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
-	"addons.getBulkUpdateState": {
+	"addons.getJob": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -16456,19 +16525,19 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
-	"addons.listActiveBulkUpdates": {
+	"addons.listCapabilityProviders": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
-	"addons.listCapabilityProviders": {
+	"addons.listFrameworkPackages": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
-	"addons.listFrameworkPackages": {
+	"addons.listJobs": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -16552,7 +16621,7 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"addons.startBulkUpdate": {
+	"addons.startJob": {
 		capName: "addons",
 		capScope: "system",
 		addonId: null,
@@ -20539,5 +20608,31 @@ Object.freeze({
 	"network-access": "ingress",
 	"smtp-provider": "email"
 });
+var frameworkSwapPackageSchema = object({
+	name: string(),
+	stagedPath: string(),
+	backupPath: string(),
+	toVersion: string(),
+	fromVersion: string().nullable()
+});
+object({
+	jobId: string(),
+	taskId: string(),
+	packages: array(frameworkSwapPackageSchema),
+	requestedAtMs: number(),
+	schemaVersion: literal(1)
+});
+object({
+	jobId: string(),
+	taskId: string(),
+	backups: array(object({
+		name: string(),
+		backupPath: string(),
+		livePath: string()
+	})),
+	appliedAtMs: number(),
+	bootAttempts: number(),
+	schemaVersion: literal(1)
+});
 //#endregion
 export { networkAccessCapability as a, array as c, literal as d, number as f, defineCustomActions as i, boolean as l, string as m, EventCategory as n, turnProviderCapability as o, object as p, customAction as r, _enum as s, BaseAddon as t, discriminatedUnion as u };

package/dist/tunnel/cloudflare-tunnel.addon.js

@@ -1,7 +1,38 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dist = require("../dist-FQAxmoZY.js");
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+const require_dist = require("../dist-BaLJK4dE.js");
+let node_path = require("node:path");
+node_path = __toESM(node_path);
 let node_crypto = require("node:crypto");
 let node_child_process = require("node:child_process");
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs);
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = __toESM(node_fs_promises);
+let node_os = require("node:os");
+node_os = __toESM(node_os);
+let node_stream_promises = require("node:stream/promises");
 //#region src/tunnel/cloudflare-tunnel.ts
 /**
 * Direct child_process.spawn() driver for the `cloudflared` binary.
@@ -23,19 +54,23 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 	config;
 	logger;
 	eventBus;
+	resolveCloudflaredBin;
 	id = "cloudflare-tunnel";
 	type = "cloudflare";
 	endpoint = null;
 	lastError;
 	child = null;
+	/** Resolved cloudflared path/command (set on first start, reused on restart). */
+	cloudflaredBin = "cloudflared";
 	restartCount = 0;
 	intentionalStop = false;
 	static MAX_RESTARTS = 5;
 	static STOP_GRACE_MS = 5e3;
-	constructor(config, logger, eventBus) {
+	constructor(config, logger, eventBus, resolveCloudflaredBin = async () => "cloudflared") {
 		this.config = config;
 		this.logger = logger;
 		this.eventBus = eventBus;
+		this.resolveCloudflaredBin = resolveCloudflaredBin;
 	}
 	async start() {
 		this.logger.info("Starting Cloudflare tunnel", {
@@ -76,6 +111,18 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 		this.intentionalStop = false;
 		this.restartCount = 0;
 		this.lastError = void 0;
+		try {
+			this.cloudflaredBin = await this.resolveCloudflaredBin();
+		} catch (err) {
+			this.logger.error("Failed to provision cloudflared binary", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "provision-error"
+				}
+			});
+			throw err;
+		}
 		this.spawnChild();
 		const placeholderHost = this.config.mode === "custom" ? this.config.customHostname : "pending.trycloudflare.com";
 		this.endpoint = {
@@ -192,7 +239,7 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 		const args = [...debugFlags, ...tunnelArgs];
 		let child;
 		try {
-			child = (0, node_child_process.spawn)("cloudflared", args, { stdio: [
+			child = (0, node_child_process.spawn)(this.cloudflaredBin, args, { stdio: [
 				"ignore",
 				"pipe",
 				"pipe"
@@ -340,6 +387,130 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 		});
 	}
 };
+var RELEASE_BASE = "https://github.com/cloudflare/cloudflared/releases/download";
+/**
+* Map a Node `platform`/`arch` to the matching cloudflared release asset.
+* Pure + exported for testing. Throws on an unsupported combination.
+*/
+function cloudflaredAsset(platform, arch) {
+	const a = arch === "x64" ? "amd64" : arch === "arm64" ? "arm64" : arch === "arm" ? "arm" : null;
+	if (a === null) throw new Error(`cloudflared: unsupported arch '${arch}'`);
+	switch (platform) {
+		case "linux": return {
+			fileName: `cloudflared-linux-${a}`,
+			isArchive: false
+		};
+		case "darwin": return {
+			fileName: `cloudflared-darwin-${a === "arm64" ? "amd64" : a}.tgz`,
+			isArchive: true
+		};
+		case "win32": return {
+			fileName: `cloudflared-windows-${a}.exe`,
+			isArchive: false
+		};
+		default: throw new Error(`cloudflared: unsupported platform '${platform}'`);
+	}
+}
+/** Resolve a working `cloudflared` from PATH, or null if not runnable. */
+async function cloudflaredOnPath() {
+	return await runsOk("cloudflared") ? "cloudflared" : null;
+}
+/** True when `<bin> --version` exits 0 (binary present + executable). */
+function runsOk(bin) {
+	return new Promise((resolve) => {
+		let done = false;
+		const finish = (ok) => {
+			if (!done) {
+				done = true;
+				resolve(ok);
+			}
+		};
+		try {
+			const child = (0, node_child_process.spawn)(bin, ["--version"], { stdio: "ignore" });
+			child.on("error", () => finish(false));
+			child.on("exit", (code) => finish(code === 0));
+			setTimeout(() => {
+				child.kill("SIGKILL");
+				finish(false);
+			}, 5e3);
+		} catch {
+			finish(false);
+		}
+	});
+}
+async function downloadTo(url, dest) {
+	const res = await fetch(url, { redirect: "follow" });
+	if (!res.ok || !res.body) throw new Error(`cloudflared download failed: HTTP ${res.status} for ${url}`);
+	const tmp = `${dest}.partial`;
+	await (0, node_stream_promises.pipeline)(res.body, node_fs.createWriteStream(tmp));
+	await node_fs_promises.rename(tmp, dest);
+}
+/** Extract the `cloudflared` entry from a downloaded .tgz into `destBin`. */
+async function extractArchive(archivePath, destBin, logger) {
+	const dir = node_path.dirname(destBin);
+	await new Promise((resolve, reject) => {
+		const child = (0, node_child_process.spawn)("tar", [
+			"-xzf",
+			archivePath,
+			"-C",
+			dir
+		], { stdio: "inherit" });
+		child.on("error", reject);
+		child.on("exit", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`tar exited ${code}`)));
+	});
+	if (!node_fs.existsSync(destBin)) logger.warn("cloudflared archive did not yield expected binary name", {
+		meta: { destBin },
+		tags: {
+			topic: "tunnel",
+			phase: "extract"
+		}
+	});
+	await node_fs_promises.rm(archivePath, { force: true });
+}
+/**
+* Return a path/command for a runnable `cloudflared`, downloading + caching it
+* on first use. Prefers an existing PATH install; otherwise caches under
+* `binDir`. Throws (with an actionable message) if it cannot be provisioned.
+*/
+async function ensureCloudflared(opts) {
+	const onPath = await cloudflaredOnPath();
+	if (onPath) return onPath;
+	const cached = node_path.join(opts.binDir, node_os.platform() === "win32" ? "cloudflared.exe" : "cloudflared");
+	if (node_fs.existsSync(cached) && await runsOk(cached)) return cached;
+	const version = opts.version ?? "2025.4.2";
+	const asset = cloudflaredAsset(node_os.platform(), node_os.arch());
+	const url = `${RELEASE_BASE}/${version}/${asset.fileName}`;
+	await node_fs_promises.mkdir(opts.binDir, { recursive: true });
+	opts.logger.info("Provisioning cloudflared (not on PATH) — downloading", {
+		meta: {
+			version,
+			asset: asset.fileName,
+			dest: cached
+		},
+		tags: {
+			topic: "tunnel",
+			phase: "provision"
+		}
+	});
+	if (asset.isArchive) {
+		const archive = node_path.join(opts.binDir, asset.fileName);
+		await downloadTo(url, archive);
+		await extractArchive(archive, cached, opts.logger);
+	} else await downloadTo(url, cached);
+	await node_fs_promises.chmod(cached, 493);
+	if (!await runsOk(cached)) throw new Error(`cloudflared downloaded to ${cached} but is not runnable`);
+	opts.logger.info("cloudflared ready", {
+		meta: {
+			path: cached,
+			version
+		},
+		tags: {
+			topic: "tunnel",
+			phase: "provision-done"
+		}
+	});
+	return cached;
+}
 //#endregion
 //#region src/tunnel/cloudflare-api.ts
 /**
@@ -666,6 +837,19 @@ var CloudflareTunnelAddon = class extends require_dist.BaseAddon {
 		}
 		return "127.0.0.1";
 	}
+	/**
+	* Resolve the `cloudflared` binary path once per addon lifetime (PATH install,
+	* or a copy downloaded + cached under `<dataDir>/bin`). Memoized so the
+	* (possible) download happens at most once, on the first tunnel start.
+	*/
+	cloudflaredBinPromise;
+	resolveCloudflared() {
+		this.cloudflaredBinPromise ??= ensureCloudflared({
+			binDir: node_path.join(this.ctx.dataDir, "bin"),
+			logger: this.ctx.logger
+		});
+		return this.cloudflaredBinPromise;
+	}
 	async onInitialize() {
 		if (this.config.localPort === 3001) {
 			this.ctx.logger.warn("Resetting stale localPort=3001 (Vite admin-ui dev port) → 0 (auto)", { tags: {
@@ -679,7 +863,7 @@ var CloudflareTunnelAddon = class extends require_dist.BaseAddon {
 			...this.config,
 			localPort: this.resolveLocalPort(),
 			localHost
-		}, this.ctx.logger, this.ctx.eventBus);
+		}, this.ctx.logger, this.ctx.eventBus, () => this.resolveCloudflared());
 		this.ctx.logger.info("Cloudflare Tunnel addon initialized", { meta: {
 			mode: this.config.mode,
 			hasCustomToken: !!this.config.customTunnelToken
@@ -735,7 +919,7 @@ var CloudflareTunnelAddon = class extends require_dist.BaseAddon {
 			...this.config,
 			localPort: this.resolveLocalPort(),
 			localHost
-		}, this.ctx.logger, this.ctx.eventBus);
+		}, this.ctx.logger, this.ctx.eventBus, () => this.resolveCloudflared());
 		if (this.isRunCapable()) {
 			this.ctx.logger.info("config changed — (re-)spawning tunnel", {
 				meta: {

package/dist/tunnel/cloudflare-tunnel.addon.mjs

@@ -1,6 +1,11 @@
-import { a as networkAccessCapability, c as array, d as literal, f as number, i as defineCustomActions, l as boolean, m as string, n as EventCategory, p as object, r as customAction, s as _enum, t as BaseAddon } from "../dist-gS41k7Cx.mjs";
+import { a as networkAccessCapability, c as array, d as literal, f as number, i as defineCustomActions, l as boolean, m as string, n as EventCategory, p as object, r as customAction, s as _enum, t as BaseAddon } from "../dist-COIj-4Zk.mjs";
+import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import { pipeline } from "node:stream/promises";
 //#region src/tunnel/cloudflare-tunnel.ts
 /**
 * Direct child_process.spawn() driver for the `cloudflared` binary.
@@ -22,19 +27,23 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 	config;
 	logger;
 	eventBus;
+	resolveCloudflaredBin;
 	id = "cloudflare-tunnel";
 	type = "cloudflare";
 	endpoint = null;
 	lastError;
 	child = null;
+	/** Resolved cloudflared path/command (set on first start, reused on restart). */
+	cloudflaredBin = "cloudflared";
 	restartCount = 0;
 	intentionalStop = false;
 	static MAX_RESTARTS = 5;
 	static STOP_GRACE_MS = 5e3;
-	constructor(config, logger, eventBus) {
+	constructor(config, logger, eventBus, resolveCloudflaredBin = async () => "cloudflared") {
 		this.config = config;
 		this.logger = logger;
 		this.eventBus = eventBus;
+		this.resolveCloudflaredBin = resolveCloudflaredBin;
 	}
 	async start() {
 		this.logger.info("Starting Cloudflare tunnel", {
@@ -75,6 +84,18 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 		this.intentionalStop = false;
 		this.restartCount = 0;
 		this.lastError = void 0;
+		try {
+			this.cloudflaredBin = await this.resolveCloudflaredBin();
+		} catch (err) {
+			this.logger.error("Failed to provision cloudflared binary", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "provision-error"
+				}
+			});
+			throw err;
+		}
 		this.spawnChild();
 		const placeholderHost = this.config.mode === "custom" ? this.config.customHostname : "pending.trycloudflare.com";
 		this.endpoint = {
@@ -191,7 +212,7 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 		const args = [...debugFlags, ...tunnelArgs];
 		let child;
 		try {
-			child = spawn("cloudflared", args, { stdio: [
+			child = spawn(this.cloudflaredBin, args, { stdio: [
 				"ignore",
 				"pipe",
 				"pipe"
@@ -339,6 +360,130 @@ var CloudflareTunnelService = class CloudflareTunnelService {
 		});
 	}
 };
+var RELEASE_BASE = "https://github.com/cloudflare/cloudflared/releases/download";
+/**
+* Map a Node `platform`/`arch` to the matching cloudflared release asset.
+* Pure + exported for testing. Throws on an unsupported combination.
+*/
+function cloudflaredAsset(platform, arch) {
+	const a = arch === "x64" ? "amd64" : arch === "arm64" ? "arm64" : arch === "arm" ? "arm" : null;
+	if (a === null) throw new Error(`cloudflared: unsupported arch '${arch}'`);
+	switch (platform) {
+		case "linux": return {
+			fileName: `cloudflared-linux-${a}`,
+			isArchive: false
+		};
+		case "darwin": return {
+			fileName: `cloudflared-darwin-${a === "arm64" ? "amd64" : a}.tgz`,
+			isArchive: true
+		};
+		case "win32": return {
+			fileName: `cloudflared-windows-${a}.exe`,
+			isArchive: false
+		};
+		default: throw new Error(`cloudflared: unsupported platform '${platform}'`);
+	}
+}
+/** Resolve a working `cloudflared` from PATH, or null if not runnable. */
+async function cloudflaredOnPath() {
+	return await runsOk("cloudflared") ? "cloudflared" : null;
+}
+/** True when `<bin> --version` exits 0 (binary present + executable). */
+function runsOk(bin) {
+	return new Promise((resolve) => {
+		let done = false;
+		const finish = (ok) => {
+			if (!done) {
+				done = true;
+				resolve(ok);
+			}
+		};
+		try {
+			const child = spawn(bin, ["--version"], { stdio: "ignore" });
+			child.on("error", () => finish(false));
+			child.on("exit", (code) => finish(code === 0));
+			setTimeout(() => {
+				child.kill("SIGKILL");
+				finish(false);
+			}, 5e3);
+		} catch {
+			finish(false);
+		}
+	});
+}
+async function downloadTo(url, dest) {
+	const res = await fetch(url, { redirect: "follow" });
+	if (!res.ok || !res.body) throw new Error(`cloudflared download failed: HTTP ${res.status} for ${url}`);
+	const tmp = `${dest}.partial`;
+	await pipeline(res.body, fs.createWriteStream(tmp));
+	await fsp.rename(tmp, dest);
+}
+/** Extract the `cloudflared` entry from a downloaded .tgz into `destBin`. */
+async function extractArchive(archivePath, destBin, logger) {
+	const dir = path.dirname(destBin);
+	await new Promise((resolve, reject) => {
+		const child = spawn("tar", [
+			"-xzf",
+			archivePath,
+			"-C",
+			dir
+		], { stdio: "inherit" });
+		child.on("error", reject);
+		child.on("exit", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`tar exited ${code}`)));
+	});
+	if (!fs.existsSync(destBin)) logger.warn("cloudflared archive did not yield expected binary name", {
+		meta: { destBin },
+		tags: {
+			topic: "tunnel",
+			phase: "extract"
+		}
+	});
+	await fsp.rm(archivePath, { force: true });
+}
+/**
+* Return a path/command for a runnable `cloudflared`, downloading + caching it
+* on first use. Prefers an existing PATH install; otherwise caches under
+* `binDir`. Throws (with an actionable message) if it cannot be provisioned.
+*/
+async function ensureCloudflared(opts) {
+	const onPath = await cloudflaredOnPath();
+	if (onPath) return onPath;
+	const cached = path.join(opts.binDir, os.platform() === "win32" ? "cloudflared.exe" : "cloudflared");
+	if (fs.existsSync(cached) && await runsOk(cached)) return cached;
+	const version = opts.version ?? "2025.4.2";
+	const asset = cloudflaredAsset(os.platform(), os.arch());
+	const url = `${RELEASE_BASE}/${version}/${asset.fileName}`;
+	await fsp.mkdir(opts.binDir, { recursive: true });
+	opts.logger.info("Provisioning cloudflared (not on PATH) — downloading", {
+		meta: {
+			version,
+			asset: asset.fileName,
+			dest: cached
+		},
+		tags: {
+			topic: "tunnel",
+			phase: "provision"
+		}
+	});
+	if (asset.isArchive) {
+		const archive = path.join(opts.binDir, asset.fileName);
+		await downloadTo(url, archive);
+		await extractArchive(archive, cached, opts.logger);
+	} else await downloadTo(url, cached);
+	await fsp.chmod(cached, 493);
+	if (!await runsOk(cached)) throw new Error(`cloudflared downloaded to ${cached} but is not runnable`);
+	opts.logger.info("cloudflared ready", {
+		meta: {
+			path: cached,
+			version
+		},
+		tags: {
+			topic: "tunnel",
+			phase: "provision-done"
+		}
+	});
+	return cached;
+}
 //#endregion
 //#region src/tunnel/cloudflare-api.ts
 /**
@@ -665,6 +810,19 @@ var CloudflareTunnelAddon = class extends BaseAddon {
 		}
 		return "127.0.0.1";
 	}
+	/**
+	* Resolve the `cloudflared` binary path once per addon lifetime (PATH install,
+	* or a copy downloaded + cached under `<dataDir>/bin`). Memoized so the
+	* (possible) download happens at most once, on the first tunnel start.
+	*/
+	cloudflaredBinPromise;
+	resolveCloudflared() {
+		this.cloudflaredBinPromise ??= ensureCloudflared({
+			binDir: path.join(this.ctx.dataDir, "bin"),
+			logger: this.ctx.logger
+		});
+		return this.cloudflaredBinPromise;
+	}
 	async onInitialize() {
 		if (this.config.localPort === 3001) {
 			this.ctx.logger.warn("Resetting stale localPort=3001 (Vite admin-ui dev port) → 0 (auto)", { tags: {
@@ -678,7 +836,7 @@ var CloudflareTunnelAddon = class extends BaseAddon {
 			...this.config,
 			localPort: this.resolveLocalPort(),
 			localHost
-		}, this.ctx.logger, this.ctx.eventBus);
+		}, this.ctx.logger, this.ctx.eventBus, () => this.resolveCloudflared());
 		this.ctx.logger.info("Cloudflare Tunnel addon initialized", { meta: {
 			mode: this.config.mode,
 			hasCustomToken: !!this.config.customTunnelToken
@@ -734,7 +892,7 @@ var CloudflareTunnelAddon = class extends BaseAddon {
 			...this.config,
 			localPort: this.resolveLocalPort(),
 			localHost
-		}, this.ctx.logger, this.ctx.eventBus);
+		}, this.ctx.logger, this.ctx.eventBus, () => this.resolveCloudflared());
 		if (this.isRunCapable()) {
 			this.ctx.logger.info("config changed — (re-)spawning tunnel", {
 				meta: {

package/dist/turn/cloudflare-turn.addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dist = require("../dist-FQAxmoZY.js");
+const require_dist = require("../dist-BaLJK4dE.js");
 //#region src/turn/cloudflare-turn.ts
 /**
 * Cloudflare returns ICE servers in several flavours depending on which

package/dist/turn/cloudflare-turn.addon.mjs

@@ -1,4 +1,4 @@
-import { d as literal, f as number, i as defineCustomActions, l as boolean, m as string, o as turnProviderCapability, p as object, r as customAction, t as BaseAddon, u as discriminatedUnion } from "../dist-gS41k7Cx.mjs";
+import { d as literal, f as number, i as defineCustomActions, l as boolean, m as string, o as turnProviderCapability, p as object, r as customAction, t as BaseAddon, u as discriminatedUnion } from "../dist-COIj-4Zk.mjs";
 //#region src/turn/cloudflare-turn.ts
 /**
 * Cloudflare returns ICE servers in several flavours depending on which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-cloudflare",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Cloudflare bundle — Tunnel (network-access) + TURN relay (turn-provider). Multi-entry npm package shipping 2 addons under a single bundle.",
   "keywords": [
     "camstack",