@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.160.1

package/src/runtime/app-registry-scaffolds.js

@@ -0,0 +1,367 @@
+/**
+ * Store-backed scaffold catalog for the Notis CLI.
+ *
+ * Every app published to the public Store lives with its full source in the
+ * public registry repository (github.com/mindtheflo/notis-apps, one app per
+ * `apps/<slug>/` directory). That repository IS the scaffold catalog:
+ * `apps scaffolds list` reads the published listings and `apps init --from
+ * <slug>` downloads the listed app's source. Publishing an app automatically
+ * makes it a scaffold — the CLI bundles nothing besides the bare template.
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+import { usageError } from './errors.js';
+
+const DEFAULT_REGISTRY_REPO = 'mindtheflo/notis-apps';
+const DEFAULT_REGISTRY_REF = 'main';
+// How many registry files to download at once when materializing a scaffold.
+const DOWNLOAD_CONCURRENCY = 4;
+const MAX_SCAFFOLD_FILES = 2_000;
+const MAX_SCAFFOLD_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_SCAFFOLD_TOTAL_BYTES = 50 * 1024 * 1024;
+const MAX_CATALOG_ENTRIES = 1_000;
+const MAX_REGISTRY_COMMIT_BYTES = 2 * 1024 * 1024;
+const MAX_REGISTRY_API_BYTES = 10 * 1024 * 1024;
+const MAX_CATALOG_METADATA_BYTES = 1024 * 1024;
+const MAX_CATALOG_TOTAL_BYTES = 20 * 1024 * 1024;
+// Registry bookkeeping that must never enter a new project: the listing
+// descriptor and the rendered Store gallery describe the published app, and a
+// scaffold copy starts a new identity.
+const REGISTRY_ARTIFACT = /^(notis-listing\.json$|screenshots(\/|$))/;
+// Files the scaffold copy step would drop anyway — skip the download.
+const SKIPPED_SOURCE = /(^|\/)(node_modules|\.notis|\.git|dist|coverage|\.next|\.turbo)(\/|$)|(^|\/)\.env|\.(test|spec)\.[cm]?[jt]sx?$/;
+
+function registryRepo() {
+  return process.env.NOTIS_APP_REGISTRY_REPO || DEFAULT_REGISTRY_REPO;
+}
+
+function registryRef() {
+  return process.env.NOTIS_APP_REGISTRY_REF || DEFAULT_REGISTRY_REF;
+}
+
+/**
+ * Local registry checkout override (`<dir>/apps/<slug>/…`). Used by tests and
+ * by offline development against a clone of the registry repository.
+ */
+function localRegistryDir() {
+  return process.env.NOTIS_APP_REGISTRY_DIR || null;
+}
+
+export function scaffoldRegistryLabel() {
+  return localRegistryDir() || `github.com/${registryRepo()}`;
+}
+
+async function fetchRegistry(url, { binary = false, maxBytes = null } = {}) {
+  let response;
+  try {
+    response = await fetch(url, { headers: { 'user-agent': 'notis-cli' } });
+  } catch (error) {
+    throw usageError(
+      `Could not reach the Notis app registry (${scaffoldRegistryLabel()}): ${error.message}. ` +
+        'Scaffolds are downloaded from published Store apps and need network access.',
+    );
+  }
+  if (!response.ok) {
+    throw usageError(`Notis app registry request failed (${response.status}) for ${url}.`);
+  }
+  const contentLength = Number(response.headers?.get?.('content-length'));
+  if (maxBytes && Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw usageError(`Notis app registry response exceeds the ${maxBytes}-byte limit.`);
+  }
+  let data;
+  if (maxBytes && response.body?.getReader) {
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = Buffer.from(value);
+      total += chunk.length;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw usageError(`Notis app registry response exceeds the ${maxBytes}-byte limit.`);
+      }
+      chunks.push(chunk);
+    }
+    data = Buffer.concat(chunks, total);
+  } else {
+    data = Buffer.from(await response.arrayBuffer());
+  }
+  if (maxBytes && data.length > maxBytes) {
+    throw usageError(`Notis app registry response exceeds the ${maxBytes}-byte limit.`);
+  }
+  return binary ? data : data.toString('utf8');
+}
+
+function encodedRegistryRepoPath() {
+  const parts = registryRepo().split('/');
+  if (
+    parts.length !== 2
+    || parts.some((part) => !part || !/^[A-Za-z0-9_.-]+$/.test(part))
+  ) {
+    throw usageError('Notis app registry repository must use the owner/repository form.');
+  }
+  return parts.map((part) => encodeURIComponent(part)).join('/');
+}
+
+async function resolveRegistryCommit() {
+  const url = `https://api.github.com/repos/${encodedRegistryRepoPath()}/commits/${encodeURIComponent(registryRef())}`;
+  // GitHub's commit-detail response includes changed-file metadata and can be
+  // substantially larger than the SHA we read from it. Keep a bounded limit,
+  // but allow normal registry commits with a long file list.
+  const payload = JSON.parse(await fetchRegistry(url, { maxBytes: MAX_REGISTRY_COMMIT_BYTES }));
+  const commitSha = typeof payload?.sha === 'string' ? payload.sha.trim() : '';
+  if (!/^[0-9a-f]{40}$/i.test(commitSha)) {
+    throw usageError(
+      `Notis app registry returned no immutable commit for ${registryRepo()}@${registryRef()}.`,
+    );
+  }
+  return commitSha;
+}
+
+async function fetchRegistryTree(commitSha) {
+  const url = `https://api.github.com/repos/${encodedRegistryRepoPath()}/git/trees/${commitSha}?recursive=1`;
+  const payload = JSON.parse(await fetchRegistry(url, { maxBytes: MAX_REGISTRY_API_BYTES }));
+  if (!Array.isArray(payload?.tree)) {
+    throw usageError(`Notis app registry returned no file tree for ${registryRepo()}@${commitSha}.`);
+  }
+  if (payload.truncated === true) {
+    throw usageError(
+      `Notis app registry tree was truncated for ${registryRepo()}@${commitSha}; refusing an incomplete scaffold catalog.`,
+    );
+  }
+  return payload.tree
+    .filter((entry) => entry?.type === 'blob' && typeof entry.path === 'string')
+    .map((entry) => ({ path: entry.path, size: Number(entry.size) }));
+}
+
+function fetchRegistryFile(path, commitSha, options) {
+  const encodedPath = String(path).split('/').map((part) => encodeURIComponent(part)).join('/');
+  return fetchRegistry(
+    `https://raw.githubusercontent.com/${encodedRegistryRepoPath()}/${commitSha}/${encodedPath}`,
+    options,
+  );
+}
+
+async function mapWithConcurrency(values, concurrency, mapper) {
+  const results = new Array(values.length);
+  let cursor = 0;
+  async function worker() {
+    while (cursor < values.length) {
+      const index = cursor;
+      cursor += 1;
+      results[index] = await mapper(values[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, worker));
+  return results;
+}
+
+function assertSafeScaffoldSlug(value) {
+  const slug = String(value || '');
+  if (!slug || slug === '.' || slug === '..' || /[\\/\0]/.test(slug)) {
+    throw usageError(`Unsafe scaffold slug: ${value}`);
+  }
+  return slug;
+}
+
+/**
+ * Resolve a registry-owned relative path without allowing either slash style,
+ * drive-letter paths, or dot segments to escape the temporary scaffold root.
+ * Exported so the platform-independent boundary contract can be unit tested on
+ * every host, including macOS CI for the Windows backslash case.
+ */
+export function resolveScaffoldTargetPath(tempRoot, registryRelativePath) {
+  const raw = String(registryRelativePath || '');
+  const normalized = raw.replace(/\\/g, '/');
+  const parts = normalized.split('/');
+  if (
+    !normalized
+    || normalized.includes('\0')
+    || normalized.startsWith('/')
+    || /^[A-Za-z]:\//.test(normalized)
+    || parts.some((part) => !part || part === '.' || part === '..')
+  ) {
+    throw usageError(`Refusing unsafe path from Notis app registry: ${registryRelativePath}`);
+  }
+
+  const root = resolve(tempRoot);
+  const target = resolve(root, ...parts);
+  const fromRoot = relative(root, target);
+  if (!fromRoot || fromRoot === '..' || fromRoot.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(fromRoot)) {
+    throw usageError(`Refusing path outside scaffold directory: ${registryRelativePath}`);
+  }
+  return target;
+}
+
+function readTsStringProperty(source, propertyName) {
+  const match = source.match(new RegExp(`\\b${propertyName}\\s*:\\s*(['"\`])([\\s\\S]*?)\\1`));
+  return match ? match[2] : null;
+}
+
+function catalogEntry(slug, listing, configSource) {
+  const description = listing?.description || readTsStringProperty(configSource, 'description') || '';
+  return {
+    slug,
+    name: listing?.name || readTsStringProperty(configSource, 'title') || slug,
+    description,
+    icon: readTsStringProperty(configSource, 'icon') || 'phosphor:squares-four',
+    categories: Array.isArray(listing?.categories) ? listing.categories.filter(Boolean) : [],
+    tagline: listing?.tagline || readTsStringProperty(configSource, 'tagline') || description,
+  };
+}
+
+function readOptionalFile(path) {
+  return existsSync(path) ? readFileSync(path, 'utf-8') : '';
+}
+
+function loadLocalCatalog(registryDir) {
+  const appsDir = join(registryDir, 'apps');
+  if (!existsSync(appsDir)) {
+    return [];
+  }
+  const scaffolds = [];
+  for (const entry of readdirSync(appsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.startsWith('_')) {
+      continue;
+    }
+    const appDir = join(appsDir, entry.name);
+    if (!existsSync(join(appDir, 'notis.config.ts'))) {
+      continue;
+    }
+    const listingPath = join(appDir, 'notis-listing.json');
+    const listing = existsSync(listingPath) ? JSON.parse(readFileSync(listingPath, 'utf-8')) : null;
+    scaffolds.push(catalogEntry(entry.name, listing, readOptionalFile(join(appDir, 'notis.config.ts'))));
+  }
+  return scaffolds.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/**
+ * List every published Store app as a scaffold.
+ */
+export async function loadScaffoldCatalog() {
+  const registryDir = localRegistryDir();
+  if (registryDir) {
+    return loadLocalCatalog(registryDir);
+  }
+  const commitSha = await resolveRegistryCommit();
+  const tree = (await fetchRegistryTree(commitSha)).map((entry) => entry.path);
+  const slugs = [...new Set(
+    tree
+      .filter((path) => /^apps\/[^/]+\//.test(path))
+      .map((path) => path.split('/')[1]),
+  )].filter((slug) => tree.includes(`apps/${slug}/notis.config.ts`));
+  if (slugs.length > MAX_CATALOG_ENTRIES) {
+    throw usageError(`Notis app registry contains too many scaffold entries (${slugs.length}; maximum ${MAX_CATALOG_ENTRIES}).`);
+  }
+  let catalogBytes = 0;
+  const scaffolds = await mapWithConcurrency(slugs, DOWNLOAD_CONCURRENCY, async (slug) => {
+    const [listingText, configSource] = await Promise.all([
+      tree.includes(`apps/${slug}/notis-listing.json`)
+        ? fetchRegistryFile(`apps/${slug}/notis-listing.json`, commitSha, { maxBytes: MAX_CATALOG_METADATA_BYTES })
+        : Promise.resolve(''),
+      fetchRegistryFile(`apps/${slug}/notis.config.ts`, commitSha, { maxBytes: MAX_CATALOG_METADATA_BYTES }),
+    ]);
+    catalogBytes += Buffer.byteLength(listingText) + Buffer.byteLength(configSource);
+    if (catalogBytes > MAX_CATALOG_TOTAL_BYTES) {
+      throw usageError(
+        `Notis app scaffold catalog exceeds the ${MAX_CATALOG_TOTAL_BYTES}-byte aggregate metadata limit.`,
+      );
+    }
+    const listing = listingText ? JSON.parse(listingText) : null;
+    return catalogEntry(slug, listing, configSource);
+  });
+  return scaffolds.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/**
+ * Case-insensitive match over slug, name, tagline, description, and categories.
+ */
+export function filterScaffoldCatalog(catalog, searchTerm) {
+  const term = String(searchTerm || '').trim().toLowerCase();
+  if (!term) {
+    return catalog;
+  }
+  const words = term.split(/\s+/);
+  return catalog.filter((entry) => {
+    const haystack = [entry.slug, entry.name, entry.tagline, entry.description, ...(entry.categories || [])]
+      .join(' ')
+      .toLowerCase();
+    return words.every((word) => haystack.includes(word));
+  });
+}
+
+/**
+ * Materialize one published app's source for `apps init --from`.
+ *
+ * Returns `{ dir, cleanup }` or null when the slug is not in the registry.
+ * The caller copies out of `dir` and must call `cleanup()` afterwards.
+ */
+export async function acquireScaffoldSource(fromSlug) {
+  const safeSlug = assertSafeScaffoldSlug(fromSlug);
+  const registryDir = localRegistryDir();
+  if (registryDir) {
+    const appDir = join(registryDir, 'apps', safeSlug);
+    if (!existsSync(join(appDir, 'notis.config.ts'))) {
+      return null;
+    }
+    return { dir: appDir, cleanup: () => {} };
+  }
+
+  const commitSha = await resolveRegistryCommit();
+  const tree = await fetchRegistryTree(commitSha);
+  const prefix = `apps/${safeSlug}/`;
+  const files = tree
+    .filter((entry) => entry.path.startsWith(prefix))
+    .map((entry) => ({ ...entry, rel: entry.path.slice(prefix.length) }))
+    .filter((entry) => entry.rel && !REGISTRY_ARTIFACT.test(entry.rel) && !SKIPPED_SOURCE.test(entry.rel));
+  if (!files.some((entry) => entry.rel === 'notis.config.ts')) {
+    return null;
+  }
+  if (files.length > MAX_SCAFFOLD_FILES) {
+    throw usageError(`Published scaffold contains too many files (${files.length}; maximum ${MAX_SCAFFOLD_FILES}).`);
+  }
+  const declaredBytes = files.reduce((total, entry) => (
+    Number.isFinite(entry.size) && entry.size >= 0 ? total + entry.size : total
+  ), 0);
+  if (files.some((entry) => Number.isFinite(entry.size) && entry.size > MAX_SCAFFOLD_FILE_BYTES)) {
+    throw usageError(`Published scaffold contains a file larger than ${MAX_SCAFFOLD_FILE_BYTES} bytes.`);
+  }
+  if (declaredBytes > MAX_SCAFFOLD_TOTAL_BYTES) {
+    throw usageError(`Published scaffold source exceeds ${MAX_SCAFFOLD_TOTAL_BYTES} bytes.`);
+  }
+
+  const tempRoot = mkdtempSync(join(tmpdir(), 'notis-scaffold-'));
+  let downloadedBytes = 0;
+  try {
+    for (let index = 0; index < files.length; index += DOWNLOAD_CONCURRENCY) {
+      const settled = await Promise.allSettled(
+        files.slice(index, index + DOWNLOAD_CONCURRENCY).map(async (entry) => {
+          const target = resolveScaffoldTargetPath(tempRoot, entry.rel);
+          const data = await fetchRegistryFile(prefix + entry.rel, commitSha, {
+            binary: true,
+            maxBytes: MAX_SCAFFOLD_FILE_BYTES,
+          });
+          downloadedBytes += data.length;
+          if (downloadedBytes > MAX_SCAFFOLD_TOTAL_BYTES) {
+            throw usageError(`Published scaffold source exceeds ${MAX_SCAFFOLD_TOTAL_BYTES} bytes.`);
+          }
+          mkdirSync(dirname(target), { recursive: true });
+          writeFileSync(target, data);
+        }),
+      );
+      const failed = settled.find((result) => result.status === 'rejected');
+      if (failed) {
+        throw failed.reason;
+      }
+    }
+  } catch (error) {
+    rmSync(tempRoot, { recursive: true, force: true });
+    throw error;
+  }
+  return { dir: tempRoot, cleanup: () => rmSync(tempRoot, { recursive: true, force: true }) };
+}

package/src/runtime/app-test-server.js

@@ -0,0 +1,292 @@
+/** Temporary, explicit app verification/screenshot server. Never mounts a Workspace app. */
+import { createServer } from 'node:http';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exportNameFromPath, getBundleDir, loadAppConfig, readManifest } from './app-platform.js';
+
+const CONTENT_TYPES = { '.js': 'application/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.map': 'application/json; charset=utf-8' };
+const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const REPO_ROOT = resolve(CLI_ROOT, '../..');
+const HARNESS_TEMPLATE_PATH = join(CLI_ROOT, 'template', '.harness', 'index.html.tmpl');
+const FALLBACK_REACT_VERSION = '19.0.0';
+
+function extFor(pathname) {
+  const idx = pathname.lastIndexOf('.');
+  return idx === -1 ? '' : pathname.slice(idx);
+}
+
+function isAllowedOrigin(origin) {
+  if (!origin) return true;
+  try {
+    const parsed = new URL(origin);
+    if (parsed.protocol === 'notis-app:') return true;
+    if (!['http:', 'https:'].includes(parsed.protocol)) return false;
+    return ['localhost', '127.0.0.1', '::1', '[::1]'].includes(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+function corsHeaders(origin) {
+  const allowOrigin = origin && isAllowedOrigin(origin) ? origin : '*';
+  return {
+    'Access-Control-Allow-Origin': allowOrigin,
+    'Access-Control-Allow-Methods': 'GET, HEAD, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Cache-Control',
+    'Cache-Control': 'no-store',
+  };
+}
+
+function safeJoin(baseDir, relPath) {
+  const normalized = relPath.replace(/\\/g, '/').replace(/^\/+/, '');
+  if (normalized.includes('..')) return null;
+  return join(baseDir, normalized);
+}
+
+function scriptJson(value) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+function readJsonFile(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function reactVersionFromPeer(peerRange) {
+  if (typeof peerRange !== 'string' || !peerRange) {
+    return FALLBACK_REACT_VERSION;
+  }
+  const exact = peerRange.match(/\d+\.\d+\.\d+/);
+  if (exact && !/[<>=~^*x]/i.test(peerRange.replace(exact[0], ''))) {
+    return exact[0];
+  }
+  if (peerRange.includes('19') || peerRange.includes('18')) {
+    return FALLBACK_REACT_VERSION;
+  }
+  return FALLBACK_REACT_VERSION;
+}
+
+function resolveHarnessReactVersion(projectDir) {
+  const candidates = [
+    join(projectDir, 'node_modules', '@notis', 'sdk', 'package.json'),
+    join(REPO_ROOT, 'packages', 'sdk', 'package.json'),
+    join(CLI_ROOT, 'template', 'packages', 'sdk', 'package.json'),
+  ];
+  for (const candidate of candidates) {
+    const pkg = readJsonFile(candidate);
+    const peer = pkg?.peerDependencies?.react;
+    if (peer) {
+      return reactVersionFromPeer(peer);
+    }
+  }
+  return FALLBACK_REACT_VERSION;
+}
+
+function titleFromSlug(slug) {
+  return String(slug || '')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function normalizeDatabaseDescriptors(databases) {
+  return (Array.isArray(databases) ? databases : [])
+    .map((entry) => {
+      if (typeof entry === 'string') {
+        return {
+          slug: entry,
+          title: titleFromSlug(entry),
+          description: null,
+          icon: null,
+          properties: [],
+        };
+      }
+      if (entry && typeof entry === 'object' && typeof entry.slug === 'string') {
+        return {
+          slug: entry.slug,
+          title: entry.title || titleFromSlug(entry.slug),
+          description: entry.description || null,
+          icon: entry.icon || null,
+          properties: Array.isArray(entry.properties) ? entry.properties : [],
+        };
+      }
+      return null;
+    })
+    .filter(Boolean);
+}
+
+function normalizeToolDescriptors(tools) {
+  return (Array.isArray(tools) ? tools : [])
+    .map((entry) => {
+      if (typeof entry === 'string') {
+        return { name: entry };
+      }
+      if (entry && typeof entry === 'object' && typeof entry.name === 'string') {
+        return entry;
+      }
+      return null;
+    })
+    .filter(Boolean);
+}
+
+function defaultRouteForManifest(manifest) {
+  const routes = Array.isArray(manifest?.routes) ? manifest.routes : [];
+  return routes.find((route) => route?.default) || routes[0] || null;
+}
+
+function findHarnessRoute(manifest, routeSlug) {
+  const routes = Array.isArray(manifest?.routes) ? manifest.routes : [];
+  if (!routeSlug) {
+    return defaultRouteForManifest(manifest);
+  }
+  return routes.find((route) => route?.slug === routeSlug) || null;
+}
+
+function buildHarnessDescriptor({ state, manifest, appConfig, route, scenario = null }) {
+  const databases = normalizeDatabaseDescriptors(
+    Array.isArray(appConfig?.databases) && appConfig.databases.length
+      ? appConfig.databases
+      : manifest.databases,
+  );
+  const tools = normalizeToolDescriptors(
+    Array.isArray(appConfig?.tools) && appConfig.tools.length
+      ? appConfig.tools
+      : manifest.tools,
+  );
+
+  return {
+    app: {
+      id: state.appId || 'harness-app',
+      slug: state.slug,
+      name: manifest.app?.name || appConfig?.name || state.slug,
+      icon: manifest.app?.icon || appConfig?.icon || null,
+      description: manifest.app?.description || appConfig?.description || null,
+    },
+    route: {
+      slug: route.slug,
+      path: route.path || '/',
+      name: route.name || titleFromSlug(route.slug),
+      icon: route.icon || null,
+      parentSlug: route.parentSlug || null,
+      default: Boolean(route.default),
+      resourceDeepLinks: route.resourceDeepLinks === true,
+      collection: route.collection || null,
+    },
+    databases,
+    context: { collectionItem: null, resourceId: null, screenshotScenario: scenario },
+    tools,
+  };
+}
+
+function plainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+/**
+ * Resolve the fixture payload injected into one harness page load.
+ *
+ * A scenario may override individual `tools` / `requests` keys on top of the
+ * file-level defaults, which is how one route renders both its populated and
+ * its empty state. Each capture is its own page load, so a shallow per-key
+ * merge is all the isolation a scenario needs.
+ */
+function harnessFixtures(projectDir, scenario) {
+  const fixtureConfig = readJsonFile(join(projectDir, 'metadata', 'screenshot-fixtures.json')) || {};
+  const scenarios = plainObject(fixtureConfig.scenarios);
+  const selected = scenario ? plainObject(scenarios[scenario]) : null;
+  return {
+    tools: { ...plainObject(fixtureConfig.tools), ...plainObject(selected?.tools) },
+    requests: { ...plainObject(fixtureConfig.requests), ...plainObject(selected?.requests) },
+    scenario: selected && Object.keys(selected).length > 0 ? selected : null,
+  };
+}
+
+function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions, scenario = null }) {
+  const template = readFileSync(HARNESS_TEMPLATE_PATH, 'utf-8');
+  const descriptor = buildHarnessDescriptor({ state, manifest, appConfig, route, scenario });
+  const routeExport = route.export_name || route.exportName || exportNameFromPath(route.path || '/');
+  const replacements = {
+    '{{REACT_VERSION}}': resolveHarnessReactVersion(state.projectDir),
+    '{{ROUTE_EXPORT}}': scriptJson(routeExport),
+    '{{RUNTIME_DESCRIPTOR}}': scriptJson(descriptor),
+    '{{MODE}}': scriptJson(harnessOptions.mode || 'stub'),
+    '{{API_BASE}}': scriptJson(harnessOptions.apiBase || null),
+    '{{JWT}}': scriptJson(harnessOptions.jwt || null),
+    '{{FIXTURES}}': scriptJson(harnessFixtures(state.projectDir, scenario)),
+  };
+  let html = template;
+  for (const [token, value] of Object.entries(replacements)) {
+    html = html.replaceAll(token, value);
+  }
+  return html;
+}
+
+
+/** Serve only explicitly supplied built projects, without discovery or filesystem watchers. */
+export async function startAppTestServer({ apps, port, harness = {} }) {
+  if (!Array.isArray(apps) || !apps.length) throw new Error('At least one built app is required.');
+  const states = new Map();
+  for (const app of apps) {
+    states.set(app.slug, {
+      ...app,
+      manifest: readManifest(app.projectDir),
+      appConfig: await loadAppConfig(app.projectDir),
+      bundleDir: getBundleDir(app.projectDir),
+    });
+  }
+  const server = createServer((req, res) => {
+    const headers = corsHeaders(req.headers.origin || '');
+    const respond = (status, content, contentType = 'text/plain; charset=utf-8') => {
+      res.writeHead(status, { ...headers, 'Content-Type': contentType });
+      res.end(req.method === 'HEAD' ? undefined : content);
+    };
+    try {
+      if (req.headers.origin && !isAllowedOrigin(req.headers.origin)) return respond(403, 'origin not allowed');
+      if (req.method === 'OPTIONS') return respond(204, '');
+      if (!['GET', 'HEAD'].includes(req.method)) return respond(405, 'method not allowed');
+      const url = new URL(req.url || '/', 'http://127.0.0.1');
+      if (url.pathname === '/healthz') return respond(200, JSON.stringify({ ok: true }), 'application/json');
+      const match = url.pathname.match(/^\/a\/([^/]+)\/(.*)$/);
+      const state = match && states.get(decodeURIComponent(match[1]));
+      if (!state) return respond(404, 'not found');
+      if (match[2] === 'harness') {
+        const route = findHarnessRoute(state.manifest, url.searchParams.get('route') || '');
+        if (!route) return respond(404, 'unknown route');
+        return respond(200, renderHarnessHtml({ state, manifest: state.manifest, appConfig: state.appConfig, route, harnessOptions: harness, scenario: url.searchParams.get('scenario') }), 'text/html; charset=utf-8');
+      }
+      if (match[2].startsWith('bundle/')) {
+        const relativePath = decodeURIComponent(match[2].slice('bundle/'.length));
+        const file = safeJoin(state.bundleDir, relativePath);
+        if (!file || !existsSync(file) || !statSync(file).isFile()) return respond(404, 'not found');
+        return respond(200, readFileSync(file), CONTENT_TYPES[extFor(file)] || 'application/octet-stream');
+      }
+      return respond(404, 'not found');
+    } catch (error) {
+      return respond(500, error instanceof Error ? error.message : String(error));
+    }
+  });
+  await new Promise((accept, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => { server.off('error', reject); accept(); });
+  });
+  let closing;
+  return {
+    port: server.address().port,
+    close() {
+      closing ||= new Promise((accept) => {
+        server.close(accept);
+        server.closeAllConnections?.();
+      });
+      return closing;
+    },
+  };
+}