@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/src/commands/connect/import.ts

@@ -3,24 +3,20 @@
  *
  * Import a pairing bundle printed by `vellum pair` on another machine and
  * register it locally so `vellum client`/`message`/`events <name>` work against
- * the remote assistant.
- *
- * The bundle is base64(JSON.stringify({ gatewayUrl, assistantId, token,
- * deviceId })). We store the entry under a UNIQUE LOCAL id (not the bundle's
- * assistantId, which is typically "self" and would collide across hosts). This
- * is safe because the gateway's runtime proxy strips the `/v1/assistants/<id>/`
- * segment before forwarding, so the local id never has to match the remote one
- * — the token (validated by signature/audience) is what authorizes requests.
+ * the remote assistant. Decoding, id derivation, and the lockfile/token writes
+ * live in `pairAssistant` (`@vellumai/local-mode`); this command owns only the
+ * argv parsing and output copy.
  */
 
-import { nanoid } from "nanoid";
+import {
+  decodePairBundle,
+  pairAssistant,
+  resolveConfigDir,
+} from "@vellumai/local-mode";
 
 import { extractFlag } from "../../lib/arg-utils.js";
-import {
-  findAssistantByName,
-  saveAssistantEntry,
-} from "../../lib/assistant-config.js";
-import { saveGuardianToken } from "../../lib/guardian-token.js";
+import { getLockfilePaths } from "../../lib/environments/paths.js";
+import { getCurrentEnvironment } from "../../lib/environments/resolve.js";
 
 function printUsage(): void {
   console.log(`vellum connect import - Register an assistant paired from another machine
@@ -41,85 +37,6 @@ EXAMPLES:
 `);
 }
 
