impel-cli 0.18.1 → 0.18.2

package/README.md

@@ -22,6 +22,11 @@ npm install --global impel-cli
 
 Node.js 18 or newer is required.
 
+On macOS, setup and update verify Apple's Xcode Command Line Tools before any
+profile, app, or skills work begins. If they are missing, Impel opens the
+system installer with `xcode-select --install` and stops safely; finish that
+installation, then rerun the same Impel command.
+
 Then run setup and paste an Impel Personal Access Token when prompted:
 
 ```sh
@@ -35,17 +40,19 @@ surfaces for each tenant. You do not need to repeat setup tenant by tenant.
 
 `impel setup`:
 
-1. Stores the PAT in the private Impel config file.
-2. Fetches the complete live tenant list.
-3. Preserves the current CLI tenant when it is still accessible, or selects the
+1. On macOS, verifies the Xcode Command Line Tools and opens Apple's installer
+   before doing any other setup work when they are missing.
+2. Stores the PAT in the private Impel config file.
+3. Fetches the complete live tenant list.
+4. Preserves the current CLI tenant when it is still accessible, or selects the
    control-plane default.
-4. Creates isolated Claude and Codex CLI profiles for every supported tenant.
-5. On Windows machines without git, installs a pinned, checksum-verified
+5. Creates isolated Claude and Codex CLI profiles for every supported tenant.
+6. On Windows machines without git, installs a pinned, checksum-verified
    MinGit into `~/.config/impel/tools/git` (no admin rights, no system PATH
    change) so Claude and Codex can install the Impel skills marketplace.
-6. Installs or repairs supported tenant desktop apps on macOS and Windows.
-7. Registers tenant apps with Finder/Spotlight or Windows Start/Search.
-8. Verifies every supported tenant surface and prints a tenant-sorted summary.
+7. Installs or repairs supported tenant desktop apps on macOS and Windows.
+8. Registers tenant apps with Finder/Spotlight or Windows Start/Search.
+9. Verifies every supported tenant surface and prints a tenant-sorted summary.
 
 Use `--tenant` only to choose the default for CLI launches. It does not limit
 which tenants setup prepares:
@@ -117,13 +124,15 @@ impel update
 
 Update:
 
-1. Checks and installs the latest `impel-cli` package from npm.
-2. Continues under the freshly installed build.
-3. Fetches the current live tenant list.
-4. Fully prepares tenants added since the previous run.
-5. Repairs and upgrades existing tenants in place.
-6. Re-registers operating-system launch entries.
-7. Reports local tenants that are no longer accessible without deleting them.
+1. On macOS, verifies the Xcode Command Line Tools and opens Apple's installer
+   before doing any other update work when they are missing.
+2. Checks and installs the latest `impel-cli` package from npm.
+3. Continues under the freshly installed build.
+4. Fetches the current live tenant list.
+5. Fully prepares tenants added since the previous run.
+6. Repairs and upgrades existing tenants in place.
+7. Re-registers operating-system launch entries.
+8. Reports local tenants that are no longer accessible without deleting them.
 
 An update preserves histories, browser state, preferences, permissions, stable
 app identity, and user-authored settings outside Impel-managed blocks. Desktop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/apps.js

@@ -726,7 +726,12 @@ export function installManagedAppFiles({
       if (resolvedVendorPaths[target] && isVendableVendorApp(target, resolvedVendorPaths[target])) {
         assertPinnedVendorAppVersion(target, resolvedVendorPaths[target]);
       }
-      if (target === "chatgpt") writeVendoredChatGPTBundle(paths, resolvedVendorPaths.chatgpt, config.gatewayUrl);
+      if (target === "chatgpt") writeVendoredChatGPTBundle(
+        paths,
+        resolvedVendorPaths.chatgpt,
+        config.gatewayUrl,
+        homeDir,
+      );
       else writeVendoredClaudeBundle(
         paths,
         resolvedVendorPaths.claude,
@@ -1561,7 +1566,7 @@ function claudeUsageCompatibilityEnabled(gatewayUrl) {
   }
 }
 
-function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
+function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl, homeDir) {
   if (!vendorPath) throw new Error("ChatGPT/Codex vendor app is unavailable");
   const definition = APP_DEFINITIONS.chatgpt;
   const executableName = definition.executableNames.find((name) => (
@@ -1600,7 +1605,7 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
     const asarHash = asarHeaderHash(runtimeAsarPath);
     const vendorExecutable = path.join(vendorBundle, "Contents", "MacOS", executableName);
     const signingIdentity = resolveVendoredAppSigningIdentity(vendorExecutable);
-    const launchHost = ensureChatGPTLaunchHost();
+    const launchHost = ensureChatGPTLaunchHost({ cacheDir: chatGPTLaunchHostCacheDir(homeDir) });
     writeAtomic(
       path.join(staging, "Contents", "Info.plist"),
       vendoredChatGPTWrapperPlist(vendorPath, asarHash, paths.chatgpt, launchHost ? "launch-host" : "launch"),
@@ -2083,7 +2088,7 @@ export function ensureChatGPTLaunchHost({
   platform = process.platform,
   osRelease = os.release(),
   compiler = "/usr/bin/cc",
-  cacheDir = fileURLToPath(new URL("../cache", import.meta.url)),
+  cacheDir = chatGPTLaunchHostCacheDir(),
   warn = console.warn,
 } = {}) {
   if (platform !== "darwin") return null;
@@ -2127,6 +2132,10 @@ export function ensureChatGPTLaunchHost({
   }
 }
 
+export function chatGPTLaunchHostCacheDir(homeDir = os.homedir()) {
+  return path.join(homeDir, ".config", "impel", "cache", "chatgpt-launch-host");
+}
+
 function vendoredChatGPTWrapperPlist(vendorPath, asarHash, identity, executableName = "launch") {
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

package/src/cli.js

@@ -20,6 +20,7 @@ import { cmdUpdate } from "./commands/update.js";
 import { cmdNuke } from "./commands/nuke.js";
 import { cmdExperimental } from "./commands/experimental.js";
 import { cmdConverge } from "./commands/converge.js";
+import { ensureMacDeveloperTools } from "./macDeveloperTools.js";
 import { refuseElevatedMacExecution } from "./privileges.js";
 
 const HELP = `impel — isolated Impel workspaces for every tenant
