impel-cli 0.7.0

package/src/tenants.js

@@ -0,0 +1,194 @@
+import {
+  normalizeGatewayUrl,
+  redactSecretText,
+  resolveDefaultAppUrl,
+  saveConfig,
+} from "./config.js";
+
+export const TENANT_CREDENTIAL_PREFIX = "impel_tenant_";
+export const PRODUCT_ACCESS_WORKSPACE = "workspace";
+export const PRODUCT_ACCESS_GATEWAY = "gateway";
+export const PAT_SCOPE_CLAUDE = "claude-code-gateway";
+export const PAT_SCOPE_CODEX = "codex-gateway";
+export const PAT_SCOPE_TASKS = "tasks";
+const PRODUCT_ACCESS_VALUES = new Set([PRODUCT_ACCESS_WORKSPACE, PRODUCT_ACCESS_GATEWAY]);
+const PROVIDER_SCOPE = Object.freeze({ claude: PAT_SCOPE_CLAUDE, codex: PAT_SCOPE_CODEX });
+const TENANT_ID_RE = /^[A-Za-z0-9_.-]{1,128}$/u;
+const PAT_SCOPE_RE = /^[a-z0-9][a-z0-9:._-]{0,63}$/u;
+
+export function normalizeProductAccess(value, { allowMissing = false } = {}) {
+  if ((value === undefined || value === null || value === "") && allowMissing) return null;
+  const productAccess = String(value || "").trim();
+  if (!PRODUCT_ACCESS_VALUES.has(productAccess)) {
+    throw new Error("tenant API returned an invalid product access value");
+  }
+  return productAccess;
+}
+
+export function productAccessLabel(value) {
+  if (value === PRODUCT_ACCESS_WORKSPACE) return "Workspace member";
+  if (value === PRODUCT_ACCESS_GATEWAY) return "Gateway member";
+  return "Unknown";
+}
+
+export function normalizePatScopes(value, { allowMissing = false } = {}) {
+  if ((value === undefined || value === null) && allowMissing) return null;
+  if (!Array.isArray(value) || value.some((scope) => typeof scope !== "string" || !PAT_SCOPE_RE.test(scope))) {
+    throw new Error("tenant API returned invalid PAT scopes");
+  }
+  return [...new Set(value)];
+}
+
+export function requiredProviderScope(provider) {
+  const scope = PROVIDER_SCOPE[provider];
+  if (!scope) throw new Error(`unsupported gateway provider "${redactSecretText(provider)}"`);
+  return scope;
+}
+
+export function assertProviderScopes(scopes, providers, { requireLive = false } = {}) {
+  if (scopes === null || scopes === undefined) {
+    if (requireLive) {
+      throw new Error("the control plane did not return live PAT scopes; retry after it is upgraded");
+    }
+    return;
+  }
+  const missing = providers
+    .map(requiredProviderScope)
+    .filter((scope) => !scopes.includes(scope));
+  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>\``,
+  );
+}
+
+export function normalizeTenantId(value) {
+  const tenantId = String(value || "").trim();
+  if (!TENANT_ID_RE.test(tenantId) || tenantId === "." || tenantId === "..") {
+    throw new Error(`invalid tenant slug "${redactSecretText(tenantId)}"`);
+  }
+  return tenantId;
+}
+
+function normalizeTenantName(value, fallback) {
+  const sanitized = redactSecretText(String(value || fallback)).trim().slice(0, 256);
+  return sanitized || 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");
+  }
+  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");
+  const appUrl = normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl());
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 7_000);
+  let response;
+  try {
+    response = await fetchImpl(new URL("/api/cli/tenants", appUrl), {
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${config.pat}`,
+      },
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const message = error?.name === "AbortError" ? "request timed out" : error?.message || error;
+    throw new Error(`could not reach ${appUrl}: ${redactSecretText(message)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error(`tenant API returned HTTP ${response.status} without JSON`);
+  }
+  if (!response.ok) {
+    throw new Error(redactSecretText(payload?.error || `tenant API returned HTTP ${response.status}`));
+  }
+  if (!Array.isArray(payload?.tenants) || typeof payload.defaultTenantId !== "string") {
+    throw new Error("tenant API returned an invalid response");
+  }
+  // Older control planes did not return productAccess. Keep discovery usable
+  // during a staged rollout, but never infer a privileged access level here.
+  const productAccess = normalizeProductAccess(payload.productAccess, { allowMissing: true });
+  const scopes = normalizePatScopes(payload.scopes, { allowMissing: true });
+  const tenants = payload.tenants.map((tenant) => {
+    const id = normalizeTenantId(tenant?.id || tenant?.slug);
+    return {
+      id,
+      slug: normalizeTenantId(tenant?.slug || id),
+      name: normalizeTenantName(tenant?.name, id),
+    };
+  });
+  const defaultTenantId = normalizeTenantId(payload.defaultTenantId);
+  if (!tenants.some((tenant) => tenant.id === defaultTenantId)) {
+    throw new Error("tenant API default is not in the available tenant list");
+  }
+  return {
+    tenants,
+    defaultTenantId,
+    patTenantId: payload.patTenantId || null,
+    productAccess,
+    scopes,
+  };
+}
+
+export async function ensureTenantSelection(config, { refresh = false } = {}) {
+  if (!config?.pat) throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  if (config.tenantId && !refresh) {
+    const tenantId = normalizeTenantId(config.tenantId);
+    return {
+      config,
+      tenantId,
+      tenants: null,
+      defaultTenantId: null,
+      productAccess: normalizeProductAccess(config.productAccess, { allowMissing: true }),
+      scopes: normalizePatScopes(config.scopes, { allowMissing: true }),
+    };
+  }
+
+  const listing = await fetchTenants(config);
+  const current = config.tenantId && listing.tenants.some((tenant) => tenant.id === config.tenantId)
+    ? config.tenantId
+    : listing.defaultTenantId;
+  config.tenantId = current;
+  if (listing.productAccess) config.productAccess = listing.productAccess;
+  else delete config.productAccess;
+  if (listing.scopes) config.scopes = listing.scopes;
+  else delete config.scopes;
+  config.tenantsUpdatedAt = new Date().toISOString();
+  saveConfig(config);
+  return {
+    config,
+    tenantId: current,
+    tenants: listing.tenants,
+    defaultTenantId: listing.defaultTenantId,
+    productAccess: listing.productAccess,
+    scopes: listing.scopes,
+  };
+}
+
+export async function selectTenant(config, tenantId) {
+  const selected = normalizeTenantId(tenantId);
+  const listing = await fetchTenants(config);
+  const tenant = listing.tenants.find((candidate) => candidate.id === selected || candidate.slug === selected);
+  if (!tenant) {
+    throw new Error(`tenant "${selected}" is not available to this user`);
+  }
+  config.tenantId = tenant.id;
+  if (listing.productAccess) config.productAccess = listing.productAccess;
+  else delete config.productAccess;
+  if (listing.scopes) config.scopes = listing.scopes;
+  else delete config.scopes;
+  config.tenantsUpdatedAt = new Date().toISOString();
+  saveConfig(config);
+  return { tenant, listing };
+}

package/src/updates.js

@@ -0,0 +1,181 @@
+// Update discovery shared by `impel update`, launch-time notices, and the
+// app-triggered background refresh.
+//
+// impel-cli is distributed as a public npm package. The package contains only
+// the same dependency-free JavaScript users run locally; access to Impel is
+// still enforced by PAT verification and live product/tenant authorization at
+// the control plane and gateway. Update checks therefore use npm's public
+// registry metadata and never require access to the private source repository.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { CONFIG_DIR } from "./config.js";
+
+export const UPDATE_CACHE_PATH = path.join(CONFIG_DIR, "update-check.json");
+export const UPDATE_CHECK_TTL_MS = 6 * 60 * 60 * 1000;
+
+const CLI_ROOT = fileURLToPath(new URL("..", import.meta.url));
+const DEFAULT_UPDATE_PACKAGE = "impel-cli";
+const DEFAULT_UPDATE_REGISTRY = "https://registry.npmjs.org";
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u;
+
+export function updatePackage() {
+  return process.env.IMPEL_UPDATE_PACKAGE || DEFAULT_UPDATE_PACKAGE;
+}
+
+export function updateRegistry() {
+  return String(process.env.IMPEL_UPDATE_REGISTRY || DEFAULT_UPDATE_REGISTRY).replace(/\/+$/u, "");
+}
+
+export function updateInstallSpec() {
+  return `${updatePackage()}@latest`;
+}
+
+export function installedVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(CLI_ROOT, "package.json"), "utf8"));
+    return validVersion(pkg.version) ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function validVersion(value) {
+  return typeof value === "string" && VERSION_RE.test(value);
+}
+
+function prereleaseParts(value) {
+  return value ? value.split(".").map((part) => (/^\d+$/u.test(part) ? Number(part) : part)) : [];
+}
+
+/** True only when `candidate` is a valid semver newer than `current`. */
+export function isNewerVersion(candidate, current) {
+  const next = validVersion(candidate) ? candidate.match(VERSION_RE) : null;
+  const installed = validVersion(current) ? current.match(VERSION_RE) : null;
+  if (!next || !installed) return false;
+
+  for (let index = 1; index <= 3; index += 1) {
+    const difference = Number(next[index]) - Number(installed[index]);
+    if (difference !== 0) return difference > 0;
+  }
+
+  const nextPre = prereleaseParts(next[4]);
+  const installedPre = prereleaseParts(installed[4]);
+  if (nextPre.length === 0 || installedPre.length === 0) {
+    return nextPre.length === 0 && installedPre.length > 0;
+  }
+  const length = Math.max(nextPre.length, installedPre.length);
+  for (let index = 0; index < length; index += 1) {
+    if (nextPre[index] === undefined) return false;
+    if (installedPre[index] === undefined) return true;
+    if (nextPre[index] === installedPre[index]) continue;
+    if (typeof nextPre[index] === "number" && typeof installedPre[index] === "string") return false;
+    if (typeof nextPre[index] === "string" && typeof installedPre[index] === "number") return true;
+    return nextPre[index] > installedPre[index];
+  }
+  return false;
+}
+
+/** Read the latest published version from npm's registry metadata. */
+export async function fetchRemoteVersion({
+  packageName = updatePackage(),
+  registry = updateRegistry(),
+  timeoutMs = 10_000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const encodedName = encodeURIComponent(packageName);
+    const response = await fetchImpl(`${String(registry).replace(/\/+$/u, "")}/${encodedName}/latest`, {
+      headers: { accept: "application/json" },
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    const metadata = await response.json();
+    return validVersion(metadata?.version) ? metadata.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function readUpdateCache() {
+  try {
+    const cache = JSON.parse(fs.readFileSync(UPDATE_CACHE_PATH, "utf8"));
+    return cache && typeof cache === "object" ? cache : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeUpdateCache(patch) {
+  const next = { ...(readUpdateCache() || {}), ...patch };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  const tmp = `${UPDATE_CACHE_PATH}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, UPDATE_CACHE_PATH);
+  return next;
+}
+
+export function cacheIsFresh(cache, now = Date.now()) {
+  return Boolean(cache?.checkedAt && now - cache.checkedAt < UPDATE_CHECK_TTL_MS);
+}
+
+/** Fetch npm's latest version and record it; returns the updated cache (or null). */
+export async function refreshUpdateCache(dependencies = {}) {
+  const fetchLatest = dependencies.fetchRemoteVersion || fetchRemoteVersion;
+  const writeCache = dependencies.writeCache || writeUpdateCache;
+  const remoteVersion = await fetchLatest();
+  if (!remoteVersion) return null;
+  return writeCache({ remoteVersion, checkedAt: Date.now() });
+}
+
+/** One-line human notice when npm has a newer stable package. */
+export function updateNoticeLine({ cache = readUpdateCache(), current = installedVersion() } = {}) {
+  const remote = cache?.remoteVersion;
+  if (!isNewerVersion(remote, current)) return null;
+  return `impel-cli update available (v${current} → v${remote}): run \`impel update\``;
+}
+
+/**
+ * Best-effort, never-blocking update visibility for launch surfaces: print the
+ * cached notice if one applies, and refresh a stale cache in a detached child
+ * so the NEXT launch sees a current answer. TTY-gated — notices are for
+ * humans, and piped/CI invocations must not spawn background work.
+ */
+export function maybePrintUpdateNotice({ stream = process.stderr } = {}) {
+  if (!stream.isTTY) return;
+  if (process.env.IMPEL_SKIP_UPDATE_CHECK === "1" || process.env.IMPEL_SKIP_UPDATE_CHECK === "true") {
+    return;
+  }
+  const cache = readUpdateCache();
+  const line = updateNoticeLine({ cache });
+  if (line) stream.write(`${line}\n`);
+  if (!cacheIsFresh(cache)) spawnDetachedCacheRefresh();
+}
+
+export function spawnDetachedCacheRefresh() {
+  spawnDetached(["update", "--refresh-cache"]);
+}
+
+/** Background config/catalog/skills convergence; no-ops inside the TTL. */
+export function spawnDetachedAppRefresh() {
+  spawnDetached(["app", "refresh", "--stale-only"]);
+}
+
+function spawnDetached(args) {
+  try {
+    const child = spawn(process.execPath, [path.join(CLI_ROOT, "bin", "impel.js"), ...args], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+  } catch {
+    // Purely opportunistic; the next explicit `impel update` still works.
+  }
+}