@openparachute/hub 0.5.2 → 0.5.9-rc.6

package/src/module-manifest.ts

@@ -114,6 +114,27 @@ export interface ModuleManifest {
    * as `hasAuth` / `init` / `urlForEntry`.
    */
   readonly managementUrl?: string;
+  /**
+   * Where the module's primary user-facing UI lives. Hub renders a tile on
+   * the discovery page (`/`) Services section when set (see
+   * `parachute-patterns/patterns/module-json-extensibility.md` and the
+   * `loadUiUrls` resolver in `hub-server.ts`).
+   *
+   * Two shapes — same rules as `managementUrl`:
+   *   - A relative path (e.g. `"/notes"`, `"/agent"`) — hub resolves
+   *     against the canonical hub origin.
+   *   - A full absolute URL — hub uses verbatim.
+   *
+   * Absent = no Services tile rendered (the module is API-only or surfaces
+   * its UI via a sibling module — e.g. vault content browses through Notes,
+   * so vault has no `uiUrl`).
+   *
+   * Read at every discovery render via `installDir/.parachute/module.json`
+   * (mirrors how `managementUrl` is sourced for vaults). Not persisted in
+   * services.json — that file's "services own the write side" semantics
+   * would clobber any install-time copy on the next service boot.
+   */
+  readonly uiUrl?: string;
   /**
    * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
    * before forwarding (so the backend sees `/health` rather than
@@ -374,6 +395,7 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   const dependencies = asDependencies(m.dependencies, where);
   const configSchema = asConfigSchema(m.configSchema, where);
   const managementUrl = asManagementUrl(m.managementUrl, where);
+  const uiUrl = asUiUrl(m.uiUrl, where);
   let stripPrefix: boolean | undefined;
   if (m.stripPrefix !== undefined) {
     if (typeof m.stripPrefix !== "boolean") {
@@ -396,6 +418,9 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   if (managementUrl !== undefined) {
     (out as { managementUrl?: string }).managementUrl = managementUrl;
   }
+  if (uiUrl !== undefined) {
+    (out as { uiUrl?: string }).uiUrl = uiUrl;
+  }
   if (stripPrefix !== undefined) {
     (out as { stripPrefix?: boolean }).stripPrefix = stripPrefix;
   }
@@ -403,26 +428,39 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
 }
 
 function asManagementUrl(v: unknown, where: string): string | undefined {
+  return asPathOrUrl(v, where, "managementUrl");
+}
+
+function asUiUrl(v: unknown, where: string): string | undefined {
+  return asPathOrUrl(v, where, "uiUrl");
+}
+
+/**
+ * Validate a "path or http(s) URL" field. Both `managementUrl` and `uiUrl`
+ * follow the same shape per the module-json-extensibility pattern doc;
+ * factored so the next URL-shaped field doesn't have to copy-paste.
+ */
+function asPathOrUrl(v: unknown, where: string, field: string): string | undefined {
   if (v === undefined) return undefined;
   if (typeof v !== "string" || v.length === 0) {
-    throw new ModuleManifestError(
-      `${where}: "managementUrl" must be a non-empty string if present`,
-    );
-  }
-  // Two valid shapes: a path starting with "/" or a full http(s) URL.
-  if (v.startsWith("/")) return v;
+    throw new ModuleManifestError(`${where}: "${field}" must be a non-empty string if present`);
+  }
+  // Two valid shapes: an absolute path starting with a single "/" or a full
+  // http(s) URL. Reject protocol-relative forms like "//evil.com" — they
+  // start with "/" but `new URL("//evil.com", base)` resolves to the foreign
+  // origin, which would let a malicious module render an off-origin tile and
+  // turn the discovery page into an open-redirect surface.
+  if (v.startsWith("/") && !v.startsWith("//")) return v;
   try {
     const u = new URL(v);
     if (u.protocol !== "http:" && u.protocol !== "https:") {
-      throw new ModuleManifestError(
-        `${where}: "managementUrl" absolute form must use http: or https:`,
-      );
+      throw new ModuleManifestError(`${where}: "${field}" absolute form must use http: or https:`);
     }
     return v;
   } catch (err) {
     if (err instanceof ModuleManifestError) throw err;
     throw new ModuleManifestError(
-      `${where}: "managementUrl" must be a path starting with "/" or a full http(s) URL`,
+      `${where}: "${field}" must be a path starting with "/" or a full http(s) URL`,
     );
   }
 }

