@crossworks/app-build 0.232.10 → 0.232.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/app-build",
-  "version": "0.232.10",
+  "version": "0.232.11",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -14,7 +14,7 @@
     "lucide-react": "^1.25.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "@mantle/share-ui": "npm:@crossworks/share-ui@0.232.10"
+    "@mantle/share-ui": "npm:@crossworks/share-ui@0.232.11"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/runtime-exports.test.ts

@@ -0,0 +1,94 @@
+/**
+ * The manifest lookup must not depend on the working directory. app_build runs
+ * from BOTH server/web (Next) and server/mcp (the agent's MCP server); a bare
+ * cwd-relative path works in the first and resolves to nothing in the second,
+ * which took every agent-driven build down with ENOENT until it was fixed.
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadRuntimeExports, manifestCandidates } from './runtime-exports';
+
+const ENV = 'MANTLE_APP_RUNTIME_MANIFEST';
+let saved: string | undefined;
+
+beforeEach(() => {
+  saved = process.env[ENV];
+});
+afterEach(() => {
+  if (saved === undefined) delete process.env[ENV];
+  else process.env[ENV] = saved;
+});
+
+describe('manifestCandidates', () => {
+  it('includes a package-relative path that does not depend on cwd', () => {
+    delete process.env[ENV];
+    const [pkgRelative] = manifestCandidates();
+    expect(path.isAbsolute(pkgRelative!)).toBe(true);
+    expect(pkgRelative).toContain(path.join('server', 'web', 'public', 'app-runtime'));
+  });
+
+  it('puts an explicit override ahead of everything else', () => {
+    process.env[ENV] = '/tmp/somewhere/manifest.json';
+    expect(manifestCandidates()[0]).toBe('/tmp/somewhere/manifest.json');
+  });
+
+  it('still offers the cwd convention as a fallback', () => {
+    delete process.env[ENV];
+    expect(manifestCandidates()).toContain(path.resolve('public/app-runtime/manifest.json'));
+  });
+});
+
+describe('loadRuntimeExports', () => {
+  it('reads the exports map from the override path', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-mf-'));
+    const file = path.join(dir, 'manifest.json');
+    fs.writeFileSync(file, JSON.stringify({ imports: {}, exports: { '@host': ['host'] } }));
+    process.env[ENV] = file;
+    try {
+      await expect(loadRuntimeExports()).resolves.toEqual({ '@host': ['host'] });
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('throws and names every path it tried when nothing is found', async () => {
+    // Candidates are injected: the real list always resolves inside this repo,
+    // so the not-found path cannot be reached through the environment alone.
+    const missing = [
+      path.join(os.tmpdir(), 'nope-a', 'manifest.json'),
+      path.join(os.tmpdir(), 'nope-b', 'manifest.json'),
+    ];
+    await expect(loadRuntimeExports(missing)).rejects.toThrow(/manifest not found[\s\S]*Tried:/);
+    for (const m of missing) {
+      await expect(loadRuntimeExports(missing)).rejects.toThrow(m);
+    }
+  });
+
+  it('does not fall through to another candidate when one is present but broken', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-mf-'));
+    const broken = path.join(dir, 'manifest.json');
+    fs.writeFileSync(broken, JSON.stringify({ imports: {} }));
+    const good = path.join(dir, 'good.json');
+    fs.writeFileSync(good, JSON.stringify({ exports: { '@host': ['host'] } }));
+    try {
+      // A stale copy further down the list must never win over a broken one.
+      await expect(loadRuntimeExports([broken, good])).rejects.toThrow(/no 'exports' map/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses a manifest that exists but carries no exports map', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-mf-'));
+    const file = path.join(dir, 'manifest.json');
+    fs.writeFileSync(file, JSON.stringify({ imports: { react: '/x.js' } }));
+    process.env[ENV] = file;
+    try {
+      await expect(loadRuntimeExports()).rejects.toThrow(/no 'exports' map/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/runtime-exports.ts

@@ -7,38 +7,81 @@
  * names here) keeps one source of truth: the check can only ever describe the
  * runtime that is actually deployed alongside it.
  *
- * Path convention matches server/web/lib/app-frame.ts, which reads the same
- * file for the import map: relative to cwd, which is server/web in dev and in
- * the image. Cached for the process — the file only changes on deploy.
+ * Resolution deliberately does NOT trust the working directory. The manifest is
+ * generated into server/web/public, and server/web's cwd is what
+ * `server/web/lib/app-frame.ts` relies on — but app_build also runs from the
+ * MCP server, whose cwd is server/mcp, and a bare relative path there resolves
+ * to nothing. That cost a live build outage: every agent-driven app_build
+ * failed with ENOENT until the lookup stopped assuming one caller. So the
+ * package locates the manifest relative to ITSELF first (the repo and the image
+ * share the same layout), falls back to the cwd convention for anything that
+ * relocates it, and takes an explicit env override ahead of both.
  *
- * A missing or malformed manifest THROWS. It must never degrade to "no
- * exports known", because an empty map would flag every import as invalid, and
- * an optional map would silently stop guarding.
+ * A missing or malformed manifest THROWS, naming every path it tried. It must
+ * never degrade to "no exports known": an empty map would flag every import as
+ * invalid, and an optional one would silently stop guarding.
  */
 import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const MANIFEST_PATH = 'public/app-runtime/manifest.json';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
 
