@vellumai/cli 0.10.12-staging.1 → 0.10.12-staging.2

package/src/lib/environments/__tests__/detect.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  crossEnvironmentAssistantHint,
+  detectOtherEnvironmentAssistants,
+} from "../detect.js";
+import { getSeed } from "../resolve.js";
+
+const prod = getSeed("production")!;
+
+/** Create `<XDG_DATA_HOME>/vellum-<env>/assistants/<id>/` for a non-prod env. */
+function seedAssistantDir(dataHome: string, envName: string, id: string): void {
+  mkdirSync(join(dataHome, `vellum-${envName}`, "assistants", id), {
+    recursive: true,
+  });
+}
+
+describe("cross-environment assistant detection", () => {
+  let dataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    dataHome = mkdtempSync(join(tmpdir(), "cli-detect-xdg-"));
+    process.env.XDG_DATA_HOME = dataHome;
+    // Pin the current env so the hint's "this CLI targets '<env>'" copy and
+    // the current-env skip are deterministic regardless of machine config.
+    process.env.VELLUM_ENVIRONMENT = "production";
+  });
+
+  afterEach(() => {
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(dataHome, { recursive: true, force: true });
+  });
+
+  test("finds an env whose data dir holds an assistant subdirectory", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    expect(detectOtherEnvironmentAssistants(prod)).toContain("dev");
+  });
+
+  test("reports every other env that holds assistants", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    seedAssistantDir(dataHome, "staging", "staging-bot");
+    const others = detectOtherEnvironmentAssistants(prod);
+    expect(others).toContain("dev");
+    expect(others).toContain("staging");
+  });
+
+  test("skips the current environment even when it holds assistants", () => {
+    // production's own multi-instance dir (no env suffix).
+    mkdirSync(join(dataHome, "vellum", "assistants", "prod-bot"), {
+      recursive: true,
+    });
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("ignores an env dir that holds no assistant subdirectory", () => {
+    mkdirSync(join(dataHome, "vellum-dev", "assistants"), { recursive: true });
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("returns empty when no env data dirs exist", () => {
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("swallows fs errors (data root is a file, not a dir) and returns empty", () => {
+    const filePath = join(dataHome, "not-a-dir");
+    writeFileSync(filePath, "x");
+    process.env.XDG_DATA_HOME = filePath;
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+    expect(crossEnvironmentAssistantHint()).toBeNull();
+  });
+
+  test("hint names the env, the current env, and both fixes", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    const hint = crossEnvironmentAssistantHint();
+    expect(hint).not.toBeNull();
+    expect(hint).toContain("'dev'");
+    expect(hint).toContain("This CLI targets 'production'");
+    expect(hint).toContain("Install vellum Command");
+    expect(hint).toContain("VELLUM_ENVIRONMENT=dev");
+  });
+
+  test("hint is null when no other env has assistants", () => {
+    expect(crossEnvironmentAssistantHint()).toBeNull();
+  });
+});

package/src/lib/environments/detect.ts

@@ -0,0 +1,79 @@
+import { readdirSync } from "fs";
+
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+
+import { getMultiInstanceDir } from "./paths.js";
+import { getCurrentEnvironment } from "./resolve.js";
+
+/**
+ * Names of OTHER environments (every seed except `currentEnv`) whose
+ * multi-instance data dir exists and holds at least one assistant
+ * subdirectory.
+ *
+ * Each environment has its own on-host data layout — see
+ * {@link getMultiInstanceDir}. A user who hatched via a dev/staging desktop
+ * app but runs the production npm CLI (or vice versa) targets a different
+ * layout than the app did, so the assistant the app created is invisible to
+ * this CLI. This cheap filesystem scan surfaces that split so callers can
+ * point the user at the environment that actually holds their assistants.
+ *
+ * Never throws: a missing or unreadable dir just means that environment has no
+ * discoverable assistants, so it is skipped. Returns an empty array on any
+ * error.
+ */
+export function detectOtherEnvironmentAssistants(
+  currentEnv: EnvironmentDefinition,
+): string[] {
+  const found: string[] = [];
+  for (const env of Object.values(SEEDS)) {
+    if (env.name === currentEnv.name) {
+      continue;
+    }
+    try {
+      const hasAssistant = readdirSync(getMultiInstanceDir(env), {
+        withFileTypes: true,
+      }).some((dirent) => dirent.isDirectory());
+      if (hasAssistant) {
+        found.push(env.name);
+      }
+    } catch {
+      // Missing or unreadable dir — this environment has no discoverable
+      // assistants. Skip it.
+    }
+  }
+  return found;
+}
+
+/**
+ * One-line hint appended to "no assistant found" and "gateway unreachable"
+ * errors when another environment's data dir holds assistants. A first-time
+ * user who hatched via a dev/staging desktop app while running the production
+ * npm CLI otherwise gets a bare failure with no clue the two tools target
+ * different environments.
+ *
+ * Returns null when nothing is found so callers can append unconditionally:
+ * `message + (crossEnvironmentAssistantHint() ?? "")`. Detection failure never
+ * propagates — the caller's original error must survive intact.
+ */
+export function crossEnvironmentAssistantHint(): string | null {
+  let currentEnv: EnvironmentDefinition;
+  let others: string[];
+  try {
+    currentEnv = getCurrentEnvironment();
+    others = detectOtherEnvironmentAssistants(currentEnv);
+  } catch {
+    return null;
+  }
+  if (others.length === 0) {
+    return null;
+  }
+
+  const quoted = others.map((name) => `'${name}'`).join(", ");
+  const noun = others.length > 1 ? "environments" : "environment";
+  return (
+    `\n\nFound assistants in the ${quoted} ${noun} (managed by a dev/staging ` +
+    `desktop app). This CLI targets '${currentEnv.name}'. Use the desktop ` +
+    `app's 'Install vellum Command…' menu item to get a matching CLI, or ` +
+    `set VELLUM_ENVIRONMENT=${others[0]}.`
+  );
+}

package/src/lib/nginx-ingress.ts

@@ -17,6 +17,7 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants.js";
+import { waitForDaemonReady } from "./http-client.js";
 import { loadRawConfig, saveRawConfig } from "./ingress-config.js";
 
 /**
@@ -540,6 +541,95 @@ export async function stopIngressNginx(workspaceDir: string): Promise<boolean> {
   return true;
 }
 
+/** Probe budget for confirming the freshly-spawned edge answers /healthz. */
+export const INGRESS_READY_TIMEOUT_MS = 5_000;
+
+/**
+ * Outcome of an attempt to bring up the remote-web nginx ingress edge. Callers
+ * render their own messaging per variant: `nginx-ingress up` prints
+ * install/build guidance and exits non-zero, while the wake restore path warns
+ * and continues.
+ */
+export type StartRemoteWebIngressResult =
+  | {
+      status: "started";
+      listenPort: number;
+      webDistDir: string;
+      version: string;
+    }
+  | { status: "already-running"; listenPort: number }
+  | { status: "nginx-missing" }
+  | { status: "web-dist-missing" }
+  | { status: "unreachable"; listenPort: number; logPath: string };
+
+/**
+ * Generate the nginx config and start the remote-web ingress edge, then probe
+ * /healthz through it to prove the ingress → gateway path is live. A spawned
+ * but unreachable nginx is rolled back so a failed attempt leaves no half-up
+ * edge behind.
+ *
+ * Pure mechanism: it performs no console output and never exits the process, so
+ * both the `nginx-ingress up` command and the wake restore path can share one
+ * implementation and map the returned result to their own UX.
+ */
+export async function startRemoteWebIngress(opts: {
+  workspaceDir: string;
+  gatewayPort: number;
+  listenPort?: number;
+  readyTimeoutMs?: number;
+  /**
+   * Invoked once, after every preflight check passes and immediately before
+   * nginx is spawned, so callers can emit their own "starting" progress line
+   * with the resolved version/dist/port. Never fires on a preflight bail-out
+   * (nginx-missing, already-running, web-dist-missing).
+   */
+  onStarting?: (info: {
+    version: string;
+    webDistDir: string;
+    listenPort: number;
+  }) => void;
+}): Promise<StartRemoteWebIngressResult> {
+  const listenPort = opts.listenPort ?? getNginxIngressPort();
+
+  const version = getNginxVersion();
+  if (!version) {
+    return { status: "nginx-missing" };
+  }
+
+  if (isIngressRunning(opts.workspaceDir)) {
+    return { status: "already-running", listenPort };
+  }
+
+  const webDistDir = findWebDistDir();
+  if (!webDistDir) {
+    return { status: "web-dist-missing" };
+  }
+
+  opts.onStarting?.({ version, webDistDir, listenPort });
+
+  const child = startIngressNginx({
+    workspaceDir: opts.workspaceDir,
+    gatewayPort: opts.gatewayPort,
+    listenPort,
+    remoteWebIngress: { webDistDir },
+  });
+  child.unref();
+
+  // /healthz proxies through nginx to the gateway, so a 200 proves the whole
+  // ingress → gateway path works.
+  const ready = await waitForDaemonReady(
+    listenPort,
+    opts.readyTimeoutMs ?? INGRESS_READY_TIMEOUT_MS,
+  );
+  if (!ready) {
+    const { logPath } = getIngressPaths(opts.workspaceDir);
+    await stopIngressNginx(opts.workspaceDir);
+    return { status: "unreachable", listenPort, logPath };
+  }
+
+  return { status: "started", listenPort, webDistDir, version };
+}
+
 /**
  * Resolve the local port a tunnel should target: the nginx ingress when it is
  * recorded AND its process is alive, otherwise the gateway port directly

package/src/lib/stale-cli-hint.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared tail for errors where this CLI doesn't recognize an option or provider
+ * the user named. The name may be valid in a newer release, so point the user
+ * at the self-update path before they conclude the feature doesn't exist.
+ *
+ * `bun install -g vellum@latest` refreshes the `vellum` binary directly — the
+ * mechanism the installer and the CLI's own self-update use. (`vellum upgrade`
+ * targets the assistant runtime, not the CLI binary, for local assistants.)
+ */
+export const STALE_CLI_UPDATE_HINT =
+  "your CLI may be out of date — update it with `bun install -g vellum@latest` and retry.";