Make a fresh clone work without submodules or a build step

RhysSullivan · RhysSullivan · commit d6d6acfa46b7 · 2026-06-10T07:57:29.000-07:00
A fresh `git clone &amp;&amp; bun install` previously could not run `bun dev`
or `bun run test:e2e`:

- @executor-js/vite-plugin only ships a built `dist/`, which used to
  require knowing to run `turbo run build` after installing. The root
  `prepare` hook now bundles it on every install (tsup, ~0.2s), so the
  package resolves on a fresh clone. (Pointing `exports.default` at the
  TS source instead would only work on Node &gt;= 23.6 type-stripping —
  vite externalizes the plugin import from vite.config.ts, so Node
  itself has to load it.)
- e2e and testkit imported `vendor/mcporter/dist`, which requires
  initializing the submodule AND building it with pnpm. Consume the fork
  from npm as @executor-js/mcporter instead; the submodule stays for
  developing the fork itself (see vendor/README.md). The fork's 0.11.4
  relaxes its zod range to ^4.3.6 so the repo keeps a single zod copy.
- The cloud e2e stub (EXECUTOR_E2E_STUB=1) stubbed WorkOS auth and Autumn
  but not WorkOS Vault, so any secret write (e.g. oauth.createClient with
  a client secret) dialed the real WorkOS API with the stub key and
  500'd — the cloud half of the oauth-callback-url scenario was failing
  on main. Inject the existing in-memory test vault client in stub mode.

Verified by cloning the repo fresh into /tmp: install, format, lint,
typecheck, and the full e2e suite (cloud + selfhost) all pass with no
submodules initialized and no manual build step.
diff --git a/.gitignore b/.gitignore
@@ -60,10 +60,11 @@ apps/desktop/resources/
 apps/cloud/.dev-db/
 apps/cloud/.e2e-db/
 
-# e2e suite: generated run artifacts + throwaway target state
+# e2e suite: generated run artifacts + throwaway target state (the * also
+# covers ad-hoc variants like .e2e-stub-db-manual from debugging boots)
 e2e/runs/
-apps/cloud/.e2e-stub-db/
-apps/host-selfhost/.e2e-data/
+apps/cloud/.e2e-stub-db*/
+apps/host-selfhost/.e2e-data*/
 
 # playwright e2e artifacts
 test-results/
diff --git a/README.md b/README.md
@@ -126,6 +126,17 @@ bun dev
 
 The dev server starts at `http://127.0.0.1:4788`.
 
