@alexkroman1/aai-cli 14.0.0 → 15.1.0

package/dist/build-BhEaxBPu.mjs

@@ -0,0 +1,481 @@
+#!/usr/bin/env node
+import { a as ok, t as CliError } from "./_output-DBP9Op_d.mjs";
+import { n as log, r as notify } from "./_ui-DCt4qZrk.mjs";
+import { n as withPreservedNodeEnv } from "./_vite-env-kejF0p2L.mjs";
+import { n as WORKER_ARTIFACT_REL, t as CLIENT_ARTIFACT_REL } from "./_artifacts-BJOYGQPp.mjs";
+import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-DM0d0M7m.mjs";
+import { assertTypechecks } from "./_typecheck-gate-U3jcil8L.mjs";
+import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-CvpqMpdh.mjs";
+import { TEST_FILES, classifyVitestError, runVitest } from "./test-D032V2cA.mjs";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { invariant } from "@alexkroman1/aai/internal";
+import { build } from "vite";
+import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
+import { DEFAULT_SYSTEM_PROMPT } from "@alexkroman1/aai";
+//#region src/_build-target.ts
+/**
+* Deployment TARGETS — what `aai build` emits beside the worker so a host can
+* run this project without the project holding anything host-specific.
+*
+* ## Why a target rather than a file in the scaffold
+*
+* Every host wants a different entry shape: Vercel wants a module whose default
+* export is an `http.Server` it binds itself, a container wants a long-lived
+* process, another platform wants something else again. Committing one of those
+* to the scaffold makes every project assert a fact that is load-bearing on
+* exactly one host — the same objection that removed `server.mjs`.
+*
+* Nitro is the worked precedent: one codebase, a preset per provider, and the
+* preset EMITS the host's expected shape into the build directory. `node-server`
+* is its default and Vercel/Netlify/Cloudflare are detected from the CI
+* environment with no configuration. Next does the same narrower thing with
+* `output: "standalone"` — it generates a `server.js` rather than asking anyone
+* to write one. Either way the user's repository contains no host file, which is
+* the property to preserve here.
+*
+* ## Auto-detection, and why it is safe
+*
+* A target is chosen with `--target`, or detected from the environment when the
+* flag is absent. Detection reads the variables the hosts set on their own build
+* containers ({@link TARGET_ENV_MARKERS}), so it only ever fires where the build
+* is genuinely running on that host — a laptop sets none of them and gets
+* {@link DEFAULT_BUILD_TARGET}, which emits nothing extra and is what every
+* existing project already does.
+*/
+/** The targets `aai build --target` accepts. */
+const BUILD_TARGETS = ["node", "vercel"];
+/**
+* What a build with no `--target` and no host environment produces: the worker
+* and the client, and nothing else.
+*
+* `node` rather than a `"none"` sentinel because it NAMES the deployment it
+* serves — a long-lived process running `aai start` — which is what every
+* container platform wants and what the scaffold's own `start` script runs.
+*/
+const DEFAULT_BUILD_TARGET = "node";
+/**
+* The environment variable each host sets on its own build container.
+*
+* `VERCEL` is set for every Vercel build and deployment. Detection is per host
+* rather than a single "am I in CI" test, because a GitHub Action building a
+* container image is CI too and wants the default.
+*/
+const TARGET_ENV_MARKERS = { VERCEL: "vercel" };
+function isBuildTarget(value) {
+	return BUILD_TARGETS.includes(value);
+}
+/**
+* Resolve the target for this build: an explicit flag wins, then the
+* environment, then {@link DEFAULT_BUILD_TARGET}.
+*
+* An unrecognised `--target` is REFUSED naming what is accepted, rather than
+* falling back to the default — a typo'd target that silently built the default
+* would deploy a project missing the entry its host needs, and the failure would
+* arrive as a 404 from the platform rather than as an error from the build.
+*/
+function resolveBuildTarget(explicit, env = process.env) {
+	if (explicit !== void 0) {
+		if (!isBuildTarget(explicit)) throw new Error(`Unknown build target "${explicit}". Accepted: ${BUILD_TARGETS.join(", ")}.`);
+		return explicit;
+	}
+	for (const [marker, target] of Object.entries(TARGET_ENV_MARKERS)) if (env[marker]) return target;
+	return DEFAULT_BUILD_TARGET;
+}
+/**
+* Where a PREBUILT Vercel deployment lives, relative to the project root.
+*
+* The Build Output API rather than an `api/` entry plus a `vercel.json`, and
+* the reason is ORDERING. Vercel reads `vercel.json` and decides what to build
+* BEFORE it runs the build command, so a `vercel.json` that the build WRITES
+* configures the NEXT deployment and not this one — a clean clone deploys with
+* no rewrite and no function at all. The `api/` shape only ever appeared to
+* work because a previous local `aai build --target vercel` had left both
+* files in the working tree, which is a property of one laptop rather than of
+* the repository. `.vercel/output/` is read AFTER the build command; it is the
+* only place a build can describe its own deployment.
+*
+* Two more things fall out of owning the directory, both of which the `api/`
+* shape got wrong and could not fix. The function bundle is ASSEMBLED here
+* rather than traced, so `.aai/worker.mjs` — loaded through a dynamic
+* `import(pathToFileURL(...))` that no static tracer can follow — and
+* `.env.example` — the file that DECLARES which variables become `ctx.env` —
+* are present because they were copied in. And the built client is served by
+* the CDN out of `static/` instead of through the function.
+*
+* Nitro's vercel preset is the worked precedent and lands in exactly here:
+* `output.dir = {{rootDir}}/.vercel/output`, `serverDir` a `.func` under it.
+*
+* @see https://vercel.com/docs/build-output-api/v3
+*/
+const VERCEL_OUTPUT_DIR = path.join(".vercel", "output");
+/**
+* The one function every request that is not a static file reaches.
+*
+* The Build Output API derives a function's ROUTE from its path, so the
+* directory name IS a URL and must not collide with one the static output
+* claims. **`index.func` collides**, which a deployment is the only way to
+* find out: it is served at `/index`, and Vercel's directory index resolves
+* `/` to the extensionless `/index` — so the function won `/`, every other
+* asset came off the CDN correctly, and the home page 500'd on a deployment
+* whose static output was perfect. Measured on a real preview:
+* `/favicon.ico`, `/index.html` and both hashed `/assets/*` returned 200
+* while `/` and `/index` did not.
+*
+* `__server` is Nitro's answer to the same problem (`__server.func`) and the
+* reason is this one: a double-underscore prefix is not a path any bundler
+* emits, so no static file can ever take the name.
+*/
+const VERCEL_FUNCTION_DIR = path.join(VERCEL_OUTPUT_DIR, "functions", "__server.func");
+/**
+* The route {@link VERCEL_FUNCTION_DIR} is served at — its directory name
+* without `.func`, which is how the Build Output API names a function.
+*/
+const VERCEL_FUNCTION_ROUTE = "/__server";
+/** Static assets the Vercel CDN serves directly, never reaching the function. */
+const VERCEL_STATIC_DIR = path.join(VERCEL_OUTPUT_DIR, "static");
+/**
+* Node versions Vercel offers. A build on anything newer picks the newest of
+* these rather than naming a runtime the platform will reject.
+*
+* @see https://vercel.com/docs/functions/runtimes/node-js/node-js-versions
+*/
+const SUPPORTED_NODE_MAJORS = [
+	20,
+	22,
+	24
+];
+/** `nodejs<major>.x` for the Node running this build, clamped to what Vercel offers. */
+function vercelNodeRuntime(version = process.versions.node) {
+	const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+	return `nodejs${Number.isNaN(major) ? 22 : SUPPORTED_NODE_MAJORS.findLast((v) => v <= major) ?? SUPPORTED_NODE_MAJORS[0]}.x`;
+}
+/**
+* The Vercel function entry, emitted into {@link VERCEL_FUNCTION_DIR}.
+*
+* ## Why a `(req, res)` handler and not `export default server`
+*
+* `export default <http.Server>` is what Vercel's own `@vercel/node` BUILDER
+* accepts, and it is the shape the previous `api/index.mjs` used. The Build
+* Output API has no builder in the path: `launcherType: "Nodejs"` invokes the
+* module's default export as a request handler, so the server never gets
+* bound and there is nothing to raise an `upgrade` event on it.
+*
+* ## How a WebSocket survives that
+*
+* Vercel hands a Node function the raw upgrade through its PER-REQUEST
+* context — `globalThis[Symbol.for("@vercel/request-context")].get()
+* .upgradeWebSocket()` returns the `{ req, socket, head }` triple — rather
+* than as an event. Nitro reaches it through `crossws/adapters/vercel`; here
+* the adapter is three lines, because {@link AgentServer.node} is a real
+* `http.Server` that already has both an `upgrade` and a `request` listener
+* registered. Re-emitting onto it is the whole translation, and it means the
+* deployed path through `server.ts` is the same one `aai dev` and `aai start`
+* take — no second WebSocket entry point to keep in step.
+*
+* The `204` afterwards is what the launcher needs to consider the invocation
+* finished; the socket the agent is now talking on is not this `res`.
+*
+* ## `import.meta.dirname`, not `process.cwd()`
+*
+* The function's working directory belongs to the platform, but `.aai/` and
+* `.env.example` were copied in BESIDE this file. Resolving from the module
+* keeps that a fact about the bundle rather than about how Vercel happens to
+* invoke it.
+*/
+const VERCEL_ENTRY_SOURCE = `// Generated by \`aai build --target vercel\` — do not edit, and do not commit.
+// Vercel invokes this handler per request and delivers a WebSocket upgrade
+// through its request context. See @alexkroman1/aai-cli/start.
+import { createProjectServer } from "@alexkroman1/aai-cli/start";
+
+const server = (await createProjectServer({ cwd: import.meta.dirname })).node;
+
+const REQUEST_CONTEXT = Symbol.for("@vercel/request-context");
+
+export default function handler(req, res) {
+  if (req.method === "GET" && req.headers.upgrade?.toLowerCase() === "websocket") {
+    const upgrade = globalThis[REQUEST_CONTEXT]?.get?.()?.upgradeWebSocket?.();
+    if (upgrade) {
+      server.emit("upgrade", upgrade.req, upgrade.socket, upgrade.head);
+      if (!res.headersSent && !res.writableEnded) {
+        res.statusCode = 204;
+        res.end();
+      }
+      return;
+    }
+  }
+  server.emit("request", req, res);
+}
+`;
+/**
+* `.vc-config.json` — how the platform runs {@link VERCEL_ENTRY_SOURCE}.
+*
+* `supportsResponseStreaming` is not optional here: an agent streams TTS audio
+* and SSE workflow events, and without it the platform buffers a response to
+* completion, which for a stream that ends when the call does means it never
+* arrives. `shouldAddHelpers` stays off — the entry speaks `node:http`, and
+* the helpers exist to bolt Express-shaped sugar onto a handler that does not.
+*/
+function vercelFunctionConfigSource(runtime = vercelNodeRuntime()) {
+	return `${JSON.stringify({
+		runtime,
+		handler: "index.mjs",
+		launcherType: "Nodejs",
+		shouldAddHelpers: false,
+		supportsResponseStreaming: true
+	}, null, 2)}\n`;
+}
+/**
+* `config.json` — the routing table, and the reason static assets stop paying
+* for a function invocation.
+*
+* `{ "handle": "filesystem" }` serves anything present in
+* {@link VERCEL_STATIC_DIR} from the CDN and only then falls through, so the
+* client bundle, its assets and the worklets are edge-served while
+* `/client-config`, `/websocket`, `/workflows/*` and the webhook route reach
+* the agent. The `api/` shape routed EVERY request through the function, which
+* this file's earlier revision noted as deliberate and "not what makes a
+* deployment work or not" — true of correctness, false of cost, and free here
+* because the Build Output API already separates the two directories.
+*/
+const VERCEL_BUILD_CONFIG_SOURCE = `${JSON.stringify({
+	version: 3,
+	routes: [{ handle: "filesystem" }, {
+		src: "/(.*)",
+		dest: VERCEL_FUNCTION_ROUTE
+	}]
+}, null, 2)}\n`;
+//#endregion
+//#region src/_vercel-output.ts
+/**
+* Assemble a PREBUILT Vercel deployment — `.vercel/output/` — from what
+* `aai build` just produced.
+*
+* The argument for the Build Output API over an `api/` entry is in
+* `_build-target.ts` at {@link VERCEL_OUTPUT_DIR}; what this module adds is the
+* consequence of it. A `.func` directory is a directory WE fill, so every file
+* the server reads at runtime is present because it was copied in, and nothing
+* depends on a static tracer following a path it structurally cannot:
+*
+* - **`.aai/worker.mjs`** is loaded through `import(pathToFileURL(...))`
+*   (`start.ts`), which `@vercel/nft` cannot resolve. Under the `api/` shape
+*   the build was green and the function 500'd on its first request with
+*   "No built agent at .aai/worker.mjs".
+* - **`.env.example`** is not documentation here. `resolveServerEnv` treats it
+*   as the DECLARATION of which variables become `ctx.env` (see
+*   `DEPLOY_ENV_FILES`), so a function without it hands every tool an empty
+*   env while the Vercel project has the values set — a failure that looks
+*   like a credential problem and is a packaging one.
+* - **The client** is copied to `static/`, where the CDN serves it, and also
+*   beside the worker, so `resolveClientDir` finds a real directory rather
+*   than reaching into a `node_modules` that the bundle replaced.
+*
+* The entry is BUNDLED rather than shipped with a `node_modules`. Same call as
+* the worker (`ssr: { noExternal: true }`, `root: cwd`), so it resolves the
+* project's own installed SDK and pulls the runtime, `ws` and `pg` in with it
+* — which is already the arrangement a deployed worker runs under, and it is
+* what makes the function independent of whether the host's install left a
+* usable, hoisted `node_modules` behind.
+*/
+/**
+* Files copied verbatim into the function, each one read at RUNTIME by a path
+* no bundler can see. A missing one is skipped rather than fatal.
+*
+* **`.env` is deliberately NOT here.** `resolveServerEnv` reads
+* {@link DEPLOY_ENV_FILES} — `.env.example` then `.env` — but only the first is
+* a DECLARATION; the second holds a developer's own keys, and copying it would
+* bake them into a deployment artifact and let them silently win over the
+* values set in the Vercel project. Declarations ship, values come from the
+* platform environment. Verified by building the `simple` template: a local
+* `.env` with live credentials landed in the function until this list dropped
+* it.
+*/
+const RUNTIME_FILES = [WORKER_ARTIFACT_REL, ".env.example"];
+/**
+* Write `.vercel/output/` for this project.
+*
+* The directory is REMOVED first. It is not addressed by content, so a
+* function or a static asset left by an earlier build with a different shape
+* would be deployed alongside this one — and `vercel deploy --prebuilt`
+* uploads whatever is there.
+*/
+async function emitVercelOutput(cwd, options = {}) {
+	const outputDir = path.join(cwd, VERCEL_OUTPUT_DIR);
+	const functionDir = path.join(cwd, VERCEL_FUNCTION_DIR);
+	const staticDir = path.join(cwd, VERCEL_STATIC_DIR);
+	await fs.rm(outputDir, {
+		recursive: true,
+		force: true
+	});
+	await fs.mkdir(functionDir, { recursive: true });
+	await fs.writeFile(path.join(outputDir, "config.json"), VERCEL_BUILD_CONFIG_SOURCE, "utf-8");
+	await fs.writeFile(path.join(functionDir, ".vc-config.json"), vercelFunctionConfigSource(), "utf-8");
+	const bundle = options.bundle ?? bundleEntry;
+	await fs.writeFile(path.join(functionDir, "index.mjs"), await bundle(cwd), "utf-8");
+	for (const rel of RUNTIME_FILES) {
+		const from = path.join(cwd, rel);
+		if (!await exists(from)) continue;
+		const to = path.join(functionDir, rel);
+		await fs.mkdir(path.dirname(to), { recursive: true });
+		await fs.copyFile(from, to);
+	}
+	const clientSource = await exists(path.join(cwd, CLIENT_ARTIFACT_REL, "index.html")) ? path.join(cwd, CLIENT_ARTIFACT_REL) : defaultClientDir();
+	await fs.cp(clientSource, staticDir, { recursive: true });
+	await fs.cp(clientSource, path.join(functionDir, CLIENT_ARTIFACT_REL), { recursive: true });
+}
+/**
+* Bundle {@link VERCEL_ENTRY_SOURCE} and everything it imports into one ESM
+* file.
+*
+* The entry is written INTO the project rather than a temp directory, because
+* that is what makes `@alexkroman1/aai-cli/start` resolve against the user's
+* install — the deployed server is then the version their lockfile pins, which
+* is the same guarantee `aai publish` gives. Removed in a `finally`: a build
+* that throws must not leave a file that looks authored.
+*/
+async function bundleEntry(cwd) {
+	const entryPath = path.join(cwd, ".aai", "vercel-entry.mjs");
+	await fs.mkdir(path.dirname(entryPath), { recursive: true });
+	await fs.writeFile(entryPath, VERCEL_ENTRY_SOURCE, "utf-8");
+	let result;
+	try {
+		result = await withPreservedNodeEnv(() => build({
+			root: cwd,
+			logLevel: "silent",
+			configFile: false,
+			ssr: { noExternal: true },
+			build: {
+				ssr: true,
+				lib: {
+					entry: entryPath,
+					formats: ["es"],
+					fileName: "index"
+				},
+				target: "node20",
+				minify: false,
+				write: false,
+				rollupOptions: { output: {
+					entryFileNames: "[name].mjs",
+					codeSplitting: false
+				} }
+			}
+		}));
+	} finally {
+		await fs.rm(entryPath, { force: true }).catch(() => void 0);
+	}
+	const output = Array.isArray(result) ? result[0] : result;
+	invariant(output !== void 0, "vercel.entry.output");
+	const chunk = output.output.find((o) => o.type === "chunk" && o.isEntry);
+	invariant(chunk !== void 0, "vercel.entry.chunk", () => ({ kinds: output.output.map((o) => o.type) }));
+	return chunk.code;
+}
+async function exists(target) {
+	return await fs.stat(target).then(() => true, () => false);
+}
+//#endregion
+//#region src/build.ts
+/**
+* `aai build` — bundle the agent without deploying, behind the same gates
+* deploy runs (tests, then typecheck), so the command previews the deploy
+* artifact and its failures alike.
+*
+* It also LEAVES that artifact on disk, at {@link WORKER_ARTIFACT_REL}, which is
+* what makes self-hosting work: `aai start` loads the built worker rather than
+* `agent.ts`, because a tool is discovered by the bundler enumerating `tools/`
+* and no un-bundled loader can see that directory. See `start.ts` and
+* "Self-hosting is the scaffold's default" in `packages/aai-cli/CLAUDE.md`.
+*
+* `--target` decides what else it emits — see `_build-target.ts`.
+*/
+/**
+* The prose slot, named by convention. Mirrors `worker-bundler.ts`'s constant of
+* the same name — the two cannot share one without an import cycle
+* (`build.ts` → `_bundler.ts` → `worker-bundler.ts`), so `_build.test.ts` pins
+* the pair end to end instead: a build whose prompt really came from the file
+* has to report the file.
+*/
+const SYSTEM_PROMPT_FILE = "system-prompt.md";
+/** What {@link systemPromptSource} reports when nothing declared a prompt. */
+const FRAMEWORK_DEFAULT_PROMPT_SOURCE = "the framework default (DEFAULT_SYSTEM_PROMPT)";
+/**
+* Which of the three possible authors of this agent's system prompt actually
+* wrote the one in the bundle.
+*
+* `aai build` reported `name` and `workerBytes` and nothing about the prompt,
+* and the prompt is the one field that can change COMPLETELY without any
+* config changing: deleting `system-prompt.md` swaps in
+* `DEFAULT_SYSTEM_PROMPT` — a total personality change — with exit 0 and no
+* line anywhere. `withSystemPrompt` refuses the case where a file exists and
+* nothing reads it; it cannot refuse a file that is simply GONE, because that
+* is what an agent with no file legitimately looks like. So this is a report
+* rather than a check.
+*
+* Decided by comparing VALUES against the built agent's resolved prompt, which
+* is the same method `withSystemPrompt` uses and for the same reason — the
+* alternative asks the bundler's module graph a question, and the author may
+* have imported the file and composed it, which is neither "the file" nor
+* "agent.ts" alone.
+*/
+async function systemPromptSource(cwd, resolved) {
+	if (resolved === DEFAULT_SYSTEM_PROMPT) return FRAMEWORK_DEFAULT_PROMPT_SOURCE;
+	const trimmed = (await fs.readFile(path.join(cwd, SYSTEM_PROMPT_FILE), "utf-8").catch(() => void 0))?.trim();
+	if (trimmed === void 0 || trimmed === "" || !resolved.includes(trimmed)) return "agent.ts";
+	return resolved.trim() === trimmed ? SYSTEM_PROMPT_FILE : `agent.ts (composing ${SYSTEM_PROMPT_FILE})`;
+}
+/**
+* Map a {@link runVitest} failure to a CliError — distinguishing a real test
+* failure (test_failed) from the runner not spawning (spawn_failed) instead
+* of a generic command_failed.
+*/
+function testGateError(err) {
+	const { code, message } = classifyVitestError(err);
+	return new CliError(code, message, "Re-run with --skipTests to build without tests", { cause: err });
+}
+async function executeBuild(opts) {
+	const { cwd } = opts;
+	const target = resolveBuildTarget(opts.target);
+	if (!opts.skipTests) try {
+		runVitest(cwd, {
+			candidates: TEST_FILES,
+			all: true
+		});
+	} catch (err) {
+		throw testGateError(err);
+	}
+	await assertTypechecks(cwd, { skip: opts.skipTypecheck });
+	const bundle = await buildAgentBundle(cwd, { minify: true });
+	const agentDef = await evalWorkerBundle(bundle.worker);
+	for (const warning of agentConfigWarnings(agentDef)) notify("warn", warning);
+	for (const warning of determinismWarnings(await scanWorkflowDeterminism(cwd))) notify("warn", warning);
+	const worker = path.join(cwd, WORKER_ARTIFACT_REL);
+	await fs.mkdir(path.dirname(worker), { recursive: true });
+	await fs.writeFile(worker, bundle.worker, "utf-8");
+	await emitTargetFiles(cwd, target);
+	const systemPrompt = await systemPromptSource(cwd, agentDef.systemPrompt);
+	log.info(`System prompt: ${systemPrompt}`);
+	log.success("Build complete");
+	return ok({
+		name: agentDef.name,
+		workerBytes: bundle.worker.length,
+		worker,
+		systemPrompt,
+		target
+	});
+}
+/**
+* Write what a target needs, if it needs anything.
+*
+* `node` writes nothing: a long-lived process runs `aai start`, which needs no
+* generated file. `vercel` writes a complete prebuilt deployment under
+* `.vercel/output/` — see `_vercel-output.ts`, and `VERCEL_OUTPUT_DIR` in
+* `_build-target.ts` for why that directory and not an `api/` entry beside a
+* generated `vercel.json`.
+*/
+async function emitTargetFiles(cwd, target) {
+	if (target === "node") return;
+	await emitVercelOutput(cwd);
+	log.info(`Target ${target}: wrote ${VERCEL_OUTPUT_DIR}`);
+}
+//#endregion
+export { executeBuild };

