@crewx/app 0.1.0-rc.2 → 0.1.0-rc.21

package/SKILL.md

@@ -14,14 +14,60 @@ metadata:
 | `crewx app open <appId>` | Open an App in this conversation |
 | `crewx app state <instanceId>` | Read AI-visible state, buttons, and agent access |
 | `crewx app run <instanceId|appId> <actionId> [--input <JSON>|-] [--request-id <id>]` | Run one available action |
-| `crewx app receipt <receiptId>` | Read a safe action receipt |
+| `crewx app receipt <receiptId> [--wait=<seconds>]` | Read a safe action receipt. With `--wait`, poll until it settles or the wait ends |
+| `crewx app build [<appDir>] [--check | --watch]` | Build a `@Tool` App: bundle `server.ts` into `dist/` and regenerate the `manifest.json` actions. `--check` writes nothing and fails on a stale file; `--watch` rebuilds on every change |
+| `crewx app dev <app> [--no-open]` | Start a foreground App dev session with build and reload watching |
+| `crewx app check <app> [--json]` | Run the App dev checks |
+| `crewx app run --dev <app> <actionId> [--input <JSON>|-]` | Run an App action through the dev checks |
 | `crewx app usage` | Show this guide |
+| `crewx app usage <appId>` | Show one App's manual (its SKILL.md) and an action table generated from its declaration: inputs with real types, agent access, confirmation |
+
+`<app>` is the App folder name under `apps/` or its App id (`name` in `manifest.json`, or `pluginId` in `ui-plugin.json`).
+
+## Read the manual before the first run
+
+`crewx app usage <appId>` prints the App's manual, then a table of every action: its inputs (`*` = required, real types, limits, allowed values), the agent access (`allowed`, `approval_required`, `denied`, the same words `crewx app state` prints) and the confirmation mode. Send exactly the keys listed. After a successful `crewx app run`, stderr suggests `→ Check: crewx app state <instanceId>`.
+
+## Build a `@Tool` App
+
+`crewx app build` needs nothing but the CrewX CLI: it ships the bundler and the SDK that `server.ts` imports as `@crewx/sdk/app`. Run it in the App folder (or pass the folder). The folder needs `server.ts` (default-exports a `CrewXApp` subclass) and a `package.json` with one `bin` name (or `crewx.app.command`); `manifest.json` is created when missing, otherwise only its `_meta["dev.crewx"].actions` is rewritten.
+
+Set `crewx.app.env` in `package.json` to `["CREWX_APP_INSTANCE_ID", "CREWX_THREAD_ID"]` (one or both, no repeats, nothing else) when your `@Tool` code reads those values from `process.env`: the build writes the list to every action's `backend.env` and the Host then puts exactly those values in the backend process; without it the backend gets neither and no `env` key is written.
+
+stdout is one JSON line with the written `files` and the `actions` found; after a build, stderr says the next command. Exit 0 = built (or in sync with `--check`), 1 = `BUILD_FAILED` (stderr says why) or `BUILD_STALE` (`--check` found a stale file; run `crewx app build`), 2 = usage. `--watch` stays in the foreground and prints one plain line per build until Ctrl-C.
+
+## App development
+
+Run the watcher from a developer terminal and leave it in the foreground until you stop it with Ctrl-C:
+
+```bash
+crewx app dev <app>
+```
+
+Use `--no-open` when a browser tab is not needed. The watcher runs `npm run build` when the App has a `build` script,
+then reloads the dev tab after each build. Without a build script, file changes trigger a manual reload.
+
+For a one-shot agent run, build and check before calling an action:
+
+```bash
+cd apps/<app>
+npm run build
+cd ../..
+crewx app check <app> --json
+crewx app run --dev <app> <actionId> --input '{"key":"value"}'
+```
+
+`check` exits with code 13 when errors remain. `run --dev` prints the server result and checks; it exits non-zero when the
+action did not succeed. A one-shot agent should use this build/check/run loop instead of holding the foreground watcher.
 
 ## When blocked
 
 - Exit 3, 9, 10, or 11: do not click the screen, use CUA, or open another browser. Report that you could not use the App route.