@@ -82,6 +83,7 @@ function normalizeTarget(token) {
 
 export async function main(argv) {
   if (refuseElevatedMacExecution(argv)) return;
+  if (!ensureMacDeveloperTools(argv)) return;
   const [cmd, ...rest] = argv;
 
   switch (cmd) {

package/src/macDeveloperTools.js

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+
+const XCODE_SELECT = "/usr/bin/xcode-select";
+
+function hasHelpFlag(argv) {
+  return argv[0] === "help" || argv.slice(1).some((arg) => ["--help", "-h"].includes(arg));
+}
+
+/**
+ * Commands that may clone a skills marketplace or build a managed macOS app.
+ * Read-only commands deliberately stay available while Apple's installer is
+ * pending, and `update --check` keeps its documented no-mutation contract.
+ */
+export function commandRequiresMacDeveloperTools(argv = []) {
+  const [command, subcommand] = argv;
+  if (!command || hasHelpFlag(argv)) return false;
+
+  if (["setup", "_converge"].includes(command)) return true;
+  if (["update", "upgrade"].includes(command)) {
+    return !argv.includes("--check") && !argv.includes("--refresh-cache");
+  }
+  if (["skill", "skills"].includes(command)) return !subcommand || subcommand === "sync";
+  if (["app", "apps"].includes(command)) {
+    return ["install", "update", "open", "refresh"].includes(subcommand);
+  }
+  return false;
+}
+
+/**
+ * Ensure Apple's Command Line Tools are available before Impel mutates any
+ * lifecycle state that depends on git or the native compiler. The Apple
+ * installer runs asynchronously, so a newly requested install must stop this
+ * invocation and let the operator rerun it after installation finishes.
+ */
+export function ensureMacDeveloperTools(argv = [], dependencies = {}) {
+  const io = {
+    platform: process.platform,
+    spawn: spawnSync,
+    log: (message) => console.log(message),
+    error: (message) => console.error(message),
+    setExitCode: (code) => {
+      process.exitCode = code;
+    },
+    ...dependencies,
+  };
+  if (io.platform !== "darwin" || !commandRequiresMacDeveloperTools(argv)) return true;
+
+  const selected = io.spawn(XCODE_SELECT, ["-p"], { stdio: "ignore" });
+  if (!selected.error && selected.status === 0) return true;
+
+  io.log("Xcode Command Line Tools are required; opening Apple's installer…");
+  const requested = io.spawn(XCODE_SELECT, ["--install"], { stdio: "inherit" });
+  if (requested.error) {
+    io.error(`impel: could not start the Xcode Command Line Tools installer (${requested.error.message || requested.error}).`);
+    io.error("  Run `xcode-select --install`, finish the system installation, then rerun this Impel command.");
+  } else if (requested.status !== 0) {
+    io.error("impel: the Xcode Command Line Tools installer did not start successfully.");
+    io.error("  Run `xcode-select --install`, finish the system installation, then rerun this Impel command.");
+  } else {
+    io.error("impel: finish installing the Xcode Command Line Tools in the system dialog, then rerun this command.");
+    io.error("  No Impel profiles, apps, or skills were changed.");
+  }
+  io.setExitCode(1);
+  return false;
+}