@specific.dev/spectest 0.87.0 → 0.88.0

package/src/components/electron-chrome.ts

@@ -0,0 +1,76 @@
+// Runs before the application's main entry, like Playwright's Electron loader.
+// Observe constructor options; do not replace the app entry, preload, IPC, or OS.
+export const ELECTRON_CHROME_HOOK = String.raw`
+const electron = require('electron');
+const NativeBrowserWindow = electron.BrowserWindow;
+const WrappedBrowserWindow = new Proxy(NativeBrowserWindow, {
+  construct(Target, args, NewTarget) {
+    const win = Reflect.construct(Target, args, NewTarget);
+    const options = args[0] || {};
+    const chrome = {
+      titleBarStyle: options.titleBarStyle || 'default',
+      frame: options.frame !== false,
+      trafficLightPosition: options.trafficLightPosition || null,
+      titleBarOverlay: options.titleBarOverlay || false,
+      roundedCorners: options.roundedCorners !== false,
+      buttonVisibility: null,
+    };
+    const publish = () => {
+      if (win.isDestroyed() || win.webContents.isDestroyed()) return;
+      void win.webContents.executeJavaScript(
+        'window.__spectestElectronChrome = ' + JSON.stringify(chrome)
+      ).catch(() => {}); // A document can be replaced while this is in flight.
+    };
+    win.webContents.on('dom-ready', publish);
+    // Capture supported native setters too, without adding macOS APIs on Linux.
+    for (const [method, key] of [
+      ['setWindowButtonVisibility', 'buttonVisibility'],
+      ['setWindowButtonPosition', 'trafficLightPosition'],
+      ['setTitleBarOverlay', 'titleBarOverlay'],
+    ]) {
+      if (typeof win[method] !== 'function') continue;
+      const original = win[method];
+      win[method] = function(value) {
+        const result = original.call(this, value);
+        chrome[key] = value;
+        publish();
+        return result;
+      };
+    }
+    return win;
+  },
+});
+// Electron's own exports are non-configurable. Wrap module resolution instead
+// of modifying them; all other exports retain their original descriptors.
+const Module = require('node:module');
+const originalLoad = Module._load;
+const facades = new Map();
+Module._load = function(request, ...args) {
+  const exports = originalLoad.call(this, request, ...args);
+  if (request !== 'electron' && request !== 'electron/main') return exports;
+  if (!facades.has(exports)) {
+    const descriptors = Object.getOwnPropertyDescriptors(exports);
+    descriptors.BrowserWindow = { value: WrappedBrowserWindow, enumerable: true };
+    facades.set(exports, Object.defineProperties({}, descriptors));
+  }
+  return facades.get(exports);
+};
+// Electron's native ESM translator bypasses Module._load. Route ESM imports
+// through the same facade using Node's synchronous loader hooks when available.
+if (typeof Module.registerHooks === 'function') {
+  const source = 'import { createRequire } from "node:module";\n' +
+    'const electron = createRequire(' + JSON.stringify(__filename) + ')("electron");\n' +
+    'export default electron;\n' + Object.keys(electron)
+      .filter(key => /^[A-Za-z_$][\w$]*$/.test(key))
+      .map(key => 'export const ' + key + ' = electron.' + key + ';').join('\n');
+  const url = 'data:text/javascript,' + encodeURIComponent(source);
+  Module.registerHooks({
+    resolve(specifier, context, next) {
+      if ((specifier === 'electron' || specifier === 'electron/main') && context.conditions.includes('import')) {
+        return { url, shortCircuit: true };
+      }
+      return next(specifier, context);
+    },
+  });
+}
+`;

