@crewx/app 0.1.0-rc.17 → 0.1.0-rc.19

package/SKILL.md

@@ -14,13 +14,25 @@ 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 `pluginId` from `ui-plugin.json`.
+`<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.
+
+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
 
@@ -52,7 +64,8 @@ action did not succeed. A one-shot agent should use this build/check/run loop in
 - 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.
+- 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.
-- Check later 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. If the turn must end first, report **pending approval** and include the `receiptId`.
+- 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,54 @@
+export const SDK_APP_SOURCE_ENTRY: string;
+
+export interface BuildOptions {
+  appDirectory: string;
+  check: boolean;
+  watch: boolean;
+}
+
+export interface AppConfig {
+  command: string[];
+  external: 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,
+): { 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,448 @@
+// 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
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, watch, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+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 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.
+ */
+export function renderActionDeclarations(imported, command, existingText) {
+  const generated = imported.generateManifest(imported.default, command);
+  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');
+  }
+  return { command, external };
+}
+
+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);
+  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);
+
+    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') };

package/build-app/manifest.mjs

@@ -0,0 +1,63 @@
+// The part of the v2 -> manifest.json mapping the App build needs: a new App (no manifest.json yet)
+// gets a whole manifest.json derived from the static definition in server.ts.
+//
+// scripts/convert-app-manifest.mjs (the repository's converter command) keeps its own copy of this
+// mapping; packages/built-in/app/tests/build-app.test.ts compares the two on the same inputs, so a
+// drift fails a test instead of reaching an App.
+
+export const MCPB_MANIFEST_VERSION = '0.3';
+export const CREWX_META_NAMESPACE = 'dev.crewx';
+export const INITIAL_RELEASE_VERSION = '0.1.0';
+
+// v2 fields that are not carried below `_meta["dev.crewx"]` as they are.
+const MOVED_OUT_OF_DEV_NAMESPACE = new Set([
+  'manifestVersion',
+  'pluginId',
+  'definitionId',
+  'version',
+  'name',
+  'description',
+  '_meta',
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Maps one parsed v2 manifest to the `manifest.json` shape.
+ * Throws when the input is not a v2 manifest or cannot be represented.
+ */
+export function convertV2ToManifest(v2, options = {}) {
+  if (!isPlainObject(v2) || v2.manifestVersion !== 2) {
+    throw new Error('only a manifestVersion 2 ui-plugin.json can be converted');
+  }
+  for (const key of ['pluginId', 'definitionId', 'name', 'description']) {
+    if (typeof v2[key] !== 'string') throw new Error(`ui-plugin.json ${key} must be a string`);
+  }
+  if (!Number.isSafeInteger(v2.version) || v2.version < 1) {
+    throw new Error('ui-plugin.json version must be a positive integer');
+  }
+  if (v2._meta !== undefined && !isPlainObject(v2._meta)) {
+    throw new Error('ui-plugin.json _meta must be an object');
+  }
+  if (v2._meta !== undefined && Object.hasOwn(v2._meta, CREWX_META_NAMESPACE)) {
+    throw new Error(`ui-plugin.json _meta already uses the "${CREWX_META_NAMESPACE}" key`);
+  }
+
+  const dev = {};
+  if (v2.definitionId !== v2.pluginId) dev.definitionId = v2.definitionId;
+  dev.definitionVersion = v2.version;
+  for (const [key, value] of Object.entries(v2)) {
+    if (!MOVED_OUT_OF_DEV_NAMESPACE.has(key)) dev[key] = value;
+  }
+
+  return {
+    manifest_version: MCPB_MANIFEST_VERSION,
+    name: v2.pluginId,
+    display_name: v2.name,
+    version: options.version ?? INITIAL_RELEASE_VERSION,
+    description: v2.description,
+    _meta: { ...(v2._meta ?? {}), [CREWX_META_NAMESPACE]: dev },
+  };
+}

package/dist/src/engine.d.ts

@@ -1,3 +1,4 @@
+import { type WaitClock } from './receipt-wait.js';
 export interface AppCommandOutcome {
     exitCode: number;
     payload: Record<string, unknown>;
@@ -5,5 +6,7 @@ export interface AppCommandOutcome {
     stdout?: string;
     suppressOutput?: boolean;
 }
-export declare function executeAppCommand(args: string[]): Promise<AppCommandOutcome>;
+export declare function executeAppCommand(args: string[], { clock }?: {
+    clock?: WaitClock;
+}): Promise<AppCommandOutcome>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/src/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAgCA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAqwCD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+ElF"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAaA,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AA4B3B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAgmDD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,KAAiB,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,CAAA;CAAO,GAChD,OAAO,CAAC,iBAAiB,CAAC,CA0E5B"}