@sempods/apps 0.0.0-stage → 0.7.0-dev.1

package/scripts/check.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Checks the owner's apps: manifest, generated configuration, the shared SDK
+// version and its shipped app-author reference, declared dependencies, and
+// lint, typecheck, build and tests of every app. The tooling's own checks
+// run in its source repository (check-tooling.mjs).
+// Usage: pnpm run check [--standalone <id|all>]
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { builtinModules, createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import semver from 'semver';
+import { readApps } from './lib/apps.mjs';
+import { staleGenerated } from './lib/generate.mjs';
+import { migrationState } from './migrate.mjs';
+import { readJson, writeJson } from './lib/json.mjs';
+import { repositoryRoot, TOOLING } from './lib/paths.mjs';
+import { INSTALL, pnpm, scriptArgs } from './lib/pnpm.mjs';
+import { EXACT_VERSION, REFERENCE, SDK } from './lib/sdk.mjs';
+
+const SOURCE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const BUILTIN = new Set(builtinModules);
+
+// Build output, installed packages and static files are not app source.
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'dev-dist', 'public']);
+
+function sourceFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory())
+      return SKIP_DIRS.has(name) || name.startsWith('.')
+        ? []
+        : sourceFiles(path);
+    return SOURCE_EXT.test(name) ? [path] : [];
+  });
+}
+
+let typescript;
+function scanner() {
+  // TypeScript's own import scanner: it skips comments and strings and finds
+  // static and dynamic imports, re-exports and require() calls. Keep the root
+  // dependency on TypeScript 6: TypeScript 7 does not ship this compiler API.
+  // Apps can use the native compiler independently of this scanner.
+  typescript ??= createRequire(import.meta.url)('typescript');
+  return typescript;
+}
+
+/** Package names imported by a source file (bare specifiers only). */
+export function importedPackages(source) {
+  const names = new Set();
+  const { importedFiles } = scanner().preProcessFile(source, true, true);
+  for (const { fileName: spec } of importedFiles) {
+    if (/^(\.|\/|node:|virtual:|[a-z]+:\/\/)/.test(spec)) continue;
+    const parts = spec.split('/');
+    const name = spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+    if (!BUILTIN.has(name)) names.add(name);
+  }
+  return names;
+}
+
+/**
+ * Problems found without running any tool: manifest, generation, versions,
+ * imports and an outstanding starter migration. `tooling` is the installed
+ * @sempods/apps.
+ */
+export function staticProblems(root, { tooling = TOOLING } = {}) {
+  const problems = [];
+  let manifest;
+  try {
+    manifest = readApps(root);
+  } catch (error) {
+    return [error.message];
+  }
+  const appsDir = join(root, 'apps');
+  // Every directory counts, with or without package.json: an unlisted one
+  // would also block new-app for that ID.
+  const dirs = existsSync(appsDir)
+    ? readdirSync(appsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name)
+    : [];
+  for (const dir of dirs)
+    if (!manifest.apps.some((app) => app.id === dir))
+      problems.push(
+        `apps/${dir} is not listed in apps.json; add it there or remove the directory`,
+      );
+
+  const rootManifest = readJson(join(root, 'package.json'));
+
+  const versions = new Map();
+  const expect = (where, pkg, version) => {
+    if (!EXACT_VERSION.test(version ?? ''))
+      problems.push(
+        `${where}: ${pkg} must be an exact version, found ${JSON.stringify(version)}`,
+      );
+    versions.set(`${where} ${pkg}`, version);
+  };
+  // The root installs the SDK too, so its shipped reference is there before any
+  // app; new-app gives a new app the root's version.
+  for (const pkg of SDK)
+    expect('root', pkg, rootManifest.devDependencies?.[pkg]);
+
+  for (const app of manifest.apps) {
+    const dir = join(appsDir, app.id);
+    if (!existsSync(join(dir, 'package.json'))) {
+      problems.push(`apps/${app.id} is listed in apps.json but missing`);
+      continue;
+    }
+    for (const file of staleGenerated(dir, app, manifest.site))
+      problems.push(
+        `apps/${app.id}/${file} does not match apps.json; regenerate it instead of editing`,
+      );
+    const pkg = readJson(join(dir, 'package.json'));
+    for (const sdk of SDK)
+      expect(`apps/${app.id}`, sdk, pkg.dependencies?.[sdk]);
+    const declared = new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+    for (const file of sourceFiles(dir))
+      for (const name of importedPackages(readFileSync(file, 'utf8')))
+        if (!declared.has(name))
+          problems.push(
+            `${file.slice(root.length + 1)} imports ${name}, which apps/${app.id}/package.json does not declare`,
+          );
+  }
+
+  const found = new Set(versions.values());
+  for (const sdk of SDK) {
+    const installed = join(root, 'node_modules', sdk, 'package.json');
+    if (existsSync(installed)) found.add(readJson(installed).version);
+  }
+  if (found.size > 1)
+    problems.push(
+      `SDK versions differ (${[...found].join(', ')}): the root, all apps and the installed packages must use one version`,
+    );
+  // The tooling generates code against the SDK, so it names the releases it
+  // supports.
+  const toolingManifest = readJson(join(tooling, 'package.json'));
+  for (const sdk of SDK) {
+    const range = toolingManifest.peerDependencies?.[sdk];
+    const version = rootManifest.devDependencies?.[sdk];
+    if (
+      range &&
+      EXACT_VERSION.test(version ?? '') &&
+      !semver.satisfies(version, range, { includePrerelease: true })
+    )
+      problems.push(
+        `${sdk} ${version} is outside the range ${toolingManifest.name} ${toolingManifest.version} supports (${range}); update ${toolingManifest.name} or use a supported SDK version`,
+      );
+  }
+  // The app-author reference ships inside the installed SDK.
+  if (
+    existsSync(join(root, 'node_modules', '@sempods', 'app-sdk')) &&
+    !existsSync(join(root, ...REFERENCE.split('/')))
+  )
+    problems.push(
+      `${REFERENCE} is missing: the installed @sempods/app-sdk ships no app-author reference`,
+    );
+  const migration = migrationState(root, tooling);
+  if (migration) problems.push(migration);
+  return problems;
+}
+
+const run = (args, cwd) => pnpm(args, { cwd }).status === 0;
+
+function standalone(root, id, packageManager) {
+  const work = mkdtempSync(join(tmpdir(), `sempods-${id}-`));
+  try {
+    cpSync(join(root, 'apps', id), work, {
+      recursive: true,
+      filter: (src) =>
+        !/[\\/](node_modules|dist)([\\/]|$)/.test(src.slice(root.length)),
+    });
+    // The workspace settings (no install scripts, Node version, overrides)
+    // apply here too; its package pattern matches nothing in the copy.
+    cpSync(join(root, 'pnpm-workspace.yaml'), join(work, 'pnpm-workspace.yaml'));
+    // The copy installs with the root's pinned pnpm, not whichever pnpm or
+    // Corepack default would serve a manifest without packageManager.
+    const manifest = readJson(join(work, 'package.json'));
+    manifest.packageManager = packageManager;
+    writeJson(join(work, 'package.json'), manifest);
+    // Installs, lints, builds and tests without the workspace, so a package that
+    // only another app or the root tooling provides fails here.
+    return (
+      run(INSTALL, work) &&
+      run(['run', 'lint'], work) &&
+      run(['run', 'build'], work) &&
+      run(['run', 'test'], work)
+    );
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+function main() {
+  const { values } = parseArgs({
+    args: scriptArgs(),
+    options: { standalone: { type: 'string' } },
+  });
+  const root = repositoryRoot();
+  const failures = staticProblems(root);
+  for (const problem of failures) console.error(`✗ ${problem}`);
+
+  const step = (label, ok) => {
+    console.log(`${ok ? '✓' : '✗'} ${label}`);
+    if (!ok) failures.push(label);
+  };
+  for (const app of readAppsSafe(root)) {
+    const dir = join(root, 'apps', app.id);
+    step(`apps/${app.id}: lint`, run(['run', 'lint'], dir));
+    step(`apps/${app.id}: typecheck and build`, run(['run', 'build'], dir));
+    step(`apps/${app.id}: tests`, run(['run', 'test'], dir));
+  }
+  // Outside the workspace, an app finds only what its own package.json
+  // declares, including CLIs its scripts call.
+  const apps = readAppsSafe(root).map((app) => app.id);
+  const isolated =
+    values.standalone === 'all'
+      ? apps
+      : values.standalone
+        ? [values.standalone]
+        : [];
+  const { packageManager } = readJson(join(root, 'package.json'));
+  for (const id of isolated)
+    step(
+      `apps/${id}: standalone install, lint, build and tests`,
+      apps.includes(id) && standalone(root, id, packageManager),
+    );
+
+  if (failures.length > 0) {
+    console.error(`\ncheck failed: ${failures.length} problem(s).`);
+    process.exit(1);
+  }
+  console.log('\ncheck passed.');
+}
+
+function readAppsSafe(root) {
+  try {
+    return readApps(root).apps;
+  } catch {
+    return [];
+  }
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+)
+  main();

package/scripts/configure-site.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Records where the site is published in apps.json and regenerates every app's
+// configuration from it. Each app gets a did:web identity per site origin;
+// local development keeps its own profile.
+// Usage: pnpm run configure-site --production <origin> [--preview <origin> |
+//        --no-preview] [--change-domain]
+import { callbackUrl, checkDidWeb } from '@sempods/client-sdk/oauth/host';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import {
+  readApps,
+  SITE_PROFILES,
+  siteIdentity,
+  validateApps,
+  writeApps,
+} from './lib/apps.mjs';
+import { writeGenerated } from './lib/generate.mjs';
+import { repositoryRoot } from './lib/paths.mjs';
+import { scriptArgs } from './lib/pnpm.mjs';
+
+/** Applies the options to apps.json and regenerates the apps; returns the site. */
+export function configureSite(
+  root,
+  { production, preview, noPreview = false, changeDomain = false } = {},
+) {
+  const manifest = readApps(root);
+  const current = manifest.site;
+  if (preview !== undefined && noPreview)
+    throw new Error('Use either --preview or --no-preview.');
+  // A new origin is a new identity for every app: logins and grants start over.
+  if (
+    current?.production &&
+    production !== undefined &&
+    production !== current.production &&
+    !changeDomain
+  )
+    throw new Error(
+      `site.production is ${current.production}. Changing it gives every app a new identity, so every login and Pod grant must be made again. Rerun with --change-domain if that is intended.`,
+    );
+  const nextPreview = noPreview ? undefined : (preview ?? current?.preview);
+  const site = {
+    production: production ?? current?.production,
+    ...(nextPreview && { preview: nextPreview }),
+  };
+  if (site.production === undefined)
+    throw new Error('Name the published site: --production <https-origin>.');
+  const next = { ...manifest, site };
+  const problems = validateApps(next);
+  if (problems.length > 0) throw new Error(problems.join('; '));
+  // The SDK's own checks, so a site is accepted exactly when the runtime
+  // would accept its identities (canonical HTTPS callback, no loopback,
+  // did:web matching the callback).
+  for (const profile of SITE_PROFILES) {
+    if (!site[profile]) continue;
+    const { clientId, redirectUri } = siteIdentity(site[profile], {
+      id: 'app',
+      path: '/app/',
+    });
+    try {
+      checkDidWeb(clientId, callbackUrl(redirectUri, false));
+    } catch {
+      throw new Error(
+        `site.${profile} ${site[profile]} is not a published address the SDK accepts: use a public HTTPS host, such as https://apps.example.org.`,
+      );
+    }
+  }
+  writeApps(root, next);
+  for (const app of next.apps) {
+    const dir = join(root, 'apps', app.id);
+    if (existsSync(dir)) writeGenerated(dir, app, site);
+  }
+  return next;
+}
+
+function main() {
+  const { values } = parseArgs({
+    args: scriptArgs(),
+    options: {
+      production: { type: 'string' },
+      preview: { type: 'string' },
+      'no-preview': { type: 'boolean' },
+      'change-domain': { type: 'boolean' },
+    },
+  });
+  const root = repositoryRoot();
+  const { site, apps } = configureSite(root, {
+    production: values.production,
+    preview: values.preview,
+    noPreview: values['no-preview'],
+    changeDomain: values['change-domain'],
+  });
+  console.log('Site configured.');
+  for (const profile of SITE_PROFILES) {
+    if (!site[profile]) continue;
+    console.log(`\n${profile}: ${site[profile]}`);
+    for (const app of apps) {
+      const { clientId, redirectUri } = siteIdentity(site[profile], app);
+      console.log(`  ${app.id}: ${clientId} → ${redirectUri}`);
+    }
+  }
+  console.log(
+    '\nBuild it: pnpm run build-site (see instructions/publish.md in @sempods/apps)',
+  );
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`configure-site: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/create.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Creates a new apps repository from the starter this package ships, records
+// the starter snapshot it applied as the repository's baseline and initializes
+// Git on main, the branch the starter's workflows check.
+// Usage: sempods-apps create <directory>   (pnpm create @sempods/apps <dir>)
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readJson, writeJson } from './lib/json.mjs';
+import { TOOLING } from './lib/paths.mjs';
+import { scriptArgs } from './lib/pnpm.mjs';
+import { starterAt, writeBaseline } from './lib/shared.mjs';
+
+const NAME = /^[a-z0-9][a-z0-9._-]*$/;
+
+/**
+ * Writes the starter of `snapshot` into `target`, which must be missing or
+ * empty, with the tooling `version` in its manifest.
+ */
+export function create(target, { snapshot, version }) {
+  const dir = resolve(target);
+  if (existsSync(dir) && readdirSync(dir).length > 0)
+    throw new Error(`${target} already exists and is not empty`);
+  for (const file of Object.keys(snapshot.files)) {
+    mkdirSync(dirname(join(dir, file)), { recursive: true });
+    writeFileSync(join(dir, file), readFileSync(snapshot.path(file)));
+  }
+  const manifest = readJson(join(dir, 'package.json'));
+  const name = basename(dir).toLowerCase();
+  if (NAME.test(name)) manifest.name = name;
+  manifest.devDependencies['@sempods/apps'] = version;
+  writeJson(join(dir, 'package.json'), manifest);
+  writeBaseline(dir, { version, revision: snapshot.revision });
+  return dir;
+}
+
+/** The starter this installed package ships; only a packed package has one. */
+export function packagedStarter() {
+  if (!existsSync(join(TOOLING, 'shared', 'snapshot.json')))
+    throw new Error(
+      'this @sempods/apps has no packed starter; create repositories with a published version, for example pnpm create @sempods/apps <directory>',
+    );
+  return starterAt(TOOLING);
+}
+
+export function main(args = scriptArgs()) {
+  if (args.length !== 1 || args[0].startsWith('-'))
+    throw new Error('Usage: pnpm create @sempods/apps <directory>');
+  const dir = create(args[0], packagedStarter());
+  const git = spawnSync('git', ['init', '--quiet', '-b', 'main'], {
+    cwd: dir,
+    stdio: 'ignore',
+  });
+  console.log(`Created ${dir}.`);
+  if (git.status !== 0)
+    console.log(
+      'Git is missing or failed: initialize the repository on the main branch before the first commit.',
+    );
+  // No shell command to copy: open the folder; INIT.md has the setup steps.
+  console.log(`
+Open this folder in your coding assistant and paste:
+
+  Read AGENTS.md and INIT.md. Help me build my first app.`);
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`create: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/dev.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Starts the development server of one app. Usage: pnpm run dev <id>
+import { join } from 'node:path';
+import { readApps } from './lib/apps.mjs';
+import { repositoryRoot } from './lib/paths.mjs';
+import { pnpm, scriptArgs } from './lib/pnpm.mjs';
+
+const root = repositoryRoot();
+const [id] = scriptArgs();
+const manifest = readApps(root);
+const app = manifest.apps.find((entry) => entry.id === id);
+if (!app) {
+  const known = manifest.apps.map((entry) => entry.id).join(', ') || 'none yet';
+  console.error(`Usage: pnpm run dev <id>. Apps: ${known}.`);
+  process.exit(2);
+}
+console.log(`${app.title}: http://127.0.0.1:${app.devPort}${app.path}`);
+const result = pnpm(['run', 'dev'], { cwd: join(root, 'apps', app.id) });
+process.exit(result.status ?? 1);

package/scripts/lib/apps.mjs

@@ -0,0 +1,164 @@
+// Reads and validates apps.json, the owner's manifest of apps.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJson, writeJson } from './json.mjs';
+
+export const SCHEMA_VERSION = 1;
+export const FIRST_DEV_PORT = 5174;
+export const LANGUAGES = ['en', 'de'];
+// Where the site is published (configure-site): one origin per profile and the
+// host whose routing build-site writes for.
+export const SITE_PROFILES = ['production', 'preview'];
+const SITE_KEYS = new Set(SITE_PROFILES);
+
+const ID_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+// Paths the site itself uses, and directory names that would confuse the
+// repository layout.
+const SITE_RESERVED = new Set([
+  'apps',
+  'assets',
+  'callback',
+  'index',
+  'node_modules',
+  'public',
+  'reference',
+  'src',
+  'static',
+]);
+// Windows reserves these device names, with or without an extension.
+const WINDOWS_DEVICES = new Set([
+  'con',
+  'prn',
+  'aux',
+  'nul',
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+
+/** Returns a reason when `id` cannot name an app, otherwise undefined. */
+export function invalidId(id) {
+  if (typeof id !== 'string' || !ID_PATTERN.test(id))
+    return 'an app ID is one lowercase segment: a letter, then up to 39 letters, digits or hyphens';
+  if (id.endsWith('-')) return 'an app ID does not end with a hyphen';
+  if (SITE_RESERVED.has(id)) return `"${id}" is reserved by the site layout`;
+  if (WINDOWS_DEVICES.has(id))
+    return `"${id}" is a reserved device name on Windows`;
+  return undefined;
+}
+
+/**
+ * Returns a reason when `value` is not an origin as apps.json records it,
+ * otherwise undefined. configure-site also lets the SDK check the identity.
+ */
+export function invalidOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    url = undefined;
+  }
+  // The origin round trip rejects a path, query, credentials and uppercase:
+  // did:web and the callback derive from exactly this host.
+  if (url?.protocol !== 'https:' || url.origin !== value || url.port)
+    return 'must be an HTTPS origin without a path or port, such as https://apps.example.org';
+  return undefined;
+}
+
+/** The did:web identity and callback of an app published at `origin`. */
+export function siteIdentity(origin, app) {
+  return {
+    clientId: `did:web:${new URL(origin).hostname}:${app.id}`,
+    redirectUri: `${origin}${app.path}callback`,
+  };
+}
+
+/** Lists every problem of the optional site configuration. */
+export function validateSite(site) {
+  if (site === undefined) return [];
+  if (site === null || typeof site !== 'object' || Array.isArray(site))
+    return ['site must be an object'];
+  const problems = [];
+  for (const key of Object.keys(site))
+    if (!SITE_KEYS.has(key)) problems.push(`site.${key} is not a known field`);
+  if (site.production === undefined)
+    problems.push('site.production is required once site is set');
+  for (const profile of SITE_PROFILES) {
+    if (site[profile] === undefined) continue;
+    const reason = invalidOrigin(site[profile]);
+    if (reason) problems.push(`site.${profile} ${reason}`);
+  }
+  if (site.preview !== undefined && site.preview === site.production)
+    problems.push('site.preview must differ from site.production');
+  return problems;
+}
+
+export function appsFile(root) {
+  return join(root, 'apps.json');
+}
+
+/** Reads apps.json. Throws when it is missing or invalid. */
+export function readApps(root) {
+  const file = appsFile(root);
+  if (!existsSync(file))
+    throw new Error(
+      'apps.json is missing; it lists the apps of this repository and must exist, even with no apps',
+    );
+  const manifest = readJson(file);
+  const problems = validateApps(manifest);
+  if (problems.length > 0) throw new Error(`apps.json: ${problems.join('; ')}`);
+  return manifest;
+}
+
+export function writeApps(root, manifest) {
+  const apps = [...manifest.apps].sort((a, b) => a.id.localeCompare(b.id));
+  writeJson(appsFile(root), { ...manifest, apps });
+}
+
+/** Lists every problem of a parsed apps.json. */
+export function validateApps(manifest) {
+  const problems = [];
+  if (manifest?.schemaVersion !== SCHEMA_VERSION)
+    problems.push(`schemaVersion must be ${SCHEMA_VERSION}`);
+  problems.push(...validateSite(manifest?.site));
+  if (!Array.isArray(manifest?.apps))
+    return [...problems, 'apps must be a list'];
+  const ids = new Set();
+  const ports = new Set();
+  for (const app of manifest.apps) {
+    const reason = invalidId(app?.id);
+    if (reason) {
+      problems.push(`${JSON.stringify(app?.id)}: ${reason}`);
+      continue;
+    }
+    if (ids.has(app.id)) problems.push(`${app.id}: listed twice`);
+    ids.add(app.id);
+    if (typeof app.title !== 'string' || app.title.trim() === '')
+      problems.push(`${app.id}: title must be text`);
+    if (!LANGUAGES.includes(app.language))
+      problems.push(
+        `${app.id}: language must be one of ${LANGUAGES.join(', ')}`,
+      );
+    if (app.path !== `/${app.id}/`)
+      problems.push(`${app.id}: path must be "/${app.id}/"`);
+    if (
+      !Number.isInteger(app.devPort) ||
+      app.devPort < 1024 ||
+      app.devPort > 65535
+    )
+      problems.push(`${app.id}: devPort must be a port number from 1024`);
+    else if (ports.has(app.devPort))
+      problems.push(`${app.id}: devPort ${app.devPort} is used twice`);
+    ports.add(app.devPort);
+    if (typeof app.pwa !== 'boolean')
+      problems.push(`${app.id}: pwa must be true or false`);
+  }
+  return problems;
+}
+
+/** The first development port after the ones in use. */
+export function nextDevPort(manifest) {
+  const used = new Set(manifest.apps.map((app) => app.devPort));
+  let port = FIRST_DEV_PORT;
+  while (used.has(port)) port += 1;
+  return port;
+}