package/src/components/electron.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { electron } from './electron.js';
+import { desktopApp, isDesktopApp } from '../desktop.js';
+
+function fixture(run: (directory: string) => void) {
+  const directory = mkdtempSync(join(tmpdir(), 'spectest-electron-'));
+  try {
+    writeFileSync(join(directory, 'package.json'), JSON.stringify({ devDependencies: { electron: '43.2.0' } }));
+    run(directory);
+  } finally { rmSync(directory, { recursive: true, force: true }); }
+}
+
+describe('Electron component contract', () => {
+  test('rejects apps without Electron before starting an expensive build', () => fixture(appDir => {
+    writeFileSync(join(appDir, 'package.json'), '{}');
+    expect(() => electron({ appDir })).toThrow('declare electron');
+  }));
+  test('honors locked installation, custom build commands, and app environment', () => fixture(appDir => {
+    writeFileSync(join(appDir, 'package-lock.json'), '{}');
+    const service = electron({ appDir, buildCommand: 'npm run compile', env: { API_URL: 'http://backend:4320' } });
+    expect(service.image).toMatchObject({ context: appDir });
+    expect((service.image as { content: string }).content).toContain('RUN npm ci\n');
+    expect((service.image as { content: string }).content).toContain('RUN npm run compile\n');
+    expect(service.env?.API_URL).toBe('http://backend:4320');
+  }));
+  test('rejects malformed image tags and multiline Dockerfile injection', () => fixture(appDir => {
+    expect(() => electron({ appDir, nodeVersion: '24\nRUN false' })).toThrow('image tag');
+    expect(() => electron({ appDir, buildCommand: 'npm run build\nUSER other' })).toThrow('single-line');
+  }));
+  test('desktop identity cannot be mistaken for a URL or browser/mobile handle', () => {
+    expect(isDesktopApp(desktopApp('http://app.internal:9223', 'app'))).toBe(true);
+    expect(isDesktopApp({ url: 'http://app.internal:8081' })).toBe(false);
+    expect(isDesktopApp(null)).toBe(false);
+  });
+});