+### Tests
+
+```bash
+bun run test       # unit + integration suites
+bun run test:e2e   # full-stack e2e: boots the cloud and self-host apps and drives them
+```
+
+The browser e2e scenarios need Playwright's Chromium once per machine:
+`bunx playwright install chromium`. The git submodules under `vendor/` are
+optional — see [vendor/README.md](vendor/README.md).
+
 ## Community
 
 Join the Discord: [https://discord.gg/eF29HBHwM6](https://discord.gg/eF29HBHwM6)
diff --git a/apps/cloud/src/engine/execution-stack.ts b/apps/cloud/src/engine/execution-stack.ts
@@ -47,6 +47,7 @@ import { makeDynamicWorkerExecutor } from "@executor-js/runtime-dynamic-worker";
 import executorConfig from "../../executor.config";
 import { DbService } from "../db/db";
 import { cloudDbProviderLayer } from "../db/fuma";
+import { E2E_STUB, E2EStubVaultClient } from "../testing/e2e-stub";
 
 export { makeExecutionStack } from "@executor-js/api/server";
 
@@ -56,13 +57,16 @@ export const CloudDbProvider = cloudDbProviderLayer(collectTables());
 
 // Fresh plugin instances per request, carrying the Worker env's WorkOS Vault
 // credentials. Matches the old `createScopedExecutor`'s `orgPlugins()`.
+// EXECUTOR_E2E_STUB swaps the Vault client for the shared in-memory stub —
+// secret writes would otherwise dial the real WorkOS API with the stub key.
 export const CloudPluginsProvider: Layer.Layer<PluginsProvider> = Layer.succeed(PluginsProvider)({
   plugins: () =>
     executorConfig.plugins({
       workosCredentials: {
         apiKey: env.WORKOS_API_KEY,
         clientId: env.WORKOS_CLIENT_ID,
       },
+      ...(E2E_STUB ? { workosVaultClient: E2EStubVaultClient } : {}),
     }),
 });
 
diff --git a/apps/cloud/src/testing/e2e-stub.ts b/apps/cloud/src/testing/e2e-stub.ts
@@ -4,6 +4,8 @@
 //
 // Enabled by `EXECUTOR_E2E_STUB=1`. NEVER set in production — when unset, the
 // served route composition is byte-for-byte the real `*Live` layers.
+import { makeTestWorkOSVaultClient } from "@executor-js/plugin-workos-vault/testing";
+
 import { WorkOSTestLayer, makeWorkOSTestState } from "../auth/workos.test-layer";
 import { AutumnTestLayer, makeAutumnTestState } from "../extensions/billing/service.test-layer";
 
@@ -19,3 +21,8 @@ const autumn = makeAutumnTestState({}); // no paid subscription → free plan 
 
 export const E2EStubWorkOSLayer = WorkOSTestLayer(workos);
 export const E2EStubAutumnLayer = AutumnTestLayer(autumn);
+
+// In-memory WorkOS Vault, shared across requests like the stubs above. Without
+// it, any secret write (e.g. `oauth.createClient` with a client secret) dials
+// the real WorkOS API with the stub key and 500s.
+export const E2EStubVaultClient = makeTestWorkOSVaultClient();
diff --git a/bun.lock b/bun.lock
diff --git a/e2e/package.json b/e2e/package.json
@@ -13,6 +13,7 @@
   },
   "dependencies": {
     "@executor-js/api": "workspace:*",
+    "@executor-js/mcporter": "0.11.4",
     "@executor-js/plugin-graphql": "workspace:*",
     "@executor-js/plugin-mcp": "workspace:*",
     "@executor-js/plugin-openapi": "workspace:*",
diff --git a/e2e/src/surfaces/mcp.ts b/e2e/src/surfaces/mcp.ts
@@ -1,14 +1,14 @@
-// MCP surface: the vendored mcporter fork as a programmatic MCP client, with
-// headless OAuth via the target's consent strategy. Session methods are
-// Effects; mcporter itself is promise-native underneath. Assertions are
-// vitest's job.
+// MCP surface: our mcporter fork (@executor-js/mcporter on npm; develop it in
+// the vendor/mcporter submodule) as a programmatic MCP client, with headless
+// OAuth via the target's consent strategy. Session methods are Effects;
+// mcporter itself is promise-native underneath. Assertions are vitest's job.
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { Effect } from "effect";
 
-import { createRuntime, type Runtime } from "../../../vendor/mcporter/dist/index.js";
+import { createRuntime, type Runtime } from "@executor-js/mcporter";
 
 import type { Identity, Target } from "../target";
 
diff --git a/e2e/targets/selfhost.ts b/e2e/targets/selfhost.ts
@@ -4,7 +4,7 @@
 // in setup/selfhost.globalsetup.ts.
 import { Effect } from "effect";
 
-import { cookieConsentStrategy } from "../../vendor/mcporter/dist/index.js";
+import { cookieConsentStrategy } from "@executor-js/mcporter";
 
 import type { Identity, Target } from "../src/target";
 
diff --git a/package.json b/package.json
@@ -63,7 +63,7 @@
     "release:publish:packages:prepare": "bun run scripts/publish-packages.ts --prepare-only",
     "release:smoke:packages": "bun run scripts/smoke-test-packed.ts",
     "clean": "bun run scripts/clean.ts",
-    "prepare": "effect-language-service patch && effect-tsgo patch"
+    "prepare": "effect-language-service patch && effect-tsgo patch && bun run --cwd packages/core/vite-plugin build:bundle"
   },
   "dependencies": {},
   "devDependencies": {
diff --git a/packages/core/vite-plugin/package.json b/packages/core/vite-plugin/package.json
@@ -35,6 +35,7 @@
   },
   "scripts": {
     "build": "tsup && (tsc --declaration --emitDeclarationOnly --outDir dist --rootDir src || true)",
+    "build:bundle": "tsup",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "typecheck:slow": "tsc --noEmit"
diff --git a/testkit/README.md b/testkit/README.md
@@ -1,7 +1,8 @@
 # testkit (MCP surface) — MVP
 
-Black-box tests through the **MCP surface**, on the vendored mcporter fork
-(`vendor/mcporter`, with its headless `cookieConsentStrategy`). Every run emits a
+Black-box tests through the **MCP surface**, on our mcporter fork
+(`@executor-js/mcporter` on npm, with its headless `cookieConsentStrategy`;
+develop the fork itself in the `vendor/mcporter` submodule). Every run emits a
 **chat-transcript recording** (`run.json`) — the MCP surface *is* an agent-in-a-chat,
 so that's the natural shape.
 
diff --git a/testkit/record-flow.mjs b/testkit/record-flow.mjs
@@ -5,7 +5,7 @@
 // Run from testkit/ (playwright resolves here): node record-flow.mjs
 import { chromium } from "playwright";
 import { execSync } from "node:child_process";
-import { createRuntime, cookieConsentStrategy } from "../vendor/mcporter/dist/index.js";
+import { createRuntime, cookieConsentStrategy } from "@executor-js/mcporter";
 import { renderPlayer } from "./src/render.mjs";
 import { mkdtempSync, writeFileSync, readdirSync, renameSync, rmSync, mkdirSync } from "node:fs";
 import { tmpdir, homedir } from "node:os"; import { join } from "node:path";
diff --git a/testkit/src/driver.mjs b/testkit/src/driver.mjs
@@ -1,7 +1,7 @@
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createRuntime } from "../../vendor/mcporter/dist/index.js";
+import { createRuntime } from "@executor-js/mcporter";
 
 class AssertionError extends Error {}
 const textOf = (res) =>
