@vox-ai/cli 0.1.0-beta.8 → 0.1.0-beta.9

package/README.md

@@ -109,14 +109,33 @@ Development and local builds never emit telemetry.
 
 ## Upgrade
 
-`vox upgrade` checks for a newer release and prints the upgrade command for how you installed it — it does not modify your installation itself. Run the printed command (or one of the below) to actually update:
+`vox upgrade` is a package-manager aware upgrade assistant: it detects how vox was installed (npm, Homebrew, standalone, or unknown) and prints the exact upgrade command for that install. It never modifies your installation itself — run the printed command to update.
 
 ```bash
-vox upgrade                              # check for a newer version and print the upgrade command
+vox upgrade                              # detect the install and print the exact upgrade command
+vox upgrade --channel beta               # check the beta channel
+vox upgrade --json                       # structured output for scripts / coding agents
 npm install -g @vox-ai/cli@latest        # update an npm install
 brew upgrade vox-public/tap/vox          # update a Homebrew install
 ```
 
+For Homebrew, `vox upgrade` distinguishes the newest upstream release from what the formula currently offers, so it won't tell you to `brew upgrade` before the formula has caught up. `vox upgrade --json` (schema `vox.ai.cli.upgrade.v2`) returns `status`, `confidence`, `actions`, and `verify_commands` so a coding agent can pick the next command without parsing human text.
+
+### Update notices
+
+vox occasionally checks — at most once a day, when you run a command — whether a newer version is published, and caches the result locally (no daemon, no background process). When an update exists, it prints a single line to stderr on your next interactive run:
+
+```text
+A newer vox.ai CLI is available: 0.1.0-beta.9
+Run `vox upgrade` for the exact upgrade command.
+```
+
+The check only queries the public npm registry — it is not telemetry and sends no account, organization, or auth information. It stays silent for `--json`, non-interactive shells, and CI, and never changes a command's exit code. **Homebrew installs are not nudged by this periodic notice** (npm alone cannot tell whether the formula has published the new version yet) — run `vox upgrade` or `brew outdated` for accurate Homebrew guidance. Turn it off with:
+
+```bash
+VOX_NO_UPDATE_NOTIFIER=1 vox …
+```
+
 ### macOS code signing
 
 Official macOS binaries are signed with the company Developer ID Application identity, with a stable signing identity across builds:

package/bin/vox.cjs

@@ -12,63 +12,94 @@ const platformPackages = {
   "win32-x64": "@vox-ai/cli-win32-x64",
 };
 
