@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/node_modules/@mycadet/environments/src/__tests__/package-boundary.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Package boundary tests for @mycadet/environments.
+ *
+ * This package is the lowest layer of the shared-packages hierarchy:
+ * environment types, constants, and small helpers over node builtins, with no
+ * runtime dependencies. It must stay a leaf so any consumer (CLI, assistant,
+ * local-mode host) can depend on it without dragging in a dependency tree.
+ *
+ * Enforces that the package:
+ * 1. Imports only node builtins and its own relative modules — no `@mycadet/*`
+ *    packages and no third-party runtime imports.
+ * 2. Declares no runtime `dependencies` (devDependencies only).
+ * 3. Is marked `private`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
+const SRC_DIR = join(PACKAGE_ROOT, "src");
+
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue;
+      files.push(...collectSourceFiles(full));
+    } else if (
+      entry.endsWith(".ts") &&
+      !entry.endsWith(".test.ts") &&
+      !entry.endsWith(".d.ts")
+    ) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Matches the module specifier of any `import ... from "<spec>"` /
+ * `export ... from "<spec>"` / `require("<spec>")` statement.
+ */
+const IMPORT_SPEC = /(?:from|require\s*\(\s*)["']([^"']+)["']/g;
+
+/** A bare specifier is anything that is not a relative or node-builtin import. */
+function isForbiddenSpecifier(spec: string): boolean {
+  if (spec.startsWith(".") || spec.startsWith("/")) return false;
+  if (spec.startsWith("node:")) return false;
+  return true;
+}
+
+describe("package boundary", () => {
+  const sourceFiles = collectSourceFiles(SRC_DIR);
+
+  test("has source files to validate", () => {
+    expect(sourceFiles.length).toBeGreaterThan(0);
+  });
+
+  test("imports only node builtins and relative modules", () => {
+    const violations: string[] = [];
+
+    for (const file of sourceFiles) {
+      const lines = readFileSync(file, "utf-8").split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        for (const match of lines[i]!.matchAll(IMPORT_SPEC)) {
+          const spec = match[1]!;
+          if (isForbiddenSpecifier(spec)) {
+            const relative = file.replace(PACKAGE_ROOT + "/", "");
+            violations.push(`${relative}:${i + 1}: ${spec}`);
+          }
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found ${violations.length} forbidden import(s) in @mycadet/environments:\n` +
+          violations.map((v) => `  - ${v}`).join("\n") +
+          "\n\n@mycadet/environments is a dependency-free leaf and must\n" +
+          "import only node builtins and its own relative modules.",
+      );
+    }
+  });
+
+  test("package.json declares it as private with no runtime dependencies", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies ?? {}).toEqual({});
+  });
+});

package/node_modules/@mycadet/environments/src/__tests__/test-path-guard.test.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  assertTestPathIsEphemeral,
+  canonicalizePathThroughExistingParent,
+  isBunTestProcess,
+} from "../test-path-guard.js";
+
+const OPTIONS = {
+  allowEnvVar: "TEST_PATH_GUARD_ALLOW",
+  runHint: "Run tests from the package root.",
+};
+
+describe("isBunTestProcess", () => {
+  test("detects this bun test run", () => {
+    expect(isBunTestProcess()).toBe(true);
+  });
+});
+
+describe("canonicalizePathThroughExistingParent", () => {
+  test("resolves symlinks on the deepest existing ancestor", () => {
+    const root = mkdtempSync(join(tmpdir(), "test-path-guard-"));
+    try {
+      const target = join(root, "target");
+      mkdirSync(target);
+      const link = join(root, "link");
+      symlinkSync(target, link, "dir");
+      expect(
+        canonicalizePathThroughExistingParent(join(link, "missing", "leaf")),
+      ).toBe(
+        join(canonicalizePathThroughExistingParent(target), "missing", "leaf"),
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("returns the input path when no ancestor exists", () => {
+    expect(canonicalizePathThroughExistingParent("/nonexistent-root-x/y")).toBe(
+      "/nonexistent-root-x/y",
+    );
+  });
+});
+
+describe("assertTestPathIsEphemeral", () => {
+  test("allows paths under tmpdir, existing or not", () => {
+    expect(() =>
+      assertTestPathIsEphemeral(join(tmpdir(), "guard-missing", "x"), OPTIONS),
+    ).not.toThrow();
+  });
+
+  test("refuses paths outside tmpdir, naming the escape hatch and hint", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const dir = join(homedir(), "test-path-guard-live");
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use[\s\S]*package root[\s\S]*TEST_PATH_GUARD_ALLOW/,
+    );
+  });
+
+  test("refuses a tmpdir symlink that resolves outside tmpdir", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const link = join(tmpdir(), `test-path-guard-escape-${process.pid}`);
+    rmSync(link, { force: true });
+    symlinkSync(homedir(), link);
+    try {
+      expect(() => assertTestPathIsEphemeral(link, OPTIONS)).toThrow(
+        /Refusing to use/,
+      );
+    } finally {
+      rmSync(link, { force: true });
+    }
+  });
+
+  test("the allow env var bypasses the guard, per call", () => {
+    const dir = join(homedir(), "test-path-guard-optout");
+    process.env[OPTIONS.allowEnvVar] = "1";
+    try {
+      expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).not.toThrow();
+    } finally {
+      delete process.env[OPTIONS.allowEnvVar];
+    }
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use/,
+    );
+  });
+});

package/node_modules/@mycadet/environments/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @mycadet/environments: the single source of truth for how a Cadet install
+ * is laid out and which deployment environment it belongs to.
+ *
+ * Two things live here:
+ *
+ *   - The known deployment environments (names, platform/web URLs, per-service
+ *     port blocks). The Swift client mirrors the same set in
+ *     `CadetEnvironment.swift`.
+ *   - Install layout: whether a runtime is a repo checkout or an installed
+ *     package, and where the `assistant` command it ships lives.
+ *
+ * Consumed by the CLI, the assistant daemon, and the local-mode host library
+ * so each answer is defined exactly once on the TS side.
+ *
+ * This is the lowest layer of the shared-packages hierarchy and stays a leaf:
+ * types, constants, and small helpers over node builtins, with no runtime
+ * dependencies of its own. See `__tests__/package-boundary.test.ts`.
+ */
+export * from "./types.js";
+export * from "./seeds.js";
+export * from "./install-layout.js";

package/node_modules/@mycadet/environments/src/install-layout.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading the layout a Cadet runtime is installed in.
+ *
+ * The daemon is started either from a developer's repo checkout or from an
+ * installed npm package (`<install>/node_modules/@mycadet/assistant/src/
+ * index.ts`, which is what the desktop app runs). The CLI needs the layout to
+ * decide whether a launch is a dev run and what to put on the daemon's PATH;
+ * the daemon needs it to decide what to install as the `assistant` command.
+ * Both ask the same two questions, so they ask them here.
+ */
+
+import { existsSync } from "node:fs";
+import { join, sep } from "node:path";
+
+const NODE_MODULES_SEGMENT = `${sep}node_modules${sep}`;
+
+/**
+ * Whether `path` sits in a developer's repo checkout rather than inside an
+ * installed package.
+ */
+export function isRepoCheckoutPath(path: string): boolean {
+  return !path.includes(NODE_MODULES_SEGMENT);
+}
+
+/**
+ * The `assistant` command shipped with the install that contains `path`, or
+ * null when there is none (a repo checkout, or an install whose dependency
+ * graph omits the package declaring the bin).
+ *
+ * Searches innermost `node_modules` outward, since a nested install shadows a
+ * hoisted one.
+ */
+export function findAssistantCommand(path: string): string | null {
+  let index = path.lastIndexOf(NODE_MODULES_SEGMENT);
+
+  while (index !== -1) {
+    const nodeModulesDir = path.slice(
+      0,
+      index + NODE_MODULES_SEGMENT.length - 1,
+    );
+    const command = join(nodeModulesDir, ".bin", "assistant");
+    if (existsSync(command)) {
+      return command;
+    }
+    index = path.lastIndexOf(NODE_MODULES_SEGMENT, index - 1);
+  }
+
+  return null;
+}

package/node_modules/@mycadet/environments/src/seeds.ts

@@ -0,0 +1,99 @@
+import type { EnvironmentDefinition, PortMap } from "./types.js";
+
+/**
+ * Non-prod port blocks. Each environment gets a 1000-port window in the
+ * 17000–21000 band. Within a block, services are spaced 100 apart so up to
+ * 100 assistants can coexist without the scan (`findAvailablePort`) running
+ * one service's range into the next. Band chosen to sit below Linux's
+ * default ephemeral start (32768) and macOS's (49152), and away from the
+ * 3000/5000/8000/9000 dev-tool swamp. Production keeps its legacy,
+ * non-contiguous port set (7821/7830/6333/8090/8080/8765): cross-env
+ * collision is the only problem this change targets, prod is unaffected
+ * because only one env's assistants compete on a given machine, and
+ * churning it would leave existing hatches on 7821 while new ones
+ * allocated elsewhere.
+ */
+function portBlock(base: number): PortMap {
+  return {
+    daemon: base,
+    gateway: base + 100,
+    qdrant: base + 200,
+    ces: base + 300,
+    outboundProxy: base + 400,
+    tcp: base + 500,
+  };
+}
+
+/**
+ * Base URL of the cloud-hosted assistant SPA (the "hub") for a deployment
+ * environment. The Capacitor mobile shell bakes this into native builds as
+ * `server.url`, and the CLI's remote-web edge stamps it into the served
+ * config as `hubUrl`, so the environment-to-hub mapping lives here exactly
+ * once.
+ *
+ * Only the cloud deployments (production, staging) serve the hosted SPA at
+ * their own web origin; every other environment (dev, test, local, unknown)
+ * falls back to the dev SPA, whose host serves remote clients that cannot
+ * reach a local or per-developer web URL.
+ *
+ * The `/assistant` suffix is deliberate: booting on the bare host lands on
+ * the marketing page, whose CTA redirects to `mycadet.ai/assistant` and
+ * bounces non-prod shells off their own host.
+ *
+ * NOTE: this module is loaded by Capacitor's single-file TS config loader
+ * (via the `@mycadet/environments/seeds` subpath), which cannot follow the
+ * package index's `.js`-suffixed runtime re-exports. Keep this file's
+ * imports type-only so it stays loadable on its own.
+ */
+export function cloudAssistantHubUrl(envName: string | undefined): string {
+  const seed =
+    envName === "production" || envName === "staging"
+      ? SEEDS[envName]
+      : SEEDS.dev;
+  return `${seed.webUrl}/assistant`;
+}
+
+/**
+ * Built-in environment definitions and the source of truth for the
+ * set of known environment names.
+ *
+ * Custom environments via a user config file are a future phase — see the
+ * "Coexisting environments" design doc. Until then, a call site that needs a
+ * new environment must add it here and rebuild.
+ */
+export const SEEDS: Record<string, EnvironmentDefinition> = {
+  production: {
+    name: "production",
+    platformUrl: "https://cloud.mycadet.ai",
+    webUrl: "https://mycadet.ai",
+  },
+  staging: {
+    name: "staging",
+    platformUrl: "https://staging-cloud.mycadet.ai",
+    webUrl: "https://staging.mycadet.ai",
+    portsOverride: portBlock(17000),
+  },
+  test: {
+    name: "test",
+    // Non-functional URL — used only by unit tests for URL resolution, never
+    // hit in production.
+    platformUrl: "https://test-cloud.mycadet.ai",
+    webUrl: "https://dev.mycadet.ai",
+    portsOverride: portBlock(19000),
+  },
+  dev: {
+    name: "dev",
+    platformUrl: "https://dev-cloud.mycadet.ai",
+    webUrl: "https://dev.mycadet.ai",
+    portsOverride: portBlock(18000),
+  },
+  local: {
+    name: "local",
+    platformUrl: "http://localhost:8000",
+    webUrl: "http://localhost:3000",
+    // assistantPlatformUrl: "http://host.docker.internal:8000",
+    // ^ uncomment this once dockerized hatch path is live.
+    // The assistant runs in a different network namespace than the host.
+    portsOverride: portBlock(20000),
+  },
+};

package/node_modules/@mycadet/environments/src/shell.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildShellInvocation,
+  buildShellSpawnFlags,
+  CHILD_OOM_SCORE_ADJ,
+  pathListDelimiter,
+  prependUniquePathEntries,
+} from "./shell.js";
+
+describe("buildShellInvocation", () => {
+  test("uses Bash on POSIX hosts", () => {
+    expect(buildShellInvocation("printf hello", "darwin")).toEqual({
+      command: "bash",
+      args: ["-c", "--", "printf hello"],
+    });
+  });
+
+  test("raises the shell's OOM-kill priority on Linux", () => {
+    expect(buildShellInvocation("printf hello", "linux")).toEqual({
+      command: "bash",
+      args: [
+        "-c",
+        "--",
+        `echo ${CHILD_OOM_SCORE_ADJ} 2>/dev/null >/proc/self/oom_score_adj; printf hello`,
+      ],
+    });
+  });
+
+  test("uses encoded non-interactive PowerShell on Windows", () => {
+    const invocation = buildShellInvocation(
+      "Write-Output 'hello 世界'",
+      "win32",
+    );
+
+    expect(invocation.command).toBe("powershell.exe");
+    expect(invocation.args.slice(0, -1)).toEqual([
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-EncodedCommand",
+    ]);
+    const encoded = invocation.args.at(-1)!;
+    const decoded = Buffer.from(encoded, "base64").toString("utf16le");
+    expect(decoded).toContain("[Console]::OutputEncoding");
+    expect(decoded).toContain("$global:LASTEXITCODE = 0");
+    expect(decoded).toContain("Write-Output 'hello 世界'");
+    expect(decoded).toContain("exit $__cadetNativeExitCode");
+    expect(decoded).toEndWith("exit 0");
+  });
+});
+
+describe("buildShellSpawnFlags", () => {
+  test("creates a POSIX process group and hides Windows consoles", () => {
+    expect(buildShellSpawnFlags("linux")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+    expect(buildShellSpawnFlags("darwin")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+  });
+
+  test("does not detach Windows children that use piped stdio", () => {
+    expect(buildShellSpawnFlags("win32")).toEqual({
+      detached: false,
+      windowsHide: true,
+    });
+  });
+});
+
+describe("path list handling", () => {
+  test("uses the platform delimiter", () => {
+    expect(pathListDelimiter("win32")).toBe(";");
+    expect(pathListDelimiter("linux")).toBe(":");
+  });
+
+  test("prepends Windows paths without splitting drive letters", () => {
+    expect(
+      prependUniquePathEntries(
+        "C:\\Windows\\System32;C:\\Tools",
+        ["C:\\Tools", "C:\\Users\\Alice\\.bun\\bin"],
+        "win32",
+      ),
+    ).toBe("C:\\Users\\Alice\\.bun\\bin;C:\\Windows\\System32;C:\\Tools");
+  });
+});

package/node_modules/@mycadet/environments/src/shell.ts

@@ -0,0 +1,110 @@
+import { delimiter } from "node:path";
+
+export interface ShellInvocation {
+  command: string;
+  args: string[];
+}
+
+export interface ShellSpawnFlags {
+  detached: boolean;
+  windowsHide: true;
+}
+
+const WINDOWS_UTF8_PREAMBLE =
+  "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}; " +
+  "$OutputEncoding = [System.Text.Encoding]::UTF8; " +
+  "$global:LASTEXITCODE = 0;";
+
+const WINDOWS_EXIT_STATUS_SUFFIX = `
+$__cadetCommandSucceeded = $?
+$__cadetNativeExitCode = $LASTEXITCODE
+if (-not $__cadetCommandSucceeded) {
+  if ($__cadetNativeExitCode -ne 0) { exit $__cadetNativeExitCode }
+  exit 1
+}
+exit 0`;
+
+/**
+ * `oom_score_adj` for assistant-owned tool processes. Any positive value
+ * outranks a 0-scored process; 1000 makes a tool the kernel's first choice
+ * whenever the container runs out of memory, so the assistant itself is never
+ * the victim of a runaway command.
+ */
+export const CHILD_OOM_SCORE_ADJ = 1000;
+
+/**
+ * Prefix for a Bash `-c` script that raises the shell's own OOM-kill priority
+ * before the command runs. Every process the command forks inherits it. Bash
+ * performs a builtin's redirection itself, so `/proc/self` is the shell.
+ * Redirections apply left to right, so stderr goes to /dev/null before the
+ * procfs open can fail and complain about it.
+ */
+const LINUX_OOM_SCORE_ADJ_PREFIX = `echo ${CHILD_OOM_SCORE_ADJ} 2>/dev/null >/proc/self/oom_score_adj; `;
+
+export function buildShellInvocation(
+  command: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+  windowsExecutable = "powershell.exe",
+): ShellInvocation {
+  if (hostPlatform === "win32") {
+    return {
+      command: windowsExecutable,
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-EncodedCommand",
+        Buffer.from(
+          `${WINDOWS_UTF8_PREAMBLE}\n${command}${WINDOWS_EXIT_STATUS_SUFFIX}`,
+          "utf16le",
+        ).toString("base64"),
+      ],
+    };
+  }
+  const script =
+    hostPlatform === "linux"
+      ? `${LINUX_OOM_SCORE_ADJ_PREFIX}${command}`
+      : command;
+  return { command: "bash", args: ["-c", "--", script] };
+}
+
+/**
+ * Spawn flags for assistant-owned shell children (sandbox bash, local
+ * host_bash fallback, sanitized CLI bash, skill runners, scheduled scripts).
+ *
+ * POSIX uses a new process group so timeout/abort can SIGKILL the tree via
+ * `-pid`. Windows process trees are torn down with `taskkill /T`, which does
+ * not need a detached process. Combining `DETACHED_PROCESS`,
+ * `CREATE_NO_WINDOW`, and piped stdio on Windows can emit `close` with exit
+ * 0 and empty pipes without running the encoded command.
+ */
+export function buildShellSpawnFlags(
+  hostPlatform: NodeJS.Platform = process.platform,
+): ShellSpawnFlags {
+  return {
+    detached: hostPlatform !== "win32",
+    windowsHide: true,
+  };
+}
+
+export function pathListDelimiter(
+  hostPlatform: NodeJS.Platform = process.platform,
+): string {
+  return hostPlatform === process.platform
+    ? delimiter
+    : hostPlatform === "win32"
+      ? ";"
+      : ":";
+}
+
+export function prependUniquePathEntries(
+  value: string | undefined,
+  entries: readonly string[],
+  hostPlatform: NodeJS.Platform = process.platform,
+): string {
+  const separator = pathListDelimiter(hostPlatform);
+  const current = value?.split(separator).filter(Boolean) ?? [];
+  const missing = entries.filter((entry) => !current.includes(entry));
+  return [...missing, ...current].join(separator);
+}

package/node_modules/@mycadet/environments/src/test-path-guard.ts

@@ -0,0 +1,113 @@
+/**
+ * Live-path guard for test processes, shared by every service that resolves
+ * install-layout paths (the assistant daemon's workspace/root, the gateway's
+ * workspace and security dirs).
+ *
+ * A test process must never resolve one of those paths to a real, non-temp
+ * directory: production code exercised by a test would then read and
+ * destructively write live state. The tmpdir redirection normally comes from
+ * each package's bunfig.toml test preload, but bun only loads bunfig from
+ * the cwd, so `bun test` run from any other directory skips the preload and
+ * inherits the ambient env (or a ~/.cadet fallback). The containment
+ * assertion therefore lives in production code, where it fires no matter how
+ * the test process was launched.
+ *
+ * assistant/src/__tests__/assert-not-live-db.ts keeps its own containment
+ * check: test machinery must not import production dependencies.
+ */
+
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+
+/**
+ * Resolve symlinks in the deepest existing ancestor of `path`, then
+ * re-append the not-yet-created tail. This keeps containment checks honest
+ * both for paths under a symlinked temp root (macOS /var/folders) and for
+ * symlinks that point outside it, whether or not the leaf exists yet.
+ */
+export function canonicalizePathThroughExistingParent(path: string): string {
+  const resolvedPath = resolve(path);
+  const pendingSegments: string[] = [];
+  let currentPath = resolvedPath;
+
+  while (true) {
+    try {
+      return resolve(realpathSync(currentPath), ...pendingSegments.reverse());
+    } catch {
+      const parentPath = dirname(currentPath);
+      if (parentPath === currentPath) {
+        return resolvedPath;
+      }
+      pendingSegments.push(basename(currentPath));
+      currentPath = parentPath;
+    }
+  }
+}
+
+/** Lazily computed: is this process a `bun test` run? */
+let isTestProcess: boolean | undefined;
+
+/**
+ * True when this process is a `bun test` run. Computed once and cached for
+ * the process lifetime, so a runtime flip of NODE_ENV or BUN_TEST does not
+ * change the answer. Test-mode behavior toggles that must observe such
+ * flips read the env directly instead of calling this.
+ */
+export function isBunTestProcess(): boolean {
+  isTestProcess ??=
+    process.env.NODE_ENV === "test" ||
+    process.env.BUN_TEST === "1" ||
+    // `bun test` sets NODE_ENV=test only when unset; Bun.main being the test
+    // file itself is the backstop signal that survives a preset NODE_ENV.
+    (typeof Bun !== "undefined" &&
+      /\.(test|spec)\.[cm]?[jt]sx?$/.test(Bun.main));
+  return isTestProcess;
+}
+
+export interface EphemeralTestPathOptions {
+  /**
+   * Escape hatch for the rare intentional run against real state: setting
+   * this env var to "1" bypasses the guard. Callers reuse the variable their
+   * DB-open guard already honors. Deliberately not forwarded into
+   * agent-spawned shells (assistant/src/tools/terminal/safe-env.ts), so a
+   * daemon-level opt-out cannot disarm the guard for tests run from there.
+   */
+  allowEnvVar: string;
+  /** Package-specific line telling the reader where to run tests from. */
+  runHint: string;
+}
+
+/**
+ * Throws when called in a bun-test process and `dir` does not resolve under
+ * `os.tmpdir()`. Inert outside test processes. Canonicalizes on every call
+ * (no memo): a previously validated path could later be replaced by a
+ * symlink, and the guard only runs in test processes anyway.
+ */
+export function assertTestPathIsEphemeral(
+  dir: string,
+  options: EphemeralTestPathOptions,
+): void {
+  if (!isBunTestProcess()) {
+    return;
+  }
+  if (process.env[options.allowEnvVar] === "1") {
+    return;
+  }
+  const tmpRoot = canonicalizePathThroughExistingParent(tmpdir());
+  const resolved = canonicalizePathThroughExistingParent(dir);
+  if (resolved !== tmpRoot && !resolved.startsWith(tmpRoot + sep)) {
+    throw new Error(
+      [
+        `Refusing to use ${dir} (resolves to ${resolved}) in a test process: it is not under the temp directory (${tmpRoot}).`,
+        "",
+        "Tests must only touch ephemeral state; a real directory would expose",
+        "live install state to destructive test fixtures. This usually means",
+        "`bun test` ran from a cwd without the package's bunfig.toml, so the",
+        "test preload that redirects paths to a tmpdir never loaded.",
+        options.runHint,
+        `Set ${options.allowEnvVar}=1 to bypass deliberately.`,
+      ].join("\n"),
+    );
+  }
+}