@latitude-data/openclaw-telemetry 0.0.2 → 0.0.4

package/dist/cli.js

@@ -1,15 +1,141 @@
 #!/usr/bin/env node
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { cancel, confirm, intro, isCancel, log, note, outro, password, spinner, text } from "@clack/prompts";
 import pc from "picocolors";
-import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
+//#region src/openclaw-cli.ts
+/**
+* Lowest OpenClaw version we support. The reporter verified hook-dispatch
+* gating works correctly here; older versions either reject
+* `hooks.allowConversationAccess` outright (≤ 2026.4.21) or have unverified
+* gating behaviour (2026.4.22 – 2026.4.24). Refusing to install on older
+* versions is intentional — we'd rather fail loudly than ship a
+* config the gateway will quarantine or hooks the dispatcher will block.
+*/
+const MIN_OPENCLAW_VERSION = "2026.4.25";
+const DEFAULT_TIMEOUT_MS = 1e4;
+/**
+* Spawn `openclaw <args>` synchronously. Reports failure modes structurally so
+* callers can decide how to degrade (missing binary vs. timed out vs. exited
+* non-zero). Never throws; ENOENT becomes `{ reason: "enoent" }`.
+*/
+function runOpenclaw(args, opts = {}) {
+	const result = spawnSync("openclaw", args, {
+		encoding: "utf-8",
+		timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		input: opts.stdin,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	});
+	const err = result.error;
+	if (err?.code === "ENOENT") return {
+		ok: false,
+		reason: "enoent",
+		stdout: "",
+		stderr: "",
+		code: null
+	};
+	if (err?.code === "ETIMEDOUT" || result.signal === "SIGTERM" || result.signal === "SIGKILL") return {
+		ok: false,
+		reason: "timeout",
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? "",
+		code: null
+	};
+	if (err) return {
+		ok: false,
+		reason: "exit",
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? String(err),
+		code: typeof result.status === "number" ? result.status : 1
+	};
+	if (result.status === 0) return {
+		ok: true,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? "",
+		code: 0
+	};
+	return {
+		ok: false,
+		reason: "exit",
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? "",
+		code: typeof result.status === "number" ? result.status : 1
+	};
+}
+/**
+* Run `openclaw --version` and parse out the version string.
+*
+* Banner format (per OpenClaw `src/cli/banner.ts` `formatCliBannerLine`):
+*   `🦞 OpenClaw <version> (<commit-sha>)`
+*
+* The banner is normally suppressed when `--version` is the flag, but the
+* version itself still goes to stdout. We accept either layout (with or
+* without the lobster + commit sha) so we don't break if OpenClaw later
+* prints just the bare version string.
+*/
+function getOpenclawVersion() {
+	const result = runOpenclaw(["--version"], { timeoutMs: 5e3 });
+	if (!result.ok) {
+		if (result.reason === "enoent") return {
+			ok: false,
+			error: "missing"
+		};
+		return {
+			ok: false,
+			error: "unparseable",
+			raw: result.stdout || result.stderr
+		};
+	}
+	const raw = result.stdout.trim();
+	const match = raw.match(/(\d{4}\.\d+\.\d+)/);
+	if (!match) return {
+		ok: false,
+		error: "unparseable",
+		raw
+	};
+	return {
+		ok: true,
+		version: match[1],
+		raw
+	};
+}
+/**
+* Compare two CalVer strings (`YYYY.M.PATCH`). Returns -1 if `a` < `b`,
+* 0 if equal, 1 if `a` > `b`. Strings with extra components or non-numeric
+* pieces fall back to a per-component string comparison so unexpected
+* formats don't crash the installer.
+*/
+function compareCalver(a, b) {
+	const ap = a.split(".");
+	const bp = b.split(".");
+	const len = Math.max(ap.length, bp.length);
+	for (let i = 0; i < len; i++) {
+		const ai = ap[i] ?? "0";
+		const bi = bp[i] ?? "0";
+		const an = Number(ai);
+		const bn = Number(bi);
+		if (Number.isFinite(an) && Number.isFinite(bn)) {
+			if (an < bn) return -1;
+			if (an > bn) return 1;
+			continue;
+		}
+		if (ai < bi) return -1;
+		if (ai > bi) return 1;
+	}
+	return 0;
+}
+//#endregion
 //#region src/settings-file.ts
 const CONFIG_DIR = join(homedir(), ".openclaw");
 const SETTINGS_PATH = join(CONFIG_DIR, "openclaw.json");
 const SETTINGS_BACKUP_PATH = join(CONFIG_DIR, "openclaw.json.latitude-bak");
