impel-cli 0.7.0

package/src/nativeProcess.js

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const WINDOWS_DEFAULT_PATH_EXTENSIONS = [".COM", ".EXE", ".BAT", ".CMD"];
+const WINDOWS_BATCH_EXTENSION_RE = /\.(?:bat|cmd)$/iu;
+const WINDOWS_BARE_COMMAND_RE = /^[A-Za-z0-9_.-]+$/u;
+const WINDOWS_SHELL_META_RE = /([()\][%!^"`<>&|;, *?])/gu;
+const WINDOWS_UNSAFE_LINE_RE = /[\u0000\r\n]/u;
+
+function pathApi(platform) {
+  return platform === "win32" ? path.win32 : path;
+}
+
+function pathDelimiter(platform) {
+  return platform === "win32" ? ";" : path.delimiter;
+}
+
+export function environmentValue(environment, name) {
+  if (environment[name] !== undefined) return environment[name];
+  const key = Object.keys(environment).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+  return key ? environment[key] : undefined;
+}
+
+function isExecutable(filePath, platform = process.platform) {
+  try {
+    if (!fs.statSync(filePath).isFile()) return false;
+    if (platform !== "win32") fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function windowsPathExtensions(environment) {
+  const configured = String(environmentValue(environment, "PATHEXT") || "")
+    .split(";")
+    .map((extension) => extension.trim())
+    .filter(Boolean)
+    .map((extension) => (extension.startsWith(".") ? extension : `.${extension}`));
+  return configured.length ? configured : WINDOWS_DEFAULT_PATH_EXTENSIONS;
+}
+
+function binaryCandidates(directory, tool, environment, platform) {
+  const paths = pathApi(platform);
+  const base = paths.join(directory, tool);
+  if (platform !== "win32" || paths.extname(tool)) return [base];
+  // Windows npm distributions include extensionless Unix companion scripts
+  // beside the executable shims. They are regular files but CreateProcess
+  // cannot run them, so only PATHEXT candidates are valid on Windows.
+  return windowsPathExtensions(environment).map((extension) => `${base}${extension}`);
+}
+
+function overrideName(tool) {
+  if (tool === "claude") return "IMPEL_CLAUDE_BIN";
+  if (tool === "codex") return "IMPEL_CODEX_BIN";
+  if (tool === "npm") return "IMPEL_NPM_BIN";
+  return null;
+}
+
+function stripPathEntryQuotes(entry) {
+  const trimmed = entry.trim();
+  return trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')
+    ? trimmed.slice(1, -1)
+    : trimmed;
+}
+
+function expandWindowsEnvironmentVariables(value, environment) {
+  return value.replace(/%([^%]+)%/gu, (match, name) => environmentValue(environment, name) ?? match);
+}
+
+function commonCandidates(tool, environment, platform) {
+  const paths = pathApi(platform);
+  const home = environmentValue(environment, "USERPROFILE") || environmentValue(environment, "HOME") || os.homedir();
+  const locations = [];
+
+  if (tool === "claude") {
+    locations.push(
+      [paths.join(home, ".local", "bin"), "claude"],
+      [paths.join(home, ".claude", "local"), "claude"],
+    );
+  }
+
+  if (platform === "win32") {
+    const appData = environmentValue(environment, "APPDATA");
+    const localAppData = environmentValue(environment, "LOCALAPPDATA");
+    const nvmSymlink = environmentValue(environment, "NVM_SYMLINK");
+    const programFiles = environmentValue(environment, "ProgramFiles");
+    const nodeDirectory = path.win32.isAbsolute(process.execPath)
+      ? path.win32.dirname(process.execPath)
+      : null;
+
+    // npm's default global prefix on Windows. This also finds the vendor CLIs
+    // immediately after installation when the parent PowerShell process has a
+    // stale PATH value.
+    if ((tool === "claude" || tool === "codex") && appData) {
+      locations.push([paths.join(appData, "npm"), tool]);
+    }
+
+    // Official standalone Codex installs live here. Claude's official native
+    // installer uses ~/.local/bin, which is covered above.
+    if (tool === "codex" && localAppData) {
+      locations.push([paths.join(localAppData, "Programs", "OpenAI", "Codex", "bin"), "codex"]);
+    }
+
+    // npm itself normally sits beside node.exe. Include the common Node and
+    // NVM locations so setup/update do not depend on PATH normalization.
+    if (tool === "npm") {
+      if (nodeDirectory) locations.push([nodeDirectory, "npm"]);
+      if (nvmSymlink) locations.push([nvmSymlink, "npm"]);
+      if (programFiles) locations.push([paths.join(programFiles, "nodejs"), "npm"]);
+    }
+  }
+
+  return locations.flatMap(([directory, name]) => binaryCandidates(directory, name, environment, platform));
+}
+
+/** Resolve a real executable/shim if one is installed, otherwise return null. */
+export function findNativeBinary(tool, environment = process.env, platform = process.platform) {
+  const override = overrideName(tool);
+  const overriddenBinary = override ? environmentValue(environment, override) : null;
+  if (overriddenBinary) return isExecutable(overriddenBinary, platform) ? overriddenBinary : null;
+
+  for (const rawDirectory of String(environmentValue(environment, "PATH") || "").split(pathDelimiter(platform))) {
+    const expandedDirectory = platform === "win32"
+      ? expandWindowsEnvironmentVariables(rawDirectory, environment)
+      : rawDirectory;
+    const directory = stripPathEntryQuotes(expandedDirectory);
+    if (!directory) continue;
+    for (const candidate of binaryCandidates(directory, tool, environment, platform)) {
+      if (isExecutable(candidate, platform)) return candidate;
+    }
+  }
+
+  return commonCandidates(tool, environment, platform).find((candidate) => isExecutable(candidate, platform)) || null;
+}
+
+/** Resolve an executable for launch, preserving explicit overrides and useful ENOENT errors. */
+export function resolveNativeBinary(tool, environment = process.env, platform = process.platform) {
+  const override = overrideName(tool);
+  const overriddenBinary = override ? environmentValue(environment, override) : null;
+  return overriddenBinary || findNativeBinary(tool, environment, platform) || tool;
+}
+
+// Windows cannot execute npm's .cmd/.bat shims directly. This is the escaping
+// strategy used by cross-spawn, inlined here to keep the CLI dependency-free.
+// Arguments are quoted individually and command metacharacters are escaped
+// twice because npm shims forward them through `%*`, causing a second parse.
+function escapeWindowsBatchCommand(value) {
+  return String(value).replace(WINDOWS_SHELL_META_RE, "^$1");
+}
+
+export function escapeWindowsBatchArgument(value) {
+  let escaped = String(value);
+  if (WINDOWS_UNSAFE_LINE_RE.test(escaped)) {
+    throw new Error("cannot safely forward an argument containing a NUL or line break through a Windows batch shim");
+  }
+  escaped = escaped.replace(/(?=(\\+?)?)\1"/gu, "$1$1\\\"");
+  escaped = escaped.replace(/(?=(\\+?)?)\1$/gu, "$1$1");
+  escaped = `"${escaped}"`;
+  escaped = escaped.replace(WINDOWS_SHELL_META_RE, "^$1");
+  return escaped.replace(WINDOWS_SHELL_META_RE, "^$1");
+}
+
+export function nativeSpawnInvocation(binary, argv, environment = process.env, platform = process.platform) {
+  const bareWindowsCommand = (
+    platform === "win32"
+    && WINDOWS_BARE_COMMAND_RE.test(binary)
+    && path.win32.basename(binary) === binary
+  );
+  if (platform !== "win32" || (!WINDOWS_BATCH_EXTENSION_RE.test(binary) && !bareWindowsCommand)) {
+    return { command: binary, args: argv, windowsVerbatimArguments: false };
+  }
+  if (WINDOWS_UNSAFE_LINE_RE.test(binary)) {
+    throw new Error("cannot safely launch a Windows batch shim whose path contains a NUL or line break");
+  }
+  const shellCommand = [
+    escapeWindowsBatchCommand(pathApi(platform).normalize(binary)),
+    ...argv.map(escapeWindowsBatchArgument),
+  ].join(" ");
+  return {
+    command: environmentValue(environment, "ComSpec") || "cmd.exe",
+    args: ["/d", "/s", "/v:off", "/c", `"${shellCommand}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
+/** Resolve a PATH command and produce a spawn-safe invocation for this platform. */
+export function nativeCommandInvocation(tool, argv, environment = process.env, platform = process.platform) {
+  const binary = resolveNativeBinary(tool, environment, platform);
+  return { binary, ...nativeSpawnInvocation(binary, argv, environment, platform) };
+}

package/src/prompt.js

@@ -0,0 +1,51 @@
+// Minimal stdlib-only prompt helpers (no inquirer/prompts dependency).
+
+import readline from "node:readline";
+
+/**
+ * Prompts on the TTY with the typed characters masked as `*`.
+ * Falls back to a plain (unmasked) prompt when stdin isn't a TTY
+ * (e.g. piped input in CI), since there's nothing to mask there anyway.
+ */
+export function promptSecret(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: process.stdin.isTTY,
+    });
+
+    if (process.stdin.isTTY) {
+      // Intercept the internal write so keystrokes render as `*` instead of
+      // the real character. This is the standard trick for masked prompts
+      // with plain `readline` (no external deps).
+      const rlInternal = /** @type {any} */ (rl);
+      const originalWrite = rlInternal._writeToOutput?.bind(rlInternal);
+      if (originalWrite) {
+        rlInternal._writeToOutput = (stringToWrite) => {
+          if (stringToWrite === question) {
+            originalWrite(stringToWrite);
+            return;
+          }
+          originalWrite("*".repeat(stringToWrite.length));
+        };
+      }
+    }
+
+    rl.question(question, (answer) => {
+      rl.close();
+      process.stdout.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+
+export function promptText(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}

package/src/selfInvocation.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from "node:url";
+
+/** Stable entry point used by managed subprocess configs, including on Windows. */
+export const IMPEL_CLI_ENTRYPOINT = fileURLToPath(new URL("../bin/impel.js", import.meta.url));
+
+export function impelCliInvocation(args = []) {
+  return {
+    command: process.execPath,
+    args: [IMPEL_CLI_ENTRYPOINT, ...args],
+  };
+}
+
+export const IMPEL_MANAGED_MCP_ENV = "IMPEL_MANAGED_MCP";
+
+export function impelMcpInvocation(args = []) {
+  return {
+    type: "stdio",
+    ...impelCliInvocation(["mcp", ...args]),
+    env: { [IMPEL_MANAGED_MCP_ENV]: "1" },
+  };
+}

package/src/skills.js

@@ -0,0 +1,314 @@
+// Syncs Impel's Bifrost shared-skills marketplace into the managed Claude Code
+// and Codex clients. The Bifrost gateway exposes a PUBLIC (unauthenticated)
+// skills registry that bundles every served skill into a single plugin named
+// `bifrost-all-skills`, published through per-client marketplaces:
+//
+//   Claude Code: <gateway>/api/skills/serve/claude-code/.claude-plugin/marketplace.json
+//   Codex source: <gateway>/api/skills/serve/codex
+//     manifest:   <source>/.agents/plugins/marketplace.json
+//
+// `syncSkills` is idempotent: it registers the marketplace, ensures
+// `bifrost-all-skills` is installed, then runs the refresh commands so an
+// already-installed plugin picks up a newer bundle. It NEVER throws — every
+// failure degrades to a warning so the install/update path that called it keeps
+// going.
+//
+// The two clients expose different plugin verbs (confirmed against the shipped
+// CLIs, July 2026):
+//   - Claude Code: `plugin marketplace add|update`, `plugin install`, `plugin update`
+//   - Codex:       `plugin marketplace add|upgrade`, `plugin add` (install + refresh)
+// so we keep a per-client command table rather than assuming one shape.
+
+import { spawnSync } from "node:child_process";
+
+import { resolveDefaultGateway, normalizeGatewayUrl } from "./config.js";
+import { nativeCommandInvocation } from "./nativeProcess.js";
+
+/** The bundled plugin the Bifrost registry publishes; contains every served skill. */
+export const SKILL_PLUGIN_NAME = "bifrost-all-skills";
+
+/** Final fallback only — prefer the configured gateway (see resolveSkillsGateway). */
+export const SKILLS_FALLBACK_GATEWAY_URL = "https://gateway.useimpel.ai";
+
+// Benign, expected non-zero outcomes when re-running an idempotent sync. Codex
+// and Claude both exit non-zero when a marketplace/plugin is already present, so
+// these must not be reported as real failures.
+const BENIGN_OUTPUT = /already (exist|install|add|present|configur)|up[ -]?to[ -]?date|no changes|nothing to (do|update)/i;
+
+const CLIENT_SPECS = {
+  claude: {
+    bin: "claude",
+    label: "Claude Code",
+    marketplacePath: "/api/skills/serve/claude-code/.claude-plugin/marketplace.json",
+    marketplaceSourcePath: "/api/skills/serve/claude-code/.claude-plugin/marketplace.json",
+  },
+  codex: {
+    bin: "codex",
+    label: "Codex",
+    marketplacePath: "/api/skills/serve/codex/.agents/plugins/marketplace.json",
+    marketplaceSourcePath: "/api/skills/serve/codex",
+  },
+};
+
+/** Public marketplace manifest URL used to resolve the registered name. */
+export function marketplaceUrl(gatewayUrl, client) {
+  const spec = CLIENT_SPECS[client];
+  if (!spec) throw new Error(`unknown skills client "${client}"`);
+  return `${normalizeGatewayUrl(gatewayUrl)}${spec.marketplacePath}`;
+}
+
+/**
+ * Public source accepted by the client's marketplace registration command.
+ * Claude accepts its manifest URL; Codex clones the Git repository root and
+ * discovers `.agents/plugins/marketplace.json` inside it.
+ */
+export function marketplaceSourceUrl(gatewayUrl, client) {
+  const spec = CLIENT_SPECS[client];
+  if (!spec) throw new Error(`unknown skills client "${client}"`);
+  return `${normalizeGatewayUrl(gatewayUrl)}${spec.marketplaceSourcePath}`;
+}
+
+/** The registered marketplace name, read from a fetched marketplace.json (its `name`). */
+export function resolveMarketplaceName(marketplace) {
+  const name = marketplace?.name;
+  return typeof name === "string" && name.trim() ? name.trim() : null;
+}
+
+/**
+ * Resolve the gateway URL for skill serving. Reuses the CLI's configured gateway
+ * (the caller passes `config.gatewayUrl`), then the env/default from config.js,
+ * and only as a last resort the hardcoded fallback.
+ */
+export function resolveSkillsGateway(explicit) {
+  let base = explicit && String(explicit).trim() ? explicit : null;
+  if (!base) {
+    try {
+      base = resolveDefaultGateway();
+    } catch {
+      base = null;
+    }
+  }
+  return normalizeGatewayUrl(base || SKILLS_FALLBACK_GATEWAY_URL);
+}
+
+/**
+ * Build the ordered, idempotent command list (argv after the client binary) for
+ * a client. When the marketplace name is unknown (fetch failed), commands that
+ * strictly need it are dropped and installs fall back to a bare plugin id.
+ */
+export function buildSkillCommands({ client, marketplaceSourceUrl: sourceUrl, marketplaceName }) {
+  const spec = CLIENT_SPECS[client];
+  if (!spec) throw new Error(`unknown skills client "${client}"`);
+  const plugin = SKILL_PLUGIN_NAME;
+  const name = marketplaceName || null;
+  const commands = [
+    { phase: "register", description: "register marketplace", args: ["plugin", "marketplace", "add", sourceUrl] },
+  ];
+
+  if (client === "claude") {
+    // Claude resolves a bare plugin id across all marketplaces, so install works
+    // even without the name; @name just pins the source when we know it.
+    commands.push({
+      phase: "install",
+      description: `install ${plugin}`,
+      args: ["plugin", "install", name ? `${plugin}@${name}` : plugin],
+    });
+    if (name) {
+      commands.push({
+        phase: "refresh-marketplace",
+        description: "refresh marketplace",
+        args: ["plugin", "marketplace", "update", name],
+      });
+    }
+    commands.push({
+      phase: "refresh-plugin",
+      description: `update ${plugin}`,
+      // Claude registers the plugin under PLUGIN@MARKETPLACE; the bare name is
+      // "not found" once installed from a named marketplace.
+      args: ["plugin", "update", name ? `${plugin}@${name}` : plugin],
+    });
+  } else {
+    // Codex's `plugin add` requires a marketplace (PLUGIN@MARKETPLACE). Without a
+    // name we can only best-effort a bare add; with a name we install, upgrade
+    // the snapshot, and re-add to pin the refreshed bundle.
+    if (name) {
+      commands.push({
+        phase: "install",
+        description: `install ${plugin}`,
+        args: ["plugin", "add", `${plugin}@${name}`],
+      });
+      commands.push({
+        phase: "refresh-marketplace",
+        description: "refresh marketplace",
+        args: ["plugin", "marketplace", "upgrade", name],
+      });
+      commands.push({
+        phase: "refresh-plugin",
+        description: `update ${plugin}`,
+        args: ["plugin", "add", `${plugin}@${name}`],
+      });
+    } else {
+      commands.push({
+        phase: "install",
+        description: `install ${plugin}`,
+        args: ["plugin", "add", plugin],
+      });
+    }
+  }
+
+  return commands;
+}
+
+/** Default command runner: spawns the client binary non-interactively. */
+function defaultRun(bin, args, env) {
+  const environment = { ...process.env, ...env };
+  let invocation;
+  try {
+    invocation = nativeCommandInvocation(bin, args, environment);
+  } catch (error) {
+    return {
+      ok: false,
+      missing: false,
+      status: null,
+      stdout: "",
+      stderr: error?.message || String(error),
+    };
+  }
+  const result = spawnSync(invocation.command, invocation.args, {
+    env: environment,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 120000,
+    windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+  });
+  if (result.error) {
+    return {
+      ok: false,
+      missing: result.error.code === "ENOENT",
+      status: null,
+      stdout: "",
+      stderr: result.error.message || String(result.error),
+    };
+  }
+  return {
+    ok: result.status === 0,
+    missing: false,
+    status: result.status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+}
+
+function firstLine(text) {
+  return String(text || "").split(/\r?\n/).map((line) => line.trim()).find(Boolean) || "";
+}
+
+function isBenign(result) {
+  return result.ok || BENIGN_OUTPUT.test(`${result.stdout}\n${result.stderr}`);
+}
+
+/** Fetch the marketplace.json and return its registered name, or null on any failure. */
+export async function fetchMarketplaceName(url, fetchImpl = fetch) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 10000);
+  try {
+    const response = await fetchImpl(url, { signal: controller.signal });
+    if (!response?.ok) return null;
+    const payload = await response.json();
+    return resolveMarketplaceName(payload);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Idempotently sync the Bifrost shared-skills plugin into one managed client
+ * profile. Targets the SAME binary + profile the caller manages by passing the
+ * relevant `env` overrides (e.g. `CODEX_HOME` for a Codex profile,
+ * `CLAUDE_CONFIG_DIR` for an isolated Claude profile). Never throws.
+ *
+ * @returns {Promise<{client, label, synced?, skipped?, reason?, marketplaceName?, failures?}>}
+ */
+export async function syncSkills({
+  client,
+  gatewayUrl,
+  env = {},
+  label,
+  fetchImpl = fetch,
+  run = defaultRun,
+  logger = console,
+} = {}) {
+  const spec = CLIENT_SPECS[client];
+  if (!spec) {
+    logger.warn(`impel: cannot sync skills for unknown client "${client}".`);
+    return { client, label: label || String(client), skipped: true, reason: "unknown-client" };
+  }
+  const displayLabel = label || spec.label;
+
+  // Escape hatch for offline/CI/enterprise use: skip all skill syncing.
+  if (process.env.IMPEL_SKIP_SKILL_SYNC === "1" || process.env.IMPEL_SKIP_SKILL_SYNC === "true") {
+    return { client, label: displayLabel, skipped: true, reason: "disabled" };
+  }
+
+  try {
+    // Confirm the binary and its `plugin` subcommand exist before doing anything.
+    const help = run(spec.bin, ["plugin", "--help"], env);
+    if (help.missing) {
+      logger.warn(`impel: skipping skill sync for ${displayLabel} — \`${spec.bin}\` CLI not found on PATH.`);
+      return { client, label: displayLabel, skipped: true, reason: "binary-missing" };
+    }
+    if (!help.ok) {
+      logger.warn(`impel: skipping skill sync for ${displayLabel} — \`${spec.bin}\` has no \`plugin\` command (update the CLI).`);
+      return { client, label: displayLabel, skipped: true, reason: "no-plugin-subcommand" };
+    }
+
+    const manifestUrl = marketplaceUrl(gatewayUrl, client);
+    const sourceUrl = marketplaceSourceUrl(gatewayUrl, client);
+    const marketplaceName = await fetchMarketplaceName(manifestUrl, fetchImpl);
+    const commands = buildSkillCommands({ client, marketplaceSourceUrl: sourceUrl, marketplaceName });
+
+    logger.log(`Skills: syncing ${SKILL_PLUGIN_NAME} for ${displayLabel}…`);
+    const failures = [];
+    for (const command of commands) {
+      const result = run(spec.bin, command.args, env);
+      if (result.missing) {
+        failures.push({ phase: command.phase, reason: `\`${spec.bin}\` disappeared mid-sync` });
+        break;
+      }
+      if (!isBenign(result)) {
+        failures.push({ phase: command.phase, reason: firstLine(result.stderr) || `exit ${result.status}` });
+      }
+    }
+
+    if (failures.length > 0) {
+      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\`.`
+      );
+      return { client, label: displayLabel, synced: false, marketplaceName, failures };
+    }
+
+    logger.log(`Skills: ${displayLabel} up to date (${SKILL_PLUGIN_NAME}${marketplaceName ? ` via ${marketplaceName}` : ""}).`);
+    return { client, label: displayLabel, synced: true, marketplaceName };
+  } catch (error) {
+    logger.warn(`impel: skill sync for ${displayLabel} failed (${error?.message || error}); continuing.`);
+    return { client, label: displayLabel, synced: false, reason: "error" };
+  }
+}
+
+/**
+ * Convenience wrapper used by install/update call sites: awaits syncSkills and
+ * swallows any unexpected rejection so the parent command can never fail because
+ * of skill syncing.
+ */
+export async function syncSkillsSafe(options) {
+  try {
+    return await syncSkills(options);
+  } catch (error) {
+    (options?.logger || console).warn(`impel: skill sync error (${error?.message || error}); continuing.`);
+    return { synced: false, reason: "error" };
+  }
+}