impel-cli 0.18.4 → 0.18.5

package/src/runtimeBrand.js

@@ -0,0 +1,140 @@
+import path from "node:path";
+
+const SAFE_ID = /^[a-z][a-z0-9-]{1,63}$/u;
+const SAFE_NAMESPACE = /^[a-z][a-z0-9_-]{1,63}$/u;
+const SAFE_PREFIX = /^[a-z][a-z0-9_]{2,63}_$/u;
+const SAFE_ENV = /^[A-Z][A-Z0-9_]{1,63}$/u;
+const SAFE_TENANT = /^[A-Za-z0-9_.-]{1,128}$/u;
+const SAFE_PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]{0,62}\/)?[a-z0-9][a-z0-9._-]{0,126}$/u;
+const SAFE_BUNDLE_PREFIX = /^[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)+$/u;
+const CONTROL_RE = /[\u0000-\u001F\u007F-\u009F]/u;
+const SUPPORTED_COMMANDS = new Set(["setup", "auth", "pat", "app", "claude", "codex", "status", "token"]);
+
+const DEFAULT = Object.freeze({
+  schemaVersion: 1,
+  product: Object.freeze({ id: "impel", displayName: "Impel" }),
+  cli: Object.freeze({
+    command: "impel",
+    packageName: "impel-cli",
+    configNamespace: "impel",
+    providerId: "impel",
+    managedMarker: "impel-cli",
+    environmentPrefix: "IMPEL",
+  }),
+  auth: Object.freeze({ patPrefix: "impel_pat_", tenantPrefix: "impel_tenant_" }),
+  tenant: Object.freeze({ defaultId: null, displayName: null }),
+  gateway: Object.freeze({ defaultOrigin: "https://gateway.useimpel.com" }),
+  controlPlane: Object.freeze({ defaultOrigin: "https://www.useimpel.com" }),
+  apps: Object.freeze({
+    displayPrefix: "Impel",
+    bundleIdentifierPrefix: "com.useimpel",
+    windowsStartMenuFolder: "Impel",
+  }),
+  capabilities: Object.freeze({ commands: Object.freeze([...SUPPORTED_COMMANDS]), agentPats: true }),
+  features: Object.freeze({ sessions: true, mcp: true, skills: true, agents: true }),
+});
+
+function text(name, value, pattern = null) {
+  if (typeof value !== "string" || !value || value.trim() !== value || value.length > 128 || CONTROL_RE.test(value)) {
+    throw new Error(`impel-cli runtime brand ${name} is invalid`);
+  }
+  if (pattern && !pattern.test(value)) throw new Error(`impel-cli runtime brand ${name} is invalid`);
+  return value;
+}
+
+function origin(name, value) {
+  const parsed = new URL(text(name, value));
+  const local = parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+  if ((parsed.protocol !== "https:" && !local) || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw new Error(`impel-cli runtime brand ${name} must be a bare HTTPS origin`);
+  }
+  return parsed.toString().replace(/\/$/u, "");
+}
+
+function pathSegment(name, value) {
+  const result = text(name, value);
+  if (result === "." || result === ".." || /[\\/:]/u.test(result)) {
+    throw new Error(`impel-cli runtime brand ${name} is invalid`);
+  }
+  return result;
+}
+
+export function validateRuntimeBrand(input) {
+  if (!input || Array.isArray(input) || typeof input !== "object" || input.schemaVersion !== 1) {
+    throw new Error("impel-cli runtime brand schemaVersion must be 1");
+  }
+  const command = text("cli.command", input.cli?.command, SAFE_ID);
+  const packageName = text("cli.packageName", input.cli?.packageName || command, SAFE_PACKAGE);
+  if (path.isAbsolute(packageName)) throw new Error("impel-cli runtime brand cli.packageName is invalid");
+  const defaultTenant = input.tenant?.defaultId == null ? null : text("tenant.defaultId", input.tenant.defaultId, SAFE_TENANT);
+  const requestedCommands = input.capabilities?.commands;
+  if (!Array.isArray(requestedCommands) || requestedCommands.length === 0) {
+    throw new Error("impel-cli runtime brand capabilities.commands must be a non-empty array");
+  }
+  const commands = [...new Set(requestedCommands.map((commandName) => text("capabilities.commands", commandName, SAFE_ID)))];
+  if (commands.some((commandName) => !SUPPORTED_COMMANDS.has(commandName))) {
+    throw new Error("impel-cli runtime brand capabilities.commands contains an unsupported command");
+  }
+  return Object.freeze({
+    schemaVersion: 1,
+    product: Object.freeze({
+      id: text("product.id", input.product?.id, SAFE_ID),
+      displayName: text("product.displayName", input.product?.displayName),
+    }),
+    cli: Object.freeze({
+      command,
+      packageName,
+      configNamespace: text("cli.configNamespace", input.cli?.configNamespace, SAFE_NAMESPACE),
+      providerId: text("cli.providerId", input.cli?.providerId, SAFE_NAMESPACE),
+      managedMarker: text("cli.managedMarker", input.cli?.managedMarker, SAFE_NAMESPACE),
+      environmentPrefix: text("cli.environmentPrefix", input.cli?.environmentPrefix, SAFE_ENV),
+    }),
+    auth: Object.freeze({
+      patPrefix: text("auth.patPrefix", input.auth?.patPrefix, SAFE_PREFIX),
+      tenantPrefix: text("auth.tenantPrefix", input.auth?.tenantPrefix, SAFE_PREFIX),
+    }),
+    tenant: Object.freeze({
+      defaultId: defaultTenant,
+      displayName: input.tenant?.displayName == null ? defaultTenant : text("tenant.displayName", input.tenant.displayName),
+    }),
+    gateway: Object.freeze({ defaultOrigin: origin("gateway.defaultOrigin", input.gateway?.defaultOrigin) }),
+    controlPlane: Object.freeze({ defaultOrigin: origin("controlPlane.defaultOrigin", input.controlPlane?.defaultOrigin) }),
+    apps: Object.freeze({
+      displayPrefix: pathSegment("apps.displayPrefix", input.apps?.displayPrefix || input.product?.displayName),
+      bundleIdentifierPrefix: text("apps.bundleIdentifierPrefix", input.apps?.bundleIdentifierPrefix, SAFE_BUNDLE_PREFIX),
+      windowsStartMenuFolder: pathSegment("apps.windowsStartMenuFolder", input.apps?.windowsStartMenuFolder || input.product?.displayName),
+    }),
+    capabilities: Object.freeze({
+      commands: Object.freeze(commands),
+      agentPats: input.capabilities?.agentPats === true,
+    }),
+    features: Object.freeze({
+      sessions: input.features?.sessions === true,
+      mcp: input.features?.mcp === true,
+      skills: input.features?.skills === true,
+      agents: input.features?.agents === true,
+    }),
+  });
+}
+
+function loadRuntimeBrand() {
+  const encoded = process.env.IMPEL_CLI_RUNTIME_BRAND;
+  if (!encoded) return DEFAULT;
+  let parsed;
+  try { parsed = JSON.parse(encoded); }
+  catch { throw new Error("IMPEL_CLI_RUNTIME_BRAND must contain valid JSON"); }
+  return validateRuntimeBrand(parsed);
+}
+
+export const RUNTIME_BRAND = loadRuntimeBrand();
+
+export function brandedEnvironmentName(suffix) {
+  return `${RUNTIME_BRAND.cli.environmentPrefix}_${suffix}`;
+}
+
+export function brandedText(value) {
+  return String(value)
+    .replaceAll("impel-cli", `${RUNTIME_BRAND.cli.command}-cli`)
+    .replaceAll("Impel", RUNTIME_BRAND.product.displayName)
+    .replaceAll("impel", RUNTIME_BRAND.cli.command);
+}