-const PLUGIN_INSTALL_DIR = join(join(CONFIG_DIR, "extensions"), "latitude-telemetry");
 /** Plugin id used both as the npm package name and as the OpenClaw plugin id. */
 const PLUGIN_ID = "@latitude-data/openclaw-telemetry";
 function readSettings() {
@@ -29,22 +155,38 @@ function backupSettings() {
 	if (existsSync(SETTINGS_PATH)) copyFileSync(SETTINGS_PATH, SETTINGS_BACKUP_PATH);
 }
 /**
-* Set the `plugins.entries[id]` block for our plugin. Writes credentials and
-* options into the `.config` bucket — never under `hooks` (strict zod) and
-* never as top-level `env` keys (root schema rejects them).
+* Set the `plugins.entries[id]` block for our plugin.
+*
+* Two places in the entry get written:
+*
+*   - `.config` (free-form `record(string, unknown)`): credentials, baseUrl,
+*     and our copy of `allowConversationAccess`. This is what the plugin
+*     runtime reads via `api.pluginConfig`.
+*   - `.hooks.allowConversationAccess`: controls whether OpenClaw's hook
+*     dispatcher actually forwards `llm_input` / `llm_output` / tool /
+*     `agent_end` events to our handlers. Without it set to `true` on
+*     OpenClaw 2026.4.25+, every typed hook is blocked at the dispatcher
+*     and the plugin's handlers never fire.
+*
+* The two flags mean different things — `hooks.*` is the dispatch gate,
+* `config.*` is the payload-content gate — but for THIS plugin we always
+* couple them: dispatch off + payload on is useless (no payloads to gate),
+* and dispatch on + payload off is a legitimate "structural-only telemetry"
+* mode (timing, tokens, ids, agent name; no message bodies). Always writing
+* both from the same source keeps the operator's mental model simple.
 *
 * Re-install idempotency: only `apiKey` / `project` / `baseUrl` always
-* overwrite (these come from the install prompts). `enabled`, `debug`, and
-* `allowConversationAccess` are preserved when not provided in the patch,
-* so a user who hand-edited `enabled: false` or `debug: true` doesn't lose
-* their choice on a re-install.
+* overwrite (these come from install prompts). `enabled`, `debug`, and
+* `allowConversationAccess` are preserved when not provided in the patch.
 */
 function setPluginEntry(settings, patch) {
 	const plugins = settings.plugins ?? {};
 	const entries = plugins.entries ?? {};
 	const existing = entries["@latitude-data/openclaw-telemetry"] ?? {};
+	const existingConfig = existing.config ?? {};
+	const existingHooks = existing.hooks ?? {};
 	const nextConfig = {
-		...existing.config ?? {},
+		...existingConfig,
 		apiKey: patch.apiKey,
 		project: patch.project
 	};
@@ -52,16 +194,22 @@ function setPluginEntry(settings, patch) {
 	else delete nextConfig.baseUrl;
 	if (patch.allowConversationAccess !== void 0) nextConfig.allowConversationAccess = patch.allowConversationAccess;
 	if (patch.debug !== void 0) nextConfig.debug = patch.debug;
+	const effectiveAccess = typeof nextConfig.allowConversationAccess === "boolean" ? nextConfig.allowConversationAccess : typeof existingHooks.allowConversationAccess === "boolean" ? existingHooks.allowConversationAccess : true;
+	const nextHooks = {
+		...existingHooks,
+		allowConversationAccess: effectiveAccess
+	};
 	const nextEnabled = patch.enabled ?? existing.enabled ?? true;
 	entries[PLUGIN_ID] = {
 		...existing,
 		enabled: nextEnabled,
+		hooks: nextHooks,
 		config: nextConfig
 	};
 	plugins.entries = entries;
 	settings.plugins = plugins;
 }
-/** Remove the plugin entry entirely. */
+/** Remove the plugin entry entirely. Used by uninstall as defense-in-depth. */
 function removePluginEntry(settings) {
 	const plugins = settings.plugins;
 	if (!plugins?.entries) return false;
@@ -69,26 +217,58 @@ function removePluginEntry(settings) {
 	delete plugins.entries[PLUGIN_ID];
 	return true;
 }
+/**
+* Add the plugin id to `plugins.allow`. Idempotent — returns `true` only when
+* the array changed. OpenClaw warns at every gateway start when a non-bundled
+* plugin auto-loads without provenance via `plugins.allow` or an install
+* record. We get one warning cleared by going through `openclaw plugins
+* install` (provenance) and the other by adding ourselves to allow.
+*
+* Defensive against hand-edited non-array values: if `plugins.allow` is
+* present but not an array (e.g. someone wrote a string), we replace it
+* with a single-element array rather than spreading the bad value.
+*/
+function addToPluginsAllow(settings) {
+	const plugins = settings.plugins ?? {};
+	const existing = plugins.allow;
+	const allow = Array.isArray(existing) ? existing : [];
+	if (allow.includes("@latitude-data/openclaw-telemetry")) return false;
+	plugins.allow = [...allow, PLUGIN_ID];
+	settings.plugins = plugins;
+	return true;
+}
+/**
+* Inverse of `addToPluginsAllow`. Defense-in-depth — `openclaw plugins
+* uninstall` already strips the entry, but the install path can be skipped
+* (e.g. the user removed the plugin manually) and we want re-install/uninstall
+* round-trips to be tidy regardless.
+*/
+function removeFromPluginsAllow(settings) {
+	const allow = settings.plugins?.allow;
+	if (!Array.isArray(allow) || !allow.includes("@latitude-data/openclaw-telemetry")) return false;
+	if (settings.plugins) settings.plugins.allow = allow.filter((id) => id !== PLUGIN_ID);
+	return true;
+}
 function hasLatitudePlugin(settings) {
 	return Boolean(settings.plugins?.entries && "@latitude-data/openclaw-telemetry" in settings.plugins.entries);
 }
 /**
-* Strip any leftover top-level keys our older installer (<= 0.0.1) wrote. The
-* 0.0.1 installer wrote `hooks.allowConversationAccess` (rejected by strict
-* zod) and `LATITUDE_*` keys at root-level `env` (also rejected). Both are
-* cleaned up here so re-running install lands a config OpenClaw will validate.
+* Strip leftover keys from older installers that the strict zod schema
+* rejects on current OpenClaw versions.
+*
+* 0.0.1 wrote `LATITUDE_*` keys directly under `settings.env`. OpenClaw's
+* root schema is strict; the `env` block accepts only `{shellEnv, vars}`,
+* so those keys cause the gateway to quarantine the config as
+* `clobbered.<ts>` and roll back. We sweep them on every install.
+*
+* Note: 0.0.1 also wrote `hooks.allowConversationAccess` (when that key was
+* not yet in the schema). We deliberately do NOT strip it anymore — on
+* OpenClaw 2026.4.25+ the key IS in the schema and IS load-bearing for
+* dispatch. `setPluginEntry` overwrites it on every install with the right
+* value, so any 0.0.1 leftover is reconciled there.
 */
 function migrateLegacyEntries(settings) {
 	let changed = false;
-	const entry = settings.plugins?.entries?.[PLUGIN_ID];
-	if (entry && typeof entry === "object") {
-		const hooks = entry.hooks;
-		if (hooks && typeof hooks === "object" && "allowConversationAccess" in hooks) {
-			delete hooks.allowConversationAccess;
-			if (Object.keys(hooks).length === 0) delete entry.hooks;
-			changed = true;
-		}
-	}
 	const env = settings.env;
 	if (env && typeof env === "object" && !Array.isArray(env)) {
 		const envObj = env;
@@ -105,62 +285,6 @@ function migrateLegacyEntries(settings) {
 	return { changed };
 }
 //#endregion
-//#region src/install-files.ts
-/**
-* Copies the plugin's runtime files into `~/.openclaw/extensions/latitude-telemetry/`
-* so OpenClaw's discovery (`<configDir>/extensions/<plugin>`) picks it up.
-*
-* `npx -y @latitude-data/openclaw-telemetry` runs the CLI from a temporary npm
-* location — relying on that path persisting across runs (or even across the
-* gateway restart that follows install) is unsafe. So we materialize a stable
-* copy under the user's OpenClaw config dir, the same path OpenClaw scans on
-* startup. Layout we produce:
-*
-*   ~/.openclaw/extensions/latitude-telemetry/
-*     openclaw.plugin.json   <- the manifest, required by discovery
-*     package.json           <- minimal — keeps node module-resolution happy
-*     dist/                  <- compiled plugin entrypoint(s)
-*/
-function installPluginFiles() {
-	const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-	const manifestSrc = join(packageRoot, "openclaw.plugin.json");
-	const distSrc = join(packageRoot, "dist");
-	const pkgSrc = join(packageRoot, "package.json");
-	if (!existsSync(manifestSrc)) throw new Error(`Cannot install: missing openclaw.plugin.json at ${manifestSrc}. This is a packaging bug — please file an issue.`);
-	if (!existsSync(distSrc)) throw new Error(`Cannot install: missing compiled dist at ${distSrc}.`);
-	if (existsSync(PLUGIN_INSTALL_DIR)) rmSync(PLUGIN_INSTALL_DIR, {
-		recursive: true,
-		force: true
-	});
-	mkdirSync(PLUGIN_INSTALL_DIR, { recursive: true });
-	copyFileSync(manifestSrc, join(PLUGIN_INSTALL_DIR, "openclaw.plugin.json"));
-	cpSync(distSrc, join(PLUGIN_INSTALL_DIR, "dist"), { recursive: true });
-	if (existsSync(pkgSrc)) {
-		const sourcePkg = JSON.parse(readFileSync(pkgSrc, "utf-8"));
-		const minimalPkg = {
-			name: sourcePkg.name,
-			version: sourcePkg.version,
-			type: sourcePkg.type ?? "module",
-			main: sourcePkg.main ?? "./dist/plugin.js",
-			private: true
-		};
-		writeFileSync(join(PLUGIN_INSTALL_DIR, "package.json"), `${JSON.stringify(minimalPkg, null, 2)}\n`, "utf-8");
-	}
-	return {
-		destination: PLUGIN_INSTALL_DIR,
-		entryPath: join(PLUGIN_INSTALL_DIR, "dist", "plugin.js")
-	};
-}
-/** Remove the materialized plugin directory under `~/.openclaw/extensions/`. */
-function removePluginFiles() {
-	if (!existsSync(PLUGIN_INSTALL_DIR)) return false;
-	rmSync(PLUGIN_INSTALL_DIR, {
-		recursive: true,
-		force: true
-	});
-	return true;
-}
-//#endregion
 //#region src/setup.ts
 const DOCS_URL = "https://docs.latitude.so/openclaw-telemetry";
 const PRODUCTION_ENV = {
@@ -217,6 +341,7 @@ function normalizeInstallFlags(flags) {
 		project: typeof flags.project === "string" ? flags.project : void 0,
 		environment,
 		allowConversationAccess,
+		noTrust: flags["no-trust"] === true,
 		noPrompt: flags["no-prompt"] === true || flags.yes === true,
 		yes: flags.yes === true
 	};
@@ -227,6 +352,7 @@ async function runInstall(flags = {}) {
 }
 async function runInteractiveInstall(flags) {
 	intro(pc.bgCyan(pc.black(" Latitude · OpenClaw telemetry ")));
+	ensureOpenclawIsCompatible();
 	const existingConfig = readSettings().plugins?.entries?.["@latitude-data/openclaw-telemetry"]?.config ?? void 0;
 	const envConfig = flags.environment ?? PRODUCTION_ENV;
 	const urls = urlsFor(envConfig);
@@ -247,7 +373,8 @@ async function runInteractiveInstall(flags) {
 		apiKey,
 		project,
 		envConfig,
-		allowConversationAccess: flags.allowConversationAccess
+		allowConversationAccess: flags.allowConversationAccess,
+		noTrust: flags.noTrust === true
 	});
 	note([
 		"Restart the OpenClaw gateway for the plugin to load:",
@@ -258,6 +385,7 @@ async function runInteractiveInstall(flags) {
 	outro(pc.green("✓ Installed"));
 }
 async function runFlagDrivenInstall(flags) {
+	ensureOpenclawIsCompatible();
 	const apiKey = flags.apiKey;
 	const project = flags.project;
 	if (!apiKey || !project) throw new Error("Non-interactive install requires --api-key=... and --project=... (or run in a TTY).");
@@ -265,10 +393,10 @@ async function runFlagDrivenInstall(flags) {
 		apiKey,
 		project,
 		envConfig: flags.environment ?? PRODUCTION_ENV,
-		allowConversationAccess: flags.allowConversationAccess
+		allowConversationAccess: flags.allowConversationAccess,
+		noTrust: flags.noTrust === true
 	});
 	process.stdout.write(`Installed Latitude plugin in ${SETTINGS_PATH}\n`);
-	process.stdout.write(`Plugin files at ${PLUGIN_INSTALL_DIR}\n`);
 }
 async function promptApiKey(_existing, flag) {
 	if (flag) return flag;
@@ -295,48 +423,92 @@ function onCancel() {
 	cancel("Cancelled — nothing was changed");
 	process.exit(1);
 }
-async function applyChanges({ apiKey, project, envConfig, allowConversationAccess }) {
-	const filesSpinner = spinner();
-	filesSpinner.start("Installing plugin files");
-	const { destination } = installPluginFiles();
-	filesSpinner.stop(`Plugin files installed at ${destination}`);
-	const settingsSpinner = spinner();
-	settingsSpinner.start("Updating openclaw.json");
+async function applyChanges({ apiKey, project, envConfig, allowConversationAccess, noTrust }) {
 	ensureSettingsDir();
 	backupSettings();
+	const packageRoot = resolvePackageRoot();
+	const installSpinner = spinner();
+	installSpinner.start(`Installing plugin via openclaw plugins install ${packageRoot}`);
+	const installResult = runOpenclaw([
+		"plugins",
+		"install",
+		packageRoot,
+		"--force"
+	], { timeoutMs: 6e4 });
+	if (!installResult.ok) {
+		installSpinner.stop("openclaw plugins install failed");
+		if (installResult.reason === "enoent") throw new Error("`openclaw` not found on PATH. Install OpenClaw first (https://openclaw.ai/install) and re-run.");
+		if (installResult.reason === "timeout") throw new Error("openclaw plugins install timed out after 60s. Try running it manually to see what's stuck.");
+		const detail = installResult.stderr.trim() || installResult.stdout.trim() || `exit code ${installResult.code}`;
+		throw new Error(`openclaw plugins install failed: ${detail}`);
+	}
+	installSpinner.stop("Plugin registered with OpenClaw");
+	const settingsSpinner = spinner();
+	settingsSpinner.start("Updating openclaw.json");
 	const settings = readSettings();
 	migrateLegacyEntries(settings);
-	const existingConfig = settings.plugins?.entries?.["@latitude-data/openclaw-telemetry"]?.config ?? {};
-	const finalAllowConversationAccess = allowConversationAccess ?? existingConfig.allowConversationAccess ?? true;
 	setPluginEntry(settings, {
 		apiKey,
 		project,
 		baseUrl: envConfig.name === "production" ? void 0 : envConfig.ingest,
-		allowConversationAccess: finalAllowConversationAccess
+		allowConversationAccess
 	});
+	if (!noTrust) addToPluginsAllow(settings);
 	writeSettings(settings);
 	settingsSpinner.stop(`Updated ${SETTINGS_PATH}`);
 	if (existsSync(SETTINGS_BACKUP_PATH)) log.info(`Backup saved at ${pc.dim(SETTINGS_BACKUP_PATH)}`);
+	if (noTrust) log.warning(`--no-trust set; OpenClaw will warn at every gateway start that ${PLUGIN_ID} is untrusted. Add it to plugins.allow yourself when you're ready.`);
 }
 function ensureSettingsDir() {
 	const dir = dirname(SETTINGS_PATH);
 	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
+/**
+* Verify `openclaw` is on PATH AND its version is >= MIN_OPENCLAW_VERSION.
+* Aborts with a clear upgrade message otherwise. Called before any user
+* prompts so we don't waste their time collecting credentials we can't
+* use.
+*/
+function ensureOpenclawIsCompatible() {
+	const v = getOpenclawVersion();
+	if (!v.ok) {
+		if (v.error === "missing") {
+			cancel("OpenClaw CLI not found on PATH. Install or update via `npm install -g openclaw@latest` and re-run.");
+			process.exit(1);
+		}
+		cancel(`Couldn't parse OpenClaw version output${v.raw ? ` (got: ${pc.dim(v.raw)})` : ""}. Run \`openclaw --version\` and report the output.`);
+		process.exit(1);
+	}
+	if (compareCalver(v.version, "2026.4.25") < 0) {
+		cancel(`OpenClaw ${v.version} is older than the minimum supported version (${MIN_OPENCLAW_VERSION}). Run \`npm install -g openclaw@latest\` and re-run install.`);
+		process.exit(1);
+	}
+	log.info(`OpenClaw ${pc.dim(v.version)} (>= ${MIN_OPENCLAW_VERSION})`);
+}
+/**
+* Resolve the absolute path to our package's root (the directory that
+* contains `package.json` + `openclaw.plugin.json` + `dist/`). The compiled
+* CLI lives at `<package-root>/dist/cli.js`, so `import.meta.url`'s parent
+* directory's parent is our root.
+*
+* `openclaw plugins install <path>` copies files synchronously, so we
+* don't have to keep this directory alive past the spawn return.
+*/
+function resolvePackageRoot() {
+	return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
 async function runUninstall(flags = {}) {
 	intro(pc.bgYellow(pc.black(" Latitude · OpenClaw telemetry — uninstall ")));
-	const settings = readSettings();
-	const hasEntry = hasLatitudePlugin(settings);
-	const hasFiles = existsSync(PLUGIN_INSTALL_DIR);
-	if (!hasEntry && !hasFiles) {
-		note("No Latitude plugin entry or files found — nothing to remove.", "Status");
+	if (!hasLatitudePlugin(readSettings())) {
+		note("No Latitude plugin entry found — nothing to remove.", "Status");
 		outro(pc.dim("Nothing changed"));
 		return;
 	}
 	note([
-		hasEntry ? `Remove "${PLUGIN_ID}" plugin entry from ${SETTINGS_PATH}` : null,
-		hasFiles ? `Delete plugin files at ${PLUGIN_INSTALL_DIR}` : null,
+		`Run \`openclaw plugins uninstall ${PLUGIN_ID} --force\` (removes files, install record, and plugin entry)`,
+		`Sweep any leftover LATITUDE_* keys from settings.env`,
 		`Backup of openclaw.json saved at ${SETTINGS_BACKUP_PATH}`
-	].filter(Boolean).join("\n"), "Plan");
+	].join("\n"), "Plan");
 	if (!flags.noPrompt && process.stdin.isTTY === true) {
 		const ok = await confirm({
 			message: "Proceed?",
@@ -344,22 +516,71 @@ async function runUninstall(flags = {}) {
 		});
 		if (isCancel(ok) || ok !== true) return onCancel();
 	}
+	backupSettings();
 	const s = spinner();
-	s.start("Reverting settings");
-	if (hasEntry) {
-		backupSettings();
-		removePluginEntry(settings);
-		migrateLegacyEntries(settings);
-		writeSettings(settings);
-	}
-	if (hasFiles) removePluginFiles();
-	s.stop("Done");
+	s.start("Reverting via openclaw plugins uninstall");
+	const uninstallResult = runOpenclaw([
+		"plugins",
+		"uninstall",
+		PLUGIN_ID,
+		"--force"
+	], { timeoutMs: 6e4 });
+	if (!uninstallResult.ok) {
+		s.stop("openclaw plugins uninstall failed");
+		if (uninstallResult.reason === "enoent") log.warning("`openclaw` not found on PATH. Falling back to local cleanup — files at ~/.openclaw/extensions/ may remain.");
+		else {
+			const detail = uninstallResult.stderr.trim() || uninstallResult.stdout.trim() || `exit code ${uninstallResult.code}`;
+			log.warning(`openclaw plugins uninstall reported: ${detail}. Continuing with local cleanup.`);
+		}
+	} else s.stop("Plugin removed by OpenClaw");
+	const cleanupSpinner = spinner();
+	cleanupSpinner.start("Reverting openclaw.json");
+	const post = readSettings();
+	removePluginEntry(post);
+	removeFromPluginsAllow(post);
+	migrateLegacyEntries(post);
+	writeSettings(post);
+	cleanupSpinner.stop("Done");
 	outro(pc.green("✓ Uninstalled"));
 }
 //#endregion
 //#region src/cli.ts
+const USAGE = `usage: latitude-openclaw <command> [options]
+
+commands:
+  install               Install the plugin (interactive when stdin is a TTY)
+  uninstall             Remove the plugin entry and files
+  --version, -v         Print the package version
+  --help, -h            Print this message
+
+install options:
+  --api-key=<key>       Pass the API key non-interactively
+  --project=<slug>      Pass the project slug non-interactively
+  --staging             Target https://staging.latitude.so / staging-ingest
+  --dev                 Target http://localhost:3000 / 3002
+  --no-content          Skip raw prompt/response/tool I/O capture
+  --allow-conversation  Force conversation capture on (overrides existing config)
+  --yes / --no-prompt   Skip all prompts (required for non-TTY / CI)
+`;
+function readVersion() {
+	const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+	try {
+		return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+}
 async function main() {
-	const { subcommand, flags } = parseFlags(process.argv.slice(2));
+	const argv = process.argv.slice(2);
+	if (argv[0] === "--version" || argv[0] === "-v") {
+		process.stdout.write(`${readVersion()}\n`);
+		return;
+	}
+	if (argv[0] === "--help" || argv[0] === "-h") {
+		process.stdout.write(USAGE);
+		return;
+	}
+	const { subcommand, flags } = parseFlags(argv);
 	if (subcommand === "install" || subcommand === void 0) {
 		await runInstall(normalizeInstallFlags(flags));
 		return;
@@ -369,7 +590,7 @@ async function main() {
 		return;
 	}
 	process.stderr.write(`unknown subcommand: ${subcommand}\n`);
-	process.stderr.write("usage: latitude-openclaw [install|uninstall] [--api-key=...] [--project=...] [--staging|--dev] [--yes]\n");
+	process.stderr.write(USAGE);
 	process.exit(1);
 }
 main().catch((err) => {