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

package/SKILL.md

@@ -32,6 +32,8 @@ metadata:
 
 `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

package/build-app/index.d.mts

@@ -9,6 +9,8 @@ export interface BuildOptions {
 export interface AppConfig {
   command: string[];
   external: string[];
+  /** crewx.app.env; present only when package.json sets it. */
+  env?: string[];
 }
 
 export interface BuildResult {
@@ -33,6 +35,7 @@ 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;

package/build-app/index.mjs

@@ -22,11 +22,16 @@
 // 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
+//     "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, readFileSync, realpathSync, rmSync, watch, writeFileSync } from 'node:fs';
+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';
@@ -58,6 +63,10 @@ const SERVER_WRAPPER = [
   '',
 ].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.
@@ -83,9 +92,18 @@ const TSCONFIG_RAW = {
  * 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) {
-  const generated = imported.generateManifest(imported.default, command);
+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);
@@ -140,7 +158,38 @@ export function readAppConfig(appDirectory) {
   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 };
+  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) {
@@ -296,6 +345,7 @@ 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`);
@@ -317,7 +367,7 @@ export async function buildApp({ appDirectory, check = false, log = () => {} })
     }
     const manifestPath = join(appDirectory, MANIFEST_FILE);
     const existingManifest = existsSync(manifestPath) ? readFileSync(manifestPath, 'utf8') : undefined;
-    const declarations = renderActionDeclarations(imported, config.command, existingManifest);
+    const declarations = renderActionDeclarations(imported, config.command, existingManifest, config.env);
 
     const generated = [
       { path: join(appDirectory, SERVER_BUNDLE), text: server.text },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/app",
-  "version": "0.1.0-rc.19",
+  "version": "0.1.0-rc.20",
   "description": "Task-scoped CLI access to CrewX Apps",
   "type": "commonjs",
   "main": "dist/src/engine.js",
@@ -28,7 +28,7 @@
   ],
   "dependencies": {
     "esbuild": "0.27.7",
-    "@crewx/sdk": "0.9.0-rc.138"
+    "@crewx/sdk": "0.9.0-rc.139"
   },
   "keywords": [
     "crewx",