package/src/components/electron.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { ServiceDefinition } from "../index.js";
+import { resolveProjectPath } from "../project-files.js";
+import { desktopApp, type DesktopApp } from "../desktop.js";
+import { ELECTRON_CHROME_HOOK } from "./electron-chrome.js";
+
+export interface ElectronOptions {
+  /** Project-relative app directory; must contain package.json and Electron. */
+  appDir?: string;
+  /** Debian Node image tag, default 24-bookworm-slim. */
+  nodeVersion?: string;
+  /** Build the main/preload/renderer output; default npm run build. */
+  buildCommand?: string;
+  /** Dependency install command; defaults to npm ci when a lockfile exists. */
+  installCommand?: string;
+  /** App entry relative to /app, default . (package.json main). */
+  entry?: string;
+  env?: Record<string, string>;
+  dependsOn?: string[];
+}
+
+// Test-only debugger proxy: Electron binds its CDP socket to loopback. Forward
+// HTTP and WebSocket traffic from the VM to that socket, normalizing Host as
+// Chromium requires. It exposes no app-specific actions or state endpoints.
+export const ELECTRON_LAUNCHER = String.raw`
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+const require = createRequire('/app/package.json');
+const child = spawn(require('electron'), [
+  ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
+  '--disable-dev-shm-usage', '--remote-debugging-port=9222',
+  '-r', '/spectest-electron-chrome.cjs',
+  process.env.SPECTEST_ELECTRON_ENTRY || '.',
+], { cwd: '/app', stdio: 'inherit', env: process.env });
+const upstream = req => ({
+  host: '127.0.0.1', port: 9222, path: req.url, method: req.method,
+  headers: { ...req.headers, host: '127.0.0.1:9222' },
+});
+const server = http.createServer((req, res) => {
+  const proxy = http.request(upstream(req), response => {
+    res.writeHead(response.statusCode, response.headers);
+    response.pipe(res);
+  });
+  proxy.on('error', () => { res.writeHead(503); res.end('Electron debugger starting'); });
+  req.pipe(proxy);
+});
+server.on('upgrade', (req, socket, head) => {
+  const proxy = http.request(upstream(req));
+  proxy.on('upgrade', (response, remote, remoteHead) => {
+    socket.write('HTTP/1.1 101 Switching Protocols\r\n' +
+      Object.entries(response.headers).map(([k, v]) => k + ': ' + v).join('\r\n') + '\r\n\r\n');
+    if (remoteHead.length) socket.write(remoteHead);
+    if (head.length) remote.write(head);
+    socket.pipe(remote); remote.pipe(socket);
+    socket.on('error', () => remote.destroy());
+    remote.on('error', () => socket.destroy());
+    socket.on('close', () => remote.destroy());
+    remote.on('close', () => socket.destroy());
+  });
+  proxy.on('response', () => socket.destroy());
+  proxy.on('error', () => socket.destroy());
+  proxy.end();
+});
+server.listen(9223, '0.0.0.0');
+child.on('error', error => { console.error(error); process.exit(1); });
+child.on('exit', code => process.exit(code ?? 1));
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => child.kill(signal));
+`;
+
+/** Real Linux Electron under Xvfb, with a generated image and graphical replay.
+ * Like expo(), returns an app handle for the matching context method.
+ * Requires Linux-compatible application dependencies and binaries. */
+export function electron(options: ElectronOptions = {}) {
+  const appDir = options.appDir ?? ".";
+  const manifest = resolveProjectPath(`${appDir}/package.json`);
+  if (!existsSync(manifest)) throw new Error(`electron(): no package.json in ${appDir}`);
+  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+  if (!pkg.dependencies?.electron && !pkg.devDependencies?.electron) {
+    throw new Error("electron(): declare electron in the app's dependencies or devDependencies");
+  }
+  const locked = existsSync(resolveProjectPath(`${appDir}/package-lock.json`));
+  const node = options.nodeVersion ?? "24-bookworm-slim";
+  if (!/^[\w.-]+$/.test(node)) throw new Error("electron(): invalid Node image tag");
+  const install = options.installCommand ?? (locked ? "npm ci" : "npm install");
+  const build = options.buildCommand ?? "npm run build";
+  if ([install, build].some(command => /[\r\n]/.test(command))) {
+    throw new Error("electron(): build/install commands must be single-line shell commands");
+  }
+  return {
+    image: {
+      type: "dockerfile",
+      context: appDir,
+      exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
+      content: `FROM node:${node}
+RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY . .
+RUN ${install}
+RUN node node_modules/electron/install.js
+RUN ${build}
+`,
+    },
+    files: [
+      { path: "/spectest-electron.mjs", content: ELECTRON_LAUNCHER },
+      { path: "/spectest-electron-chrome.cjs", content: ELECTRON_CHROME_HOOK },
+    ],
+    command: "xvfb-run -a node /spectest-electron.mjs",
+    env: { ...options.env, SPECTEST_ELECTRON_ENTRY: options.entry ?? "." },
+    dependsOn: options.dependsOn,
+    ports: [9223],
+    readyCheck: { type: "http", port: 9223, path: "/json/version", timeoutSecs: 60 },
+    helpers: ({ name }: { name: string }) => desktopApp(`http://${name}.internal:9223`, name),
+  } satisfies ServiceDefinition<DesktopApp>;
+}

package/src/components/index.ts

@@ -97,3 +97,4 @@ export {
   type CassetteResponse,
   type CassetteState,
 } from "./replayFake.js";
+export { electron, type ElectronOptions } from "./electron.js";

package/src/components/supabase-functions-reach.test.ts

