@openparachute/app 0.2.0-rc.10

package/src/self-register.ts

@@ -0,0 +1,184 @@
+/**
+ * `selfRegister()` — stamp app's entry into `~/.parachute/services.json`
+ * on `parachute-app serve` boot.
+ *
+ * Why this exists, in one sentence: hub-as-supervisor (v0.6) reads
+ * `~/.parachute/services.json` to know which modules exist on the host; a
+ * module that doesn't self-register is invisible to `parachute status`,
+ * `parachute restart`, the admin SPA module catalog, and the live
+ * `/.well-known/parachute.json` builder.
+ *
+ * Two reads from the file before we write:
+ *   1. The existing row's `port` is preserved on subsequent boots so an
+ *      operator (or hub) who set `app.port = 1948` in services.json stays
+ *      at 1948 across restarts — even if the env var that pointed app at
+ *      1948 is later unset. Same first-boot-vs-subsequent-boot rule
+ *      scribe + agent + runner settled (scribe#40, paraclaw#145).
+ *   2. The existing row's hub-stamped fields (`installDir` from
+ *      parachute-hub#84, future `uiUrl` / `managementUrl`) merge through
+ *      because `upsertService` spreads `entry` last. We re-stamp our own
+ *      `installDir = PROJECT_ROOT` regardless — hub#293/#302 made the
+ *      runtime install path stamp installDir, and we want services.json
+ *      to keep that resolution after a `git pull` moves the checkout.
+ *
+ * Failure mode: any error during the write is logged + swallowed by the
+ * caller (see `serve()` in `src/index.ts`). The daemon still serves locally
+ * if services.json is unwritable, malformed, or fights with a concurrent
+ * writer — the operator just won't see app in `parachute status` until the
+ * underlying issue clears.
+ *
+ * Phase 1.2 hook: this function writes only the module-level row today.
+ * When per-UI `uis` map lands (design doc section 12), the caller assembles
+ * the `uis` field and passes it through via `extraFields`.
+ */
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+
+import pkg from "../package.json" with { type: "json" };
+import { type ServiceEntry, readServiceEntry, upsertService } from "./services-manifest.ts";
+
+/**
+ * The canonical services.json row key for the app module — sourced from
+ * `.parachute/module.json#manifestName`. Hub looks up modules in
+ * services.json by `manifestName` (vault + scribe use this convention), so
+ * self-registering under the short name "app" would create a duplicate row
+ * alongside the hub-installed `parachute-app` row and trip hub's
+ * duplicate-port detector on re-read. See parachute-patterns or the
+ * `manifestName` field on .parachute/module.json files. */
+const ROW_NAME = resolveManifestName();
+
+function resolveManifestName(): string {
+  // Read once at module load — `.parachute/module.json` ships in the
+  // package and doesn't change at runtime.
+  try {
+    const manifestPath = path.resolve(import.meta.dir, "..", ".parachute", "module.json");
+    const raw = JSON.parse(readFileSync(manifestPath, "utf8")) as { manifestName?: unknown };
+    if (typeof raw.manifestName === "string" && raw.manifestName.length > 0) {
+      return raw.manifestName;
+    }
+  } catch {
+    // Fall through to the conservative fallback. The module.json is part
+    // of the published package, so this branch is effectively unreachable
+    // in production — it exists so tests that mount a stub package layout
+    // don't hard-crash on import.
+  }
+  return "parachute-app";
+}
+
+export type SelfRegisterOpts = {
+  /**
+   * The port app just bound. Used only as the first-run fallback — if
+   * services.json already has an entry, we re-stamp the existing port
+   * unchanged to preserve operator/hub overrides.
+   */
+  boundPort: number;
+  /**
+   * Absolute path to the app package root (where `.parachute/` and
+   * `package.json` live). Stamped as `installDir` so hub can resolve
+   * `parachute restart app` back to this checkout.
+   */
+  installDir: string;
+  /**
+   * Additional fields to merge into the row — used for the per-UI `uis` map
+   * (Phase 1.2) and any future schema extensions without touching this
+   * function's signature.
+   */
+  extraFields?: Record<string, unknown>;
+  /**
+   * Override the services.json location (tests). Defaults to
+   * `$PARACHUTE_HOME/services.json`.
+   */
+  manifestPath?: string;
+  /** Logger override; default console. */
+  logger?: Pick<Console, "log" | "warn" | "error">;
+};
+
+export type SelfRegisterResult = {
+  ok: boolean;
+  /** The path we wrote to (or attempted to write to). */
+  manifestPath: string;
+  /** True when services.json already had a row for `parachute-app` before we wrote. */
+  hadExistingEntry: boolean;
+  /** The port we ended up stamping (existing-entry port or boundPort). */
+  portWritten: number;
+  /** Set when ok=false — the error swallowed by the caller. */
+  error?: Error;
+};
+
+/**
+ * Self-register app's services.json entry. Best-effort: returns
+ * `{ok: false, error}` on any failure rather than throwing, so the caller's
+ * "log + continue" branch is one shape regardless of failure mode.
+ *
+ * Idempotent against repeated calls — the canonical case is `serve()`
+ * invoking this once per boot, but if the daemon restarts in-process or a
+ * Phase 1.2 UI add/remove re-runs the registration to refresh the `uis`
+ * map, repeated calls converge to the same disk state.
+ */
+export function selfRegister(opts: SelfRegisterOpts): SelfRegisterResult {
+  const logger = opts.logger ?? console;
+  const manifestPath = opts.manifestPath; // undefined → resolveManifestPath() default
+
+  let existing: ServiceEntry | undefined;
+  try {
+    existing = readServiceEntry(ROW_NAME, manifestPath);
+  } catch (e) {
+    const err = e as Error;
+    logger.warn(`[app] skipped self-register: ${err.message}`);
+    return {
+      ok: false,
+      manifestPath: manifestPath ?? "~/.parachute/services.json",
+      hadExistingEntry: false,
+      portWritten: opts.boundPort,
+      error: err,
+    };
+  }
+
+  const portToWrite = existing?.port ?? opts.boundPort;
+  const entry: ServiceEntry = {
+    name: ROW_NAME,
+    port: portToWrite,
+    paths: ["/app", "/.parachute"],
+    health: "/app/healthz",
+    version: pkg.version,
+    displayName: "App",
+    tagline:
+      "Host module for custom Parachute UIs — drop a built bundle in and serve it under one origin.",
+    installDir: opts.installDir,
+    ...(opts.extraFields ?? {}),
+  };
+
+  try {
+    upsertService(entry, manifestPath);
+  } catch (e) {
+    const err = e as Error;
+    logger.warn(`[app] skipped self-register: ${err.message}`);
+    return {
+      ok: false,
+      manifestPath: manifestPath ?? "~/.parachute/services.json",
+      hadExistingEntry: existing !== undefined,
+      portWritten: portToWrite,
+      error: err,
+    };
+  }
+
+  logger.log(
+    `[app] self-registered services.json entry (port=${portToWrite}, installDir=${opts.installDir}${existing ? ", existing entry merged" : ", first boot"})`,
+  );
+  return {
+    ok: true,
+    manifestPath: manifestPath ?? "~/.parachute/services.json",
+    hadExistingEntry: existing !== undefined,
+    portWritten: portToWrite,
+  };
+}
+
+/**
+ * Resolve the app package root — the directory containing
+ * `.parachute/module.json` + `package.json`. `import.meta.dir` points at
+ * `src/`; walk up one level. Matches the resolver in `http-server.ts`'s
+ * `defaultParachuteDir()`.
+ */
+export function resolveProjectRoot(): string {
+  return path.resolve(import.meta.dir, "..");
+}