package/dist/build.d.ts

@@ -4,23 +4,25 @@
  * artifact and its failures alike.
  *
  * It also LEAVES that artifact on disk, at {@link WORKER_ARTIFACT_REL}, which is
- * what makes self-hosting work: `server.mjs` loads the built worker rather than
+ * what makes self-hosting work: `aai start` loads the built worker rather than
  * `agent.ts`, because a tool is discovered by the bundler enumerating `tools/`
- * and no un-bundled loader can see that directory. See the scaffold's own
- * `server.mjs` and "Self-hosting runs the built worker" in
- * `packages/aai-templates/CLAUDE.md`.
+ * and no un-bundled loader can see that directory. See `start.ts` and
+ * "Self-hosting is the scaffold's default" in `packages/aai-cli/CLAUDE.md`.
+ *
+ * `--target` decides what else it emits — see `_build-target.ts`.
  */
+import { type BuildTarget } from "./_build-target.ts";
 import { type CommandResult } from "./_output.ts";
 /**
  * Where the built worker lands, relative to the project root — under `.aai/`,
  * beside the built client, so one gitignore rule covers every build output.
  *
- * `server.mjs` hardcodes this path: it is a plain `.mjs` file in a user's
- * project and may not import from the CLI (which a deployed project does not
- * install at all). The pair is covered end-to-end by the `npm start` leg of
- * `e2e.test.ts` — the only tier that runs both halves as a user does.
+ * `start.ts` imports this constant rather than restating the path, which it
+ * could not do while the loader was a `.mjs` file in the user's project. The
+ * pair is covered end-to-end by the `npm start` leg of `e2e.test.ts` — the only
+ * tier that runs both halves as a user does.
  */
-export declare const WORKER_ARTIFACT_REL: string;
+export { WORKER_ARTIFACT_REL } from "./_artifacts.ts";
 type BuildData = {
     name: string;
     workerBytes: number;
@@ -31,10 +33,16 @@ type BuildData = {
      * {@link systemPromptSource}.
      */
     systemPrompt: string;
+    /** Which deployment shape this build emitted — see `_build-target.ts`. */
+    target: BuildTarget;
 };
 export declare function executeBuild(opts: {
     cwd: string;
     skipTests?: boolean | undefined;
     skipTypecheck?: boolean | undefined;
+    /**
+     * Which deployment shape to emit beside the worker. Absent, it is detected
+     * from the host's own build environment — see `resolveBuildTarget`.
+     */
+    target?: string | undefined;
 }): Promise<CommandResult<BuildData>>;
-export {};