clawdlets 0.2.4 → 0.3.0

package/dist/main.mjs

@@ -17,21 +17,16 @@ import { withFlakesEnv } from "@clawdlets/core/lib/nix-flakes";
 import { resolveBaseFlake } from "@clawdlets/core/lib/base-flake";
 import { getHostEncryptedAgeKeyFile, getHostExtraFilesDir, getHostExtraFilesKeyPath, getHostExtraFilesSecretsDir, getHostOpenTofuDir, getHostRemoteSecretsDir, getHostSecretsDir, getLocalOperatorAgeKeyPath, getRepoLayout } from "@clawdlets/core/repo-layout";
 import { collectDoctorChecks } from "@clawdlets/core/doctor";
+import { resolveHostNameOrExit } from "@clawdlets/core/lib/host-resolve";
 import { ensureDir, writeFileAtomic } from "@clawdlets/core/lib/fs-safe";
 import { splitDotPath } from "@clawdlets/core/lib/dot-path";
-import { safeCattleLabelValue } from "@clawdlets/core/lib/cattle-planner";
-import { openCattleState } from "@clawdlets/core/lib/cattle-state";
-import { CATTLE_LABEL_PERSONA, buildCattleLabelSelector, destroyCattleServer, listCattleServers, reapExpiredCattle } from "@clawdlets/core/lib/hcloud-cattle";
-import { parseTtlToSeconds } from "@clawdlets/core/lib/ttl";
-import { CATTLE_TASK_SCHEMA_VERSION, CattleTaskSchema } from "@clawdlets/core/lib/cattle-task";
-import { shellQuote, sshCapture, sshRun, validateTargetHost } from "@clawdlets/core/lib/ssh-remote";
-import { PersonaNameSchema, sanitizeOperatorId } from "@clawdlets/core/lib/identifiers";
-import { CLF_PROTOCOL_VERSION, createClfClient } from "@clawdlets/clf-queue";
 import { formatDotenvValue, parseDotenv } from "@clawdlets/core/lib/dotenv-file";
 import { looksLikeSshPrivateKey, parseSshPublicKeysFromText } from "@clawdlets/core/lib/ssh";
+import { shellQuote, sshCapture, sshRun, validateTargetHost } from "@clawdlets/core/lib/ssh-remote";
+import { loadHostContextOrExit } from "@clawdlets/core/lib/context";
 import { tmpdir } from "node:os";
 import { downloadTemplate } from "giget";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { normalizeTemplateSource } from "@clawdlets/core/lib/template-source";
 import { ageKeygen } from "@clawdlets/core/lib/age-keygen";
 import { parseAgeKeyFile } from "@clawdlets/core/lib/age";
@@ -39,11 +34,29 @@ import { mkpasswdYescryptHash } from "@clawdlets/core/lib/mkpasswd";
 import { upsertSopsCreationRule } from "@clawdlets/core/lib/sops-config";
 import { sopsDecryptYamlFile, sopsEncryptYamlToFile } from "@clawdlets/core/lib/sops";
 import { getHostAgeKeySopsCreationRulePathRegex, getHostSecretsSopsCreationRulePathRegex } from "@clawdlets/core/lib/sops-rules";
+import { sanitizeOperatorId } from "@clawdlets/core/lib/identifiers";
 import { buildSecretsInitTemplate, isPlaceholderSecretValue, listSecretsInitPlaceholders, parseSecretsInitJson, resolveSecretsInitFromJsonArg, validateSecretsInitNonInteractive } from "@clawdlets/core/lib/secrets-init";
 import { readYamlScalarFromMapping } from "@clawdlets/core/lib/yaml-scalar";
 import { createSecretsTar } from "@clawdlets/core/lib/secrets-tar";
 import YAML from "yaml";
 
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
 //#region src/lib/wizard.ts
 const NAV_BACK = Symbol("clawdlets.nav.back");
 const NAV_EXIT = Symbol("clawdlets.nav.exit");
@@ -77,7 +90,7 @@ function validateBotId(value) {
 	if (!v) return "bot id required";
 	if (!/^[a-z][a-z0-9_-]*$/.test(v)) return "use: [a-z][a-z0-9_-]*";
 }