package/src/selfInvocation.js

@@ -2,9 +2,11 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { environmentValue } from "./nativeProcess.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
 /** The running package's own bin script, used directly for live child spawns. */
-export const IMPEL_CLI_ENTRYPOINT = fileURLToPath(new URL("../bin/impel.js", import.meta.url));
+export const IMPEL_CLI_ENTRYPOINT = process.env.IMPEL_CLI_EXTENSION_ENTRYPOINT
+  || fileURLToPath(new URL("../bin/impel.js", import.meta.url));
 
 // Matches a real package install (npm/pnpm/volta all place the package under
 // node_modules/impel-cli; an unsupported project-local install matches too,
@@ -12,7 +14,9 @@ export const IMPEL_CLI_ENTRYPOINT = fileURLToPath(new URL("../bin/impel.js", imp
 // install). A git checkout or worktree never matches, so development runs
 // keep baking their own path instead of repointing the machine-wide stable
 // entry at a checkout.
-const GLOBAL_INSTALL_RE = /[\\/]node_modules[\\/]impel-cli[\\/]bin[\\/]impel\.js$/iu;
+const escapedPackageName = RUNTIME_BRAND.cli.packageName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&").replaceAll("/", "[\\\\/]");
+const escapedCommand = RUNTIME_BRAND.cli.command.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const GLOBAL_INSTALL_RE = new RegExp(`[\\\\/]node_modules[\\\\/]${escapedPackageName}[\\\\/]bin[\\\\/]${escapedCommand}\\.js$`, "iu");
 
 export function runningFromGlobalInstall(entrypoint = IMPEL_CLI_ENTRYPOINT) {
   return GLOBAL_INSTALL_RE.test(entrypoint);
@@ -22,7 +26,7 @@ export function runningFromGlobalInstall(entrypoint = IMPEL_CLI_ENTRYPOINT) {
 export function windowsStableEntrypointPath(environment = process.env) {
   const localAppData = environmentValue(environment, "LOCALAPPDATA");
   if (typeof localAppData !== "string" || !localAppData.trim()) return null;
-  return path.join(localAppData, "Impel", "bin", "impel-entry.cjs");
+  return path.join(localAppData, RUNTIME_BRAND.apps.windowsStartMenuFolder, "bin", `${RUNTIME_BRAND.cli.command}-entry.cjs`);
 }
 
 /** The directory `impel nuke` removes to erase the stable entry point. */

package/src/shellEntries.js

@@ -9,6 +9,7 @@ import { environmentValue, nativeCommandInvocation, resolveNativeBinary } from "
 import { managedCliEntrypoint } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import { windowsClaudeUserData } from "./windowsApps.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
 const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
 
@@ -42,7 +43,9 @@ export function windowsShortcutArgument(value) {
 export function windowsTenantShortcutName(product, tenantId, tenantName) {
   const id = normalizeTenantId(tenantId);
   const name = safeShortcutSegment(tenantName, id);
-  const label = product === "claude" ? "Impel Claude" : "Impel ChatGPT";
+  const label = product === "claude"
+    ? `${RUNTIME_BRAND.apps.displayPrefix} Claude`
+    : `${RUNTIME_BRAND.apps.displayPrefix} ChatGPT`;
   return `${label} (${name} · ${id}).lnk`;
 }
 
@@ -59,7 +62,7 @@ export function registerWindowsTenantShortcut({
 }) {
   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");
+  const shortcutDirectory = path.win32.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", RUNTIME_BRAND.apps.windowsStartMenuFolder);
   mkdirSync(shortcutDirectory, { recursive: true });
   const shortcutPath = path.win32.join(
     shortcutDirectory,

package/src/stableEntrypoint.js

@@ -7,6 +7,7 @@ import {
   windowsStableEntrypointPath,
 } from "./selfInvocation.js";
 import { redactSecretText } from "./config.js";
+import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
 
 /**
  * Render the stable Windows entry point (`%LOCALAPPDATA%\Impel\bin\impel-entry.cjs`).
@@ -22,12 +23,15 @@ import { redactSecretText } from "./config.js";
  * supported Node (>=18). Output is deterministic for a given baked path.
  */
 export function renderStableEntrypoint(cliEntrypoint = IMPEL_CLI_ENTRYPOINT) {
+  const packageParts = RUNTIME_BRAND.cli.packageName.split("/");
+  const cliSuffixParts = ["node_modules", ...packageParts, "bin", `${RUNTIME_BRAND.cli.command}.js`];
+  const completeInstallFile = RUNTIME_BRAND.cli.packageName === "impel-cli" ? path.join("src", "cli.js") : null;
   return `#!/usr/bin/env node
 "use strict";
-// Managed by impel-cli — stable Impel entry point.
+// Managed by ${RUNTIME_BRAND.cli.command}-cli — stable ${RUNTIME_BRAND.product.displayName} entry point.
 //
-// Vendor apps (Impel Claude, Impel ChatGPT) persist absolute invocations of
-// this file in their managed profiles. It resolves the current impel-cli
+// Vendor apps (${RUNTIME_BRAND.apps.displayPrefix} Claude, ${RUNTIME_BRAND.apps.displayPrefix} ChatGPT) persist absolute invocations of
+// this file in their managed profiles. It resolves the current ${RUNTIME_BRAND.cli.packageName}
 // global install at run time, so replacing or moving the npm global package
 // never strands the invocations baked into those profiles.
 
@@ -37,10 +41,12 @@ const { pathToFileURL } = require("node:url");
 const { spawnSync } = require("node:child_process");
 
 const BAKED_CLI = ${JSON.stringify(cliEntrypoint)};
-const CLI_SUFFIX = path.join("node_modules", "impel-cli", "bin", "impel.js");
+const CLI_SUFFIX = path.join(${cliSuffixParts.map((part) => JSON.stringify(part)).join(", ")});
+const PACKAGE_NAME = ${JSON.stringify(RUNTIME_BRAND.cli.packageName)};
+const REQUIRED_FILE = ${JSON.stringify(completeInstallFile)};
 
 function waitBudgetMs() {
-  const raw = Number.parseInt(process.env.IMPEL_ENTRYPOINT_WAIT_MS || "", 10);
+  const raw = Number.parseInt(process.env.${brandedEnvironmentName("ENTRYPOINT_WAIT_MS")} || "", 10);
   if (Number.isFinite(raw) && raw >= 0) return Math.min(raw, 60000);
   return 8000;
 }
@@ -73,8 +79,8 @@ function isFile(candidate) {
 function isCompleteInstall(cliPath) {
   try {
     const root = path.dirname(path.dirname(cliPath));
-    if (!isFile(cliPath) || !isFile(path.join(root, "src", "cli.js"))) return false;
-    return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).name === "impel-cli";
+    if (!isFile(cliPath) || (REQUIRED_FILE && !isFile(path.join(root, REQUIRED_FILE)))) return false;
+    return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).name === PACKAGE_NAME;
   } catch {
     return false;
   }
@@ -106,8 +112,8 @@ async function main() {
   if (!cli) cli = candidateCliPaths().find(isFile) || null;
   if (!cli) {
     process.stderr.write(
-      "impel-entry: no impel-cli install found (checked " + candidateCliPaths().join("; ") + "). " +
-      "Run \`npm install -g impel-cli\`, then \`impel setup\`.\\n"
+      "${RUNTIME_BRAND.cli.command}-entry: no ${RUNTIME_BRAND.cli.packageName} install found (checked " + candidateCliPaths().join("; ") + "). " +
+      "Run \`npm install -g ${RUNTIME_BRAND.cli.packageName}\`, then \`${RUNTIME_BRAND.cli.command} setup\`.\\n"
     );
     process.exit(1);
   }
@@ -125,7 +131,7 @@ async function main() {
     });
     if (typeof rerun.status === "number") process.exit(rerun.status);
     process.stderr.write(
-      "impel-entry: could not start " + cli + " (" +
+      "${RUNTIME_BRAND.cli.command}-entry: could not start " + cli + " (" +
       (error && error.message ? error.message : String(error)) + ")\\n"
     );
     process.exit(1);
@@ -134,7 +140,7 @@ async function main() {
 
 main().catch((error) => {
   process.stderr.write(
-    "impel-entry: " + (error && error.message ? error.message : String(error)) + "\\n"
+    "${RUNTIME_BRAND.cli.command}-entry: " + (error && error.message ? error.message : String(error)) + "\\n"
   );
   process.exit(1);
 });
@@ -187,7 +193,7 @@ export function ensureWindowsStableEntrypointQuietly(options = {}) {
     return ensureWindowsStableEntrypoint(options);
   } catch (error) {
     console.error(
-      `impel: could not refresh the stable Windows entry point (${redactSecretText(error?.message || error)})`
+      `${RUNTIME_BRAND.cli.command}: could not refresh the stable Windows entry point (${redactSecretText(error?.message || error)})`
     );
     return null;
   }

package/src/tenants.js

@@ -4,8 +4,9 @@ import {
   resolveDefaultAppUrl,
   saveConfig,
 } from "./config.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
-export const TENANT_CREDENTIAL_PREFIX = "impel_tenant_";
+export const TENANT_CREDENTIAL_PREFIX = RUNTIME_BRAND.auth.tenantPrefix;
 export const PRODUCT_ACCESS_WORKSPACE = "workspace";
 export const PRODUCT_ACCESS_IDENTITY = "identity";
 export const PRODUCT_ACCESS_GATEWAY = "gateway";
@@ -85,15 +86,15 @@ function normalizeTenantName(value, fallback) {
 }
 
 export function tenantCredential(pat, tenantId) {
-  if (!String(pat || "").startsWith("impel_pat_")) {
-    throw new Error("an Impel PAT is required to create a tenant credential");
+  if (!String(pat || "").startsWith(RUNTIME_BRAND.auth.patPrefix)) {
+    throw new Error(`a ${RUNTIME_BRAND.product.displayName} PAT is required to create a tenant credential`);
   }
   const encodedTenant = Buffer.from(normalizeTenantId(tenantId), "utf8").toString("base64url");
   return `${TENANT_CREDENTIAL_PREFIX}${encodedTenant}.${pat}`;
 }
 
 export async function fetchTenants(config, fetchImpl = fetch) {
-  if (!config?.pat) throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  if (!config?.pat) throw new Error(`not authenticated; run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} auth\`) first`);
   const appUrl = normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl());
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 7_000);
@@ -141,9 +142,16 @@ export async function fetchTenants(config, fetchImpl = fetch) {
   if (!tenants.some((tenant) => tenant.id === defaultTenantId)) {
     throw new Error("tenant API default is not in the available tenant list");
   }
+  const fixedTenant = RUNTIME_BRAND.tenant.defaultId;
+  const visibleTenants = fixedTenant
+    ? tenants.filter((tenant) => tenant.id === fixedTenant || tenant.slug === fixedTenant)
+    : tenants;
+  if (fixedTenant && visibleTenants.length !== 1) {
+    throw new Error(`the required ${RUNTIME_BRAND.product.displayName} tenant is not available`);
+  }
   return {
-    tenants,
-    defaultTenantId,
+    tenants: visibleTenants,
+    defaultTenantId: fixedTenant ? visibleTenants[0].id : defaultTenantId,
     patTenantId: payload.patTenantId || null,
     productAccess,
     scopes,
@@ -151,7 +159,7 @@ export async function fetchTenants(config, fetchImpl = fetch) {
 }
 
 export async function ensureTenantSelection(config, { refresh = false } = {}) {
-  if (!config?.pat) throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  if (!config?.pat) throw new Error(`not authenticated; run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} auth\`) first`);
   if (config.tenantId && !refresh) {
     const tenantId = normalizeTenantId(config.tenantId);
     return {

package/src/windowsApps.js

@@ -9,6 +9,7 @@ import { pipeline } from "node:stream/promises";
 import { PINNED_VENDOR_APPS } from "./apps.js";
 import { environmentValue, nativeCommandInvocation } from "./nativeProcess.js";
 import { normalizeTenantId } from "./tenants.js";
+import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
 
 export const WINDOWS_CHATGPT_PACKAGE = "9PLM9XGG6VKS";
 export const WINDOWS_CHATGPT_PACKAGE_NAME = "OpenAI.Codex";
@@ -22,7 +23,7 @@ export function windowsClaudeUserData(environment = process.env, tenantId = null
   return path.win32.join(
     localAppData,
     "Claude-3p",
-    "Impel",
+    RUNTIME_BRAND.apps.windowsStartMenuFolder,
     normalizeTenantId(tenantId || "default"),
   );
 }
@@ -85,7 +86,7 @@ function installedMsixChatGPT(environment, run = spawnSync) {
 /** Candidate paths for Anthropic's signed per-user Windows desktop install. */
 export function windowsClaudeAppCandidates(environment = process.env, dependencies = {}) {
   const io = { readDirectory: fs.readdirSync, ...dependencies };
-  const overridden = environmentValue(environment, "IMPEL_CLAUDE_APP_BIN");
+  const overridden = environmentValue(environment, brandedEnvironmentName("CLAUDE_APP_BIN"));
   const localAppData = environmentValue(environment, "LOCALAPPDATA")
     || path.win32.join(environmentValue(environment, "USERPROFILE") || os.homedir(), "AppData", "Local");
   const programFiles = environmentValue(environment, "ProgramFiles");
@@ -114,8 +115,8 @@ export function findWindowsClaudeApp(environment = process.env, dependencies = {
 
 /** Candidate paths for an unpackaged OpenAI ChatGPT/Codex desktop install. */
 export function windowsChatGPTAppCandidates(environment = process.env) {
-  const overridden = environmentValue(environment, "IMPEL_CHATGPT_APP_BIN")
-    || environmentValue(environment, "IMPEL_CODEX_APP_BIN");
+  const overridden = environmentValue(environment, brandedEnvironmentName("CHATGPT_APP_BIN"))
+    || environmentValue(environment, brandedEnvironmentName("CODEX_APP_BIN"));
   const localAppData = environmentValue(environment, "LOCALAPPDATA")
     || path.win32.join(environmentValue(environment, "USERPROFILE") || os.homedir(), "AppData", "Local");
   const programFiles = environmentValue(environment, "ProgramFiles");
@@ -300,8 +301,8 @@ function installPinnedWindowsClaudeMsix(packagePath, environment, pin, architect
 }
 
 function windowsClaudeCacheRoot(homeDir, environment, version, architecture) {
-  const appsRoot = environmentValue(environment, "IMPEL_APP_HOME")
-    || path.join(homeDir, ".config", "impel", "apps");
+  const appsRoot = environmentValue(environment, brandedEnvironmentName("APP_HOME"))
+    || path.join(homeDir, ".config", RUNTIME_BRAND.cli.configNamespace, "apps");
   return path.join(appsRoot, "vendor-cache", "claude", version, architecture);
 }