diff --git a/testkit/src/testkit.mjs b/testkit/src/testkit.mjs
@@ -3,7 +3,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Recorder } from "./recorder.mjs";
 import { McpDriver } from "./driver.mjs";
-export { cookieConsentStrategy } from "../../vendor/mcporter/dist/index.js";
+export { cookieConsentStrategy } from "@executor-js/mcporter";
 
 const RUNS = join(dirname(fileURLToPath(import.meta.url)), "..", "runs");
 
diff --git a/vendor/README.md b/vendor/README.md
@@ -0,0 +1,34 @@
+# vendor/ — fork submodules (optional)
+
+These are git submodules holding our forks of upstream projects. **Nothing in
+the repo imports from `vendor/` at runtime** — code consumes the published
+packages from npm — so a fresh clone works without initializing submodules.
+They exist so the forks can be developed alongside the code that uses them.
+
+| Submodule | Published as | Used by |
+| --- | --- | --- |
+| `vendor/mcporter` | `@executor-js/mcporter` | `e2e/` + `testkit/` (headless MCP client with `cookieConsentStrategy`) |
+| `vendor/emulate` | _not yet published_ | nothing on `main` (stateful API emulators, used on feature branches) |
+
+## Developing a fork
+
+```bash
+git submodule update --init vendor/mcporter
+cd vendor/mcporter
+pnpm install && pnpm build
+```
+
+To test local fork changes against the repo before publishing, point the
+consumer at the submodule build with a temporary `file:` override (or
+`bun link`), then revert once the new version is published:
+
+```jsonc
+// e2e/package.json (temporary, do not commit)
+"@executor-js/mcporter": "file:../vendor/mcporter"
+```
+
+## Releasing a fork
+
+Bump the fork's `package.json` version, publish from the submodule
+(`npm publish --access public`), push the fork branch, bump the consumer's
+dependency here, and commit the new submodule pointer.