package/src/services-manifest.ts

@@ -0,0 +1,104 @@
+/**
+ * Self-registration into `~/.parachute/services.json` on `parachute-app
+ * serve` boot.
+ *
+ * Mirrors `parachute-runner/src/services-manifest.ts` deliberately — the file
+ * shape is the contract between every Parachute module and the hub
+ * (`parachute-hub/src/services-manifest.ts` is the canonical reader).
+ *
+ * Failure mode: any write error is logged + swallowed by the caller. Self-
+ * registration is best-effort — the daemon still serves locally even if the
+ * manifest write fails (permissions, disk full, race with another writer,
+ * malformed pre-existing file).
+ *
+ * `installDir` is the third-party-module hook (parachute-hub#84): hub looks
+ * the field up to resolve `parachute restart app` back to the checkout it
+ * should drive. Self-registering it here means app doesn't need a vendored
+ * fallback in hub's `FIRST_PARTY_FALLBACKS` registry.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import { dirname, join } from "node:path";
+
+export interface ServiceEntry {
+  name: string;
+  port: number;
+  paths: string[];
+  health: string;
+  version: string;
+  displayName?: string;
+  tagline?: string;
+  installDir?: string;
+  /**
+   * Hub-stamped fields (e.g. `installDir` from parachute-hub#84, future
+   * uiUrl / managementUrl pass-throughs) ride on the row even though the
+   * module itself doesn't author them. The upsert merges rather than
+   * replaces so those survive a self-registration write.
+   *
+   * App-specific: the per-UI `uis` map (design doc section 12) also lands
+   * here once Phase 1.2 ships per-UI registration. The current shape lets
+   * a Phase 1.2 PR add `uis` without re-touching the storage layer.
+   */
+  [key: string]: unknown;
+}
+
+interface ServicesManifest {
+  services: ServiceEntry[];
+}
+
+/**
+ * Canonical location of `services.json`. Honors `PARACHUTE_HOME` for sandbox +
+ * Render deployments (matches the convention every other committed-core
+ * module follows).
+ */
+export function resolveManifestPath(env: Record<string, string | undefined> = process.env): string {
+  const base = env.PARACHUTE_HOME ?? join(env.HOME ?? os.homedir(), ".parachute");
+  return join(base, "services.json");
+}
+
+function readManifest(path: string): ServicesManifest {
+  if (!existsSync(path)) return { services: [] };
+  const raw = JSON.parse(readFileSync(path, "utf8"));
+  if (!raw || typeof raw !== "object" || !Array.isArray((raw as { services?: unknown }).services)) {
+    throw new Error(`services manifest at ${path} is malformed (missing "services" array)`);
+  }
+  return raw as ServicesManifest;
+}
+
+/**
+ * Read an existing service entry from the manifest. Returns `undefined` when
+ * the file is missing or no row matches `name`.
+ *
+ * Used at boot so app can respect an operator- or hub-set port already
+ * recorded in services.json (same first-boot-vs-subsequent-boot discipline
+ * scribe + agent settled on — see paraclaw#145 / scribe#40).
+ */
+export function readServiceEntry(
+  name: string,
+  path: string = resolveManifestPath(),
+): ServiceEntry | undefined {
+  const manifest = readManifest(path);
+  return manifest.services.find((s) => s.name === name);
+}
+
+/**
+ * Idempotent upsert of a service entry. Merges into any existing row rather
+ * than replacing it — preserves hub-stamped fields the module doesn't own
+ * (installDir from hub#84, future uiUrl, etc.). The module still wins for
+ * the fields it owns (port, paths, version, health, displayName, installDir
+ * — because `entry` spreads last in the merge).
+ *
+ * Atomic write: stages to `<path>.tmp-<pid>-<now>`, then renames over the
+ * target. A crash mid-write leaves the prior file intact rather than
+ * corrupting it.
+ */
+export function upsertService(entry: ServiceEntry, path: string = resolveManifestPath()): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const manifest = readManifest(path);
+  const idx = manifest.services.findIndex((s) => s.name === entry.name);
+  if (idx >= 0) manifest.services[idx] = { ...manifest.services[idx], ...entry };
+  else manifest.services.push(entry);
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`);
+  renameSync(tmp, path);
+}

package/src/tenancy-injection.ts

@@ -0,0 +1,149 @@
+/**
+ * Runtime tenancy contract injection — implements the host side of
+ * `parachute-patterns/patterns/runtime-tenancy-contract.md`.
+ *
+ * For every `index.html` parachute-app serves on behalf of a hosted UI we
+ * inject a small block of structured environment metadata into `<head>`:
+ *
+ *   <head>
+ *     <base href="/app/<name>/">                              browser URL resolution
+ *     <meta name="parachute-mount" content="/app/<name>">     runtime code reads this
+ *     <meta name="parachute-hub" content="<hub-origin>">      OAuth discovery
+ *     ... existing head ...
+ *   </head>
+ *
+ * Two layers, deliberately:
+ *
+ *   - `<base href>` is load-bearing for the BROWSER's URL resolution. Without
+ *     it, Vite-built bundles' `./assets/...` URLs resolve against the
+ *     document's perceived directory (`/app/` when the operator visits
+ *     `/app/notes` with no trailing slash), and 404 on every asset.
+ *   - `<meta name="parachute-mount">` / `<meta name="parachute-hub">` are
+ *     read at runtime by `@openparachute/app-client` (parachute-app#22).
+ *     Strings the bundle reads as JavaScript — no help from the browser's
+ *     URL resolver, hence the separate meta tags.
+ *
+ * Tags deliberately deferred (out of scope for parachute-app#21):
+ *   - `parachute-vault` — needs vault-binding-via-session design that's
+ *     orthogonal to the mount-path concerns this PR addresses.
+ *   - `parachute-tenant-id` — derivable on the consumer side from
+ *     `parachute-mount`; not worth its own injection.
+ *   - `parachute-vault-origin` — forward-looking for cross-origin vault.
+ *
+ * Why string scanning (no `cheerio`): the rationale in `dev-injection.ts`
+ * applies identically here. One conservative substring insertion; we don't
+ * want to canonicalize the operator's HTML.
+ *
+ * Idempotency: if `<meta name="parachute-mount">` is already present in
+ * the source HTML (e.g. some future bundle ships its own injection), we
+ * leave the document untouched. The marker check is regex-based — a false
+ * positive (a comment containing the exact attribute) suppresses injection
+ * harmlessly.
+ */
+
+/** Regex marker for idempotency. Matches both quote styles + case. */
+const MOUNT_META_REGEX = /<meta\b[^>]*\bname\s*=\s*['"]parachute-mount['"][^>]*>/i;
+/** Find the opening `<head ...>` tag, case-insensitive, whitespace-tolerant. */
+const HEAD_OPEN_REGEX = /<head(\s[^>]*)?>/i;
+
+/** Minimal HTML attribute-value escape — order matters (escape `&` first). */
+export function escapeHtmlAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export type TenancyInjectionResult = {
+  /** The (maybe-modified) document. */
+  html: string;
+  /** Did we change anything? */
+  injected: boolean;
+  /** Why we skipped, if we did. `undefined` on the happy path. */
+  skipped?: "already-present" | "no-head";
+};
+
+/**
+ * Inject the runtime tenancy contract tags into `html`.
+ *
+ *   - `mount` is the UI's mount path (`/app/<name>`, no trailing slash).
+ *     Used unchanged in `<meta name="parachute-mount">`; appended with `/`
+ *     in `<base href>` (the trailing slash is browser-URL-resolution
+ *     critical).
+ *   - `hubOrigin` is the absolute hub URL (`http://127.0.0.1:1939` or
+ *     `https://parachute.example.com`).
+ *
+ * Returns `{ html, injected, skipped? }`:
+ *   - `injected: true` + `skipped: undefined` on the happy path.
+ *   - `injected: false` + `skipped: "already-present"` when the source
+ *     already declares `parachute-mount` (idempotent).
+ *   - `injected: false` + `skipped: "no-head"` when the document has no
+ *     `<head>` (malformed; caller logs + serves unmodified).
+ *
+ * Note we insert AFTER the opening `<head>` tag, not before `</head>` like
+ * `dev-injection.ts` does. The contract tags should come BEFORE any
+ * existing `<base>` / `<link rel=icon>` / `<script>` so the browser's
+ * URL resolver picks up the injected `<base href>` for everything in the
+ * document. (Per HTML spec, the first `<base>` wins — if the bundle ships
+ * its own and we insert after it, the bundle's wins; inserting at head-top
+ * lets the host's mount-aware base take precedence.)
+ */
+export function injectTenancyContract(
+  html: string,
+  mount: string,
+  hubOrigin: string,
+): TenancyInjectionResult {
+  // Idempotent: bail if the marker is already in the doc.
+  if (MOUNT_META_REGEX.test(html)) {
+    return { html, injected: false, skipped: "already-present" };
+  }
+
+  // Find the first <head> that's NOT inside an HTML comment. Vite-built
+  // HTML never has `<!-- <head> -->` comments, but be defensive — a
+  // false match inside a comment would inject malformed HTML.
+  let searchFrom = 0;
+  let headMatch: RegExpExecArray | null = null;
+  while (true) {
+    HEAD_OPEN_REGEX.lastIndex = 0;
+    const candidate = HEAD_OPEN_REGEX.exec(html.slice(searchFrom));
+    if (!candidate) break;
+    const absoluteIndex = searchFrom + candidate.index;
+    if (!isInsideComment(html, absoluteIndex)) {
+      headMatch = candidate;
+      headMatch.index = absoluteIndex;
+      break;
+    }
+    // Skip past this comment and search again.
+    const commentClose = html.indexOf("-->", absoluteIndex);
+    if (commentClose === -1) break;
+    searchFrom = commentClose + 3;
+  }
+  if (!headMatch) {
+    return { html, injected: false, skipped: "no-head" };
+  }
+
+  const baseHref = `${mount}/`;
+  const block = [
+    `<base href="${escapeHtmlAttr(baseHref)}">`,
+    `<meta name="parachute-mount" content="${escapeHtmlAttr(mount)}">`,
+    `<meta name="parachute-hub" content="${escapeHtmlAttr(hubOrigin)}">`,
+  ].join("\n    ");
+
+  const insertAt = headMatch.index + headMatch[0].length;
+  return {
+    html: `${html.slice(0, insertAt)}\n    ${block}${html.slice(insertAt)}`,
+    injected: true,
+  };
+}
+
+/**
+ * True if `pos` falls inside an unclosed HTML comment that opens before
+ * it. Used to skip `<head>` matches that are really `<!-- ... <head> ... -->`.
+ */
+function isInsideComment(html: string, pos: number): boolean {
+  const lastOpen = html.lastIndexOf("<!--", pos);
+  if (lastOpen === -1) return false;
+  const closeAfterOpen = html.indexOf("-->", lastOpen);
+  return closeAfterOpen !== -1 && closeAfterOpen > pos;
+}

package/src/ui-registry.ts

@@ -0,0 +1,202 @@
+/**
+ * UI discovery for parachute-app.
+ *
+ * Scans `$PARACHUTE_HOME/app/uis/` for subdirectories. For each:
+ *   1. Look for `meta.json` — skip + warn if missing.
+ *   2. Look for `dist/index.html` — skip + warn if missing.
+ *   3. Parse + validate meta.json via `parseMeta` — skip + warn on invalid.
+ *   4. Compute the absolute paths app will resolve assets against at serve-time.
+ *
+ * Returns the validated `RegisteredUi[]` list. Mount-path collisions are
+ * resolved deterministically: alphabetical-by-name wins, others are demoted
+ * to `status: "collision"` and dropped from the active mount set (still
+ * surfaced in `parachute-app list` once that lands in Phase 1.2). Same shape
+ * the design doc landed in section 8, modulo the alphabetical tie-break
+ * which the Phase 1.1 brief asked for explicitly.
+ *
+ * `RegisteredUi.distDir` is the absolute path to the `dist/` directory; the
+ * HTTP layer resolves each asset request against it.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import * as path from "node:path";
+
+import { resolveUisDir } from "./config.ts";
+import { InvalidMetaError, type UiMeta, parseMeta } from "./meta-schema.ts";
+
+export type UiStatus =
+  | "active"
+  | "missing-meta"
+  | "missing-dist"
+  | "invalid-meta"
+  | "collision"
+  | "reserved-path";
+
+export type RegisteredUi = {
+  /** Directory name under `uis/`. May differ from `meta.name` until Phase 1.2 enforces alignment. */
+  dirName: string;
+  /** Absolute path to the `<uis>/<dirName>/` directory. */
+  uiDir: string;
+  /** Absolute path to the `<uis>/<dirName>/dist/` directory. */
+  distDir: string;
+  /** Parsed meta.json. */
+  meta: UiMeta;
+};
+
+export type SkippedUi = {
+  dirName: string;
+  uiDir: string;
+  status: Exclude<UiStatus, "active">;
+  reason: string;
+};
+
+export type ScanResult = {
+  /** UIs that mounted successfully + survived collision resolution. */
+  registered: RegisteredUi[];
+  /** UIs the scanner found but couldn't activate. */
+  skipped: SkippedUi[];
+};
+
+export type ScanOpts = {
+  /** Override the uis-dir location (tests). Defaults to `resolveUisDir()`. */
+  uisDir?: string;
+  /** Logger override; default console. */
+  logger?: Pick<Console, "log" | "warn" | "error">;
+};
+
+/**
+ * Path the admin SPA reserves once Phase 1.2 lands. A meta.json that tries
+ * to claim it is rejected at scan time. Kept as a const so Phase 1.2's
+ * `add` flow can share the same check.
+ */
+export const RESERVED_PATHS: ReadonlySet<string> = new Set(["/app/admin", "/app/dev"]);
+
+/**
+ * Scan `uisDir` for declared UIs. Best-effort: a malformed UI is skipped +
+ * surfaced in `skipped`; it never throws. Only an exception reading the
+ * uisDir itself (permissions, broken symlink at the directory level)
+ * propagates — that's a fatal config issue the operator needs to see.
+ */
+export function scanUis(opts: ScanOpts = {}): ScanResult {
+  const uisDir = opts.uisDir ?? resolveUisDir();
+  const logger = opts.logger ?? console;
+
+  if (!existsSync(uisDir)) {
+    // Fresh install — no `uis/` directory yet. That's fine; just return empty.
+    logger.log(`[app] uis dir not found at ${uisDir}; no UIs to mount`);
+    return { registered: [], skipped: [] };
+  }
+
+  let entries: string[];
+  try {
+    entries = readdirSync(uisDir);
+  } catch (e) {
+    logger.error(`[app] failed to read uis dir ${uisDir}: ${(e as Error).message}`);
+    throw e;
+  }
+
+  const candidates: Array<RegisteredUi | SkippedUi> = [];
+
+  for (const dirName of entries.sort()) {
+    const uiDir = path.join(uisDir, dirName);
+    let st: ReturnType<typeof statSync>;
+    try {
+      st = statSync(uiDir);
+    } catch {
+      // Disappearing entries (race, broken symlink) — skip silently.
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+
+    const metaPath = path.join(uiDir, "meta.json");
+    const distDir = path.join(uiDir, "dist");
+    const indexPath = path.join(distDir, "index.html");
+
+    if (!existsSync(metaPath)) {
+      const reason = `missing meta.json at ${metaPath}`;
+      logger.warn(`[app] skip ${dirName}: ${reason}`);
+      candidates.push({ dirName, uiDir, status: "missing-meta", reason });
+      continue;
+    }
+
+    if (!existsSync(indexPath)) {
+      const reason = `missing dist/index.html at ${indexPath}`;
+      logger.warn(`[app] skip ${dirName}: ${reason}`);
+      candidates.push({ dirName, uiDir, status: "missing-dist", reason });
+      continue;
+    }
+
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(metaPath, "utf8"));
+    } catch (e) {
+      const reason = `meta.json is not valid JSON: ${(e as Error).message}`;
+      logger.warn(`[app] skip ${dirName}: ${reason}`);
+      candidates.push({ dirName, uiDir, status: "invalid-meta", reason });
+      continue;
+    }
+
+    let meta: UiMeta;
+    try {
+      meta = parseMeta(raw);
+    } catch (e) {
+      const reason =
+        e instanceof InvalidMetaError
+          ? e.message
+          : `meta.json validation failed: ${(e as Error).message}`;
+      logger.warn(`[app] skip ${dirName}: ${reason}`);
+      candidates.push({ dirName, uiDir, status: "invalid-meta", reason });
+      continue;
+    }
+
+    if (RESERVED_PATHS.has(meta.path)) {
+      const reason = `meta.path "${meta.path}" is reserved (admin SPA)`;
+      logger.warn(`[app] skip ${dirName}: ${reason}`);
+      candidates.push({ dirName, uiDir, status: "reserved-path", reason });
+      continue;
+    }
+
+    candidates.push({ dirName, uiDir, distDir, meta });
+  }
+
+  // Resolve mount-path collisions deterministically: among UIs declaring the
+  // same `meta.path`, the lexicographically-smallest `meta.name` wins; the
+  // others are demoted to `status: "collision"`.
+  const byPath = new Map<string, RegisteredUi[]>();
+  const skipped: SkippedUi[] = [];
+  for (const c of candidates) {
+    if ("meta" in c) {
+      const list = byPath.get(c.meta.path) ?? [];
+      list.push(c);
+      byPath.set(c.meta.path, list);
+    } else {
+      skipped.push(c);
+    }
+  }
+
+  const registered: RegisteredUi[] = [];
+  for (const [mountPath, list] of byPath) {
+    if (list.length === 1) {
+      registered.push(list[0]!);
+      continue;
+    }
+    list.sort((a, b) => a.meta.name.localeCompare(b.meta.name));
+    const winner = list[0]!;
+    registered.push(winner);
+    for (let i = 1; i < list.length; i++) {
+      const loser = list[i]!;
+      const reason = `mount path ${mountPath} also claimed by "${winner.meta.name}" — alphabetical tie-break wins`;
+      logger.warn(`[app] skip ${loser.dirName}: ${reason}`);
+      skipped.push({
+        dirName: loser.dirName,
+        uiDir: loser.uiDir,
+        status: "collision",
+        reason,
+      });
+    }
+  }
+
+  // Stable ordering for downstream consumers (HTTP routing + admin list).
+  registered.sort((a, b) => a.meta.path.localeCompare(b.meta.path));
+  return { registered, skipped };
+}