@crewx/app 0.1.0-rc.26 → 0.1.0-rc.28

package/build-app/index.mjs

@@ -1,618 +1,7 @@
-// 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, ...)
-//
-// Bridge mode (package.json has a "bin" or crewx.app.command): the App is a CLI that the manifest's
-//         <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
-//
-// Tool mode (neither): server.ts is the whole backend. Nothing is written into the manifest; the build
-// writes the declarations and a self-starting entry next to the bundle, and the Host reads them from there.
-//         <app>/dist/main.mjs    the self-starting entry: runAppEntry over ./server.mjs, no argument
-//         <app>/dist/tools.json  { "schemaVersion": 1, "actions": [...] }: one object per @Tool, no backend
-//         <app>/manifest.json    only _meta["dev.crewx"].actions is removed; 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"].
-//                                    // With neither a bin nor a command the App is in tool mode.
-//     "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.
-//                                    // Bridge mode only: a tool-mode process is always told both.
-//   } }
-
-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';
-// Tool mode. `dist/entry.mjs` is not reused: bridge launchers import it as a library (apps/timer/timer.mjs).
-const MAIN_BUNDLE = 'dist/main.mjs';
-const TOOLS_FILE = 'dist/tools.json';
-const TOOLS_SCHEMA_VERSION = 1;
-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 tool-mode process entry: server.mjs stays its own file, and the entry imports it at run time.
-const MAIN_WRAPPER = [
-  "import { runAppEntry } from '@crewx/sdk/app';",
-  "await runAppEntry(() => import('./server.mjs'));",
-  '',
-].join('\n');
-// The declarations are read from a bundle of their own (like the env rule below), so server.mjs keeps
-// its exports and an older shipped SDK that lacks generateToolDeclarations only fails a tool-mode build.
-const DECLARATIONS_WRAPPER = [
-  `import App from './${SERVER_ENTRY}';`,
-  'export default App;',
-  "export { generateToolDeclarations } from '@crewx/sdk/app';",
-  '',
-].join('\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` };
-}
-
-/**
- * Tool mode counterpart of `renderActionDeclarations`: the declarations go to `dist/tools.json`, and the
- * manifest loses `_meta["dev.crewx"].actions` (every other key keeps its value and place). A new App gets a
- * whole manifest.json derived from the static definition, which has no `actions`. `imported` is the
- * declarations bundle: its default export is the App class, and it exports `generateToolDeclarations`.
- */
-export function renderToolDeclarations(imported, existingText) {
-  const actions = imported.generateToolDeclarations(imported.default);
-  let manifest;
-  if (existingText === undefined) {
-    manifest = convertV2ToManifest({ ...imported.default.definition });
-  } 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}"]`);
-    }
-    delete dev.actions;
-  }
-  return {
-    fileName: MANIFEST_FILE,
-    text: `${JSON.stringify(manifest, null, 2)}\n`,
-    toolsFileName: TOOLS_FILE,
-    toolsText: `${JSON.stringify({ schemaVersion: TOOLS_SCHEMA_VERSION, actions }, 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 ?? {};
-  if (isToolMode(pkg)) {
-    if (config.env !== undefined) {
-      throw new Error('crewx.app.env is only for an App with a bin or crewx.app.command; a server.ts-only App always gets its instance and thread as this.context');
-    }
-    const toolExternal = config.external ?? [];
-    if (!Array.isArray(toolExternal) || !toolExternal.every((glob) => typeof glob === 'string')) {
-      throw new Error('crewx.app.external must be an array of globs');
-    }
-    // No `command` key: that is how the build tells a tool-mode App from a bridge App.
-    return { external: toolExternal };
-  }
-  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 }) };
-}
-
-/**
- * Tool mode: `server.ts` is the whole backend. A package.json with no `bin` and no `crewx.app.command` has
- * no CLI for the manifest to call, so there is nothing to bridge. (`main` does not matter: an App may keep
- * one for a command an agent runs by hand.)
- */
-function isToolMode(pkg) {
-  return pkg.bin === undefined && pkg.crewx?.app?.command === undefined;
-}
-
-/** 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 };
-      });
-    },
-  }];
-}
-
-// The tool-mode entry imports ./server.mjs when it runs, from dist/ next to it: not a file to bundle.
-const SERVER_IMPORT_PLUGIN = {
-  name: 'crewx-app-server-import',
-  setup(buildContext) {
-    buildContext.onResolve({ filter: /^\.\/server\.mjs$/ }, ({ path }) => ({ path, external: true }));
-  },
-};
-
-async function bundle(esbuild, appDirectory, config, { contents, sourcefile, outfile, metafile = false, plugins = [] }) {
-  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), ...plugins],
-    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 toolMode = config.command === undefined;
-  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 = toolMode
-      ? await bundle(esbuild, appDirectory, config, {
-        contents: MAIN_WRAPPER, sourcefile: 'crewx-app-main.ts', outfile: MAIN_BUNDLE, plugins: [SERVER_IMPORT_PLUGIN],
-      })
-      : await bundle(esbuild, appDirectory, config, {
-        contents: ENTRY_WRAPPER, sourcefile: 'crewx-app-entry.ts', outfile: ENTRY_BUNDLE,
-      });
-    // Tool mode reads the declarations from a bundle of their own; bridge mode reads them from server.mjs.
-    const evaluated = toolMode ? await bundleDeclarations(esbuild, appDirectory, config) : server;
-
-    // The bundle imports its externals relative to dist/, so it has to run from there.
-    mkdirSync(distDirectory, { recursive: true });
-    writeFileSync(temporaryBundle, evaluated.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 = toolMode
-      ? renderToolDeclarations(imported, existingManifest)
-      : renderActionDeclarations(imported, config.command, existingManifest, config.env);
-
-    const generated = [
-      { path: join(appDirectory, SERVER_BUNDLE), text: server.text },
-      { path: join(appDirectory, toolMode ? MAIN_BUNDLE : ENTRY_BUNDLE), text: entry.text },
-      ...(toolMode ? [{ path: join(appDirectory, declarations.toolsFileName), text: declarations.toolsText }] : []),
-      { 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');
-      const shown = (name) => relative(process.cwd(), join(appDirectory, name));
-      log(toolMode
-        ? `Built ${shown(SERVER_BUNDLE)} and ${shown(MAIN_BUNDLE)}, wrote ${shown(TOOLS_FILE)} and regenerated ${shown(declarations.fileName)}.`
-        : `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: toolMode ? declaredToolActionIds(declarations.toolsText) : declaredActionIds(declarations.text),
-      mode: toolMode ? 'tool' : 'bridge',
-      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 });
-  }
-}
-
-/** The bundle a tool-mode build evaluates: the App class and `generateToolDeclarations`, not written anywhere. */
-async function bundleDeclarations(esbuild, appDirectory, config) {
-  try {
-    return await bundle(esbuild, appDirectory, config, {
-      contents: DECLARATIONS_WRAPPER, sourcefile: 'crewx-app-declarations.ts', outfile: 'dist/.declarations-build.mjs',
-    });
-  } catch (error) {
-    if (error.errors?.some(({ text }) => /No matching export/u.test(text) && /generateToolDeclarations/u.test(text))) {
-      throw new Error('a server.ts-only App (no bin, no crewx.app.command) needs a newer @crewx/sdk: reinstall the CrewX CLI');
-    }
-    throw error;
-  }
-}
-
-function declaredToolActionIds(toolsText) {
-  const actions = JSON.parse(toolsText)?.actions;
-  return Array.isArray(actions) ? actions.map((action) => action?.actionId).filter((id) => typeof id === 'string') : [];
-}
-
-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;
-  }
-}
+import{existsSync as x,mkdirSync as z,mkdtempSync as Q,readFileSync as R,realpathSync as W,rmSync as C,watch as Z,writeFileSync as O}from"node:fs";import{createRequire as F}from"node:module";import{tmpdir as ee}from"node:os";import{basename as te,dirname as _,isAbsolute as re,join as c,relative as h,resolve as N,sep as U}from"node:path";import{fileURLToPath as ne,pathToFileURL as T}from"node:url";import{CREWX_META_NAMESPACE as S,convertV2ToManifest as J}from"./manifest.mjs";const D=_(ne(import.meta.url));const oe=F(import.meta.url);const se=c("packages","built-in","app","build-app");const L=N(D,"..","..","..","..");const $=c(L,"packages","sdk","src","app","index.ts");const V=_($);const E="server.ts";const k="dist/server.mjs";const q="dist/entry.mjs";const I="dist/main.mjs";const K="dist/tools.json";const ae=1;const y="manifest.json";const ie=100;const ce=[`import App from './${E}';`,`export * from './${E}';`,"export default App;","export { AppError, CrewXApp, Tool, executeAppRequest, generateManifest, getToolDeclarations, runSkillApp } from '@crewx/sdk/app';",""].join("\n");const le="export { runAppEntry } from '@crewx/sdk/app';\n";const fe=["import { runAppEntry } from '@crewx/sdk/app';","await runAppEntry(() => import('./server.mjs'));",""].join("\n");const ue=[`import App from './${E}';`,"export default App;","export { generateToolDeclarations } from '@crewx/sdk/app';",""].join("\n");const de="export { SKILL_BACKEND_ENV_NAMES, isSkillBackendEnv } from '@crewx/sdk/app';\n";const pe="dist/.env-rule.mjs";const me="import { createRequire as __crewxCreateRequire } from 'node:module'; const require = __crewxCreateRequire(import.meta.url);";const we={compilerOptions:{target:"ES2022",module:"ESNext",moduleResolution:"Bundler",experimentalDecorators:false,emitDecoratorMetadata:false,useDefineForClassFields:true,lib:["ES2022","esnext.decorators"],allowJs:true,checkJs:false}};function he(e,r,n,o){let s=e.generateManifest(e.default,r);if(o!==void 0&&Array.isArray(s.actions)){s={...s,actions:s.actions.map(a=>({...a,backend:{...a.backend,env:[...o]}}))}}let t;if(n===void 0){t=J(s)}else{try{t=JSON.parse(n)}catch(i){throw new Error(`${y} is not valid JSON: ${i instanceof Error?i.message:String(i)}`)}const a=t?._meta?.[S];if(a===null||typeof a!=="object"||Array.isArray(a)){throw new Error(`${y} must have an object at _meta["${S}"]`)}a.actions=s.actions}return{fileName:y,text:`${JSON.stringify(t,null,2)}
+`}}function xe(e,r){const n=e.generateToolDeclarations(e.default);let o;if(r===void 0){o=J({...e.default.definition})}else{try{o=JSON.parse(r)}catch(t){throw new Error(`${y} is not valid JSON: ${t instanceof Error?t.message:String(t)}`)}const s=o?._meta?.[S];if(s===null||typeof s!=="object"||Array.isArray(s)){throw new Error(`${y} must have an object at _meta["${S}"]`)}delete s.actions}return{fileName:y,text:`${JSON.stringify(o,null,2)}
+`,toolsFileName:K,toolsText:`${JSON.stringify({schemaVersion:ae,actions:n},null,2)}
+`}}function Ee(e,r=process.cwd()){let n;let o=false;let s=false;const t=a=>{if(n!==void 0)throw new Error("Give the app folder only once");n=N(r,a)};for(const a of e){if(a==="--check")o=true;else if(a==="--watch")s=true;else if(a.startsWith("--app-dir="))t(a.slice("--app-dir=".length));else if(a.startsWith("-"))throw new Error(`Unknown argument: ${a}`);else t(a)}if(o&&s)throw new Error("--check and --watch cannot be combined");return{appDirectory:n??r,check:o,watch:s}}function ye(e){const r=c(e,"package.json");if(!x(r))throw new Error(`${r} not found; run the build from an app folder or give the app folder`);const n=JSON.parse(R(r,"utf8"));const o=n.crewx?.app??{};if(Ae(n)){if(o.env!==void 0){throw new Error("crewx.app.env is only for an App with a bin or crewx.app.command; a server.ts-only App always gets its instance and thread as this.context")}const i=o.external??[];if(!Array.isArray(i)||!i.every(d=>typeof d==="string")){throw new Error("crewx.app.external must be an array of globs")}return{external:i}}const s=o.command??ve(n);if(!Array.isArray(s)||s.length===0||!s.every(i=>typeof i==="string"&&i!=="")){throw new Error("crewx.app.command must be a non-empty array of strings")}const t=o.external??[];if(!Array.isArray(t)||!t.every(i=>typeof i==="string")){throw new Error("crewx.app.external must be an array of globs")}const a=o.env;if(a!==void 0&&(!Array.isArray(a)||!a.every(i=>typeof i==="string"))){throw new Error("crewx.app.env must be an array of environment variable names")}return{command:s,external:t,...a===void 0?{}:{env:a}}}function Ae(e){return e.bin===void 0&&e.crewx?.app?.command===void 0}async function ge(e,r,n){let o;try{o=await b(e,r,n,{contents:de,sourcefile:"crewx-app-env-rule.ts",outfile:pe})}catch(t){if(t.errors?.some(({text:a})=>/No matching export/u.test(a))){throw new Error("crewx.app.env needs a newer @crewx/sdk: reinstall the CrewX CLI")}throw t}const s=Q(c(ee(),"crewx-app-env-"));try{const t=c(s,"rule.mjs");O(t,o.text,"utf8");const a=await import(T(t).href);if(!a.isSkillBackendEnv(n.env)){throw new Error(`crewx.app.env must be a non-empty list of distinct names from ${a.SKILL_BACKEND_ENV_NAMES.join(", ")}`)}}finally{C(s,{recursive:true,force:true})}}function ve(e){const r=e.bin;const n=typeof r==="string"?[String(e.name??"").replace(/^@[^/]+\//u,"")]:Object.keys(r??{});if(n.length!==1||n[0]===""){throw new Error('cannot derive the skill command: give package.json exactly one "bin" name, or set crewx.app.command')}return[n[0],"app"]}function Se(e){let r="^";for(let n=0;n<e.length;n+=1){const o=e[n];if(o==="*"&&e[n+1]==="*"){r+=".*";n+=1}else if(o==="*"){r+="[^/]*"}else if(o==="?"){r+="[^/]"}else{r+=o.replace(/[\\^$+{}()[\].|]/g,"\\$&")}}return new RegExp(`${r}$`)}function be(e,r){const n=h(e,r);return n!==""&&!n.startsWith("..")&&!re(n)}function P(e){if(D!==c(L,se))return false;if(!x($))return false;return be(W(L),W(e))}async function Re(e){try{const r=F(c(e,"package.json")).resolve("esbuild");return await import(T(r).href)}catch{}try{return await import("esbuild")}catch{throw new Error("cannot load esbuild: it comes with @crewx/app, so reinstall the CrewX CLI")}}const M="crewx-sdk";const _e="app/index.js";function X(){try{return oe.resolve("@crewx/sdk/app")}catch{return void 0}}function Ne(e,r){const n=r.external.map(Se);const o=P(e);return[{name:"crewx-sdk-app",setup(s){s.onResolve({filter:/^@crewx\/sdk\/app$/},()=>{if(o)return{path:$};const t=X();if(t===void 0){return{errors:[{text:"cannot resolve @crewx/sdk/app: it comes with the CrewX CLI, so reinstall the CLI"}]}}return{path:_e,namespace:M,pluginData:{file:t}}});s.onLoad({filter:/.*/,namespace:M},({pluginData:t})=>({contents:R(t.file,"utf8"),loader:"js",resolveDir:_(t.file)}))}},{name:"crewx-app-external-files",setup(s){if(n.length===0)return;s.onResolve({filter:/^\.\.?\//},({path:t,resolveDir:a})=>{const i=N(a,t);const d=h(e,i).split(U).join("/");if(d.startsWith("..")||!n.some(l=>l.test(d)))return void 0;const p=h(c(e,"dist"),i).split(U).join("/");return{path:p.startsWith(".")?p:`./${p}`,external:true}})}}]}const $e={name:"crewx-app-server-import",setup(e){e.onResolve({filter:/^\.\/server\.mjs$/},({path:r})=>({path:r,external:true}))}};async function b(e,r,n,{contents:o,sourcefile:s,outfile:t,metafile:a=false,plugins:i=[]}){const d=await e.build({...P(r)?{}:{banner:{js:me}},absWorkingDir:r,stdin:{contents:o,resolveDir:r,sourcefile:s,loader:"ts"},outfile:t,bundle:true,write:false,metafile:a,format:"esm",platform:"node",target:"node22",packages:"external",plugins:[...Ne(r,n),...i],tsconfigRaw:we,logLevel:"silent"}).catch(f=>{if(f.errors?.some(({text:w})=>/No matching export in ".*server\.ts" for import "default"/u.test(w))){throw new Error(`${E} must default-export a CrewXApp subclass with a static definition`)}throw f});const p=c(r,t);const l=d.outputFiles.find(f=>f.path===p)?.text;if(l===void 0)throw new Error(`esbuild did not produce ${t}`);if(/@crewx\/sdk(?:['"/])/u.test(l.replace(/^\s*\/\/.*$/gmu,""))){throw new Error(`${t} still imports @crewx/sdk; server.ts may import only @crewx/sdk/app`)}return{text:l,inputs:d.metafile?Object.keys(d.metafile.inputs):[]}}async function Y({appDirectory:e,check:r=false,log:n=()=>{}}){if(!x(c(e,E)))throw new Error(`${c(e,E)} not found`);const o=ye(e);const s=o.command===void 0;const t=await Re(e);if(o.env!==void 0)await ge(t,e,o);const a=c(e,"dist");const i=x(a);const d=c(a,`.server-build-${process.pid}.mjs`);try{const p=await b(t,e,o,{contents:ce,sourcefile:"crewx-app-server.ts",outfile:k,metafile:true});const l=s?await b(t,e,o,{contents:fe,sourcefile:"crewx-app-main.ts",outfile:I,plugins:[$e]}):await b(t,e,o,{contents:le,sourcefile:"crewx-app-entry.ts",outfile:q});const f=s?await ke(t,e,o):p;z(a,{recursive:true});O(d,f.text,"utf8");const w=await import(`${T(d).href}?build=${Date.now()}`);if(typeof w.default!=="function"||w.default.definition===void 0){throw new Error(`${E} must default-export a CrewXApp subclass with a static definition`)}const g=c(e,y);const A=x(g)?R(g,"utf8"):void 0;const m=s?xe(w,A):he(w,o.command,A,o.env);const j=[{path:c(e,k),text:p.text},{path:c(e,s?I:q),text:l.text},...s?[{path:c(e,m.toolsFileName),text:m.toolsText}]:[],{path:c(e,m.fileName),text:m.text}];const B=j.filter(({path:u,text:v})=>!x(u)||R(u,"utf8")!==v);const H=B.map(({path:u})=>h(process.cwd(),u));if(!r){for(const{path:v,text:G}of j)O(v,G,"utf8");const u=v=>h(process.cwd(),c(e,v));n(s?`Built ${u(k)} and ${u(I)}, wrote ${u(K)} and regenerated ${u(m.fileName)}.`:`Built ${h(process.cwd(),c(e,k))} and regenerated ${h(process.cwd(),c(e,m.fileName))}.`)}return{stale:r?H:[],staleFiles:r?B.map(({path:u})=>h(e,u)):[],files:j.map(({path:u})=>h(e,u)),actions:s?Pe(m.toolsText):je(m.text),mode:s?"tool":"bridge",sdkEntry:P(e)?$:X(),inputs:p.inputs.filter(u=>!u.startsWith(`${M}:`)).map(u=>N(e,u))}}finally{C(d,{force:true});if(!i&&r)C(a,{recursive:true,force:true})}}async function ke(e,r,n){try{return await b(e,r,n,{contents:ue,sourcefile:"crewx-app-declarations.ts",outfile:"dist/.declarations-build.mjs"})}catch(o){if(o.errors?.some(({text:s})=>/No matching export/u.test(s)&&/generateToolDeclarations/u.test(s))){throw new Error("a server.ts-only App (no bin, no crewx.app.command) needs a newer @crewx/sdk: reinstall the CrewX CLI")}throw o}}function Pe(e){const r=JSON.parse(e)?.actions;return Array.isArray(r)?r.map(n=>n?.actionId).filter(n=>typeof n==="string"):[]}function je(e){const r=JSON.parse(e)?._meta?.[S]?.actions;return Array.isArray(r)?r.map(n=>n?.actionId).filter(n=>typeof n==="string"):[]}async function Ce(e,r,{signal:n}={}){const o=new Map;let s=false;let t=false;let a;let i=new Set;const d=async()=>{if(s){t=true;return}s=true;try{const l=await Y({appDirectory:e,log:r});i=new Set(l.inputs)}catch(l){r(`Build failed: ${l instanceof Error?l.message:String(l)}`)}finally{s=false;if(!n?.aborted)p();if(t&&!n?.aborted){t=false;void d()}}};const p=()=>{const l=new Set([e,...[...i].map(f=>_(f))]);if(P(e))l.add(V);for(const[f,w]of o){if(!l.has(f)){w.close();o.delete(f)}}for(const f of l){if(o.has(f)||!x(f))continue;o.set(f,Z(f,(w,g)=>{if(g===null)return;const A=c(f,g.toString());const m=i.has(A)||A===c(e,"package.json")||f===V&&/\.tsx?$/u.test(A);if(!m)return;clearTimeout(a);a=setTimeout(()=>void d(),ie)}))}};await d();r("Watching for changes. Press Ctrl+C to stop.");await new Promise(l=>{if(n===void 0)return;if(n.aborted)l();else n.addEventListener("abort",l,{once:true})});clearTimeout(a);for(const l of o.values())l.close();o.clear()}async function We(e,{cwd:r=process.cwd(),stdout:n=process.stdout,stderr:o=process.stderr}={}){const s=t=>n.write(`${t}
+`);try{const t=Ee(e,r);if(t.watch){await Ce(t.appDirectory,s);return 0}const{stale:a}=await Y({appDirectory:t.appDirectory,check:t.check,log:s});if(!t.check)return 0;if(a.length>0){o.write(`Stale generated files: ${a.join(", ")}
+`);return 1}s(`${te(t.appDirectory)} App build artifacts are in sync.`);return 0}catch(t){o.write(`${t instanceof Error?t.message:String(t)}
+`);return 1}}export{$ as SDK_APP_SOURCE_ENTRY,Y as buildApp,Ee as parseArguments,ye as readAppConfig,he as renderActionDeclarations,xe as renderToolDeclarations,We as runScript,P as usesSdkSource,Ce as watchApp};

package/build-app/load.cjs

@@ -1,4 +1 @@
-// 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') };
+var l=Object.create;var i=Object.defineProperty;var t=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var m=Object.getPrototypeOf;var s=Object.prototype.hasOwnProperty;var u=(p,o,r,e)=>{if(o&&typeof o==="object"||typeof o==="function"){for(let d of a(o))if(!s.call(p,d)&&d!==r)i(p,d,{get:()=>o[d],enumerable:!(e=t(o,d))||e.enumerable})}return p};var x=(p,o,r)=>(r=p!=null?l(m(p)):{},u(o||!p||!p.__esModule?i(r,"default",{value:p,enumerable:true}):r,p));module.exports={loadAppBuilder:()=>import("./index.mjs")};