package/src/notes-serve.ts

@@ -25,6 +25,7 @@
  */
 
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
 interface Args {
@@ -67,16 +68,76 @@ export function normalizeMount(raw: string): string {
   return raw.replace(/\/+$/, "");
 }
 
-function resolveNotesDist(): string {
-  const pkgPath = Bun.resolveSync("@openparachute/notes/package.json", process.cwd());
-  const root = dirname(pkgPath);
-  const dist = join(root, "dist");
-  if (!existsSync(dist)) {
-    throw new Error(
-      `@openparachute/notes is installed but has no dist/ directory at ${dist}. The package may not ship a prebuilt bundle — ask the notes maintainer to add a prepublishOnly build step.`,
-    );
+/**
+ * Candidate base directories that `Bun.resolveSync` walks from when looking
+ * for `@openparachute/notes/package.json`. Order matters:
+ *
+ *   1. `process.cwd()` — works when notes-serve is invoked from inside the
+ *      notes checkout (e.g. via `installDir` cwd in lifecycle.ts) or from
+ *      any project that depends on `@openparachute/notes`.
+ *   2. `~/.bun/install/global/node_modules` — modern Bun's global-install
+ *      layout. This is where `bun add -g @openparachute/notes` lands the
+ *      package, and where `bun link @openparachute/notes` symlinks it.
+ *   3. `~/.bun/install/global` — defensive fallback for older Bun layouts.
+ *
+ * Hub itself does NOT depend on `@openparachute/notes`, so when
+ * `parachute start notes` is run from the hub repo dir, the cwd-relative
+ * resolve walks ancestral node_modules and finds nothing. Bun does not
+ * auto-consult the global install dir, so bun-linked installs fail to
+ * resolve without (2)/(3). hub#194: Aaron hit silent 502 on tailnet
+ * `/notes/` because of this — fixed by trying the global install dirs.
+ *
+ * Exported (and parameterized via `cwd`/`home`) so tests can drive the
+ * resolution order against a real fixture install without monkey-patching
+ * `Bun.resolveSync`.
+ */
+export function notesDistCandidates(cwd: string, home: string): string[] {
+  return [cwd, join(home, ".bun/install/global/node_modules"), join(home, ".bun/install/global")];
+}
+
+export interface ResolveNotesDistDeps {
+  cwd?: string;
+  home?: string;
+  /** Override `Bun.resolveSync` for tests. */
+  resolveSync?: (specifier: string, base: string) => string;
+  existsSync?: (path: string) => boolean;
+}
+
+export function resolveNotesDistFrom(deps: ResolveNotesDistDeps = {}): string {
+  const cwd = deps.cwd ?? process.cwd();
+  const home = deps.home ?? homedir();
+  const resolveSync = deps.resolveSync ?? Bun.resolveSync;
+  const exists = deps.existsSync ?? existsSync;
+  const candidates = notesDistCandidates(cwd, home);
+  const resolveErrors: string[] = [];
+  for (const base of candidates) {
+    let pkgPath: string;
+    try {
+      pkgPath = resolveSync("@openparachute/notes/package.json", base);
+    } catch (err) {
+      resolveErrors.push(`  - ${base}: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    const root = dirname(pkgPath);
+    const dist = join(root, "dist");
+    if (!exists(dist)) {
+      // Found the package but it has no dist/. This is a hard error
+      // (package shipped without a prebuilt bundle); don't fall through to
+      // other candidates — they'd resolve to the same package and report
+      // the same problem.
+      throw new Error(
+        `@openparachute/notes resolved at ${root} has no dist/ directory at ${dist}. The package may not ship a prebuilt bundle — ask the notes maintainer to add a prepublishOnly build step.`,
+      );
+    }
+    return dist;
   }
-  return dist;
+  throw new Error(
+    `Could not resolve @openparachute/notes from any of:\n${resolveErrors.join("\n")}\nIs the package installed? Try \`bun add -g @openparachute/notes\` or \`parachute install notes\`.`,
+  );
+}
+
+function resolveNotesDist(): string {
+  return resolveNotesDistFrom();
 }
 
 function mimeFor(path: string): string | undefined {