-const artifact = `${process.platform}-${process.arch}`;
-const packageName = platformPackages[artifact];
-
-if (!packageName) {
-  console.error(
-    [
-      `vox CLI does not ship a prebuilt npm binary for ${artifact}.`,
-      "Supported platforms: macOS (arm64/x64), Linux x64, and Windows x64. On macOS you can also use the Homebrew formula.",
-    ].join("\n"),
-  );
-  process.exit(1);
+// Build the environment handed to the spawned platform binary. Injecting the
+// install source lets `vox upgrade` report `install_source: "npm"` with high
+// confidence even though the real executable lives under a platform package
+// (@vox-ai/cli-<artifact>/bin/vox[.exe]). Pre-set values win so a parent
+// wrapper / user override is respected.
+function buildSpawnEnv(baseEnv, options) {
+  return {
+    ...baseEnv,
+    VOX_INSTALL_SOURCE: baseEnv.VOX_INSTALL_SOURCE || "npm",
+    VOX_EXECUTABLE_PATH: baseEnv.VOX_EXECUTABLE_PATH || options.scriptPath,
+    VOX_PLATFORM_PACKAGE: baseEnv.VOX_PLATFORM_PACKAGE || options.packageName,
+    VOX_PLATFORM_ARTIFACT: baseEnv.VOX_PLATFORM_ARTIFACT || options.artifact,
+  };
 }
 
-// Bun compiles the Windows binary as `vox.exe`; every other platform ships an
-// extension-less `vox`.
-const binaryName = process.platform === "win32" ? "vox.exe" : "vox";
-let binaryPath;
-
-try {
-  binaryPath = join(dirname(require.resolve(`${packageName}/package.json`)), "bin", binaryName);
-} catch (error) {
-  console.error(
-    [
-      `The platform package ${packageName} is missing.`,
-      "Reinstall @vox-ai/cli without omitting optional dependencies.",
-      "",
-      summarizeError(error),
-    ].filter(Boolean).join("\n"),
-  );
-  process.exit(1);
+function summarizeError(error) {
+  return error && typeof error.message === "string" ? error.message : String(error);
 }
 
-try {
-  chmodSync(binaryPath, 0o755);
-} catch {
-  // Best-effort for tarballs that did not preserve executable mode.
-}
+function main() {
+  const artifact = `${process.platform}-${process.arch}`;
+  const packageName = platformPackages[artifact];
+
+  if (!packageName) {
+    console.error(
+      [
+        `vox CLI does not ship a prebuilt npm binary for ${artifact}.`,
+        "Supported platforms: macOS (arm64/x64), Linux x64, and Windows x64. On macOS you can also use the Homebrew formula.",
+      ].join("\n"),
+    );
+    process.exit(1);
+  }
 
-const child = spawn(binaryPath, process.argv.slice(2), {
-  stdio: "inherit",
-});
+  // Bun compiles the Windows binary as `vox.exe`; every other platform ships an
+  // extension-less `vox`.
+  const binaryName = process.platform === "win32" ? "vox.exe" : "vox";
+  let binaryPath;
 
-child.on("error", (error) => {
-  console.error(`Failed to start vox binary at ${binaryPath}: ${error.message}`);
-  process.exit(1);
-});
+  try {
+    binaryPath = join(dirname(require.resolve(`${packageName}/package.json`)), "bin", binaryName);
+  } catch (error) {
+    console.error(
+      [
+        `The platform package ${packageName} is missing.`,
+        "Reinstall @vox-ai/cli without omitting optional dependencies.",
+        "",
+        summarizeError(error),
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    );
+    process.exit(1);
+  }
 
-child.on("exit", (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
+  try {
+    chmodSync(binaryPath, 0o755);
+  } catch {
+    // Best-effort for tarballs that did not preserve executable mode.
   }
 
-  process.exit(code ?? 1);
-});
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+    env: buildSpawnEnv(process.env, {
+      packageName,
+      artifact,
+      scriptPath: process.argv[1],
+    }),
+  });
 
-function summarizeError(error) {
-  return error && typeof error.message === "string" ? error.message : String(error);
+  child.on("error", (error) => {
+    console.error(`Failed to start vox binary at ${binaryPath}: ${error.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 1);
+  });
 }
 
+module.exports = { buildSpawnEnv, platformPackages };
+
+// Only launch when executed as the bin entry (`vox`), not when imported by a
+// unit test.
+if (require.main === module) {
+  main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vox-ai/cli",
-  "version": "0.1.0-beta.8",
+  "version": "0.1.0-beta.9",
   "description": "vox.ai command-line workflow tools",
   "homepage": "https://www.tryvox.co",
   "license": "MIT",
@@ -13,10 +13,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@vox-ai/cli-darwin-arm64": "0.1.0-beta.8",
-    "@vox-ai/cli-darwin-x64": "0.1.0-beta.8",
-    "@vox-ai/cli-linux-x64": "0.1.0-beta.8",
-    "@vox-ai/cli-win32-x64": "0.1.0-beta.8"
+    "@vox-ai/cli-darwin-arm64": "0.1.0-beta.9",
+    "@vox-ai/cli-darwin-x64": "0.1.0-beta.9",
+    "@vox-ai/cli-linux-x64": "0.1.0-beta.9",
+    "@vox-ai/cli-win32-x64": "0.1.0-beta.9"
   },
   "engines": {
     "node": ">=20.17.0"