impel-cli 0.16.4 → 0.17.0

package/src/sessionHooks.js

@@ -0,0 +1,242 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+
+import { impelCliInvocation } from "./selfInvocation.js";
+
+const MANAGED_MARKER = "--impel-managed-session-hook-v1";
+const CODEX_TRUST_START = "# >>> impel managed session hook trust >>>";
+const CODEX_TRUST_END = "# <<< impel managed session hook trust <<<";
+
+export const CLAUDE_SESSION_EVENTS = Object.freeze([
+  "SessionStart",
+  "UserPromptSubmit",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "SubagentStart",
+  "SubagentStop",
+  "PreCompact",
+  "PostCompact",
+  "Stop",
+  "StopFailure",
+  "SessionEnd",
+]);
+
+export const CODEX_SESSION_EVENTS = Object.freeze([
+  "SessionStart",
+  "UserPromptSubmit",
+  "PostToolUse",
+  "SubagentStart",
+  "SubagentStop",
+  "PreCompact",
+  "PostCompact",
+  "Stop",
+]);
+
+function ensurePrivateDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    // Best effort on platforms where chmod is unavailable.
+  }
+}
+
+function readJsonObject(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const raw = fs.readFileSync(filePath, "utf8").trim();
+  if (!raw) return {};
+  try {
+    const value = JSON.parse(raw);
+    if (!value || Array.isArray(value) || typeof value !== "object") throw new Error();
+    return value;
+  } catch {
+    throw new Error(`${filePath} exists but isn't a valid JSON object. Fix or remove it, then re-run.`);
+  }
+}
+
+function writePrivateJson(filePath, value) {
+  ensurePrivateDirectory(path.dirname(filePath));
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporaryPath, filePath);
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {
+      // Best effort on platforms where chmod is unavailable.
+    }
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // The successful rename already removed the temporary file.
+    }
+  }
+}
+
+function managedInvocation(provider, surface, tenantId) {
+  return impelCliInvocation([
+    "sessions",
+    "hook",
+    "--provider",
+    provider,
+    "--surface",
+    surface,
+    "--tenant",
+    tenantId,
+    MANAGED_MARKER,
+  ]);
+}
+
+function validTenantId(tenantId) {
+  return typeof tenantId === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(tenantId);
+}
+
+function handlerIsManaged(handler) {
+  if (!handler || typeof handler !== "object") return false;
+  if (Array.isArray(handler.args)) return handler.args.includes(MANAGED_MARKER);
+  return typeof handler.command === "string" && handler.command.includes(MANAGED_MARKER);
+}
+
+function mergeEventHook(existing, event, handler) {
+  const groups = Array.isArray(existing?.[event]) ? existing[event] : [];
+  const preserved = [];
+  for (const group of groups) {
+    if (!group || typeof group !== "object") {
+      preserved.push(group);
+      continue;
+    }
+    const hooks = Array.isArray(group.hooks)
+      ? group.hooks.filter((candidate) => !handlerIsManaged(candidate))
+      : [];
+    if (hooks.length > 0 || !Array.isArray(group.hooks)) preserved.push({ ...group, hooks });
+  }
+  preserved.push({ hooks: [handler] });
+  return preserved;
+}
+
+export function ensureClaudeSessionHooks(configDir, tenantId, surface = "claude_cli") {
+  const settingsPath = path.join(configDir, "settings.json");
+  if (!validTenantId(tenantId)) return { settingsPath, events: [], skipped: true };
+  const settings = readJsonObject(settingsPath);
+  const invocation = managedInvocation("claude_code", surface, tenantId);
+  const handler = {
+    type: "command",
+    command: invocation.command,
+    args: invocation.args,
+    timeout: 15,
+    async: true,
+  };
+  const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+    ? { ...settings.hooks }
+    : {};
+  for (const event of CLAUDE_SESSION_EVENTS) hooks[event] = mergeEventHook(hooks, event, handler);
+  settings.hooks = hooks;
+  writePrivateJson(settingsPath, settings);
+  return { settingsPath, events: [...CLAUDE_SESSION_EVENTS] };
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function windowsCommandQuote(value) {
+  const text = String(value);
+  if (/[\r\n\0%]/u.test(text)) throw new Error("cannot safely write this Windows hook command");
+  return `"${text.replaceAll('"', '""')}"`;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+function codexHookHash(event, handler) {
+  const command = process.platform === "win32" && handler.commandWindows
+    ? handler.commandWindows
+    : handler.command;
+  const identity = canonicalize({
+    event_name: event.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toLowerCase(),
+    hooks: [{
+      type: "command",
+      command,
+      timeout: handler.timeout,
+      async: false,
+    }],
+  });
+  return `sha256:${crypto.createHash("sha256").update(JSON.stringify(identity)).digest("hex")}`;
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function replaceManagedTrustBlock(configPath, entries) {
+  const current = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
+  const start = current.indexOf(CODEX_TRUST_START);
+  let without = current;
+  if (start !== -1) {
+    const end = current.indexOf(CODEX_TRUST_END, start);
+    if (end === -1) throw new Error(`${configPath} has an incomplete Impel session-hook trust block`);
+    without = current.slice(0, start) + current.slice(end + CODEX_TRUST_END.length);
+  }
+  const block = [CODEX_TRUST_START];
+  for (const entry of entries) {
+    block.push(
+      `[hooks.state.${tomlString(entry.key)}]`,
+      `trusted_hash = ${tomlString(entry.hash)}`,
+      "",
+    );
+  }
+  block.push(CODEX_TRUST_END);
+  const next = `${without.trimEnd()}${without.trim() ? "\n\n" : ""}${block.join("\n")}\n`;
+  ensurePrivateDirectory(path.dirname(configPath));
+  const temporaryPath = `${configPath}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, next, { mode: 0o600 });
+    fs.renameSync(temporaryPath, configPath);
+    try { fs.chmodSync(configPath, 0o600); } catch { /* Best effort on Windows. */ }
+  } finally {
+    try { fs.rmSync(temporaryPath, { force: true }); } catch { /* Rename removed it. */ }
+  }
+}
+
+export function ensureCodexSessionHooks(codexHome, tenantId, surface = "codex_cli") {
+  const hooksPath = path.join(codexHome, "hooks.json");
+  if (!validTenantId(tenantId)) return { hooksPath, events: [], skipped: true };
+  const document = readJsonObject(hooksPath);
+  const invocation = managedInvocation("codex", surface, tenantId);
+  const unixCommand = [invocation.command, ...invocation.args].map(shellQuote).join(" ");
+  const windowsTokens = [invocation.command, ...invocation.args].map(windowsCommandQuote).join(" ");
+  // Codex executes commandWindows with `cmd.exe /C`. The outer quote preserves
+  // a quoted executable path when it contains spaces.
+  const windowsCommand = `"${windowsTokens}"`;
+  const handler = {
+    type: "command",
+    command: unixCommand,
+    commandWindows: windowsCommand,
+    timeout: 15,
+  };
+  const hooks = document.hooks && typeof document.hooks === "object" && !Array.isArray(document.hooks)
+    ? { ...document.hooks }
+    : {};
+  const trustEntries = [];
+  for (const event of CODEX_SESSION_EVENTS) {
+    hooks[event] = mergeEventHook(hooks, event, handler);
+    const groupIndex = hooks[event].length - 1;
+    trustEntries.push({ event, groupIndex, hash: codexHookHash(event, handler) });
+  }
+  document.hooks = hooks;
+  writePrivateJson(hooksPath, document);
+  const canonicalHooksPath = fs.realpathSync(hooksPath);
+  for (const entry of trustEntries) {
+    entry.key = `${canonicalHooksPath}:${entry.event.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toLowerCase()}:${entry.groupIndex}:0`;
+    delete entry.event;
+    delete entry.groupIndex;
+  }
+  const configPath = path.join(codexHome, "config.toml");
+  replaceManagedTrustBlock(configPath, trustEntries);
+  return { hooksPath, configPath, events: [...CODEX_SESSION_EVENTS], trustEntries };
+}

package/src/shellEntries.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { appPaths, CLAUDE_CONFIG_ID } from "./apps.js";
+import { redactSecretText } from "./config.js";
+import { environmentValue, nativeCommandInvocation, resolveNativeBinary } from "./nativeProcess.js";
+import { IMPEL_CLI_ENTRYPOINT } from "./selfInvocation.js";
+import { normalizeTenantId } from "./tenants.js";
+import { windowsClaudeUserData } from "./windowsApps.js";
+
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+
+function safeShortcutSegment(value, fallback) {
+  const cleaned = String(value || "")
+    .replace(/[<>:"/\\|?*\u0000-\u001F]/gu, " ")
+    .replace(/[. ]+$/gu, "")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, 80);
+  const reserved = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu;
+  return cleaned && !reserved.test(cleaned) ? cleaned : fallback;
+}
+
+function powershellLiteral(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+// Serialize one argv token using the CommandLineToArgvW rules used by native
+// Windows executables. The resulting string is stored in a .lnk Arguments
+// field; no tenant-controlled value is evaluated as PowerShell source.
+export function windowsShortcutArgument(value) {
+  const text = String(value);
+  if (/[\u0000\r\n]/u.test(text)) throw new Error("cannot put a NUL or line break in a Windows shortcut argument");
+  if (text && !/[\s"]/u.test(text)) return text;
+  return `"${text
+    .replace(/(\\*)"/gu, "$1$1\\\"")
+    .replace(/(\\*)$/u, "$1$1")}"`;
+}
+
+export function windowsTenantShortcutName(product, tenantId, tenantName) {
+  const id = normalizeTenantId(tenantId);
+  const name = safeShortcutSegment(tenantName, id);
+  const label = product === "claude" ? "Impel Claude" : "Impel ChatGPT";
+  return `${label} (${name} · ${id}).lnk`;
+}
+
+export function registerWindowsTenantShortcut({
+  product,
+  tenantId,
+  tenantName,
+  environment = process.env,
+  run = spawnSync,
+  execPath = process.execPath,
+  cliEntrypoint = IMPEL_CLI_ENTRYPOINT,
+  iconPath = null,
+  mkdirSync = fs.mkdirSync,
+}) {
+  const appData = environmentValue(environment, "APPDATA");
+  if (!appData) throw new Error("Windows APPDATA is unavailable; Start menu entry was not created");
+  const shortcutDirectory = path.win32.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Impel");
+  mkdirSync(shortcutDirectory, { recursive: true });
+  const shortcutPath = path.win32.join(
+    shortcutDirectory,
+    windowsTenantShortcutName(product, tenantId, tenantName),
+  );
+  const command = [
+    "&",
+    powershellLiteral(execPath),
+    powershellLiteral(cliEntrypoint),
+    powershellLiteral("_app-launch"),
+    powershellLiteral(product),
+    powershellLiteral("--tenant"),
+    powershellLiteral(normalizeTenantId(tenantId)),
+  ].join(" ");
+  const launcherTarget = resolveNativeBinary("powershell", environment, "win32");
+  const launcherArgs = [
+    "-NoLogo",
+    "-NoProfile",
+    "-NonInteractive",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-Command",
+    command,
+  ];
+  const createScript = [
+    "$w=New-Object -ComObject WScript.Shell",
+    "$s=$w.CreateShortcut($env:IMPEL_SHORTCUT_PATH)",
+    "$s.TargetPath=$env:IMPEL_SHORTCUT_TARGET",
+    "$s.Arguments=$env:IMPEL_SHORTCUT_ARGS",
+    "$s.WorkingDirectory=$env:IMPEL_SHORTCUT_WORKDIR",
+    "if($env:IMPEL_SHORTCUT_ICON){$s.IconLocation=$env:IMPEL_SHORTCUT_ICON}",
+    "$s.WindowStyle=7",
+    "$s.Save()",
+  ].join("; ");
+  const powershell = nativeCommandInvocation("powershell", [
+    "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", createScript,
+  ], environment, "win32");
+  const result = run(powershell.command, powershell.args, {
+    encoding: "utf8",
+    env: {
+      ...environment,
+      IMPEL_SHORTCUT_PATH: shortcutPath,
+      IMPEL_SHORTCUT_TARGET: launcherTarget,
+      IMPEL_SHORTCUT_ARGS: launcherArgs.map(windowsShortcutArgument).join(" "),
+      IMPEL_SHORTCUT_WORKDIR: path.win32.dirname(execPath),
+      IMPEL_SHORTCUT_ICON: iconPath || "",
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    windowsVerbatimArguments: powershell.windowsVerbatimArguments,
+  });
+  if (result?.error || result?.status !== 0) {
+    throw new Error(`could not create ${path.win32.basename(shortcutPath)} (${redactSecretText(result?.error?.message || result?.stderr || `exit ${result?.status}`)})`);
+  }
+  return shortcutPath;
+}
+
+function writeShellEntryManifest(manifestPath, entries, {
+  mkdirSync = fs.mkdirSync,
+  writeFileSync = fs.writeFileSync,
+  renameSync = fs.renameSync,
+  rmSync = fs.rmSync,
+} = {}) {
+  mkdirSync(path.dirname(manifestPath), { recursive: true, mode: 0o700 });
+  const temporary = `${manifestPath}.tmp-${process.pid}`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify({
+      schemaVersion: 1,
+      entries: entries.map(({ product, path: entryPath }) => ({ product, path: entryPath })),
+      updatedAt: new Date().toISOString(),
+    }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, manifestPath);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+export function registerTenantShellEntries({
+  tenantId,
+  tenantName,
+  targets = ["claude", "chatgpt"],
+  platform = process.platform,
+  homeDir = os.homedir(),
+  environment = process.env,
+  existsSync = fs.existsSync,
+  run = spawnSync,
+  writeManifest = writeShellEntryManifest,
+  shortcut = registerWindowsTenantShortcut,
+} = {}) {
+  const id = normalizeTenantId(tenantId);
+  const paths = appPaths(homeDir, id, {
+    tenantName,
+    claudeUserData: platform === "win32" ? windowsClaudeUserData(environment, id) : null,
+  });
+  const registered = [];
+  if (platform === "darwin") {
+    for (const product of targets) {
+      const launcher = paths[product].launcher;
+      if (!existsSync(launcher)) throw new Error(`managed launcher is missing: ${launcher}`);
+      const result = run(LSREGISTER, ["-f", launcher], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+      if (result?.error || result?.status !== 0) {
+        throw new Error(`LaunchServices registration failed for ${launcher} (${redactSecretText(result?.error?.message || result?.stderr || `exit ${result?.status}`)})`);
+      }
+      registered.push({ product, path: launcher, status: "ready" });
+    }
+  } else if (platform === "win32") {
+    const available = {
+      claude: existsSync(path.join(paths.claude.userData, "configLibrary", `${CLAUDE_CONFIG_ID}.json`)),
+      chatgpt: existsSync(path.join(paths.chatgpt.codexHome, "config.toml")),
+    };
+    for (const product of targets) {
+      if (!available[product]) throw new Error(`managed ${product} profile is missing for tenant ${id}`);
+      registered.push({
+        product,
+        path: shortcut({ product, tenantId: id, tenantName, environment, run }),
+        status: "ready",
+      });
+    }
+  }
+  if (registered.length) {
+    writeManifest(path.join(paths.tenantRoot, "shell-entries.json"), registered);
+  }
+  return registered;
+}

package/src/skills.js

@@ -409,7 +409,7 @@ export async function syncSkills({
       const first = failures[0];
       logger.warn(
         `impel: skill sync for ${displayLabel} finished with warnings (${first.phase}: ${first.reason}). ` +
-          `Skills may be stale; re-run \`impel skills sync\`.`
+          `Skills may be stale; re-run \`impel update\`.`
       );
       return { client, label: displayLabel, synced: false, marketplaceName, failures };
     }

package/src/tenants.js

@@ -58,7 +58,7 @@ export function assertProviderScopes(scopes, providers, { requireLive = false }
   if (!missing.length) return;
   const labels = missing.map((scope) => `"${scope}"`).join(" and ");
   throw new Error(
-    `this PAT is missing the ${labels} scope${missing.length === 1 ? "" : "s"}; create a fresh PAT in Impel Gateway setup, then run \`impel auth --pat <pat>\``,
+    `this PAT is missing the ${labels} scope${missing.length === 1 ? "" : "s"}; create a fresh PAT in Impel Gateway setup, then run \`impel setup\` and provide it`,
   );
 }