-let cached: Promise<Record<string, string[]>> | null = null;
+/** In order of trust: explicit override, package-relative, cwd convention. */
+export function manifestCandidates(): string[] {
+  const override = process.env.MANTLE_APP_RUNTIME_MANIFEST;
+  return [
+    ...(override ? [override] : []),
+    // packages/app-build/src → <root>/server/web/public/app-runtime/manifest.json
+    path.resolve(HERE, '../../../server/web/public/app-runtime/manifest.json'),
+    path.resolve('public/app-runtime/manifest.json'),
+  ];
+}
+
+/** Keyed by the candidate list rather than a single flag: the paths are stable
+ *  in production (so this is still one read per process), and a changed
+ *  override naturally re-resolves instead of serving another location's
+ *  answer. */
+const cache = new Map<string, Promise<Record<string, string[]>>>();
 
 export function loadRuntimeExports(
-  manifestPath: string = MANIFEST_PATH,
+  /** Injectable for tests only — production always uses the real candidates.
+   *  A test cannot isolate the not-found path otherwise, because the
+   *  package-relative candidate resolves inside the repo itself. */
+  candidates: string[] = manifestCandidates(),
 ): Promise<Record<string, string[]>> {
+  const key = candidates.join('\u0000');
+  let cached = cache.get(key);
   if (!cached) {
-    cached = readFile(manifestPath, 'utf8')
-      .then((raw) => {
+    cached = (async () => {
+      const tried: string[] = [];
+      for (const candidate of candidates) {
+        tried.push(candidate);
+        let raw: string;
+        try {
+          raw = await readFile(candidate, 'utf8');
+        } catch {
+          continue; // not here; try the next location
+        }
+        // Present but unusable is a hard error — never fall through to another
+        // candidate, or a stale copy elsewhere could silently win.
         const m = JSON.parse(raw) as { exports?: Record<string, string[]> };
         if (!m.exports || Object.keys(m.exports).length === 0) {
           throw new Error(
-            `${manifestPath} has no 'exports' map — regenerate it with the app-runtime build`,
+            `${candidate} has no 'exports' map — regenerate it with the app-runtime build`,
           );
         }
         return m.exports;
-      })
-      .catch((e: unknown) => {
-        cached = null; // let the next call retry rather than pinning the failure
-        throw e;
-      });
+      }
+      throw new Error(
+        `app-runtime manifest not found. Tried:\n  ${tried.join('\n  ')}\n` +
+          'Generate it with the app-runtime build, or set MANTLE_APP_RUNTIME_MANIFEST.',
+      );
+    })().catch((e: unknown) => {
+      cache.delete(key); // let the next call retry rather than pinning the failure
+      throw e;
+    });
+    cache.set(key, cached);
   }
   return cached;
 }