-const list = defineCommand({
+const list$1 = defineCommand({
 	meta: {
 		name: "list",
 		description: "List bots (from fleet/clawdlets.json)."
@@ -88,7 +101,7 @@ const list = defineCommand({
 		console.log((config$1.fleet.botOrder || []).join("\n"));
 	}
 });
-const add$1 = defineCommand({
+const add$2 = defineCommand({
 	meta: {
 		name: "add",
 		description: "Add a bot id to fleet/clawdlets.json."
@@ -150,7 +163,7 @@ const add$1 = defineCommand({
 		console.log(`ok: added bot ${botId}`);
 	}
 });
-const rm = defineCommand({
+const rm$1 = defineCommand({
 	meta: {
 		name: "rm",
 		description: "Remove a bot id from fleet/clawdlets.json."
@@ -189,9 +202,9 @@ const bot = defineCommand({
 		description: "Manage fleet bots."
 	},
 	subCommands: {
-		add: add$1,
-		list,
-		rm
+		add: add$2,
+		list: list$1,
+		rm: rm$1
 	}
 });
 
@@ -369,41 +382,18 @@ async function requireDeployGate(params) {
 	}));
 }
 
-//#endregion
-//#region src/lib/host-resolve.ts
-function printHostTips(lines) {
-	for (const l of lines) console.error(`tip: ${l}`);
-}
-function resolveHostNameOrExit(params) {
-	const { config: config$1 } = loadClawdletsConfig({
-		repoRoot: findRepoRoot(params.cwd),
-		runtimeDir: params.runtimeDir
-	});
-	const resolved = resolveHostName({
-		config: config$1,
-		host: params.hostArg
-	});
-	if (!resolved.ok) {
-		console.error(`warn: ${resolved.message}`);
-		printHostTips(resolved.tips);
-		process$1.exitCode = 1;
-		return null;
-	}
-	return resolved.host;
-}
-
 //#endregion
 //#region src/commands/bootstrap.ts
 async function purgeKnownHosts(ipv4, opts) {
-	const rm$1 = async (host$1) => {
+	const rm$2 = async (host$1) => {
 		if (opts.dryRun) {
 			console.log(`ssh-keygen -R ${host$1}`);
 			return;
 		}
 		await run("ssh-keygen", ["-R", host$1]);
 	};
-	await rm$1(ipv4);
-	await rm$1(`[${ipv4}]:22`);
+	await rm$2(ipv4);
+	await rm$2(`[${ipv4}]:22`);
 }
 function resolveHostFromFlake(flakeBase) {
 	const hashIndex = flakeBase.indexOf("#");
@@ -813,960 +803,96 @@ const validate = defineCommand({
 });
 const get = defineCommand({
 	meta: {
-		name: "get",
-		description: "Get a value from fleet/clawdlets.json (dot path)."
-	},
-	args: {
-		path: {
-			type: "string",
-			description: "Dot path (e.g. fleet.botOrder)."
-		},
-		json: {
-			type: "boolean",
-			description: "JSON output.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const { config } = loadClawdletsConfig({ repoRoot: findRepoRoot(process$1.cwd()) });
-		const parts = splitDotPath(String(args.path || ""));
-		const v = getAtPath(config, parts);
-		if (args.json) console.log(JSON.stringify({
-			path: parts.join("."),
-			value: v
-		}, null, 2));
-		else console.log(typeof v === "string" ? v : JSON.stringify(v, null, 2));
-	}
-});
-const set$2 = defineCommand({
-	meta: {
-		name: "set",
-		description: "Set a value in fleet/clawdlets.json (dot path)."
-	},
-	args: {
-		path: {
-			type: "string",
-			description: "Dot path (e.g. fleet.botOrder)."
-		},
-		value: {
-			type: "string",
-			description: "String value."
-		},
-		"value-json": {
-			type: "string",
-			description: "JSON value (parsed)."
-		},
-		delete: {
-			type: "boolean",
-			description: "Delete the key at path.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const { configPath, config } = loadClawdletsConfigRaw({ repoRoot: findRepoRoot(process$1.cwd()) });
-		const parts = splitDotPath(String(args.path || ""));
-		const next = structuredClone(config);
-		if (args.delete) {
-			if (!deleteAtPath(next, parts)) throw new Error(`path not found: ${parts.join(".")}`);
-		} else if (args["value-json"] !== void 0) {
-			let parsed;
-			try {
-				parsed = JSON.parse(String(args["value-json"]));
-			} catch {
-				throw new Error("invalid --value-json (must be valid JSON)");
-			}
-			setAtPath(next, parts, parsed);
-		} else if (args.value !== void 0) setAtPath(next, parts, String(args.value));
-		else throw new Error("set requires --value or --value-json (or --delete)");
-		try {
-			await writeClawdletsConfig({
-				configPath,
-				config: ClawdletsConfigSchema.parse(next)
-			});
-			console.log("ok");
-		} catch (err) {
-			let details = "";
-			if (Array.isArray(err?.errors)) details = err.errors.map((e) => (Array.isArray(e.path) ? e.path.join(".") : "") || e.message).filter(Boolean).join(", ");
-			const msg = details ? `config update failed; revert or fix validation errors: ${details}` : "config update failed; revert or fix validation errors";
-			throw new Error(msg);
-		}
-	}
-});
-const config = defineCommand({
-	meta: {
-		name: "config",
-		description: "Canonical config (fleet/clawdlets.json)."
-	},
-	subCommands: {
-		init,
-		show: show$1,
-		validate,
-		get,
-		set: set$2
-	}
-});
-
-//#endregion
-//#region src/lib/context.ts
-function loadRepoContext(params) {
-	const repoRoot = findRepoRoot(params.cwd);
-	const { layout, config: config$1 } = loadClawdletsConfig({
-		repoRoot,
-		runtimeDir: params.runtimeDir
-	});
-	return {
-		repoRoot,
-		layout,
-		config: config$1
-	};
-}
-function loadHostContextOrExit(params) {
-	const hostName = resolveHostNameOrExit({
-		cwd: params.cwd,
-		runtimeDir: params.runtimeDir,
-		hostArg: params.hostArg
-	});
-	if (!hostName) return null;
-	const { repoRoot, layout, config: config$1 } = loadRepoContext({
-		cwd: params.cwd,
-		runtimeDir: params.runtimeDir
-	});
-	const hostCfg = config$1.hosts[hostName];
-	if (!hostCfg) throw new Error(`missing host in fleet/clawdlets.json: ${hostName}`);
-	return {
-		repoRoot,
-		layout,
-		config: config$1,
-		hostName,
-		hostCfg
-	};
-}
-
-//#endregion
-//#region src/commands/cattle/common.ts
-function requireEnabled(params) {
-	if (params.enabled) return;
-	throw new Error(params.hint);
-}
-function requireFile(pathname, label) {
-	if (fs.existsSync(pathname)) return;
-	throw new Error(`${label} missing: ${pathname}`);
-}
-function readJsonFile(filePath) {
-	const raw = fs.readFileSync(filePath, "utf8");
-	try {
-		return JSON.parse(raw);
-	} catch (e) {
-		throw new Error(`invalid JSON: ${filePath} (${String(e?.message || e)})`);
-	}
-}
-function requireTtlSeconds(ttlRaw) {
-	const parsed = parseTtlToSeconds(ttlRaw);
-	if (!parsed) throw new Error(`invalid --ttl: ${ttlRaw} (expected e.g. 30m, 2h, 1d)`);
-	return {
-		seconds: parsed.seconds,
-		normalized: parsed.raw
-	};
-}
-function unixSecondsNow() {
-	return Math.floor(Date.now() / 1e3);
-}
-function formatAgeSeconds(seconds) {
-	const s = Math.max(0, Math.floor(seconds));
-	const d = Math.floor(s / 86400);
-	const h = Math.floor(s % 86400 / 3600);
-	const m = Math.floor(s % 3600 / 60);
-	const ss = s % 60;
-	if (d > 0) return `${d}d${h}h`;
-	if (h > 0) return `${h}h${m}m`;
-	if (m > 0) return `${m}m${ss}s`;
-	return `${ss}s`;
-}
-function formatTable(rows) {
-	if (rows.length === 0) return "";
-	const widths = [];
-	for (const r of rows) for (let i = 0; i < r.length; i++) widths[i] = Math.max(widths[i] || 0, String(r[i] ?? "").length);
-	return rows.map((r) => r.map((c, i) => String(c ?? "").padEnd(widths[i] || 0)).join("  ").trimEnd()).join("\n");
-}
-async function resolveTailscaleIpv4(hostname) {
-	const name = String(hostname || "").trim();
-	if (!name) throw new Error("hostname missing for tailscale ip resolution");
-	const ip = (await capture("tailscale", [
-		"ip",
-		"--1",
-		"--4",
-		name
-	], { maxOutputBytes: 4096 })).trim();
-	if (!ip) throw new Error(`tailscale ip returned empty output for ${name}`);
-	return ip;
-}
-function loadTaskFromFile(taskFile) {
-	const raw = readJsonFile(taskFile);
-	const parsed = CattleTaskSchema.safeParse(raw);
-	if (!parsed.success) throw new Error(`invalid task file (expected schemaVersion ${CATTLE_TASK_SCHEMA_VERSION}): ${taskFile}`);
-	return parsed.data;
-}
-async function waitForClfJobTerminal(params) {
-	const start = Date.now();
-	while (true) {
-		const job = (await params.client.show(params.jobId)).job;
-		if (job?.status === "done" || job?.status === "failed" || job?.status === "canceled") return job;
-		if (Date.now() - start > params.timeoutMs) throw new Error(`timeout waiting for job ${params.jobId} (last=${String(job?.status || "")})`);
-		await new Promise((r) => setTimeout(r, params.pollMs));
-	}
-}
-function resolveOne(servers, idOrName) {
-	const v = String(idOrName || "").trim();
-	if (!v) throw new Error("missing id/name");
-	const byId = servers.find((s) => s.id === v);
-	if (byId) return byId;
-	const byName = servers.find((s) => s.name === v);
-	if (byName) return byName;
-	throw new Error(`cattle server not found: ${v}`);
-}
-
-//#endregion
-//#region src/commands/cattle/destroy.ts
-const cattleDestroy = defineCommand({
-	meta: {
-		name: "destroy",
-		description: "Destroy cattle servers (Hetzner delete)."
-	},
-	args: {
-		runtimeDir: {
-			type: "string",
-			description: "Runtime directory (default: .clawdlets)."
-		},
-		envFile: {
-			type: "string",
-			description: "Env file for deploy creds (default: <runtimeDir>/env)."
-		},
-		host: {
-			type: "string",
-			description: "Host name (defaults to clawdlets.json defaultHost / sole host)."
-		},
-		idOrName: {
-			type: "string",
-			description: "Cattle server id or name."
-		},
-		all: {
-			type: "boolean",
-			description: "Destroy all cattle servers.",
-			default: false
-		},
-		persona: {
-			type: "string",
-			description: "Filter by persona (with --all)."
-		},
-		dryRun: {
-			type: "boolean",
-			description: "Print plan without deleting.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const cwd = process$1.cwd();
-		const ctx = loadHostContextOrExit({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			hostArg: args.host
-		});
-		if (!ctx) return;
-		const { layout, config: config$1 } = ctx;
-		requireEnabled({
-			enabled: Boolean(config$1.cattle?.enabled),
-			hint: "cattle is disabled (set cattle.enabled=true in fleet/clawdlets.json)"
-		});
-		const deployCreds = loadDeployCreds({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			envFile: args.envFile
-		});
-		const hcloudToken = String(deployCreds.values.HCLOUD_TOKEN || "").trim();
-		if (!hcloudToken) throw new Error("missing HCLOUD_TOKEN (set in .clawdlets/env or env var; run: clawdlets env init)");
-		const personaFilterRaw = String(args.persona || "").trim();
-		const personaFilter = personaFilterRaw ? safeCattleLabelValue(personaFilterRaw, "persona") : "";
-		const servers = await listCattleServers({
-			token: hcloudToken,
-			labelSelector: buildCattleLabelSelector(personaFilter ? { [CATTLE_LABEL_PERSONA]: personaFilter } : {})
-		});
-		const targets = [];
-		if (args.all) targets.push(...servers);
-		else {
-			const idOrName = String(args.idOrName || "").trim();
-			if (!idOrName) throw new Error("missing <idOrName> (or pass --all)");
-			targets.push(resolveOne(servers, idOrName));
-		}
-		if (targets.length === 0) {
-			console.log("ok: no matching cattle servers");
-			return;
-		}
-		const st = openCattleState(layout.cattleDbPath);
-		try {
-			if (args.dryRun) {
-				console.log(formatTable([[
-					"ID",
-					"NAME",
-					"PERSONA",
-					"TASK",
-					"STATUS"
-				], ...targets.map((s) => [
-					s.id,
-					s.name,
-					s.persona || "-",
-					s.taskId || "-",
-					s.status
-				])]));
-				return;
-			}
-			const now = unixSecondsNow();
-			for (const t of targets) {
-				await destroyCattleServer({
-					token: hcloudToken,
-					id: t.id
-				});
-				st.markDeletedById(t.id, now);
-			}
-		} finally {
-			st.close();
-		}
-		console.log(`ok: destroyed ${targets.length} cattle server(s)`);
-	}
-});
-
-//#endregion
-//#region src/commands/cattle/list.ts
-const cattleList = defineCommand({
-	meta: {
-		name: "list",
-		description: "List active cattle servers (Hetzner + local state reconciliation)."
-	},
-	args: {
-		runtimeDir: {
-			type: "string",
-			description: "Runtime directory (default: .clawdlets)."
-		},
-		envFile: {
-			type: "string",
-			description: "Env file for deploy creds (default: <runtimeDir>/env)."
-		},
-		host: {
-			type: "string",
-			description: "Host name (defaults to clawdlets.json defaultHost / sole host)."
-		},
-		json: {
-			type: "boolean",
-			description: "Output JSON.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const cwd = process$1.cwd();
-		const ctx = loadHostContextOrExit({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			hostArg: args.host
-		});
-		if (!ctx) return;
-		const { layout, config: config$1 } = ctx;
-		requireEnabled({
-			enabled: Boolean(config$1.cattle?.enabled),
-			hint: "cattle is disabled (set cattle.enabled=true in fleet/clawdlets.json)"
-		});
-		const deployCreds = loadDeployCreds({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			envFile: args.envFile
-		});
-		const hcloudToken = String(deployCreds.values.HCLOUD_TOKEN || "").trim();
-		if (!hcloudToken) throw new Error("missing HCLOUD_TOKEN (set in .clawdlets/env or env var; run: clawdlets env init)");
-		const servers = await listCattleServers({
-			token: hcloudToken,
-			labelSelector: buildCattleLabelSelector()
-		});
-		const now = unixSecondsNow();
-		const byId = /* @__PURE__ */ new Map();
-		for (const s of servers) byId.set(s.id, s);
-		const st = openCattleState(layout.cattleDbPath);
-		try {
-			const activeLocal = st.listActive();
-			const remoteIds = new Set(servers.map((s) => s.id));
-			for (const local of activeLocal) if (!remoteIds.has(local.id)) st.markDeletedById(local.id, now);
-			for (const s of servers) {
-				const existing = st.findActiveByIdOrName(s.id);
-				st.upsertServer({
-					id: s.id,
-					name: s.name,
-					persona: s.persona || existing?.persona || "",
-					task: existing?.task || s.taskId || "",
-					taskId: s.taskId || existing?.taskId || "",
-					ttlSeconds: s.ttlSeconds,
-					createdAt: Math.floor(s.createdAt.getTime() / 1e3),
-					expiresAt: Math.floor(s.expiresAt.getTime() / 1e3),
-					labels: s.labels || existing?.labels || {},
-					lastStatus: s.status,
-					lastIpv4: s.ipv4
-				});
-			}
-		} finally {
-			st.close();
-		}
-		const sorted = [...servers].sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || a.id.localeCompare(b.id));
-		if (args.json) {
-			console.log(JSON.stringify({ servers: sorted }, null, 2));
-			return;
-		}
-		const rows = [[
-			"ID",
-			"NAME",
-			"PERSONA",
-			"TASK",
-			"STATUS",
-			"TTL"
-		], ...sorted.map((s) => {
-			const ttlLeft = Math.max(0, Math.floor(s.expiresAt.getTime() / 1e3) - now);
-			return [
-				s.id,
-				s.name,
-				s.persona || "-",
-				s.taskId || "-",
-				s.status,
-				formatAgeSeconds(ttlLeft)
-			];
-		})];
-		console.log(formatTable(rows));
-	}
-});
-
-//#endregion
-//#region src/commands/cattle/logs.ts
-const cattleLogs = defineCommand({
-	meta: {
-		name: "logs",
-		description: "Stream logs from a cattle VM over tailnet SSH."
-	},
-	args: {
-		runtimeDir: {
-			type: "string",
-			description: "Runtime directory (default: .clawdlets)."
-		},
-		envFile: {
-			type: "string",
-			description: "Env file for deploy creds (default: <runtimeDir>/env)."
-		},
-		host: {
-			type: "string",
-			description: "Host name (defaults to clawdlets.json defaultHost / sole host)."
-		},
-		idOrName: {
-			type: "string",
-			description: "Cattle server id or name.",
-			required: true
-		},
-		lines: {
-			type: "string",
-			description: "Number of lines (default: 200).",
-			default: "200"
-		},
-		since: {
-			type: "string",
-			description: "Time window (journalctl syntax, e.g. '10m ago')."
-		},
-		follow: {
-			type: "boolean",
-			description: "Follow logs.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const cwd = process$1.cwd();
-		const ctx = loadHostContextOrExit({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			hostArg: args.host
-		});
-		if (!ctx) return;
-		const { config: config$1 } = ctx;
-		requireEnabled({
-			enabled: Boolean(config$1.cattle?.enabled),
-			hint: "cattle is disabled (set cattle.enabled=true in fleet/clawdlets.json)"
-		});
-		const deployCreds = loadDeployCreds({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			envFile: args.envFile
-		});
-		const hcloudToken = String(deployCreds.values.HCLOUD_TOKEN || "").trim();
-		if (!hcloudToken) throw new Error("missing HCLOUD_TOKEN (set in .clawdlets/env or env var; run: clawdlets env init)");
-		const targetHost = `admin@${await resolveTailscaleIpv4(resolveOne(await listCattleServers({
-			token: hcloudToken,
-			labelSelector: buildCattleLabelSelector()
-		}), String(args.idOrName || "")).name)}`;
-		const n = String(args.lines || "200").trim() || "200";
-		if (!/^\d+$/.test(n) || Number(n) <= 0) throw new Error(`invalid --lines: ${n}`);
-		const since = args.since ? String(args.since).trim() : "";
-		await sshRun(targetHost, [
-			"sudo",
-			"journalctl",
-			"-u",
-			shellQuote("clawdlets-cattle.service"),
-			"-n",
-			shellQuote(n),
-			...since ? ["--since", shellQuote(since)] : [],
-			...args.follow ? ["-f"] : [],
-			"--no-pager"
-		].join(" "), { redact: [] });
-	}
-});
-
-//#endregion
-//#region src/commands/cattle/persona.ts
-function getPersonasDir(repoRoot) {
-	return path.join(repoRoot, "cattle", "personas");
-}
-const personaAdd = defineCommand({
-	meta: {
-		name: "add",
-		description: "Create a cattle persona skeleton under cattle/personas/<name>/."
-	},
-	args: {
-		name: {
-			type: "string",
-			description: "Persona name (safe: [a-z][a-z0-9_-]*).",
-			required: true
-		},
-		force: {
-			type: "boolean",
-			description: "Overwrite existing files.",
-			default: false
-		},
-		dryRun: {
-			type: "boolean",
-			description: "Print planned writes without writing.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const repoRoot = findRepoRoot(process$1.cwd());
-		const name = PersonaNameSchema.parse(String(args.name || "").trim());
-		const personasDir = getPersonasDir(repoRoot);
-		const dir = path.join(personasDir, name);
-		const soulPath = path.join(dir, "SOUL.md");
-		const configPath = path.join(dir, "config.json");
-		const skillsDir = path.join(dir, "skills");
-		const memoryDir = path.join(dir, "memory");
-		const soulText = `# ${name}\n\n- tone: (fill)\n- values: (fill)\n- constraints: (fill)\n`;
-		const configJson = {
-			schemaVersion: 1,
-			model: {
-				primary: "",
-				fallbacks: []
-			},
-			skills: { allowBundled: [] },
-			defaults: { maxConcurrent: 1 }
-		};
-		const plannedWrites = [
-			soulPath,
-			configPath,
-			skillsDir,
-			memoryDir
-		];
-		if (args.dryRun) {
-			for (const p$1 of plannedWrites) console.log(`planned: ${path.relative(repoRoot, p$1)}`);
-			return;
-		}
-		await ensureDir(skillsDir);
-		await ensureDir(memoryDir);
-		if (!args.force) {
-			if (fs.existsSync(soulPath)) throw new Error(`already exists: ${soulPath} (pass --force to overwrite)`);
-			if (fs.existsSync(configPath)) throw new Error(`already exists: ${configPath} (pass --force to overwrite)`);
-		}
-		await writeFileAtomic(soulPath, soulText.endsWith("\n") ? soulText : `${soulText}\n`);
-		await writeFileAtomic(configPath, `${JSON.stringify(configJson, null, 2)}\n`);
-		console.log(`ok: created cattle/personas/${name}`);
-	}
-});
-const personaList = defineCommand({
-	meta: {
-		name: "list",
-		description: "List cattle personas under cattle/personas/."
-	},
-	args: { json: {
-		type: "boolean",
-		description: "Output JSON.",
-		default: false
-	} },
-	async run({ args }) {
-		const personasDir = getPersonasDir(findRepoRoot(process$1.cwd()));
-		const out = [];
-		if (fs.existsSync(personasDir)) for (const ent of fs.readdirSync(personasDir, { withFileTypes: true })) {
-			if (!ent.isDirectory()) continue;
-			const name = ent.name;
-			if (!PersonaNameSchema.safeParse(name).success) continue;
-			out.push(name);
-		}
-		out.sort();
-		if (args.json) console.log(JSON.stringify({ personas: out }, null, 2));
-		else for (const n of out) console.log(n);
-	}
-});
-const cattlePersona = defineCommand({
-	meta: {
-		name: "persona",
-		description: "Cattle persona registry helpers (cattle/personas/<name>/)."
-	},
-	subCommands: {
-		add: personaAdd,
-		list: personaList
-	}
-});
-
-//#endregion
-//#region src/commands/cattle/reap.ts
-const cattleReap = defineCommand({
-	meta: {
-		name: "reap",
-		description: "Destroy expired cattle servers (TTL enforcement)."
-	},
-	args: {
-		runtimeDir: {
-			type: "string",
-			description: "Runtime directory (default: .clawdlets)."
-		},
-		envFile: {
-			type: "string",
-			description: "Env file for deploy creds (default: <runtimeDir>/env)."
-		},
-		host: {
-			type: "string",
-			description: "Host name (defaults to clawdlets.json defaultHost / sole host)."
-		},
-		dryRun: {
-			type: "boolean",
-			description: "Print plan without deleting.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const cwd = process$1.cwd();
-		const ctx = loadHostContextOrExit({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			hostArg: args.host
-		});
-		if (!ctx) return;
-		const { layout, config: config$1 } = ctx;
-		requireEnabled({
-			enabled: Boolean(config$1.cattle?.enabled),
-			hint: "cattle is disabled (set cattle.enabled=true in fleet/clawdlets.json)"
-		});
-		const deployCreds = loadDeployCreds({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			envFile: args.envFile
-		});
-		const hcloudToken = String(deployCreds.values.HCLOUD_TOKEN || "").trim();
-		if (!hcloudToken) throw new Error("missing HCLOUD_TOKEN (set in .clawdlets/env or env var; run: clawdlets env init)");
-		const now = unixSecondsNow();
-		const res = await reapExpiredCattle({
-			token: hcloudToken,
-			labelSelector: buildCattleLabelSelector(),
-			now: /* @__PURE__ */ new Date(now * 1e3),
-			dryRun: args.dryRun
-		});
-		const expired = res.expired;
-		if (expired.length === 0) {
-			console.log("ok: no expired cattle servers");
-			return;
-		}
-		console.log(formatTable([[
-			"ID",
-			"NAME",
-			"PERSONA",
-			"TASK",
-			"EXPIRES",
-			"STATUS"
-		], ...expired.map((s) => [
-			s.id,
-			s.name,
-			s.persona || "-",
-			s.taskId || "-",
-			String(Math.floor(s.expiresAt.getTime() / 1e3)),
-			s.status
-		])]));
-		if (args.dryRun) return;
-		const st = openCattleState(layout.cattleDbPath);
-		try {
-			for (const id of res.deletedIds) st.markDeletedById(id, now);
-		} finally {
-			st.close();
-		}
-		console.log(`ok: reaped ${res.deletedIds.length} cattle server(s)`);
-	}
-});
-
-//#endregion
-//#region src/commands/cattle/spawn.ts
-const cattleSpawn = defineCommand({
-	meta: {
-		name: "spawn",
-		description: "Enqueue a cattle.spawn job via clf-orchestrator (no secrets in user_data)."
-	},
-	args: {
-		runtimeDir: {
-			type: "string",
-			description: "Runtime directory (default: .clawdlets)."
-		},
-		host: {
-			type: "string",
-			description: "Host name (defaults to clawdlets.json defaultHost / sole host)."
-		},
-		persona: {
-			type: "string",
-			description: "Persona name.",
-			required: true
-		},
-		taskFile: {
-			type: "string",
-			description: "Task JSON file (schemaVersion 1).",
-			required: true
-		},
-		ttl: {
-			type: "string",
-			description: "TTL override (default: cattle.hetzner.defaultTtl)."
-		},
-		image: {
-			type: "string",
-			description: "Hetzner image override (default: cattle.hetzner.image)."
-		},
-		serverType: {
-			type: "string",
-			description: "Hetzner server type override (default: cattle.hetzner.serverType)."
-		},
-		location: {
-			type: "string",
-			description: "Hetzner location override (default: cattle.hetzner.location)."
-		},
-		autoShutdown: {
-			type: "boolean",
-			description: "Auto poweroff after task (default: cattle.defaults.autoShutdown)."
-		},
-		withGithubToken: {
-			type: "boolean",
-			description: "Include GITHUB_TOKEN in cattle env (explicit).",
-			default: false
-		},
-		socket: {
-			type: "string",
-			description: "clf-orchestrator unix socket path (default: /run/clf/orchestrator.sock)."
-		},
-		requester: {
-			type: "string",
-			description: "Requester id (default: $USER)."
-		},
-		idempotencyKey: {
-			type: "string",
-			description: "Idempotency key (optional)."
-		},
-		wait: {
-			type: "boolean",
-			description: "Wait for job completion.",
-			default: true
-		},
-		waitTimeout: {
-			type: "string",
-			description: "Wait timeout seconds.",
-			default: "300"
-		},
-		dryRun: {
-			type: "boolean",
-			description: "Print enqueue request without enqueueing.",
-			default: false
-		}
-	},
-	async run({ args }) {
-		const cwd = process$1.cwd();
-		const ctx = loadHostContextOrExit({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			hostArg: args.host
-		});
-		if (!ctx) return;
-		const { layout, config: config$1 } = ctx;
-		requireEnabled({
-			enabled: Boolean(config$1.cattle?.enabled),
-			hint: "cattle is disabled (set cattle.enabled=true in fleet/clawdlets.json)"
-		});
-		const persona = String(args.persona || "").trim();
-		if (!persona) throw new Error("missing --persona");
-		const taskFileRaw = String(args.taskFile || "").trim();
-		if (!taskFileRaw) throw new Error("missing --task-file");
-		const taskFile = path.isAbsolute(taskFileRaw) ? taskFileRaw : path.resolve(cwd, taskFileRaw);
-		requireFile(taskFile, "task file");
-		const task = {
-			...loadTaskFromFile(taskFile),
-			callbackUrl: ""
-		};
-		const ttlRaw = String(args.ttl || config$1.cattle?.hetzner?.defaultTtl || "").trim();
-		if (ttlRaw) requireTtlSeconds(ttlRaw);
-		const payload = {
-			persona,
-			task,
-			ttl: ttlRaw,
-			image: String(args.image || config$1.cattle?.hetzner?.image || "").trim(),
-			serverType: String(args.serverType || config$1.cattle?.hetzner?.serverType || "").trim(),
-			location: String(args.location || config$1.cattle?.hetzner?.location || "").trim(),
-			...typeof args.autoShutdown === "boolean" ? { autoShutdown: Boolean(args.autoShutdown) } : typeof config$1.cattle?.defaults?.autoShutdown === "boolean" ? { autoShutdown: Boolean(config$1.cattle.defaults.autoShutdown) } : {},
-			...args.withGithubToken ? { withGithubToken: true } : {}
-		};
-		const socketPath = String(args.socket || process$1.env.CLF_SOCKET_PATH || "/run/clf/orchestrator.sock").trim();
-		if (!socketPath) throw new Error("missing --socket (or set CLF_SOCKET_PATH)");
-		const request = {
-			protocolVersion: CLF_PROTOCOL_VERSION,
-			requester: sanitizeOperatorId(String(args.requester || process$1.env.USER || "operator")),
-			idempotencyKey: String(args.idempotencyKey || "").trim(),
-			kind: "cattle.spawn",
-			payload,
-			runAt: "",
-			priority: 0
-		};
-		if (args.dryRun) {
-			console.log(JSON.stringify({
-				action: "clf.jobs.enqueue",
-				socketPath,
-				request
-			}, null, 2));
-			return;
-		}
-		const client = createClfClient({ socketPath });
-		const res = await client.enqueue(request);
-		const waitTimeoutRaw = String(args.waitTimeout || "300").trim();
-		if (!/^\d+$/.test(waitTimeoutRaw) || Number(waitTimeoutRaw) <= 0) throw new Error(`invalid --wait-timeout: ${waitTimeoutRaw}`);
-		const timeoutMs = Number(waitTimeoutRaw) * 1e3;
-		if (!args.wait) {
-			console.log(res.jobId);
-			return;
-		}
-		const job = await waitForClfJobTerminal({
-			client,
-			jobId: res.jobId,
-			timeoutMs,
-			pollMs: 1e3
-		});
-		if (job.status !== "done") {
-			const err = String(job.lastError || "").trim();
-			throw new Error(`spawn job ${res.jobId} ${job.status}${err ? `: ${err}` : ""}`);
-		}
-		const server$1 = job.result?.server;
-		if (server$1 && typeof server$1 === "object") {
-			const id = String(server$1.id || "").trim();
-			const name = String(server$1.name || "").trim();
-			const ipv4 = String(server$1.ipv4 || "").trim();
-			const createdAtIso = String(server$1.createdAt || "").trim();
-			const expiresAtIso = String(server$1.expiresAt || "").trim();
-			const createdAt = Number.isFinite(Date.parse(createdAtIso)) ? Math.floor(Date.parse(createdAtIso) / 1e3) : unixSecondsNow();
-			const expiresAt = Number.isFinite(Date.parse(expiresAtIso)) ? Math.floor(Date.parse(expiresAtIso) / 1e3) : 0;
-			const ttlSeconds = typeof server$1.ttlSeconds === "number" && Number.isFinite(server$1.ttlSeconds) ? Math.max(0, Math.floor(server$1.ttlSeconds)) : Math.max(0, expiresAt - createdAt);
-			const labels = server$1.labels && typeof server$1.labels === "object" && !Array.isArray(server$1.labels) ? server$1.labels : {};
-			if (id && name) {
-				const st = openCattleState(layout.cattleDbPath);
-				try {
-					st.upsertServer({
-						id,
-						name,
-						persona: String(server$1.persona || persona),
-						task: String(server$1.taskId || task.taskId),
-						taskId: String(server$1.taskId || task.taskId),
-						ttlSeconds,
-						createdAt,
-						expiresAt,
-						labels,
-						lastStatus: String(server$1.status || "unknown"),
-						lastIpv4: ipv4
-					});
-				} finally {
-					st.close();
-				}
-			}
-			console.log(`ok: spawned ${name || "cattle"} (id=${id || "?"} ipv4=${ipv4 || "?"} job=${res.jobId})`);
-			return;
+		name: "get",
+		description: "Get a value from fleet/clawdlets.json (dot path)."
+	},
+	args: {
+		path: {
+			type: "string",
+			description: "Dot path (e.g. fleet.botOrder)."
+		},
+		json: {
+			type: "boolean",
+			description: "JSON output.",
+			default: false
 		}
-		console.log(`ok: spawn completed (job=${res.jobId})`);
+	},
+	async run({ args }) {
+		const { config } = loadClawdletsConfig({ repoRoot: findRepoRoot(process$1.cwd()) });
+		const parts = splitDotPath(String(args.path || ""));
+		const v = getAtPath(config, parts);
+		if (args.json) console.log(JSON.stringify({
+			path: parts.join("."),
+			value: v
+		}, null, 2));
+		else console.log(typeof v === "string" ? v : JSON.stringify(v, null, 2));
 	}
 });
-
-//#endregion
-//#region src/commands/cattle/ssh.ts
-const cattleSsh = defineCommand({
+const set$2 = defineCommand({
 	meta: {
-		name: "ssh",
-		description: "SSH into a cattle VM over tailnet (admin@<tailscale-ip>)."
+		name: "set",
+		description: "Set a value in fleet/clawdlets.json (dot path)."
 	},
 	args: {
-		runtimeDir: {
+		path: {
 			type: "string",
-			description: "Runtime directory (default: .clawdlets)."
+			description: "Dot path (e.g. fleet.botOrder)."
 		},
-		envFile: {
+		value: {
 			type: "string",
-			description: "Env file for deploy creds (default: <runtimeDir>/env)."
+			description: "String value."
 		},
-		host: {
+		"value-json": {
 			type: "string",
-			description: "Host name (defaults to clawdlets.json defaultHost / sole host)."
+			description: "JSON value (parsed)."
 		},
-		idOrName: {
-			type: "string",
-			description: "Cattle server id or name.",
-			required: true
+		delete: {
+			type: "boolean",
+			description: "Delete the key at path.",
+			default: false
 		}
 	},
 	async run({ args }) {
-		const cwd = process$1.cwd();
-		const ctx = loadHostContextOrExit({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			hostArg: args.host
-		});
-		if (!ctx) return;
-		const { config: config$1 } = ctx;
-		requireEnabled({
-			enabled: Boolean(config$1.cattle?.enabled),
-			hint: "cattle is disabled (set cattle.enabled=true in fleet/clawdlets.json)"
-		});
-		const deployCreds = loadDeployCreds({
-			cwd,
-			runtimeDir: args.runtimeDir,
-			envFile: args.envFile
-		});
-		const hcloudToken = String(deployCreds.values.HCLOUD_TOKEN || "").trim();
-		if (!hcloudToken) throw new Error("missing HCLOUD_TOKEN (set in .clawdlets/env or env var; run: clawdlets env init)");
-		await run("ssh", [
-			"-t",
-			"--",
-			`admin@${await resolveTailscaleIpv4(resolveOne(await listCattleServers({
-				token: hcloudToken,
-				labelSelector: buildCattleLabelSelector()
-			}), String(args.idOrName || "")).name)}`
-		], { redact: [] });
+		const { configPath, config } = loadClawdletsConfigRaw({ repoRoot: findRepoRoot(process$1.cwd()) });
+		const parts = splitDotPath(String(args.path || ""));
+		const next = structuredClone(config);
+		if (args.delete) {
+			if (!deleteAtPath(next, parts)) throw new Error(`path not found: ${parts.join(".")}`);
+		} else if (args["value-json"] !== void 0) {
+			let parsed;
+			try {
+				parsed = JSON.parse(String(args["value-json"]));
+			} catch {
+				throw new Error("invalid --value-json (must be valid JSON)");
+			}
+			setAtPath(next, parts, parsed);
+		} else if (args.value !== void 0) setAtPath(next, parts, String(args.value));
+		else throw new Error("set requires --value or --value-json (or --delete)");
+		try {
+			await writeClawdletsConfig({
+				configPath,
+				config: ClawdletsConfigSchema.parse(next)
+			});
+			console.log("ok");
+		} catch (err) {
+			let details = "";
+			if (Array.isArray(err?.errors)) details = err.errors.map((e) => (Array.isArray(e.path) ? e.path.join(".") : "") || e.message).filter(Boolean).join(", ");
+			const msg = details ? `config update failed; revert or fix validation errors: ${details}` : "config update failed; revert or fix validation errors";
+			throw new Error(msg);
+		}
 	}
 });
-
-//#endregion
-//#region src/commands/cattle.ts
-const cattle = defineCommand({
+const config = defineCommand({
 	meta: {
-		name: "cattle",
-		description: "Cattle (ephemeral agents on Hetzner Cloud)."
+		name: "config",
+		description: "Canonical config (fleet/clawdlets.json)."
 	},
 	subCommands: {
-		spawn: cattleSpawn,
-		list: cattleList,
-		destroy: cattleDestroy,
-		reap: cattleReap,
-		logs: cattleLogs,
-		ssh: cattleSsh,
-		persona: cattlePersona
+		init,
+		show: show$1,
+		validate,
+		get,
+		set: set$2
 	}
 });
 
@@ -2022,7 +1148,7 @@ function toStringArray(v) {
 	if (Array.isArray(v)) return v.map((x) => String(x));
 	return [String(v)];
 }
-const add = defineCommand({
+const add$1 = defineCommand({
 	meta: {
 		name: "add",
 		description: "Add a host entry to fleet/clawdlets.json."
@@ -2325,7 +1451,7 @@ const host = defineCommand({
 		description: "Manage host config (fleet/clawdlets.json)."
 	},
 	subCommands: {
-		add,
+		add: add$1,
 		"set-default": setDefault,
 		set: set$1
 	}
@@ -2888,6 +2014,141 @@ const lockdown = defineCommand({
 	}
 });
 
+//#endregion
+//#region src/commands/plugin.ts
+async function loadPlugins() {
+	return await Promise.resolve().then(() => plugins_exports);
+}
+function resolveSlug(args) {
+	const raw = String(args.name || args._?.[0] || "").trim();
+	if (!raw) throw new Error("missing plugin name (pass --name or first arg)");
+	return raw;
+}
+const list = defineCommand({
+	meta: {
+		name: "list",
+		description: "List installed plugins."
+	},
+	args: {
+		json: {
+			type: "boolean",
+			description: "Output JSON.",
+			default: false
+		},
+		runtimeDir: {
+			type: "string",
+			description: "Runtime directory (default: .clawdlets)."
+		}
+	},
+	async run({ args }) {
+		const { listInstalledPlugins: listInstalledPlugins$1 } = await loadPlugins();
+		const errors = [];
+		const plugins = listInstalledPlugins$1({
+			cwd: process$1.cwd(),
+			runtimeDir: args.runtimeDir,
+			onError: (err) => errors.push(err)
+		});
+		const payload = {
+			plugins,
+			errors: errors.map((e) => ({
+				slug: e.slug,
+				error: e.error.message
+			}))
+		};
+		if (args.json) {
+			console.log(JSON.stringify(payload, null, 2));
+			return;
+		}
+		for (const err of errors) console.error(`warn: skipping plugin ${err.slug}: ${err.error.message}`);
+		if (plugins.length === 0) {
+			console.log("ok: no plugins installed");
+			return;
+		}
+		for (const p$1 of plugins) console.log(`${p$1.command}\t${p$1.packageName}@${p$1.version}`);
+	}
+});
+const add = defineCommand({
+	meta: {
+		name: "add",
+		description: "Install a plugin into .clawdlets/plugins."
+	},
+	args: {
+		name: {
+			type: "string",
+			description: "Plugin name (e.g. cattle)."
+		},
+		package: {
+			type: "string",
+			description: "Package to install (default: @clawdlets/plugin-<name>)."
+		},
+		version: {
+			type: "string",
+			description: "Package version/tag (default: latest)."
+		},
+		allowThirdParty: {
+			type: "boolean",
+			description: "Allow third-party plugins (unsafe).",
+			default: false
+		},
+		runtimeDir: {
+			type: "string",
+			description: "Runtime directory (default: .clawdlets)."
+		}
+	},
+	async run({ args }) {
+		const slug = resolveSlug(args);
+		const packageName = String(args.package || `@clawdlets/plugin-${slug}`).trim();
+		if (!args.allowThirdParty && !packageName.startsWith("@clawdlets/")) throw new Error("third-party plugins disabled (pass --allow-third-party to override)");
+		const { installPlugin: installPlugin$1 } = await loadPlugins();
+		const plugin = await installPlugin$1({
+			cwd: process$1.cwd(),
+			runtimeDir: args.runtimeDir,
+			slug,
+			packageName,
+			version: args.version,
+			allowThirdParty: args.allowThirdParty
+		});
+		console.log(`ok: installed ${plugin.command} (${plugin.packageName}@${plugin.version})`);
+	}
+});
+const rm = defineCommand({
+	meta: {
+		name: "rm",
+		description: "Remove an installed plugin."
+	},
+	args: {
+		name: {
+			type: "string",
+			description: "Plugin name (e.g. cattle)."
+		},
+		runtimeDir: {
+			type: "string",
+			description: "Runtime directory (default: .clawdlets)."
+		}
+	},
+	async run({ args }) {
+		const slug = resolveSlug(args);
+		const { removePlugin: removePlugin$1 } = await loadPlugins();
+		removePlugin$1({
+			cwd: process$1.cwd(),
+			runtimeDir: args.runtimeDir,
+			slug
+		});
+		console.log(`ok: removed ${slug}`);
+	}
+});
+const plugin = defineCommand({
+	meta: {
+		name: "plugin",
+		description: "Plugin manager (install/remove/list)."
+	},
+	subCommands: {
+		add,
+		list,
+		rm
+	}
+});
+
 //#endregion
 //#region src/lib/template-spec.ts
 function firstNonEmpty(...values) {
@@ -2898,6 +2159,8 @@ function firstNonEmpty(...values) {
 }
 function resolveTemplateSourcePath() {
 	const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+	const packagedDistPath = path.resolve(moduleDir, "config", "template-source.json");
+	if (fs.existsSync(packagedDistPath)) return packagedDistPath;
 	const packagedPath = path.resolve(moduleDir, "..", "config", "template-source.json");
 	if (fs.existsSync(packagedPath)) return packagedPath;
 	const repoRootPath = path.resolve(moduleDir, "..", "..", "..", "..", "config", "template-source.json");
@@ -4704,11 +3967,11 @@ const serverAudit = defineCommand({
 		const sudo = needsSudo(targetHost);
 		const bots = config$1.fleet.botOrder ?? [];
 		const checks = [];
-		const add$2 = (c) => checks.push(c);
+		const add$3 = (c) => checks.push(c);
 		const must = async (label, cmd) => {
 			const out = await trySshCapture(targetHost, cmd, { tty: sudo && args.sshTty });
 			if (!out.ok) {
-				add$2({
+				add$3({
 					status: "missing",
 					label,
 					detail: out.out
@@ -4726,7 +3989,7 @@ const serverAudit = defineCommand({
 			].join(" "));
 			if (tailscaled) {
 				const parsed = parseSystemctlShow(tailscaled);
-				add$2({
+				add$3({
 					status: parsed.ActiveState === "active" ? "ok" : "missing",
 					label: "tailscale service state",
 					detail: `${parsed.ActiveState || "?"}/${parsed.SubState || "?"}`
@@ -4740,19 +4003,19 @@ const serverAudit = defineCommand({
 			].join(" "));
 			if (autoconnect) {
 				const parsed = parseSystemctlShow(autoconnect);
-				add$2({
+				add$3({
 					status: parsed.ActiveState === "active" ? "ok" : "missing",
 					label: "tailscale autoconnect state",
 					detail: `${parsed.ActiveState || "?"}/${parsed.SubState || "?"}`
 				});
 			}
 		}
-		if (Array.isArray(bots) && bots.length > 0) add$2({
+		if (Array.isArray(bots) && bots.length > 0) add$3({
 			status: "ok",
 			label: "fleet bots list",
 			detail: bots.join(", ")
 		});
-		else add$2({
+		else add$3({
 			status: "warn",
 			label: "fleet bots list",
 			detail: "(empty)"
@@ -4770,17 +4033,17 @@ const serverAudit = defineCommand({
 			const loadState = parsed.LoadState || "";
 			const activeState = parsed.ActiveState || "";
 			const subState = parsed.SubState || "";
-			if (loadState && loadState !== "loaded") add$2({
+			if (loadState && loadState !== "loaded") add$3({
 				status: "missing",
 				label: `${unit} load state`,
 				detail: `LoadState=${loadState}`
 			});
-			else if (activeState === "active" && subState === "running") add$2({
+			else if (activeState === "active" && subState === "running") add$3({
 				status: "ok",
 				label: `${unit} state`,
 				detail: `${activeState}/${subState}`
 			});
-			else add$2({
+			else add$3({
 				status: "missing",
 				label: `${unit} state`,
 				detail: `${activeState || "?"}/${subState || "?"}`
@@ -4973,6 +4236,267 @@ const server = defineCommand({
 	}
 });
 
+//#endregion
+//#region src/commands/registry.ts
+const baseCommands = {
+	bot,
+	bootstrap,
+	config,
+	doctor,
+	env,
+	host,
+	fleet,
+	image,
+	infra,
+	lockdown,
+	plugin,
+	project,
+	secrets,
+	server
+};
+const baseCommandNames = Object.freeze(Object.keys(baseCommands));
+
+//#endregion
+//#region src/lib/plugins.ts
+var plugins_exports = /* @__PURE__ */ __exportAll({
+	findPluginByCommand: () => findPluginByCommand,
+	installPlugin: () => installPlugin,
+	listInstalledPlugins: () => listInstalledPlugins,
+	listReservedCommands: () => listReservedCommands,
+	loadPluginCommand: () => loadPluginCommand,
+	removePlugin: () => removePlugin
+});
+const PLUGIN_MANIFEST = "clawdlets-plugin.json";
+const RESERVED_COMMANDS = new Set(baseCommandNames);
+const SAFE_SLUG_RE = /^[a-z][a-z0-9_-]*$/;
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9-._]*\/)?[a-z0-9][a-z0-9-._]*$/;
+function readJsonFile(filePath) {
+	const raw = fs.readFileSync(filePath, "utf8");
+	return JSON.parse(raw);
+}
+function writeJsonFile(filePath, data) {
+	const dir = path.dirname(filePath);
+	fs.mkdirSync(dir, { recursive: true });
+	const tmp = path.join(dir, `.${path.basename(filePath)}.tmp.${process.pid}`);
+	fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+	fs.renameSync(tmp, filePath);
+}
+function assertSafeSlug(value) {
+	if (!SAFE_SLUG_RE.test(value)) throw new Error(`invalid plugin command: ${value} (expected [a-z][a-z0-9_-]*)`);
+}
+function isReservedCommand(value) {
+	return RESERVED_COMMANDS.has(value);
+}
+function assertCommandName(value) {
+	assertSafeSlug(value);
+	if (isReservedCommand(value)) throw new Error(`plugin command reserved: ${value}`);
+}
+function resolvePluginsDir(params) {
+	return getRepoLayout(findRepoRoot(params.cwd), params.runtimeDir).pluginsDir;
+}
+function resolveInstallDir(params) {
+	return path.join(params.pluginsDir, params.slug);
+}
+function resolvePackageDir(params) {
+	return path.join(params.installDir, "node_modules", ...params.packageName.split("/"));
+}
+function readPluginPackageMeta(packageDir) {
+	const pkgPath = path.join(packageDir, "package.json");
+	if (!fs.existsSync(pkgPath)) throw new Error(`plugin package.json missing: ${pkgPath}`);
+	const pkg = readJsonFile(pkgPath);
+	const command = String(pkg?.clawdlets?.command || "").trim();
+	const entry = String(pkg?.clawdlets?.entry || "").trim();
+	if (!command) throw new Error(`plugin missing clawdlets.command in ${pkgPath}`);
+	if (!entry) throw new Error(`plugin missing clawdlets.entry in ${pkgPath}`);
+	assertCommandName(command);
+	return {
+		command,
+		entry
+	};
+}
+function assertPackageName(value) {
+	if (!PACKAGE_NAME_RE.test(value)) throw new Error(`invalid plugin package name: ${value}`);
+}
+function resolveManifestPath(installDir) {
+	return path.join(installDir, PLUGIN_MANIFEST);
+}
+function normalizeManifest(slug, manifest) {
+	if (!manifest || typeof manifest !== "object") throw new Error("plugin manifest invalid");
+	const packageName = String(manifest.packageName || "").trim();
+	const version = String(manifest.version || "").trim();
+	const command = String(manifest.command || "").trim();
+	const entry = String(manifest.entry || "").trim();
+	if (!packageName) throw new Error("plugin manifest missing packageName");
+	assertPackageName(packageName);
+	if (!version) throw new Error("plugin manifest missing version");
+	if (!command) throw new Error("plugin manifest missing command");
+	if (!entry) throw new Error("plugin manifest missing entry");
+	assertCommandName(command);
+	if (command !== slug) throw new Error(`plugin manifest command mismatch (expected ${slug}, got ${command})`);
+	return {
+		slug,
+		packageName,
+		version,
+		command,
+		entry
+	};
+}
+function readPluginManifest(installDir, slug) {
+	return normalizeManifest(slug, readJsonFile(resolveManifestPath(installDir)));
+}
+function writePluginManifest(installDir, manifest) {
+	writeJsonFile(resolveManifestPath(installDir), manifest);
+}
+function deriveManifestFromInstall(installDir, slug) {
+	const pkgPath = path.join(installDir, "package.json");
+	if (!fs.existsSync(pkgPath)) throw new Error(`plugin install missing package.json: ${pkgPath}`);
+	const pkg = readJsonFile(pkgPath);
+	const deps = Object.keys(pkg.dependencies || {});
+	if (deps.length !== 1) throw new Error(`plugin install must declare exactly one dependency (found ${deps.length})`);
+	const packageName = deps[0] || "";
+	if (!packageName) throw new Error("plugin dependency missing");
+	assertPackageName(packageName);
+	const packageDir = resolvePackageDir({
+		installDir,
+		packageName
+	});
+	const meta = readPluginPackageMeta(packageDir);
+	if (meta.command !== slug) throw new Error(`plugin command mismatch: expected ${slug} got ${meta.command}`);
+	const pluginPkgPath = path.join(packageDir, "package.json");
+	const pluginPkg = readJsonFile(pluginPkgPath);
+	const version = String(pluginPkg.version || "").trim();
+	if (!version) throw new Error(`plugin version missing in ${pluginPkgPath}`);
+	return {
+		slug,
+		packageName,
+		version,
+		command: meta.command,
+		entry: meta.entry
+	};
+}
+function listInstalledPlugins(params) {
+	const pluginsDir = resolvePluginsDir(params);
+	if (!fs.existsSync(pluginsDir)) return [];
+	const entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
+	const out = [];
+	for (const ent of entries) {
+		if (!ent.isDirectory()) continue;
+		const slug = ent.name;
+		if (slug.startsWith(".")) continue;
+		try {
+			assertSafeSlug(slug);
+			const installDir = resolveInstallDir({
+				pluginsDir,
+				slug
+			});
+			let manifest;
+			try {
+				manifest = readPluginManifest(installDir, slug);
+			} catch {
+				manifest = deriveManifestFromInstall(installDir, slug);
+				writePluginManifest(installDir, manifest);
+			}
+			const packageDir = resolvePackageDir({
+				installDir,
+				packageName: manifest.packageName
+			});
+			out.push({
+				...manifest,
+				installDir,
+				packageDir
+			});
+		} catch (error) {
+			params.onError?.({
+				slug,
+				error: error instanceof Error ? error : new Error(String(error))
+			});
+			continue;
+		}
+	}
+	return out.sort((a, b) => a.command.localeCompare(b.command));
+}
+function findPluginByCommand(params) {
+	const cmd = params.command.trim();
+	if (!cmd || cmd.startsWith("-") || isReservedCommand(cmd)) return null;
+	return listInstalledPlugins(params).find((p$1) => p$1.command === cmd) || null;
+}
+async function loadPluginCommand(plugin$1) {
+	const entryRel = plugin$1.entry.trim();
+	if (!entryRel) throw new Error(`plugin entry empty for ${plugin$1.command}`);
+	if (path.isAbsolute(entryRel)) throw new Error(`plugin entry must be relative: ${entryRel}`);
+	if (entryRel.split(/[/\\\\]+/).includes("..")) throw new Error(`plugin entry must not contain .. segments: ${entryRel}`);
+	const entryPath = path.resolve(plugin$1.packageDir, entryRel);
+	const entryRelPath = path.relative(plugin$1.packageDir, entryPath);
+	if (entryRelPath.startsWith("..") || path.isAbsolute(entryRelPath)) throw new Error(`plugin entry escapes package: ${entryRel}`);
+	if (!fs.existsSync(entryPath)) throw new Error(`plugin entry missing: ${entryPath}`);
+	const mod = await import(pathToFileURL(entryPath).href);
+	const command = mod.command || mod.plugin?.command || mod.default?.command || mod.default;
+	if (!command) throw new Error(`plugin entry ${entryPath} does not export a command`);
+	return command;
+}
+async function installPlugin(params) {
+	const pluginsDir = resolvePluginsDir(params);
+	const slug = params.slug.trim();
+	if (!slug) throw new Error("plugin name required");
+	assertCommandName(slug);
+	const packageName = params.packageName.trim();
+	if (!packageName) throw new Error("package name required");
+	assertPackageName(packageName);
+	if (!params.allowThirdParty && !packageName.startsWith("@clawdlets/")) throw new Error("third-party plugins disabled (pass --allow-third-party to override)");
+	const installDir = resolveInstallDir({
+		pluginsDir,
+		slug
+	});
+	if (fs.existsSync(installDir) && fs.readdirSync(installDir).length > 0) throw new Error(`plugin already installed: ${slug} (${installDir})`);
+	fs.mkdirSync(installDir, { recursive: true });
+	const depVersion = params.version?.trim() || "latest";
+	const pkgJson = {
+		name: `clawdlets-plugin-${slug}`,
+		private: true,
+		type: "module",
+		description: `clawdlets plugin install (${slug})`,
+		dependencies: { [packageName]: depVersion }
+	};
+	writeJsonFile(path.join(installDir, "package.json"), pkgJson);
+	await run("npm", [
+		"install",
+		"--omit=dev",
+		"--no-audit",
+		"--no-fund"
+	], { cwd: installDir });
+	const manifest = deriveManifestFromInstall(installDir, slug);
+	writePluginManifest(installDir, manifest);
+	const packageDir = resolvePackageDir({
+		installDir,
+		packageName: manifest.packageName
+	});
+	return {
+		...manifest,
+		installDir,
+		packageDir
+	};
+}
+function removePlugin(params) {
+	const pluginsDir = resolvePluginsDir(params);
+	const slug = params.slug.trim();
+	if (!slug) throw new Error("plugin name required");
+	assertSafeSlug(slug);
+	const installDir = resolveInstallDir({
+		pluginsDir,
+		slug
+	});
+	const rel = path.relative(pluginsDir, installDir);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`plugin path escapes plugins dir: ${installDir}`);
+	if (!fs.existsSync(installDir)) throw new Error(`plugin not installed: ${slug}`);
+	fs.rmSync(installDir, {
+		recursive: true,
+		force: true
+	});
+}
+function listReservedCommands() {
+	return [...RESERVED_COMMANDS].sort();
+}
+
 //#endregion
 //#region src/lib/version.ts
 function resolvePackageRoot(fromUrl = import.meta.url) {
@@ -5001,37 +4525,65 @@ const main = defineCommand({
 		name: "clawdlets",
 		description: "Clawdbot fleet helper (CLI-first; runtime state in .clawdlets/; secrets in /secrets)."
 	},
-	subCommands: {
-		bot,
-		bootstrap,
-		cattle,
-		config,
-		doctor,
-		env,
-		host,
-		fleet,
-		image,
-		infra,
-		lockdown,
-		project,
-		secrets,
-		server
-	}
+	subCommands: baseCommands
 });
-{
+function resolveRuntimeDir(rawArgs) {
+	for (let i = 0; i < rawArgs.length; i += 1) {
+		const arg = rawArgs[i] || "";
+		if (arg === "--runtime-dir" || arg === "--runtimeDir") {
+			const next = rawArgs[i + 1];
+			if (next) return String(next);
+		}
+		if (arg.startsWith("--runtime-dir=")) return arg.slice(14);
+		if (arg.startsWith("--runtimeDir=")) return arg.slice(13);
+	}
+}
+function findCommandToken(rawArgs) {
+	for (let i = 0; i < rawArgs.length; i += 1) {
+		const arg = rawArgs[i];
+		if (!arg) continue;
+		if (arg === "--") continue;
+		if (arg === "--runtime-dir" || arg === "--runtimeDir") {
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--runtime-dir=") || arg.startsWith("--runtimeDir=")) continue;
+		if (arg.startsWith("-")) continue;
+		return {
+			index: i,
+			command: arg
+		};
+	}
+	return null;
+}
+async function mainEntry() {
 	const [nodeBin, script, ...rest] = process.argv;
 	const normalized = rest.filter((a) => a !== "--");
 	if (normalized.includes("--version") || normalized.includes("-v")) {
 		console.log(readCliVersion());
 		process.exit(0);
+		return;
 	}
 	process.argv = [
 		nodeBin,
 		script,
 		...normalized
 	];
+	const runtimeDir = resolveRuntimeDir(normalized);
+	const commandToken = findCommandToken(normalized);
+	const command = commandToken?.command ?? "";
+	const pluginMatch = findPluginByCommand({
+		cwd: process.cwd(),
+		runtimeDir,
+		command
+	});
+	if (pluginMatch) {
+		await runMain(await loadPluginCommand(pluginMatch), { rawArgs: commandToken ? normalized.slice(commandToken.index + 1) : [] });
+		return;
+	}
+	await runMain(main);
 }
-runMain(main);
+mainEntry();
 
 //#endregion
 export {  };