-interface PairBundle {
-  gatewayUrl: string;
-  token: string;
-  assistantId?: string;
-  deviceId?: string;
-  // Optional refresh credential. Present when the host's gateway issued a
-  // device-bound token pair; absent for older access-only bundles (which remain
-  // importable, just without auto-renewal). `refreshTokenExpiresAt` mirrors
-  // GuardianTokenData (ISO string OR epoch-ms number) so a numeric expiry isn't
-  // silently dropped on import.
-  refreshToken?: string;
-  refreshTokenExpiresAt?: string | number;
-  refreshAfter?: string;
-}
-
-/** Decode the base64 bundle, returning null if malformed or missing fields. */
-function decodeBundle(blob: string): PairBundle | null {
-  let json: unknown;
-  try {
-    json = JSON.parse(Buffer.from(blob, "base64").toString("utf8"));
-  } catch {
-    return null;
-  }
-  if (typeof json !== "object" || json === null) return null;
-  const b = json as Record<string, unknown>;
-  if (typeof b.gatewayUrl !== "string" || typeof b.token !== "string") {
-    return null;
-  }
-  // The gatewayUrl is persisted as runtimeUrl and used to build fetch URLs, so
-  // require an absolute http(s) URL here rather than letting an invalid string
-  // through (which would crash `new URL(...)` or break later client calls).
-  try {
-    const parsed = new URL(b.gatewayUrl);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-      return null;
-    }
-  } catch {
-    return null;
-  }
-  return {
-    gatewayUrl: b.gatewayUrl,
-    token: b.token,
-    assistantId: typeof b.assistantId === "string" ? b.assistantId : undefined,
-    deviceId: typeof b.deviceId === "string" ? b.deviceId : undefined,
-    refreshToken:
-      typeof b.refreshToken === "string" ? b.refreshToken : undefined,
-    refreshTokenExpiresAt:
-      typeof b.refreshTokenExpiresAt === "string" ||
-      typeof b.refreshTokenExpiresAt === "number"
-        ? b.refreshTokenExpiresAt
-        : undefined,
-    refreshAfter:
-      typeof b.refreshAfter === "string" ? b.refreshAfter : undefined,
-  };
-}
-
-/** Lowercase, collapse non-alphanumerics to single dashes, trim dashes. */
-function slugify(name: string): string {
-  return name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
-/** Best-effort JWT `exp` (epoch seconds) → epoch ms; null if undecodable. */
-function jwtExpiryMs(token: string): number | null {
-  const parts = token.split(".");
-  if (parts.length !== 3) return null;
-  try {
-    const payload = JSON.parse(
-      Buffer.from(parts[1], "base64").toString("utf8"),
-    );
-    if (typeof payload.exp === "number") return payload.exp * 1000;
-  } catch {
-    /* fall through */
-  }
-  return null;
-}
-
 export async function connectImport(): Promise<void> {
   const rawArgs = process.argv.slice(4);
 
@@ -136,82 +53,44 @@ export async function connectImport(): Promise<void> {
     process.exit(1);
   }
 
-  const bundle = decodeBundle(blob);
-  if (!bundle) {
+  const decoded = decodePairBundle(blob);
+  if (!decoded.ok) {
     console.error(
       "Error: invalid pairing bundle. Paste the full base64 string printed by `vellum pair`.",
     );
     process.exit(1);
   }
 
-  // Unique local id: a --name slug, or paired-<deviceId> (deviceId is unique
-  // per pairing). Never the bundle's "self" assistantId — that would collide.
-  // The deviceId comes from an untrusted bundle and is used as a path component
-  // by saveGuardianToken, so it MUST be slugified (no `../` traversal); fall
-  // back to a random id if it sanitizes to empty.
-  const localId = nameFlag
-    ? slugify(nameFlag)
-    : `paired-${slugify(bundle.deviceId ?? "") || nanoid()}`;
-  if (!localId) {
-    console.error(
-      "Error: --name must contain at least one alphanumeric character.",
-    );
-    process.exit(1);
-  }
-
-  // Don't clobber an existing assistant. Only update in place when the prior
-  // entry is itself a paired import (marked `paired: true`); otherwise the id
-  // collides with a real local/remote assistant and overwriting would drop its
-  // resources/runtime metadata. Reject and let the user pick a fresh --name.
-  const existing = findAssistantByName(localId);
-  if (existing && existing.paired !== true) {
-    console.error(
-      `Error: an assistant named '${localId}' already exists locally. ` +
-        "Choose a different --name to avoid overwriting it.",
-    );
+  const result = pairAssistant(
+    getLockfilePaths(getCurrentEnvironment()),
+    resolveConfigDir(process.env),
+    { bundle: decoded.bundle, name: nameFlag },
+  );
+  if (!result.ok) {
+    if (result.status === 400) {
+      console.error(
+        "Error: --name must contain at least one alphanumeric character.",
+      );
+    } else if (result.status === 409) {
+      console.error(
+        `Error: an assistant named '${result.assistantId}' already exists locally. ` +
+          "Choose a different --name to avoid overwriting it.",
+      );
+    } else {
+      console.error(`Error: ${result.error}`);
+    }
     process.exit(1);
   }
-  const existed = existing !== null;
-
-  saveAssistantEntry({
-    assistantId: localId,
-    name: nameFlag ?? `paired (${new URL(bundle.gatewayUrl).host})`,
-    runtimeUrl: bundle.gatewayUrl,
-    // Paired entries are reached by bearer token at the remote runtimeUrl
-    // (a non-"vellum" cloud selects the bearer-token auth path in client.ts).
-    // The "paired" topology lets lifecycle/status commands (ps/wake/sleep)
-    // recognize this as a remote pairing rather than an on-machine process.
-    cloud: "paired",
-    // Marks this entry as a connect-import so re-imports update in place while
-    // imports never silently overwrite a non-paired assistant (see guard above).
-    paired: true,
-    species: "vellum",
-  });
-
-  const now = Date.now();
-  const hasRefresh = Boolean(bundle.refreshToken);
-  saveGuardianToken(localId, {
-    guardianPrincipalId: "imported",
-    accessToken: bundle.token,
-    accessTokenExpiresAt:
-      jwtExpiryMs(bundle.token) ?? now + 24 * 60 * 60 * 1000,
-    refreshToken: bundle.refreshToken ?? "",
-    refreshTokenExpiresAt: bundle.refreshTokenExpiresAt ?? 0,
-    refreshAfter: bundle.refreshAfter ?? "",
-    isNew: false,
-    deviceId: bundle.deviceId ?? "",
-    leasedAt: new Date(now).toISOString(),
-  });
 
   console.log(
-    `${existed ? "Updated" : "Imported"} paired assistant '${localId}'.`,
+    `${result.updated ? "Updated" : "Imported"} paired assistant '${result.assistantId}'.`,
   );
   console.log("");
-  console.log(`  Connect with:  vellum client ${localId}`);
+  console.log(`  Connect with:  vellum client ${result.assistantId}`);
   console.log("");
   console.log(
-    hasRefresh
-      ? "Note: this connection includes a refresh credential, so it can renew itself — re-pair only if it's revoked or the refresh credential expires."
-      : "Note: the token is access-only and will expire — re-run `vellum pair` and import again when it does.",
+    result.accessOnly
+      ? "Note: the token is access-only and will expire. Re-run `vellum pair` and import again when it does."
+      : "Note: this connection includes a refresh credential, so it can renew itself. Re-pair only if it's revoked or the refresh credential expires.",
   );
 }

package/src/commands/nginx-ingress.ts

@@ -9,36 +9,39 @@ import {
 import type { AssistantEntry } from "../lib/assistant-config.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import { GATEWAY_PORT } from "../lib/constants.js";
-import {
-  formatFeatureFlagGateMessage,
-  isAssistantFeatureFlagEnabled,
-  WEB_REMOTE_INGRESS_FLAG,
-} from "../lib/feature-flags.js";
+import { WEB_REMOTE_INGRESS_FLAG } from "../lib/feature-flags.js";
 import {
   DEFAULT_NGINX_INGRESS_PORT,
+  ensureTunnelEdge,
+  formatEdgeMode,
   getIngressPaths,
   getIngressPid,
+  getNginxIngressPort,
   isIngressRunning,
-  resolveTunnelTargetPort,
-  startRemoteWebIngress,
+  readIngressState,
   stopIngressNginx,
+  type TunnelEdge,
 } from "../lib/nginx-ingress.js";
 
 function printHelp(): void {
   console.log("Usage: vellum nginx-ingress <subcommand> [<name>] [options]");
   console.log("");
+  console.log("Manage the nginx edge that fronts the gateway for tunnel");
+  console.log("traffic: browser/webhooks → tunnel (TLS) → nginx@127.0.0.1.");
   console.log(
-    "Manage the nginx web edge that serves the SPA and fronts the gateway",
+    "`vellum tunnel` starts or reuses this edge automatically; use this",
   );
   console.log(
-    "for remote web access: browser → tunnel (TLS) → nginx@127.0.0.1.",
+    "command as plumbing: check status, stop the edge, or start it for a",
   );
-  console.log("While nginx ingress is running, `vellum tunnel` targets it.");
+  console.log("bring-your-own HTTPS front (e.g. `tailscale serve`).");
   console.log("");
   console.log("Subcommands:");
-  console.log("  up       Generate the nginx config and start the proxy");
-  console.log("  down     Stop the proxy");
-  console.log("  status   Show whether the proxy is running and where");
+  console.log("  up       Generate the nginx config and start the edge");
+  console.log("  down     Stop the edge");
+  console.log(
+    "  status   Show whether the edge is running, its mode, and where",
+  );
   console.log("");
   console.log("Arguments:");
   console.log(
@@ -50,19 +53,23 @@ function printHelp(): void {
   console.log("");
   console.log("Environment:");
   console.log(
-    `  VELLUM_NGINX_INGRESS_PORT   nginx ingress loopback listen port (default ${DEFAULT_NGINX_INGRESS_PORT})`,
+    `  VELLUM_NGINX_INGRESS_PORT   nginx edge loopback listen port (default ${DEFAULT_NGINX_INGRESS_PORT})`,
   );
   console.log("  NGINX_BIN             Path to the nginx binary");
   console.log("");
   console.log("Examples:");
-  console.log("  $ vellum nginx-ingress up");
   console.log("  $ vellum nginx-ingress status");
+  console.log("  $ vellum nginx-ingress up");
   console.log("  $ vellum nginx-ingress down my-assistant");
   console.log("");
   console.log("Feature flags:");
   console.log(
-    `  ${WEB_REMOTE_INGRESS_FLAG} must be enabled to start nginx ingress`,
+    `  ${WEB_REMOTE_INGRESS_FLAG} selects the edge mode: enabled serves the`,
   );
+  console.log(
+    "  remote web app alongside webhooks; disabled starts a webhooks-only",
+  );
+  console.log("  proxy.");
 }
 
 interface NginxIngressTarget {
@@ -83,14 +90,23 @@ function parsePortFromUrl(url: unknown): number | undefined {
   }
 }
 
-function resolveEntryGatewayPort(entry: AssistantEntry | undefined): number {
+/**
+ * Derive the gateway port from an entry's recorded URLs, preferring the
+ * loopback `localUrl` over `runtimeUrl`. Undefined when neither carries an
+ * explicit port (e.g. a platform-hosted https runtime URL).
+ */
+export function parseGatewayPortFromEntryUrls(
+  entry: AssistantEntry | undefined,
+): number | undefined {
   return (
-    parsePortFromUrl(entry?.localUrl) ??
-    parsePortFromUrl(entry?.runtimeUrl) ??
-    GATEWAY_PORT
+    parsePortFromUrl(entry?.localUrl) ?? parsePortFromUrl(entry?.runtimeUrl)
   );
 }
 
+function resolveEntryGatewayPort(entry: AssistantEntry | undefined): number {
+  return parseGatewayPortFromEntryUrls(entry) ?? GATEWAY_PORT;
+}
+
 /**
  * Resolve which assistant nginx ingress fronts. Multi-instance hatches allocate
  * per-assistant gateway ports and workspaces, so both must come from the
@@ -129,100 +145,52 @@ export function resolveNginxIngressTarget(
   };
 }
 
-async function assertWebRemoteIngressEnabled(
-  target: NginxIngressTarget,
-): Promise<void> {
-  if (!target.assistantId) {
-    throw new Error(formatFeatureFlagGateMessage(WEB_REMOTE_INGRESS_FLAG));
-  }
+export async function up(target: NginxIngressTarget): Promise<void> {
+  const { workspaceDir, gatewayPort } = target;
 
-  let enabled: boolean;
+  let edge: TunnelEdge;
   try {
-    enabled = await isAssistantFeatureFlagEnabled(
-      target.assistantId,
-      WEB_REMOTE_INGRESS_FLAG,
-      { runtimeUrl: `http://127.0.0.1:${target.gatewayPort}` },
-    );
+    edge = await ensureTunnelEdge({
+      assistantId: target.assistantId,
+      workspaceDir,
+      gatewayPort,
+      onStarting: ({ version, webDistDir, listenPort }) => {
+        console.log(`Using ${version}`);
+        const webSegment = webDistDir ? `web ${webDistDir} + ` : "";
+        console.log(
+          `Starting nginx ingress on 127.0.0.1:${listenPort} → ${webSegment}gateway 127.0.0.1:${gatewayPort}...`,
+        );
+      },
+    });
   } catch (err) {
-    throw new Error(
-      `Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` feature flag. Is the assistant running? Try \`vellum wake\` and retry. ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 
-  if (!enabled) {
-    throw new Error(formatFeatureFlagGateMessage(WEB_REMOTE_INGRESS_FLAG));
-  }
-}
-
-async function up(target: NginxIngressTarget): Promise<void> {
-  const { workspaceDir, gatewayPort } = target;
+  const mode = formatEdgeMode(edge.includesWebApp);
 
-  await assertWebRemoteIngressEnabled(target);
-
-  const result = await startRemoteWebIngress({
-    workspaceDir,
-    gatewayPort,
-    onStarting: ({ version, webDistDir, listenPort }) => {
-      console.log(`Using ${version}`);
-      console.log(
-        `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
-      );
-    },
-  });
-
-  switch (result.status) {
-    case "already-running":
-      console.log("nginx ingress is already running.");
-      await status(target);
-      return;
-    case "started":
-      console.log("");
-      console.log(
-        `nginx ingress running: http://127.0.0.1:${result.listenPort}`,
-      );
-      console.log("");
-      console.log("Next steps:");
-      console.log(
-        "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
-      );
-      console.log("  vellum nginx-ingress down        # stop the proxy");
-      return;
-    case "nginx-missing":
-      console.error("Error: nginx is not installed.");
-      console.error("");
-      console.error("Install nginx:");
-      console.error("  macOS:  brew install nginx");
-      console.error("  Linux:  sudo apt install nginx");
-      console.error("");
-      console.error(
-        "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
-      );
-      break;
-    case "web-dist-missing":
-      console.error(
-        "Error: unable to locate built web assets for remote web ingress.",
-      );
-      console.error("");
-      console.error("Build the SPA first:");
-      console.error(
-        "  cd clients/web && VITE_PLATFORM_MODE=false bun run build",
-      );
-      console.error("");
-      console.error(
-        "Or install @vellumai/web so its packaged dist directory is available.",
-      );
-      break;
-    case "unreachable":
-      console.error(
-        `Error: nginx ingress did not become reachable on 127.0.0.1:${result.listenPort}.`,
-      );
-      console.error(`Check the nginx log: ${result.logPath}`);
-      break;
+  if (!edge.started) {
+    console.log(`nginx ingress is already running (${mode}).`);
+    await status(target);
+    return;
   }
 
-  process.exit(1);
+  console.log("");
+  console.log(`nginx ingress running: http://127.0.0.1:${edge.port} (${mode})`);
+  if (!edge.includesWebApp) {
+    console.log(
+      `Enable the ${WEB_REMOTE_INGRESS_FLAG} feature flag to also serve the web app remotely.`,
+    );
+  }
+  console.log("");
+  console.log("Next steps:");
+  console.log(
+    "  vellum tunnel --provider ngrok   # put an HTTPS front on this edge",
+  );
+  console.log(
+    "                                   # (cloudflare and tailscale work too)",
+  );
+  console.log("  vellum nginx-ingress down        # stop the edge");
 }
 
 async function down(target: NginxIngressTarget): Promise<void> {
@@ -236,7 +204,7 @@ async function down(target: NginxIngressTarget): Promise<void> {
   );
 }
 
-async function status(target: NginxIngressTarget): Promise<void> {
+export async function status(target: NginxIngressTarget): Promise<void> {
   const { workspaceDir, gatewayPort } = target;
   const { confPath, logPath } = getIngressPaths(workspaceDir);
   const pid = getIngressPid(workspaceDir);
@@ -244,11 +212,20 @@ async function status(target: NginxIngressTarget): Promise<void> {
     console.log("nginx ingress: not running");
     return;
   }
-  const { port } = resolveTunnelTargetPort(workspaceDir, gatewayPort);
+  const state = readIngressState(workspaceDir);
+  const listenPort = state?.listenPort ?? getNginxIngressPort();
+  const mode = formatEdgeMode(state?.includeWebApp ?? true);
+  // The recorded gateway port is what the running edge proxies; a state
+  // record without gatewayPort is unverified.
+  const gatewayLine =
+    state?.gatewayPort !== undefined
+      ? `http://127.0.0.1:${state.gatewayPort}`
+      : `http://127.0.0.1:${gatewayPort} (unverified)`;
   console.log("nginx ingress: running");
   console.log(`  PID:     ${pid}`);
-  console.log(`  Listen:  http://127.0.0.1:${port}`);
-  console.log(`  Gateway: http://127.0.0.1:${gatewayPort}`);
+  console.log(`  Mode:    ${mode}`);
+  console.log(`  Listen:  http://127.0.0.1:${listenPort}`);
+  console.log(`  Gateway: ${gatewayLine}`);
   console.log(`  Config:  ${confPath}`);
   console.log(`  Log:     ${logPath}`);
 }