@openparachute/app 0.2.0-rc.4

package/src/self-register.ts

@@ -0,0 +1,155 @@
+/**
+ * `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 * as path from "node:path";
+
+import pkg from "../package.json" with { type: "json" };
+import { type ServiceEntry, readServiceEntry, upsertService } from "./services-manifest.ts";
+
+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 `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("app", 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: "app",
+    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/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 };
+}