@openparachute/app 0.2.0-rc.10

package/src/index.ts

@@ -0,0 +1,394 @@
+/**
+ * @openparachute/app — library entry.
+ *
+ * Phase 1.1 wires the public surface: `serve` starts the long-running daemon
+ * that scans `$PARACHUTE_HOME/app/uis/`, mounts each declared UI at its
+ * declared path, serves the bundle with smart cache headers + SPA-routing
+ * fallback, and self-registers into `~/.parachute/services.json`. Admin
+ * verbs (`addUi`, `removeUi`, `listUis`, `reloadUi`) and dev mode
+ * (`setDevMode`) land in Phase 1.2 / 1.3.
+ *
+ * See the design doc:
+ *   https://github.com/ParachuteComputer/parachute.computer/blob/main/design/2026-05-21-parachute-apps-design.md
+ */
+
+import pkg from "../package.json" with { type: "json" };
+
+import { addUiInternal, buildUisExtraFieldForBoot } from "./admin-routes.ts";
+import { maybeBootstrapDefaultApps } from "./bootstrap.ts";
+import { type AppConfig, loadConfig, resolveConfigPath, resolveUisDir } from "./config.ts";
+import { disableDevMode, enableDevMode } from "./dev-mode.ts";
+import { stopAllWatchers } from "./dev-watcher.ts";
+import { type AppState, startHttpServer } from "./http-server.ts";
+import { resolveProjectRoot, selfRegister } from "./self-register.ts";
+import { scanUis } from "./ui-registry.ts";
+
+// Re-export everything so callers can drop down to a specific layer
+// without an import-path puzzle.
+export * from "./config.ts";
+export * from "./meta-schema.ts";
+export * from "./cache-headers.ts";
+export * from "./ui-registry.ts";
+export * from "./services-manifest.ts";
+export * from "./auth.ts";
+export * from "./operator-token.ts";
+export * from "./dcr.ts";
+export * from "./npm-fetch.ts";
+export * from "./dev-mode.ts";
+export * from "./dev-injection.ts";
+export * from "./dev-watcher.ts";
+export {
+  routeAdmin,
+  buildUisExtraFieldForBoot,
+  addUiInternal,
+  type AdminHandlerOpts,
+  type AdminMutableState,
+  type AddRequestBody,
+  type AddUiInternalResult,
+  type SerializedUi,
+} from "./admin-routes.ts";
+export {
+  maybeBootstrapDefaultApps,
+  type BootstrapOpts,
+  type BootstrapResult,
+  type BootstrapAddFn,
+} from "./bootstrap.ts";
+export {
+  provisionSchemaForUi,
+  type ProvisionSchemaOpts,
+  type ProvisionSchemaResult,
+} from "./provision-schema.ts";
+export { routeDev, type DevRoutesOpts } from "./dev-routes.ts";
+export { resolveProjectRoot, selfRegister } from "./self-register.ts";
+export type { SelfRegisterOpts, SelfRegisterResult } from "./self-register.ts";
+export { startHttpServer } from "./http-server.ts";
+export type { AppState, HttpServerOpts } from "./http-server.ts";
+
+/** Package semver. */
+export const VERSION: string = pkg.version;
+
+/** Default healthz port (per design doc + canonical-ports pattern, app claims 1946). */
+export const DEFAULT_PORT = 1946;
+
+/** Default mount path for app under hub's reverse proxy. */
+export const DEFAULT_MOUNT = "/app";
+
+export type ServeOptions = {
+  /** Override the healthz port. Defaults to `DEFAULT_PORT` (1946). */
+  port?: number;
+  /** Override the config path (tests). Defaults to `resolveConfigPath()`. */
+  configPath?: string;
+  /** Override the uis-dir location (tests). Defaults to `resolveUisDir()`. */
+  uisDir?: string;
+  /** Override the bind hostname (tests). Defaults to `127.0.0.1`. */
+  hostname?: string;
+  /** Override the services.json path (tests). */
+  manifestPath?: string;
+  /** Skip self-registration (tests don't want to touch `~/.parachute/`). */
+  skipSelfRegister?: boolean;
+  /** Override `.parachute/` location (tests). */
+  parachuteDir?: string;
+  /** Logger override; default console. */
+  logger?: Pick<Console, "log" | "warn" | "error">;
+  /**
+   * Override `Bun.serve` (tests). Lets us assert on the dispatched config
+   * without binding a real port.
+   */
+  serveFn?: typeof Bun.serve;
+  /**
+   * Override the absolute path to the built admin SPA bundle (tests). Defaults
+   * to `<package-root>/dist/admin/`.
+   */
+  adminDir?: string;
+  /** Inject fetch for DCR calls (tests). */
+  fetchFn?: import("./dcr.ts").FetchFn;
+  /** Override the operator-token resolver (tests). */
+  operatorTokenOverride?: () => string | undefined;
+  /** Override the npm-fetch spawner (tests). */
+  npmSpawnFn?: import("./npm-fetch.ts").NpmSpawnFn;
+  /**
+   * Skip the first-boot default-app bootstrap (tests + CI). When omitted,
+   * bootstrap runs iff `state.registeredUis.length === 0` AND
+   * `config.bootstrap_default_apps.enabled === true`.
+   */
+  skipBootstrap?: boolean;
+  /**
+   * Return a promise from `serve()` that callers can await to know when
+   * bootstrap is complete (tests). Production `serve()` callers don't
+   * need this; bootstrap is fire-and-forget for the daemon.
+   */
+  awaitBootstrap?: boolean;
+};
+
+export type ServeHandle = {
+  /** The currently-resolved app config. */
+  config: AppConfig;
+  /** The running HTTP server — `server.stop()` for graceful shutdown. */
+  server: ReturnType<typeof Bun.serve>;
+  /** The mutable state object. */
+  state: AppState;
+  /** Stop the daemon. */
+  stop: () => Promise<void>;
+  /**
+   * Resolves once first-boot bootstrap completes. `undefined` when
+   * bootstrap was skipped (state non-empty or `skipBootstrap: true`).
+   * Tests `await handle.bootstrap` to assert post-bootstrap state.
+   */
+  bootstrap?: Promise<import("./bootstrap.ts").BootstrapResult>;
+};
+
+/**
+ * Long-running daemon: scan `$PARACHUTE_HOME/app/uis/`, mount each UI at its
+ * declared path, serve the bundle with smart cache headers + SPA fallback.
+ *
+ * Phase 1.1: discovery is one-shot at startup. Phase 1.2 adds reload + watch.
+ *
+ * Returns a handle the CLI uses to wire SIGINT/SIGTERM into graceful
+ * shutdown.
+ */
+export function serve(opts: ServeOptions = {}): ServeHandle {
+  const logger = opts.logger ?? console;
+  const port = opts.port ?? DEFAULT_PORT;
+  const hostname = opts.hostname ?? "127.0.0.1";
+
+  const config = loadConfig({ configPath: opts.configPath, logger });
+
+  // Kill-switch: when `config.disabled` is true, skip the UI scan entirely
+  // so no bundles are mounted. The HTTP server still binds (healthz + the
+  // `.parachute/*` admin surface keep working) so an operator can flip the
+  // flag back via the admin SPA (Phase 1.2) without restarting the daemon.
+  // Per design doc + reviewer nit 3 — `disabled` was loaded but not honored.
+  const scan = config.disabled
+    ? { registered: [], skipped: [] as Array<{ dirName: string; status: string; reason: string }> }
+    : scanUis({ uisDir: opts.uisDir, logger });
+
+  if (config.disabled) {
+    logger.log("[app] disabled (config.disabled=true) — no UIs mounted");
+  }
+
+  const state: AppState = {
+    config,
+    registeredUis: scan.registered,
+    skippedUis: scan.skipped.map((s) => ({
+      dirName: s.dirName,
+      status: s.status,
+      reason: s.reason,
+    })),
+  };
+
+  const startedAt = new Date();
+  const server = startHttpServer({
+    state,
+    port,
+    hostname,
+    startedAt,
+    logger,
+    parachuteDir: opts.parachuteDir,
+    serveFn: opts.serveFn,
+    adminDir: opts.adminDir,
+    adminOpts: {
+      uisDir: opts.uisDir,
+      manifestPath: opts.manifestPath,
+      fetchFn: opts.fetchFn,
+      operatorTokenOverride: opts.operatorTokenOverride,
+      npmSpawnFn: opts.npmSpawnFn,
+      logger,
+      skipSelfRegisterRefresh: opts.skipSelfRegister,
+    },
+  });
+
+  logger.log(
+    `[app] Listening on http://${hostname}:${server.port} — ${state.registeredUis.length} UI${
+      state.registeredUis.length === 1 ? "" : "s"
+    } hosted${state.skippedUis.length > 0 ? ` (${state.skippedUis.length} skipped)` : ""}`,
+  );
+  for (const ui of state.registeredUis) {
+    logger.log(`[app]   ${ui.meta.path} → ${ui.meta.displayName} (${ui.meta.name})`);
+  }
+
+  // Phase 2.1 — first-boot default-app bootstrap. Runs only when no UIs
+  // are mounted (fresh install). Best-effort; failures log + continue so
+  // a network blip or unpublished package doesn't prevent daemon
+  // startup.
+  let bootstrapPromise: Promise<import("./bootstrap.ts").BootstrapResult> | undefined;
+  if (!opts.skipBootstrap && !config.disabled && state.registeredUis.length === 0) {
+    // Fire-and-forget — daemon doesn't block on bootstrap. The add path
+    // re-scans + swaps state in-place, so subsequent requests pick up
+    // the newly-mounted UIs without a restart. The promise is exposed
+    // on the handle so tests can `await handle.bootstrap`.
+    bootstrapPromise = runBootstrap({
+      config,
+      uisDir: opts.uisDir ?? resolveUisDir(),
+      adminOpts: {
+        state,
+        uisDir: opts.uisDir,
+        manifestPath: opts.manifestPath,
+        fetchFn: opts.fetchFn,
+        operatorTokenOverride: opts.operatorTokenOverride,
+        npmSpawnFn: opts.npmSpawnFn,
+        logger,
+        // Bootstrap's own callsite owns the post-bootstrap selfRegister;
+        // skip the per-add refresh to avoid stamping a stale partial
+        // services.json mid-iteration.
+        skipSelfRegisterRefresh: true,
+      },
+      manifestPath: opts.manifestPath,
+      skipSelfRegister: opts.skipSelfRegister,
+      logger,
+    }).catch((e) => {
+      logger.warn(`[app] bootstrap failed unexpectedly: ${(e as Error).message}`);
+      return { bootstrapped: [], skipped: [], failed: [], skipReason: "exception" };
+    });
+  }
+
+  if (!opts.skipSelfRegister) {
+    // `server.port` is `number | undefined` per Bun's types (it's undefined
+    // when the server uses unix sockets, which we don't here) — fall back to
+    // the operator's requested port. Both paths produce a `number`.
+    const portWritten = server.port ?? port;
+    selfRegister({
+      boundPort: portWritten,
+      installDir: resolveProjectRoot(),
+      manifestPath: opts.manifestPath,
+      extraFields: { uis: buildUisExtraFieldForBoot(state.registeredUis) },
+      logger,
+    });
+  }
+
+  const stop = async () => {
+    logger.log("[app] shutting down");
+    // Tear down any dev-mode file watchers so the process exits cleanly.
+    // The watcher slots own AbortControllers + FSWatchers; without this
+    // the daemon can hang on shutdown until the FSEvents stream closes.
+    stopAllWatchers();
+    server.stop();
+    logger.log("[app] stopped");
+  };
+
+  return {
+    config,
+    server,
+    state,
+    stop,
+    ...(bootstrapPromise ? { bootstrap: bootstrapPromise } : {}),
+  };
+}
+
+/**
+ * One-shot: scan UIs + report status, exit. Non-daemon counterpart to
+ * `serve` — useful for `parachute-app list` (Phase 1.2) and config
+ * validation in CI.
+ */
+export function runOnce(opts: ServeOptions = {}): {
+  config: AppConfig;
+  state: AppState;
+} {
+  const logger = opts.logger ?? console;
+  const config = loadConfig({ configPath: opts.configPath, logger });
+  const scan = scanUis({ uisDir: opts.uisDir, logger });
+  const state: AppState = {
+    config,
+    registeredUis: scan.registered,
+    skippedUis: scan.skipped.map((s) => ({
+      dirName: s.dirName,
+      status: s.status,
+      reason: s.reason,
+    })),
+  };
+  logger.log(
+    `[app] scan: ${state.registeredUis.length} active, ${state.skippedUis.length} skipped`,
+  );
+  for (const ui of state.registeredUis) {
+    logger.log(`[app]   active  ${ui.meta.path} (${ui.meta.name})`);
+  }
+  for (const s of state.skippedUis) {
+    logger.log(`[app]   skip    ${s.dirName} — ${s.status}: ${s.reason}`);
+  }
+  return { config, state };
+}
+
+/**
+ * Phase 1.3 surface — toggle dev mode for a UI with live reload.
+ *
+ * The dev-mode API now ships via `./dev-mode.ts`. Callers that want
+ * fine-grained control import `enableDevMode` / `disableDevMode` /
+ * `broadcastReload` directly. This wrapper stays as the canonical
+ * library-level façade for the simple "flip a UI into dev mode" case
+ * and keeps the surface stable for downstream consumers.
+ */
+export function setDevMode(
+  name: string,
+  enable: boolean,
+): { name: string; enabled: boolean; enabledAt: number } {
+  const state = enable ? enableDevMode(name) : disableDevMode(name);
+  return { name, enabled: state.enabled, enabledAt: state.enabledAt };
+}
+
+/**
+ * Internal helper — invokes `maybeBootstrapDefaultApps` with a closure
+ * that delegates to `addUiInternal` for each declared default app.
+ * Exported for tests that want to exercise the wiring without going
+ * through the full `serve()` HTTP boot.
+ *
+ * After the bootstrap iteration completes, if any UIs were added, we
+ * call `selfRegister` once so services.json carries the new `uis` map
+ * in a single atomic write (vs the per-add stamps the admin path would
+ * normally do — `skipSelfRegisterRefresh: true` is set on the addOpts).
+ */
+export async function runBootstrap(args: {
+  config: AppConfig;
+  uisDir: string;
+  /** Pre-built admin opts — same shape `routeAdmin` consumes. */
+  adminOpts: import("./admin-routes.ts").AdminHandlerOpts;
+  /** Override the services.json manifest path (tests). */
+  manifestPath?: string;
+  logger?: Pick<Console, "log" | "warn" | "error">;
+  /** Skip post-bootstrap selfRegister (tests). */
+  skipSelfRegister?: boolean;
+}): Promise<import("./bootstrap.ts").BootstrapResult> {
+  const logger = args.logger ?? console;
+  const result = await maybeBootstrapDefaultApps({
+    config: args.config,
+    uisDir: args.uisDir,
+    logger,
+    add: async (spec) => {
+      const outcome = await addUiInternal({ source: spec }, args.adminOpts);
+      if (!outcome.added) {
+        // Surface the underlying error message — best-effort body parse.
+        let detail = `HTTP ${outcome.response.status}`;
+        try {
+          const parsed = (await outcome.response.clone().json()) as {
+            error?: string;
+            message?: string;
+          };
+          detail = parsed.message ?? parsed.error ?? detail;
+        } catch {
+          // ignore
+        }
+        throw new Error(detail);
+      }
+      return { name: outcome.added.meta.name, path: outcome.added.meta.path };
+    },
+  });
+
+  // One-shot post-bootstrap services.json refresh: stamps the full uis
+  // map atomically so hub's per-request discovery sees the bootstrapped
+  // UIs on its next read.
+  if (!args.skipSelfRegister && result.bootstrapped.length > 0) {
+    try {
+      selfRegister({
+        boundPort: 0,
+        installDir: resolveProjectRoot(),
+        manifestPath: args.manifestPath,
+        extraFields: { uis: buildUisExtraFieldForBoot(args.adminOpts.state.registeredUis) },
+        logger,
+      });
+    } catch (e) {
+      logger.warn(`[app] bootstrap: services.json refresh failed: ${(e as Error).message}`);
+    }
+  }
+  return result;
+}
+
+/** Expose canonical resolvers for the bin. */
+export { resolveConfigPath, resolveUisDir };