+- Exit 14: the server did not answer after the connection was established, so the outcome is unknown. For `run`, retry the same command once with the `requestId` from the JSON payload as `--request-id`; within 15 minutes the server returns the same receipt and result without running the action twice. If it times out again, report `server response delayed, outcome unknown` with the `requestId`. Do not report success or failure, click the screen, or use another route. For other commands, retry once; if it happens again, report it.
 - Exit 4: do not retry; report the failure.
 - Use `agentAccess` from `crewx app state`: `allowed` can run, `approval_required` can request human approval, and `denied` must not run.
-- Exit 8 means **pending approval**, not success. Never claim the work is done and never work around it with screen clicks or another route.
-- Check later with `crewx app receipt <receiptId>`. If the turn must end first, report **pending approval** and include the `receiptId`.
+- Exit 8 = waiting for the user's one-time approval in the App window. Keep this turn running and wait with `crewx app receipt <receiptId> --wait=60` (repeat on exit 124); ending the turn cancels the request. Report success only if the receipt settles as `succeeded`. Never claim the work is done and never work around it with screen clicks or another route. stderr adds `→ Waiting for the user's approval in the App window (expires HH:MM)` and `→ Wait: crewx app receipt <receiptId> --wait=60 (repeat on exit 124 until it settles)`; the JSON on stdout is unchanged.
+- `crewx app receipt <receiptId> --wait=<seconds>` asks the server every 3 seconds until the receipt settles (`succeeded`, `rejected`, `failed`, `conflicted`, `expired`). A settled receipt is printed exactly as `receipt` without `--wait` prints it, with the same exit code. If the wait ends first, it exits 124 with nothing on stdout and one stderr line naming the next command. `<seconds>` is capped at 900, the 15 minutes an approval lives. `--wait=0` or no `--wait` reads the receipt once.
+- `crewx app run` returns the settled receipt, resulting state, and the declared public `result` when one exists. Check `outcome`; if it is `failed` or `rejected`, read `errorCode` to understand the failure. A 202 request returns the pending receipt without a result.
+- Read the receipt again with `crewx app receipt <receiptId>`. The same actor can read the same public `result` repeatedly for 15 minutes after success. After the result expires or the server restarts, the receipt reports `resultExpired: true` without returning the result. An approval that settles as anything but `succeeded` (`rejected`, `expired`, `failed`, `conflicted`) is not done: report the outcome and the `receiptId`.
 - Include the `receiptId` in your report. Citing an ID is not proof; the checker compares the receipt's `actor.task` with this task.

package/build-app/index.d.mts

@@ -0,0 +1,57 @@
+export const SDK_APP_SOURCE_ENTRY: string;
+
+export interface BuildOptions {
+  appDirectory: string;
+  check: boolean;
+  watch: boolean;
+}
+
+export interface AppConfig {
+  command: string[];
+  external: string[];
+  /** crewx.app.env; present only when package.json sets it. */
+  env?: string[];
+}
+
+export interface BuildResult {
+  /** Stale generated files relative to the current directory; empty unless `check`. */
+  stale: string[];
+  /** The same files relative to the app folder; empty unless `check`. */
+  staleFiles: string[];
+  /** Every generated file, relative to the app folder. */
+  files: string[];
+  /** The actionId of every `@Tool` method. */
+  actions: string[];
+  /** The file `@crewx/sdk/app` resolved to: the SDK source in the repository, the shipped SDK elsewhere. */
+  sdkEntry: string | undefined;
+  /** Absolute paths of the source files the bundle read (the shipped SDK is not among them). */
+  inputs: string[];
+}
+
+export function parseArguments(argv: string[], cwd?: string): BuildOptions;
+export function readAppConfig(appDirectory: string): AppConfig;
+export function usesSdkSource(appDirectory: string): boolean;
+export function renderActionDeclarations(
+  imported: { default: unknown; generateManifest: (app: unknown, command: string[]) => { actions?: unknown } },
+  command: string[],
+  existingText?: string,
+  backendEnv?: readonly string[],
+): { fileName: string; text: string };
+export function buildApp(options: {
+  appDirectory: string;
+  check?: boolean;
+  log?: (message: string) => void;
+}): Promise<BuildResult>;
+export function watchApp(
+  appDirectory: string,
+  log: (message: string) => void,
+  options?: { signal?: AbortSignal },
+): Promise<void>;
+export function runScript(
+  argv: string[],
+  options?: {
+    cwd?: string;
+    stdout?: { write(text: string): unknown };
+    stderr?: { write(text: string): unknown };
+  },
+): Promise<number>;

package/build-app/index.mjs

@@ -0,0 +1,498 @@
+// Shared build for every CrewX App written as a `@Tool` class. This file is the one implementation:
+// `crewx app build` (src/engine.ts) and the repository script scripts/build-app.mjs both call it.
+//
+// It is plain ESM that ships as source (no TypeScript step), so a fresh checkout can build an App
+// before any package has been compiled, and the published @crewx/app carries it as it is.
+//
+// Input : <app>/server.ts, which default-exports a CrewXApp subclass.
+// Output: <app>/dist/server.mjs  the App bundle (also exports runSkillApp, generateManifest, ...)
+//         <app>/dist/entry.mjs   the one-shot process entry (runAppEntry) for the skill CLI
+//         <app>/manifest.json    the App manifest; only _meta["dev.crewx"].actions is regenerated
+//                                from the @Tool methods, every other key stays as authored
+//
+// The build never writes ui-plugin.json. A new App (no manifest.json yet) gets a whole manifest.json
+// derived from the static definition in server.ts, with release version 0.1.0.
+//
+// `@crewx/sdk/app` resolves to the SDK source (packages/sdk/src/app/index.ts) when the app lives in
+// the CrewX repository this file is part of, so an SDK source edit reaches the next app build
+// without `pnpm build:sdk`. Anywhere else it resolves to the SDK the CrewX CLI ships with (the
+// @crewx/sdk next to @crewx/app). Either way the SDK code is inlined: no `@crewx/sdk` import is
+// left in the bundles.
+//
+// Optional app settings in <app>/package.json:
+//   "crewx": { "app": {
+//     "command":  ["sheet", "app"],  // skill command the actions run; default: [<the one bin name>, "app"]
+//     "external": ["lib/**"],        // app files (globs relative to the app) kept out of the bundle
+//                                    // and imported at run time from their real place
+//     "env": ["CREWX_APP_INSTANCE_ID", "CREWX_THREAD_ID"]
+//                                    // written to every generated action's backend.env, so the Host
+//                                    // puts these values in the process environment; absent = no env key
+//   } }
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, watch, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { CREWX_META_NAMESPACE, convertV2ToManifest } from './manifest.mjs';
+
+const ownDirectory = dirname(fileURLToPath(import.meta.url));
+const requireFromPackage = createRequire(import.meta.url);
+
+// In the CrewX repository this file is <repository>/packages/built-in/app/build-app/index.mjs.
+// Installed from npm it sits under node_modules, where the same four steps up do not reach a
+// repository, so the layout check below is what tells the two apart.
+const REPOSITORY_LAYOUT = join('packages', 'built-in', 'app', 'build-app');
+const repositoryRoot = resolve(ownDirectory, '..', '..', '..', '..');
+export const SDK_APP_SOURCE_ENTRY = join(repositoryRoot, 'packages', 'sdk', 'src', 'app', 'index.ts');
+const SDK_APP_SOURCE_DIRECTORY = dirname(SDK_APP_SOURCE_ENTRY);
+
+const SERVER_ENTRY = 'server.ts';
+const SERVER_BUNDLE = 'dist/server.mjs';
+const ENTRY_BUNDLE = 'dist/entry.mjs';
+const MANIFEST_FILE = 'manifest.json';
+const WATCH_DEBOUNCE_MS = 100;
+
+// What dist/server.mjs exposes on top of the app's own exports. sheet.mjs-style launchers call
+// runSkillApp through runAppEntry; the build itself calls generateManifest.
+const SERVER_WRAPPER = [
+  `import App from './${SERVER_ENTRY}';`,
+  `export * from './${SERVER_ENTRY}';`,
+  'export default App;',
+  "export { AppError, CrewXApp, Tool, executeAppRequest, generateManifest, getToolDeclarations, runSkillApp } from '@crewx/sdk/app';",
+  '',
+].join('\n');
+const ENTRY_WRAPPER = "export { runAppEntry } from '@crewx/sdk/app';\n";
+// The rule the manifest reader applies to backend.env. It is bundled on its own and only imported by
+// the build, so it never reaches dist/server.mjs (and every App without crewx.app.env builds the same bytes).
+const ENV_RULE_WRAPPER = "export { SKILL_BACKEND_ENV_NAMES, isSkillBackendEnv } from '@crewx/sdk/app';\n";
+const ENV_RULE_BUNDLE = 'dist/.env-rule.mjs'; // only names the esbuild output; the file is written under the OS temp folder
+
+// The published @crewx/sdk/app is CommonJS. Inlined into an ES module, its require() calls
+// (node built-ins) need a real require.
+const COMMONJS_INTEROP_BANNER = "import { createRequire as __crewxCreateRequire } from 'node:module'; const require = __crewxCreateRequire(import.meta.url);";
+
+const TSCONFIG_RAW = {
+  compilerOptions: {
+    target: 'ES2022',
+    module: 'ESNext',
+    moduleResolution: 'Bundler',
+    experimentalDecorators: false,
+    emitDecoratorMetadata: false,
+    useDefineForClassFields: true,
+    lib: ['ES2022', 'esnext.decorators'],
+    allowJs: true,
+    checkJs: false,
+  },
+};
+
+/**
+ * The one place that knows where the @Tool declarations are written: the `actions` of
+ * `<app>/manifest.json`, i.e. `_meta["dev.crewx"].actions`. `existingText` is the manifest.json
+ * already on disk. With it only `actions` is replaced, so every other key keeps its value and its
+ * place (the file is written back as two-space JSON). Without it the whole file is derived from the
+ * App's static definition and starts at release version 0.1.0.
+ *
+ * `backendEnv` (crewx.app.env, already checked by the caller) is copied to the `backend.env` of every
+ * action; left out, no action gets an `env` key.
+ */
+export function renderActionDeclarations(imported, command, existingText, backendEnv) {
+  let generated = imported.generateManifest(imported.default, command);
+  if (backendEnv !== undefined && Array.isArray(generated.actions)) {
+    generated = {
+      ...generated,
+      actions: generated.actions.map((action) => ({ ...action, backend: { ...action.backend, env: [...backendEnv] } })),
+    };
+  }
+  let manifest;
+  if (existingText === undefined) {
+    manifest = convertV2ToManifest(generated);
+  } else {
+    try {
+      manifest = JSON.parse(existingText);
+    } catch (error) {
+      throw new Error(`${MANIFEST_FILE} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const dev = manifest?._meta?.[CREWX_META_NAMESPACE];
+    if (dev === null || typeof dev !== 'object' || Array.isArray(dev)) {
+      throw new Error(`${MANIFEST_FILE} must have an object at _meta["${CREWX_META_NAMESPACE}"]`);
+    }
+    dev.actions = generated.actions;
+  }
+  return { fileName: MANIFEST_FILE, text: `${JSON.stringify(manifest, null, 2)}\n` };
+}
+
+/**
+ * `[<appDir>] [--app-dir=<dir>] [--check | --watch]`. The app folder is the current directory
+ * unless one is given, once, either way.
+ */
+export function parseArguments(argv, cwd = process.cwd()) {
+  let appDirectory;
+  let check = false;
+  let watchMode = false;
+  const setAppDirectory = (directory) => {
+    if (appDirectory !== undefined) throw new Error('Give the app folder only once');
+    appDirectory = resolve(cwd, directory);
+  };
+  for (const argument of argv) {
+    if (argument === '--check') check = true;
+    else if (argument === '--watch') watchMode = true;
+    else if (argument.startsWith('--app-dir=')) setAppDirectory(argument.slice('--app-dir='.length));
+    else if (argument.startsWith('-')) throw new Error(`Unknown argument: ${argument}`);
+    else setAppDirectory(argument);
+  }
+  if (check && watchMode) throw new Error('--check and --watch cannot be combined');
+  return { appDirectory: appDirectory ?? cwd, check, watch: watchMode };
+}
+
+export function readAppConfig(appDirectory) {
+  const packagePath = join(appDirectory, 'package.json');
+  if (!existsSync(packagePath)) throw new Error(`${packagePath} not found; run the build from an app folder or give the app folder`);
+  const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+  const config = pkg.crewx?.app ?? {};
+  const command = config.command ?? deriveCommand(pkg);
+  if (!Array.isArray(command) || command.length === 0 || !command.every((token) => typeof token === 'string' && token !== '')) {
+    throw new Error('crewx.app.command must be a non-empty array of strings');
+  }
+  const external = config.external ?? [];
+  if (!Array.isArray(external) || !external.every((glob) => typeof glob === 'string')) {
+    throw new Error('crewx.app.external must be an array of globs');
+  }
+  const env = config.env;
+  if (env !== undefined && (!Array.isArray(env) || !env.every((name) => typeof name === 'string'))) {
+    throw new Error('crewx.app.env must be an array of environment variable names');
+  }
+  return { command, external, ...(env === undefined ? {} : { env }) };
+}
+
+/** Refuses a `crewx.app.env` the manifest reader would refuse, by asking the reader's own rule. */
+async function assertBackendEnv(esbuild, appDirectory, config) {
+  let ruleBundle;
+  try {
+    ruleBundle = await bundle(esbuild, appDirectory, config, {
+      contents: ENV_RULE_WRAPPER, sourcefile: 'crewx-app-env-rule.ts', outfile: ENV_RULE_BUNDLE,
+    });
+  } catch (error) {
+    if (error.errors?.some(({ text }) => /No matching export/u.test(text))) {
+      throw new Error('crewx.app.env needs a newer @crewx/sdk: reinstall the CrewX CLI');
+    }
+    throw error;
+  }
+  // The bundle imports nothing from the app, so it runs from the OS temp folder and leaves dist/ alone.
+  const temporaryDirectory = mkdtempSync(join(tmpdir(), 'crewx-app-env-'));
+  try {
+    const temporaryRule = join(temporaryDirectory, 'rule.mjs');
+    writeFileSync(temporaryRule, ruleBundle.text, 'utf8');
+    const rule = await import(pathToFileURL(temporaryRule).href);
+    if (!rule.isSkillBackendEnv(config.env)) {
+      throw new Error(`crewx.app.env must be a non-empty list of distinct names from ${rule.SKILL_BACKEND_ENV_NAMES.join(', ')}`);
+    }
+  } finally {
+    rmSync(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+function deriveCommand(pkg) {
+  const bin = pkg.bin;
+  const names = typeof bin === 'string'
+    ? [String(pkg.name ?? '').replace(/^@[^/]+\//u, '')]
+    : Object.keys(bin ?? {});
+  if (names.length !== 1 || names[0] === '') {
+    throw new Error('cannot derive the skill command: give package.json exactly one "bin" name, or set crewx.app.command');
+  }
+  return [names[0], 'app'];
+}
+
+function globToRegExp(glob) {
+  let pattern = '^';
+  for (let index = 0; index < glob.length; index += 1) {
+    const character = glob[index];
+    if (character === '*' && glob[index + 1] === '*') {
+      pattern += '.*';
+      index += 1;
+    } else if (character === '*') {
+      pattern += '[^/]*';
+    } else if (character === '?') {
+      pattern += '[^/]';
+    } else {
+      pattern += character.replace(/[\\^$+{}()[\].|]/g, '\\$&');
+    }
+  }
+  return new RegExp(`${pattern}$`);
+}
+
+function isInside(parent, child) {
+  const relativePath = relative(parent, child);
+  return relativePath !== '' && !relativePath.startsWith('..') && !isAbsolute(relativePath);
+}
+
+/** True when the app folder is part of the CrewX repository this file belongs to, so the SDK source is the right target. */
+export function usesSdkSource(appDirectory) {
+  if (ownDirectory !== join(repositoryRoot, REPOSITORY_LAYOUT)) return false;
+  if (!existsSync(SDK_APP_SOURCE_ENTRY)) return false;
+  return isInside(realpathSync(repositoryRoot), realpathSync(appDirectory));
+}
+
+async function loadEsbuild(appDirectory) {
+  // Prefer the esbuild the app pins, so its output matches what its own build produced before.
+  try {
+    const resolved = createRequire(join(appDirectory, 'package.json')).resolve('esbuild');
+    return await import(pathToFileURL(resolved).href);
+  } catch {
+    // Otherwise the esbuild that comes with @crewx/app.
+  }
+  try {
+    return await import('esbuild');
+  } catch {
+    throw new Error('cannot load esbuild: it comes with @crewx/app, so reinstall the CrewX CLI');
+  }
+}
+
+// The shipped SDK is bundled under this virtual name instead of its real path. esbuild writes a
+// CommonJS module's path into the bundle (`__commonJS({ "<path>"(exports) {`); the real path is
+// <install>/node_modules/@crewx/sdk/dist/app/index.js, which would put "@crewx/sdk" into the bundle
+// and make its bytes depend on where the CLI is installed.
+const SHIPPED_SDK_NAMESPACE = 'crewx-sdk';
+const SHIPPED_SDK_MODULE = 'app/index.js';
+
+/** The `@crewx/sdk/app` file the CLI ships with (the @crewx/sdk next to @crewx/app), or undefined. */
+function shippedSdkEntry() {
+  try {
+    return requireFromPackage.resolve('@crewx/sdk/app');
+  } catch {
+    return undefined;
+  }
+}
+
+function createPlugins(appDirectory, config) {
+  const externalPatterns = config.external.map(globToRegExp);
+  const sdkFromSource = usesSdkSource(appDirectory);
+  return [{
+    name: 'crewx-sdk-app',
+    setup(buildContext) {
+      buildContext.onResolve({ filter: /^@crewx\/sdk\/app$/ }, () => {
+        if (sdkFromSource) return { path: SDK_APP_SOURCE_ENTRY };
+        const shipped = shippedSdkEntry();
+        if (shipped === undefined) {
+          return { errors: [{ text: 'cannot resolve @crewx/sdk/app: it comes with the CrewX CLI, so reinstall the CLI' }] };
+        }
+        return { path: SHIPPED_SDK_MODULE, namespace: SHIPPED_SDK_NAMESPACE, pluginData: { file: shipped } };
+      });
+      buildContext.onLoad({ filter: /.*/, namespace: SHIPPED_SDK_NAMESPACE }, ({ pluginData }) => ({
+        contents: readFileSync(pluginData.file, 'utf8'),
+        loader: 'js',
+        resolveDir: dirname(pluginData.file),
+      }));
+    },
+  }, {
+    name: 'crewx-app-external-files',
+    setup(buildContext) {
+      if (externalPatterns.length === 0) return;
+      buildContext.onResolve({ filter: /^\.\.?\// }, ({ path, resolveDir }) => {
+        const absolute = resolve(resolveDir, path);
+        const fromApp = relative(appDirectory, absolute).split(sep).join('/');
+        if (fromApp.startsWith('..') || !externalPatterns.some((pattern) => pattern.test(fromApp))) return undefined;
+        const fromDist = relative(join(appDirectory, 'dist'), absolute).split(sep).join('/');
+        return { path: fromDist.startsWith('.') ? fromDist : `./${fromDist}`, external: true };
+      });
+    },
+  }];
+}
+
+async function bundle(esbuild, appDirectory, config, { contents, sourcefile, outfile, metafile = false }) {
+  const result = await esbuild.build({
+    ...(usesSdkSource(appDirectory) ? {} : { banner: { js: COMMONJS_INTEROP_BANNER } }),
+    absWorkingDir: appDirectory,
+    stdin: { contents, resolveDir: appDirectory, sourcefile, loader: 'ts' },
+    outfile,
+    bundle: true,
+    write: false,
+    metafile,
+    format: 'esm',
+    platform: 'node',
+    target: 'node22',
+    packages: 'external',
+    plugins: createPlugins(appDirectory, config),
+    tsconfigRaw: TSCONFIG_RAW,
+    logLevel: 'silent',
+  }).catch((error) => {
+    // The wrapper imports `default` from server.ts; say what is wrong in the app's terms.
+    if (error.errors?.some(({ text }) => /No matching export in ".*server\.ts" for import "default"/u.test(text))) {
+      throw new Error(`${SERVER_ENTRY} must default-export a CrewXApp subclass with a static definition`);
+    }
+    throw error;
+  });
+  const expectedPath = join(appDirectory, outfile);
+  const text = result.outputFiles.find((file) => file.path === expectedPath)?.text;
+  if (text === undefined) throw new Error(`esbuild did not produce ${outfile}`);
+  if (/@crewx\/sdk(?:['"/])/u.test(text.replace(/^\s*\/\/.*$/gmu, ''))) {
+    throw new Error(`${outfile} still imports @crewx/sdk; server.ts may import only @crewx/sdk/app`);
+  }
+  return { text, inputs: result.metafile ? Object.keys(result.metafile.inputs) : [] };
+}
+
+/**
+ * Builds the bundles and the action declarations. With `check` nothing is written and the
+ * result lists every generated file that differs from what is on disk.
+ *
+ * Returns `stale` (paths relative to the current directory, empty unless `check`), `staleFiles`
+ * (the same files relative to the app folder), `files` (every generated file, relative to the app
+ * folder), `actions` (the actionId of every @Tool), `sdkEntry` (the file `@crewx/sdk/app` resolved
+ * to: the SDK source in the repository, the shipped SDK anywhere else) and `inputs` (the source
+ * files the bundle read; the shipped SDK is not among them).
+ */
+export async function buildApp({ appDirectory, check = false, log = () => {} }) {
+  if (!existsSync(join(appDirectory, SERVER_ENTRY))) throw new Error(`${join(appDirectory, SERVER_ENTRY)} not found`);
+  const config = readAppConfig(appDirectory);
+  const esbuild = await loadEsbuild(appDirectory);
+  if (config.env !== undefined) await assertBackendEnv(esbuild, appDirectory, config);
+  const distDirectory = join(appDirectory, 'dist');
+  const distDirectoryExisted = existsSync(distDirectory);
+  const temporaryBundle = join(distDirectory, `.server-build-${process.pid}.mjs`);
+
+  try {
+    const server = await bundle(esbuild, appDirectory, config, {
+      contents: SERVER_WRAPPER, sourcefile: 'crewx-app-server.ts', outfile: SERVER_BUNDLE, metafile: true,
+    });
+    const entry = await bundle(esbuild, appDirectory, config, {
+      contents: ENTRY_WRAPPER, sourcefile: 'crewx-app-entry.ts', outfile: ENTRY_BUNDLE,
+    });
+
+    // The bundle imports its externals relative to dist/, so it has to run from there.
+    mkdirSync(distDirectory, { recursive: true });
+    writeFileSync(temporaryBundle, server.text, 'utf8');
+    const imported = await import(`${pathToFileURL(temporaryBundle).href}?build=${Date.now()}`);
+    if (typeof imported.default !== 'function' || imported.default.definition === undefined) {
+      throw new Error(`${SERVER_ENTRY} must default-export a CrewXApp subclass with a static definition`);
+    }
+    const manifestPath = join(appDirectory, MANIFEST_FILE);
+    const existingManifest = existsSync(manifestPath) ? readFileSync(manifestPath, 'utf8') : undefined;
+    const declarations = renderActionDeclarations(imported, config.command, existingManifest, config.env);
+
+    const generated = [
+      { path: join(appDirectory, SERVER_BUNDLE), text: server.text },
+      { path: join(appDirectory, ENTRY_BUNDLE), text: entry.text },
+      { path: join(appDirectory, declarations.fileName), text: declarations.text },
+    ];
+    const staleEntries = generated.filter(({ path, text }) => !existsSync(path) || readFileSync(path, 'utf8') !== text);
+    const stale = staleEntries.map(({ path }) => relative(process.cwd(), path));
+
+    if (!check) {
+      for (const { path, text } of generated) writeFileSync(path, text, 'utf8');
+      log(`Built ${relative(process.cwd(), join(appDirectory, SERVER_BUNDLE))} and regenerated ${relative(process.cwd(), join(appDirectory, declarations.fileName))}.`);
+    }
+    return {
+      stale: check ? stale : [],
+      staleFiles: check ? staleEntries.map(({ path }) => relative(appDirectory, path)) : [],
+      files: generated.map(({ path }) => relative(appDirectory, path)),
+      actions: declaredActionIds(declarations.text),
+      sdkEntry: usesSdkSource(appDirectory) ? SDK_APP_SOURCE_ENTRY : shippedSdkEntry(),
+      inputs: server.inputs
+        .filter((input) => !input.startsWith(`${SHIPPED_SDK_NAMESPACE}:`))
+        .map((input) => resolve(appDirectory, input)),
+    };
+  } finally {
+    rmSync(temporaryBundle, { force: true });
+    if (!distDirectoryExisted && check) rmSync(distDirectory, { recursive: true, force: true });
+  }
+}
+
+function declaredActionIds(manifestText) {
+  const actions = JSON.parse(manifestText)?._meta?.[CREWX_META_NAMESPACE]?.actions;
+  return Array.isArray(actions) ? actions.map((action) => action?.actionId).filter((id) => typeof id === 'string') : [];
+}
+
+/**
+ * Rebuilds when an imported source file changes; SDK source edits count when the app uses it.
+ * Runs until `signal` aborts (never, without one) and then closes its watchers.
+ */
+export async function watchApp(appDirectory, log, { signal } = {}) {
+  const watchers = new Map();
+  let building = false;
+  let queued = false;
+  let timer;
+  let inputs = new Set();
+
+  const rebuild = async () => {
+    if (building) {
+      queued = true;
+      return;
+    }
+    building = true;
+    try {
+      const result = await buildApp({ appDirectory, log });
+      inputs = new Set(result.inputs);
+    } catch (error) {
+      log(`Build failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      building = false;
+      if (!signal?.aborted) refreshWatchers();
+      if (queued && !signal?.aborted) {
+        queued = false;
+        void rebuild();
+      }
+    }
+  };
+
+  const refreshWatchers = () => {
+    const directories = new Set([appDirectory, ...[...inputs].map((input) => dirname(input))]);
+    if (usesSdkSource(appDirectory)) directories.add(SDK_APP_SOURCE_DIRECTORY);
+    for (const [directory, watcher] of watchers) {
+      if (!directories.has(directory)) {
+        watcher.close();
+        watchers.delete(directory);
+      }
+    }
+    for (const directory of directories) {
+      if (watchers.has(directory) || !existsSync(directory)) continue;
+      watchers.set(directory, watch(directory, (_event, filename) => {
+        if (filename === null) return;
+        const changed = join(directory, filename.toString());
+        // Generated files live next to the sources; reacting to them would loop.
+        const relevant = inputs.has(changed)
+          || changed === join(appDirectory, 'package.json')
+          || (directory === SDK_APP_SOURCE_DIRECTORY && /\.tsx?$/u.test(changed));
+        if (!relevant) return;
+        clearTimeout(timer);
+        timer = setTimeout(() => void rebuild(), WATCH_DEBOUNCE_MS);
+      }));
+    }
+  };
+
+  await rebuild();
+  log('Watching for changes. Press Ctrl+C to stop.');
+  await new Promise((resolveStopped) => {
+    if (signal === undefined) return;
+    if (signal.aborted) resolveStopped();
+    else signal.addEventListener('abort', resolveStopped, { once: true });
+  });
+  clearTimeout(timer);
+  for (const watcher of watchers.values()) watcher.close();
+  watchers.clear();
+}
+
+/**
+ * The command line of scripts/build-app.mjs: plain-text lines on stdout, errors on stderr.
+ * Returns the exit code (0 ok, 1 failed or stale).
+ */
+export async function runScript(argv, { cwd = process.cwd(), stdout = process.stdout, stderr = process.stderr } = {}) {
+  const log = (message) => stdout.write(`${message}\n`);
+  try {
+    const options = parseArguments(argv, cwd);
+    if (options.watch) {
+      await watchApp(options.appDirectory, log);
+      return 0;
+    }
+    const { stale } = await buildApp({ appDirectory: options.appDirectory, check: options.check, log });
+    if (!options.check) return 0;
+    if (stale.length > 0) {
+      stderr.write(`Stale generated files: ${stale.join(', ')}\n`);
+      return 1;
+    }
+    log(`${basename(options.appDirectory)} App build artifacts are in sync.`);
+    return 0;
+  } catch (error) {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}

package/build-app/load.cjs

@@ -0,0 +1,4 @@
+// The App build is an ES module, but @crewx/app compiles to CommonJS, where TypeScript turns
+// `import()` into `require()`. This file is plain CommonJS, so the `import()` below stays a real
+// dynamic import (and works inside vitest, where `new Function('return import(...)')` does not).
+module.exports = { loadAppBuilder: () => import('./index.mjs') };