@@ -0,0 +1,90 @@
+import { afterAll, beforeAll, 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 { excludeAllBut, functionsReach, importMapLocalTargets, importSpecifiers } from "./supabase-functions-reach.js";
+
+let root: string;
+
+function file(rel: string, text: string): void {
+  mkdirSync(join(root, rel, ".."), { recursive: true });
+  writeFileSync(join(root, rel), text);
+}
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), "sb-fn-reach-"));
+  file("supabase/functions/hello/index.ts", 'import { greet } from "../../../packages/shared/src/greet.ts";\nimport "npm:zod";\nDeno.serve(() => new Response(greet()));\n');
+  file("supabase/functions/bye/index.ts", 'import { db } from "@db/client.ts";\nexport default 1;\n');
+  file("supabase/functions/deno.json", JSON.stringify({ imports: { "@db/": "../../lib/db/", "zod": "npm:zod" } }));
+  file("packages/shared/src/greet.ts", 'import { fmt } from "./fmt.ts";\nimport { util } from "../../util/mod.ts";\nexport const greet = () => fmt(util());\n');
+  file("packages/shared/src/fmt.ts", "export const fmt = (s: string) => s;\n");
+  file("packages/util/mod.ts", "export const util = () => 'x';\n");
+  file("lib/db/client.ts", "export const db = 1;\n");
+  file("docs/guide.md", "# not code\n");
+  file("site/app/page.tsx", 'import x from "../../packages/shared/src/greet.ts";\n');
+});
+
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+describe("functionsReach", () => {
+  test("follows relative imports and local import-map entries transitively, into directories", () => {
+    expect(functionsReach(root, "supabase/functions")).toEqual(["lib/db", "packages/shared/src", "packages/util", "supabase/functions"]);
+  });
+  test("a self-contained functions directory is the whole answer; a missing one is nothing", () => {
+    file("alone/functions/f/index.ts", 'import "https://deno.land/std/http/server.ts";\nimport("./helper.ts");\n');
+    expect(functionsReach(root, "alone/functions")).toEqual(["alone/functions"]);
+    expect(functionsReach(root, "nowhere/functions")).toEqual([]);
+  });
+  test("an import that leaves the project is ignored", () => {
+    file("escape/functions/f/index.ts", 'import "../../../../../../etc/passwd";\n');
+    expect(functionsReach(root, "escape/functions")).toEqual(["escape/functions"]);
+  });
+  test("the exclude list drops everything but the answer", () => {
+    expect(excludeAllBut(["lib/db", "supabase/functions"])).toEqual([
+      "**",
+      "!lib/db",
+      "!lib/db/**",
+      "!supabase/functions",
+      "!supabase/functions/**",
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/.spectest/**",
+      "**/__pycache__/**",
+      "**/.venv/**",
+    ]);
+    expect(excludeAllBut(["."])).toEqual([]);
+  });
+});
+
+describe("parsers", () => {
+  test("import specifiers of every shape", () => {
+    const t = 'import a from "./a.ts";\nexport * from "../b.ts";\nimport "./side.ts";\nconst m = await import("./dyn.ts");\nimport type { T } from "npm:x";\n';
+    expect(importSpecifiers(t)).toEqual(["./a.ts", "../b.ts", "./side.ts", "./dyn.ts", "npm:x"]);
+  });
+  test("import map local targets", () => {
+    expect(importMapLocalTargets('{"imports":{"@a/":"../../a/","b":"npm:b","c":"/c/mod.ts"}}')).toEqual(["../../a/", "/c/mod.ts"]);
+    expect(importMapLocalTargets("not json")).toEqual([]);
+  });
+});
+
+describe("supabase() wiring", () => {
+  test("the functions image context is the module graph, and the root mount is reach-exempt", async () => {
+    const prev = process.env.SPECTEST_WORKSPACE;
+    process.env.SPECTEST_WORKSPACE = root;
+    try {
+      const { supabase } = await import("./supabase.js");
+      const stack = supabase({ dir: "supabase" });
+      const parts = stack.group.services({ name: "sb", key: (part: string) => (part === "gateway" ? "sb" : `sb-${part}`) });
+      const fn = parts.functions as { image: { context?: string; exclude?: readonly string[] }; volumes?: readonly { source?: string; reachExempt?: boolean }[] };
+      expect(fn.image.context).toBe(".");
+      expect(fn.image.exclude?.slice(0, 9)).toEqual(["**", "!lib/db", "!lib/db/**", "!packages/shared/src", "!packages/shared/src/**", "!packages/util", "!packages/util/**", "!supabase/functions", "!supabase/functions/**"]);
+      expect(fn.image.exclude?.at(-1)).toBe("**/.venv/**");
+      expect(fn.volumes?.[0]).toMatchObject({ source: root, reachExempt: true });
+      expect((parts.db as { inputs?: readonly string[] }).inputs).toEqual(["supabase"]);
+    } finally {
+      if (prev === undefined) delete process.env.SPECTEST_WORKSPACE;
+      else process.env.SPECTEST_WORKSPACE = prev;
+    }
+  });
+});

package/src/components/supabase-functions-reach.ts

@@ -0,0 +1,153 @@
+// What the edge functions can load from the project — the pure part.
+//
+// The edge runtime serves each function from the project root, mounted
+// whole so that a monorepo function's `../../packages/shared/mod.ts`
+// resolves where it sits. Whole is right for the runtime and wrong for
+// the reach: with the root in a build context and a volume, every file of
+// the project could "reach" the functions, and a change to `docs/` could
+// never skip a run. So the component works out the **module graph** the
+// functions can load, statically, and hands the build context and the
+// reach exactly that: the functions directory, and every directory a
+// relative import or a local import-map entry leads to, followed
+// transitively. Directories rather than files, so a sibling module a
+// dynamic `import()` picks at run time comes along.
+//
+// What it cannot see: a computed specifier that leaves the directories
+// found (`import(\`../../${x}/mod.ts\`)`), and a `Deno.readTextFile` of a
+// path outside them. Both are rare in a function, and both are the same
+// class of hole as a test reading the workspace through `node:fs`. A tree
+// too large to walk within the budget is answered with the whole project,
+// the safe side.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/** Files the walk parses for imports. */
+const SOURCE_EXT = /\.(?:[mc]?[jt]sx?)$/;
+/** Names never walked into. */
+const SKIP = new Set(["node_modules", ".git", ".spectest", "dist", "build", ".next"]);
+/** The walk gives up past this many files and answers with the root. */
+const FILE_BUDGET = 20_000;
+
+const IMPORT_RE =
+  /\b(?:import|export)\b[^;'"`]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+/** Specifiers a source text imports, as written. */
+export function importSpecifiers(text: string): string[] {
+  const out: string[] = [];
+  for (const m of text.matchAll(IMPORT_RE)) out.push(m[1] ?? m[2] ?? m[3] ?? "");
+  return out.filter((s) => s.length > 0);
+}
+
+/** Local targets an import map (`deno.json` `imports`, `import_map.json`)
+ *  names, as written: relative values, and root-relative `/…` ones. */
+export function importMapLocalTargets(text: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  const imports = (parsed as { imports?: unknown })?.imports;
+  if (typeof imports !== "object" || imports === null) return [];
+  return Object.values(imports as Record<string, unknown>).filter(
+    (v): v is string => typeof v === "string" && (v.startsWith("./") || v.startsWith("../") || v.startsWith("/")),
+  );
+}
+
+function toPosix(p: string): string {
+  return sep === "/" ? p : p.split(sep).join("/");
+}
+
+/**
+ * The directories, project-relative and sorted, that the functions under
+ * `fnRelPath` can load modules from: `fnRelPath` itself, and every
+ * directory a relative import or a local import-map entry leads to,
+ * transitively. `["."]` when the walk runs out of budget. A directory
+ * nested under another in the answer is dropped.
+ */
+export function functionsReach(root: string, fnRelPath: string): string[] {
+  const rootAbs = resolve(root);
+  const dirs = new Set<string>();
+  const queue: string[] = [resolve(rootAbs, fnRelPath)];
+  let budget = FILE_BUDGET;
+
+  const inRoot = (p: string): boolean => p === rootAbs || p.startsWith(rootAbs + sep);
+  const enqueue = (target: string): void => {
+    if (!inRoot(target) || !existsSync(target)) return;
+    let st;
+    try {
+      st = statSync(target);
+    } catch {
+      return;
+    }
+    const dir = st.isDirectory() ? target : dirname(target);
+    if (![...dirs].some((d) => dir === d || dir.startsWith(d + sep))) queue.push(dir);
+  };
+  const follow = (fromDir: string, spec: string): void => {
+    if (spec.startsWith("./") || spec.startsWith("../")) enqueue(resolve(fromDir, spec));
+    else if (spec.startsWith("/")) enqueue(resolve(rootAbs, spec.slice(1)));
+  };
+
+  while (queue.length > 0) {
+    const dir = queue.shift()!;
+    if ([...dirs].some((d) => dir === d || dir.startsWith(d + sep))) continue;
+    if (!existsSync(dir)) continue;
+    dirs.add(dir);
+    // Every file below it, parsed for what it imports.
+    const stack: string[] = [dir];
+    while (stack.length > 0) {
+      const d = stack.pop()!;
+      let entries;
+      try {
+        entries = readdirSync(d, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const e of entries) {
+        const p = join(d, e.name);
+        if (e.isDirectory()) {
+          if (!SKIP.has(e.name)) stack.push(p);
+          continue;
+        }
+        if (!e.isFile()) continue;
+        if (--budget < 0) return ["."];
+        if (e.name === "deno.json" || e.name === "import_map.json") {
+          for (const t of importMapLocalTargets(safeRead(p))) follow(d, t.endsWith("/") ? t.slice(0, -1) : t);
+          continue;
+        }
+        if (!SOURCE_EXT.test(e.name)) continue;
+        for (const spec of importSpecifiers(safeRead(p))) follow(d, spec);
+      }
+    }
+  }
+
+  // Minimal, project-relative, sorted.
+  const rel = [...dirs].map((d) => (d === rootAbs ? "." : toPosix(relative(rootAbs, d))));
+  const minimal = rel.filter((d) => !rel.some((o) => o !== d && (o === "." || d.startsWith(o + "/"))));
+  return [...new Set(minimal)].sort();
+}
+
+function safeRead(p: string): string {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** The `exclude` list that narrows a root build context to `dirs`: drop
+ *  everything, then re-include each directory and its subtree, then drop
+ *  again what no context should carry (a re-included `packages/shared`
+ *  would otherwise bring its `node_modules` along). */
+export function excludeAllBut(dirs: readonly string[]): string[] {
+  if (dirs.includes(".")) return [];
+  return ["**", ...dirs.flatMap((d) => [`!${d}`, `!${d}/**`]), ...REEXCLUDE];
+}
+
+/** Re-excluded after the re-includes: the names the default ignore drops. */
+const REEXCLUDE = ["**/node_modules/**", "**/.git/**", "**/.spectest/**", "**/__pycache__/**", "**/.venv/**"];
+
+// Keep `isAbsolute` referenced for callers that pass absolute fnRelPath by
+// mistake: the walk resolves it against the root either way.
+void isAbsolute;

package/src/components/supabase.ts

@@ -51,6 +51,7 @@
 
 import { createHmac } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import { excludeAllBut, functionsReach } from "./supabase-functions-reach.js";
 import { readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
@@ -166,6 +167,9 @@ function providerCredentials(
  * cache rides into the image as a layer — so at run time the worker resolves
  * those URLs locally and never reaches for the network.
  *
+ * The context is the module graph the functions can load (the functions
+ * directory and what its imports lead to, `functionsReach`), copied whole
+ * so a monorepo function's `../../packages/…` resolves at bundle time too.
  * One synthetic entrypoint imports every function, so the whole set is one
  * graph rather than one per function. Bundling is best-effort: a function that
  * fails to bundle (a type error, an import that only resolves at run time)
@@ -175,13 +179,13 @@ function providerCredentials(
 function functionsDockerfile(fnRelPath: string): string {
   return `FROM ${IMAGES.functions}
 ENV DENO_DIR=${DENO_DIR}
-COPY ${fnRelPath} /warm/functions
+COPY . /warm/repo
 RUN set -eu; \
     : > /warm/all.ts; \
-    for d in /warm/functions/*/; do \
+    for d in /warm/repo/${fnRelPath}/*/; do \
       [ -f "$d/index.ts" ] || continue; \
       n=$(basename "$d"); \
-      printf 'import "./functions/%s/index.ts";\\n' "$n" >> /warm/all.ts; \
+      printf 'import "./repo/${fnRelPath}/%s/index.ts";\\n' "$n" >> /warm/all.ts; \
     done; \
     edge-runtime bundle --entrypoint /warm/all.ts --output /tmp/warm.eszip --quiet || true; \
     rm -rf /tmp/warm.eszip /warm
@@ -1684,6 +1688,10 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
         ? `${REPO_MOUNT}/${fnDir.slice(root.length + 1)}`
         : `${REPO_MOUNT}/supabase/functions`;
   const migrationsPath = inDir("migrations");
+  // The directories the functions can load modules from: the functions
+  // directory and what its imports lead to (`supabase-functions-reach.ts`).
+  // The build context and the reach are narrowed to exactly these.
+  const fnReachDirs = withFunctions ? functionsReach(root, fnRelPath) : [];
 
   // ── config file (config.toml / config.json) ───────────────────────────
   // The CLI's own project config, mapped onto the stack. Read at build time:
@@ -1890,8 +1898,20 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
       const parts: ServicesMap = {};
 
       // ── db ──────────────────────────────────────────────────────────
+      // What the stack reads from the project: the Supabase folder
+      // (config.toml, migrations, seed, functions) and the mail templates,
+      // which may sit anywhere in the repo. Declared as inputs so a change
+      // to any of them is never taken as one that can affect no test; the
+      // migrations volume carries the folder too, but only when there is
+      // a migrations directory, and a config-only project must count as
+      // well.
+      const inputs: string[] = [
+        ...(opts.dir !== undefined && !opts.dir.startsWith("/") ? [opts.dir] : []),
+        ...templateBodies.map(([, spec]) => spec.path).filter((t) => !t.startsWith("/")),
+      ];
       const dbDef: ServiceDefinition = {
         image: { type: "registry", reference: opts.db?.image ?? IMAGES.db },
+        ...(inputs.length > 0 ? { inputs } : {}),
         // `args` (not `command`): keep the image's docker-entrypoint.sh so it
         // runs initdb + its baked init-scripts before starting.
         args: [
@@ -2211,6 +2231,12 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           image: {
             type: "dockerfile",
             content: functionsDockerfile(fnRelPath),
+            // The root, narrowed to the module graph: only the functions
+            // directory and what its imports lead to enter the context, so
+            // a change anywhere else neither uploads nor counts as reaching
+            // the functions.
+            context: ".",
+            exclude: excludeAllBut(fnReachDirs),
           },
           // The **project root**, mounted with the functions directory in its
           // real position underneath. Mounting only `supabase/functions`
@@ -2219,8 +2245,10 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           // (`../../../../packages/…`), and that only resolves if the
           // directory sits where it sits in the repo. Read-only: the runtime
           // only reads sources, and a function writing into its own directory
-          // would be writing into the user's checkout.
-          volumes: [{ source: projectRootPath(), target: REPO_MOUNT, readOnly: true }],
+          // would be writing into the user's checkout. For the reach the
+          // mount is exempt: what the functions can load is the module graph
+          // above, which the build context already states.
+          volumes: [{ source: projectRootPath(), target: REPO_MOUNT, readOnly: true, reachExempt: true }],
           // Our router (see FUNCTIONS_MAIN_TS) sits outside that mount, so
           // the project never has to carry a `main/` function of ours.
           files: [{ path: "/home/deno/main/index.ts", content: FUNCTIONS_MAIN_TS }],