@openparachute/hub 0.5.10 → 0.5.11-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.10",
+  "version": "0.5.11-rc.1",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/api-modules-ops.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -656,3 +656,285 @@ describe("GET /api/modules/operations/:id", () => {
     expect(res.status).toBe(404);
   });
 });
+
+/**
+ * Well-known regen + installDir stamping coverage. These exercise the
+ * fix for the "newly installed module doesn't appear on discovery" bug:
+ * the live HTTP build at `/.well-known/parachute.json` reads each
+ * module's `installDir/.parachute/module.json` to find `uiUrl` (which
+ * the discovery page needs to render a tile). Without an installDir
+ * stamp post-install, the resolver skips the entry. We assert both
+ * the disk regen lands and the row carries installDir afterwards.
+ */
+describe("well-known regen after module ops", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+    _resetOperationsRegistryForTests();
+  });
+  afterEach(() => h.cleanup());
+
+  /** Stub findGlobalInstall + readModuleManifest pair for in-memory installs. */
+  function fakeInstall(
+    pkg: string,
+    manifest: {
+      name: string;
+      manifestName: string;
+      kind: "api" | "frontend" | "tool";
+      port: number;
+      paths: string[];
+      health: string;
+      uiUrl?: string;
+      displayName?: string;
+    },
+  ): {
+    findGlobalInstall: (p: string) => string | null;
+    readModuleManifest: (dir: string) => Promise<typeof manifest | null>;
+    installDir: string;
+  } {
+    const installDir = join(h.dir, "fake-install", ...pkg.split("/"));
+    const pkgJson = join(installDir, "package.json");
+    return {
+      findGlobalInstall: (p) => (p === pkg ? pkgJson : null),
+      readModuleManifest: async (dir) => (dir === installDir ? manifest : null),
+      installDir,
+    };
+  }
+
+  test("runInstall happy path: regenerates well-known + stamps installDir", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const { run } = alwaysOkRun();
+    const wkPath = join(h.dir, "well-known.json");
+    const install = fakeInstall("@openparachute/vault", {
+      name: "vault",
+      manifestName: "parachute-vault",
+      kind: "api",
+      port: 1940,
+      paths: ["/vault/default"],
+      health: "/vault/default/health",
+    });
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const deps = {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+      run,
+      findGlobalInstall: install.findGlobalInstall,
+      readModuleManifest: install.readModuleManifest,
+      wellKnownPath: wkPath,
+    };
+    const res = await handleInstall(
+      postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      deps,
+    );
+    expect(res.status).toBe(202);
+    await new Promise((r) => setTimeout(r, 10));
+
+    // installDir landed on the row (so the live well-known build's
+    // `uiUrl` resolver can find the module's manifest).
+    const manifest = JSON.parse(readFileSync(h.manifestPath, "utf8")) as {
+      services: Array<{ name: string; installDir?: string }>;
+    };
+    const vaultRow = manifest.services.find((s) => s.name === "parachute-vault");
+    expect(vaultRow?.installDir).toBe(install.installDir);
+
+    // The on-disk well-known doc reflects the new module.
+    const doc = JSON.parse(readFileSync(wkPath, "utf8")) as {
+      services: Array<{ name: string; version: string }>;
+      vaults: Array<{ name: string }>;
+    };
+    expect(doc.services.some((s) => s.name === "parachute-vault")).toBe(true);
+    expect(doc.vaults.some((v) => v.name === "default")).toBe(true);
+  });
+
+  test("runInstall failure: bun add fails -> no well-known regen (no partial state)", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const wkPath = join(h.dir, "well-known.json");
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const deps = {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+      run: async () => 1,
+      findGlobalInstall: () => null,
+      wellKnownPath: wkPath,
+    };
+    const res = await handleInstall(
+      postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      deps,
+    );
+    expect(res.status).toBe(202);
+    const body = (await res.json()) as { operation_id: string };
+    await new Promise((r) => setTimeout(r, 10));
+
+    // Operation failed.
+    const opRes = await handleOperationGet(
+      getReq(`/api/modules/operations/${body.operation_id}`, {
+        authorization: `Bearer ${bearer}`,
+      }),
+      body.operation_id,
+      deps,
+    );
+    const op = (await opRes.json()) as { status: string; log: string[] };
+    expect(op.status).toBe("failed");
+
+    // No well-known doc was written — the regen step only runs after a
+    // successful spawn, not on failure paths.
+    expect(existsSync(wkPath)).toBe(false);
+    // And the operation log carries no regen line (defensive — confirms
+    // the early-return short-circuit, not just an absent file).
+    expect(op.log.join(" ")).not.toMatch(/regenerated/);
+  });
+
+  test("runUpgrade regenerates well-known with the new version on the row", async () => {
+    // Seed services.json with an existing vault row at the old version,
+    // and make the supervisor's restart return a state (success path).
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.4.5",
+      },
+    ]);
+    const { supervisor } = makeIdleSupervisor();
+    await supervisor.start({ short: "vault", cmd: ["parachute-vault", "serve"] });
+
+    const { run } = alwaysOkRun();
+    const wkPath = join(h.dir, "well-known.json");
+    const install = fakeInstall("@openparachute/vault", {
+      name: "vault",
+      manifestName: "parachute-vault",
+      kind: "api",
+      port: 1940,
+      paths: ["/vault/default"],
+      health: "/vault/default/health",
+    });
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const deps = {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+      run,
+      findGlobalInstall: install.findGlobalInstall,
+      readModuleManifest: install.readModuleManifest,
+      wellKnownPath: wkPath,
+    };
+    const res = await handleUpgrade(
+      postReq("/api/modules/vault/upgrade", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      deps,
+    );
+    expect(res.status).toBe(202);
+    await new Promise((r) => setTimeout(r, 10));
+
+    const doc = JSON.parse(readFileSync(wkPath, "utf8")) as {
+      services: Array<{ name: string; version: string }>;
+    };
+    const row = doc.services.find((s) => s.name === "parachute-vault");
+    expect(row?.version).toBe("0.4.5");
+  });
+
+  test("runUninstall regenerates well-known without the removed module", async () => {
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.4.5",
+      },
+      {
+        name: "parachute-notes",
+        port: 1942,
+        paths: ["/notes"],
+        health: "/notes/health",
+        version: "0.4.0",
+      },
+    ]);
+    const { supervisor } = makeIdleSupervisor();
+    const { run } = alwaysOkRun();
+    const wkPath = join(h.dir, "well-known.json");
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const res = await handleUninstall(
+      postReq("/api/modules/vault/uninstall", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+        run,
+        wellKnownPath: wkPath,
+      },
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { log: string[] };
+    expect(body.log.join(" ")).toMatch(/regenerated/);
+
+    const doc = JSON.parse(readFileSync(wkPath, "utf8")) as {
+      services: Array<{ name: string }>;
+      vaults: Array<{ name: string }>;
+    };
+    // Vault gone, notes still present.
+    expect(doc.services.some((s) => s.name === "parachute-vault")).toBe(false);
+    expect(doc.vaults.some((v) => v.name === "default")).toBe(false);
+    expect(doc.services.some((s) => s.name === "parachute-notes")).toBe(true);
+  });
+
+  test("well-known regen is idempotent across two consecutive install ops", async () => {
+    // Two installs in a row of the same module produce the same on-disk
+    // doc — no drift from the regen path itself (e.g. extra entries,
+    // duplicated rows, non-deterministic ordering).
+    const { supervisor } = makeIdleSupervisor();
+    const { run } = alwaysOkRun();
+    const wkPath = join(h.dir, "well-known.json");
+    const install = fakeInstall("@openparachute/vault", {
+      name: "vault",
+      manifestName: "parachute-vault",
+      kind: "api",
+      port: 1940,
+      paths: ["/vault/default"],
+      health: "/vault/default/health",
+    });
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const deps = {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+      run,
+      findGlobalInstall: install.findGlobalInstall,
+      readModuleManifest: install.readModuleManifest,
+      wellKnownPath: wkPath,
+    };
+    await handleInstall(
+      postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      deps,
+    );
+    await new Promise((r) => setTimeout(r, 10));
+    const first = readFileSync(wkPath, "utf8");
+
+    await handleInstall(
+      postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      deps,
+    );
+    await new Promise((r) => setTimeout(r, 10));
+    const second = readFileSync(wkPath, "utf8");
+
+    expect(second).toBe(first);
+  });
+});

package/src/api-modules-ops.ts

@@ -34,12 +34,14 @@
 
 import type { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
 import { FIRST_PARTY_FALLBACKS, type ServiceSpec, composeServiceSpec } from "./service-spec.ts";
-import { findService, readManifest, removeService } from "./services-manifest.ts";
+import { findService, readManifest, removeService, upsertService } from "./services-manifest.ts";
 import type { ModuleState, SpawnRequest, Supervisor } from "./supervisor.ts";
+import { regenerateWellKnown } from "./well-known.ts";
 
 /**
  * Scope required for every POST + operation-poll endpoint here.
@@ -186,6 +188,20 @@ export interface ApiModulesOpsDeps {
    * inside `Bun.spawn` at child spawn time; we don't mutate `process.env`.
    */
   spawnEnv?: Record<string, string>;
+  /**
+   * Override the on-disk path for the regenerated `/.well-known/parachute.json`
+   * (test seam). Production writes to `WELL_KNOWN_PATH`; tests point at a
+   * tmp file so assertions can read the resulting doc without touching the
+   * operator's real config dir.
+   */
+  wellKnownPath?: string;
+  /**
+   * Reader for `<installDir>/.parachute/module.json` used by the well-known
+   * regen. Production reads from disk; tests inject a fake. Mirrors the
+   * hub-server `readModuleManifest` seam so the disk regen and the
+   * per-request HTTP build stay aligned.
+   */
+  readModuleManifest?: Parameters<typeof regenerateWellKnown>[0]["readModuleManifest"];
 }
 
 interface PathMatch {
@@ -266,6 +282,61 @@ function defaultRun(cmd: readonly string[]): Promise<number> {
   return proc.exited;
 }
 
+/**
+ * Stamp `installDir` on the services.json row for `spec.manifestName` when
+ * the package's globally-installed path can be resolved. Idempotent —
+ * no-ops when the row already carries the same `installDir`, when no row
+ * exists, or when `findGlobalInstall` can't locate the package (e.g. in
+ * tests with no global install).
+ *
+ * Mirrors the same stamp `parachute install <svc>` does in
+ * `commands/install.ts`. Without it, the discovery page's
+ * `loadServiceUiMetadata` resolver in `hub-server.ts` skips the entry (it
+ * reads `module.json` from `installDir`), so `uiUrl` never lands on the
+ * row + the new module's tile never renders on `/`.
+ */
+function stampInstallDir(spec: ServiceSpec, deps: ApiModulesOpsDeps): void {
+  const findGlobalInstall = deps.findGlobalInstall;
+  if (!findGlobalInstall) return;
+  const pkgJson = findGlobalInstall(spec.package);
+  if (!pkgJson) return;
+  const installDir = dirname(pkgJson);
+  const entry = findService(spec.manifestName, deps.manifestPath);
+  if (!entry || entry.installDir === installDir) return;
+  upsertService({ ...entry, installDir }, deps.manifestPath);
+}
+
+/**
+ * Regenerate `/.well-known/parachute.json` on disk after a state-changing
+ * module op (install / upgrade / uninstall). Wraps `regenerateWellKnown`
+ * with the deps-aware defaults — issuer for canonicalOrigin, deps-overridable
+ * paths + manifest reader. Errors land in the operation log rather than
+ * throwing back to the caller; the on-disk doc is a debug / inspection
+ * artifact, not the live discovery source, so a regen failure shouldn't
+ * mask the op's actual outcome.
+ */
+async function regenAfterOp(
+  opId: string,
+  registry: OperationsRegistry,
+  deps: ApiModulesOpsDeps,
+): Promise<void> {
+  try {
+    const regenOpts: Parameters<typeof regenerateWellKnown>[0] = {
+      manifestPath: deps.manifestPath,
+      canonicalOrigin: deps.issuer,
+    };
+    if (deps.wellKnownPath !== undefined) regenOpts.wellKnownPath = deps.wellKnownPath;
+    if (deps.readModuleManifest !== undefined) {
+      regenOpts.readModuleManifest = deps.readModuleManifest;
+    }
+    const { path } = await regenerateWellKnown(regenOpts);
+    registry.update(opId, {}, `regenerated ${path}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    registry.update(opId, {}, `well-known regen failed: ${msg}`);
+  }
+}
+
 /**
  * Spawn the supervised child for `short`, using the spec's startCmd
  * and the current services.json entry (so notes' port-derived
@@ -392,6 +463,14 @@ export async function runInstall(
     }
   }
 
+  // Stamp installDir on the row so the discovery page's `uiUrl` /
+  // `displayName` resolver can find `<installDir>/.parachute/module.json`.
+  // Mirrors `parachute install <svc>` — without this, the new module's
+  // tile never renders on `/` because `loadServiceUiMetadata` skips
+  // installDir-less rows. (Doing this BEFORE the spawn so the supervisor
+  // also sees the updated row if it consults services.json post-spawn.)
+  stampInstallDir(spec, deps);
+
   // Spawn the child via the supervisor. Boot-spawn semantics apply.
   const state = await spawnSupervised(short, spec, deps);
   if (!state) {
@@ -402,6 +481,14 @@ export async function runInstall(
     );
     return;
   }
+
+  // Regenerate the on-disk well-known doc so the inspection artifact
+  // tracks the just-installed module's row. The HTTP path serves a
+  // per-request build, so the discovery page picks up the new module
+  // either way; this keeps `~/.parachute/well-known/parachute.json` in
+  // sync for tooling that reads it directly.
+  await regenAfterOp(opId, registry, deps);
+
   registry.update(opId, { status: "succeeded" }, `${short} installed + spawned (pid ${state.pid})`);
 }
 
@@ -485,6 +572,11 @@ async function runUpgrade(
     registry.update(opId, {}, `bun add reported exit ${code} but package landed at ${probed}`);
   }
 
+  // Re-stamp installDir after upgrade — a major-version bump may relocate
+  // the package on disk (e.g. node_modules layout change). Idempotent
+  // when the path is stable.
+  stampInstallDir(spec, deps);
+
   const state = await deps.supervisor.restart(short);
   if (!state) {
     registry.update(
@@ -494,6 +586,13 @@ async function runUpgrade(
     );
     return;
   }
+
+  // Refresh the on-disk well-known so the version field on the upgraded
+  // module's row reflects the new install. The HTTP path rebuilds per
+  // request, so the discovery page tracks the new version regardless;
+  // this keeps the inspection artifact aligned.
+  await regenAfterOp(opId, registry, deps);
+
   registry.update(
     opId,
     { status: "succeeded" },
@@ -540,6 +639,26 @@ export async function handleUninstall(
   const code = await run(["bun", "remove", "-g", spec.package]);
   log.push(`bun remove -g ${spec.package} exited ${code}`);
 
+  // 4. Refresh the on-disk well-known so the uninstalled module no
+  // longer appears in the inspection artifact. The HTTP path rebuilds
+  // per request, so live discovery drops the entry immediately; this
+  // is the disk-side equivalent.
+  try {
+    const regenOpts: Parameters<typeof regenerateWellKnown>[0] = {
+      manifestPath: deps.manifestPath,
+      canonicalOrigin: deps.issuer,
+    };
+    if (deps.wellKnownPath !== undefined) regenOpts.wellKnownPath = deps.wellKnownPath;
+    if (deps.readModuleManifest !== undefined) {
+      regenOpts.readModuleManifest = deps.readModuleManifest;
+    }
+    const { path } = await regenerateWellKnown(regenOpts);
+    log.push(`regenerated ${path}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.push(`well-known regen failed: ${msg}`);
+  }
+
   return jsonOk({ short, log });
 }
 

package/src/well-known.ts

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR } from "./config.ts";
-import type { ServiceEntry } from "./services-manifest.ts";
+import { type ModuleManifest, readModuleManifest } from "./module-manifest.ts";
+import { type ServiceEntry, readManifest } from "./services-manifest.ts";
 
 export interface WellKnownServiceEntry {
   url: string;
@@ -214,3 +215,83 @@ export function writeWellKnownFile(doc: WellKnownDocument, path: string = WELL_K
   renameSync(tmp, path);
   return path;
 }
+
+export interface RegenerateWellKnownOpts {
+  /** Path to services.json. Defaults to `SERVICES_MANIFEST_PATH`. */
+  manifestPath: string;
+  /**
+   * Origin to embed in the doc's `url` fields. The hub HTTP path uses
+   * `configuredIssuer ?? new URL(req.url).origin`; module-ops callers don't
+   * have a request, so they pass `issuer` (the configured hub origin from
+   * `ApiModulesOpsDeps`) — same canonical URL the per-request build would
+   * emit.
+   */
+  canonicalOrigin: string;
+  /** Override the on-disk well-known path (test seam). Defaults to `WELL_KNOWN_PATH`. */
+  wellKnownPath?: string;
+  /**
+   * Reader for a module's `.parachute/module.json`. Production uses
+   * `readModuleManifest`; tests inject a stub. Mirrors hub-server's
+   * `readModuleManifest` seam so the disk regen and the per-request build
+   * stay in lockstep.
+   */
+  readModuleManifest?: (installDir: string) => Promise<ModuleManifest | null>;
+}
+
+/**
+ * Regenerate `/.well-known/parachute.json` on disk from current services.json.
+ *
+ * Mirrors the dynamic build inside `hub-server.ts`'s
+ * `/.well-known/parachute.json` handler so the on-disk doc tracks the same
+ * `uiUrl` / `displayName` / `managementUrl` shape the live discovery page
+ * fetches. Returns the path written + the resulting doc so callers can log
+ * and tests can assert without re-reading from disk.
+ *
+ * Used by `/api/modules/:short/{install,upgrade,uninstall}` post-mutation so
+ * the on-disk doc stays current after lifecycle ops. The per-request build
+ * in hub-server.ts remains the source of truth for live HTTP reads — this
+ * disk write is the inspection / debug artifact (and a belt-and-suspenders
+ * canary for anything that reads the file directly).
+ */
+export async function regenerateWellKnown(
+  opts: RegenerateWellKnownOpts,
+): Promise<{ path: string; doc: WellKnownDocument }> {
+  const read = opts.readModuleManifest ?? readModuleManifest;
+  const path = opts.wellKnownPath ?? WELL_KNOWN_PATH;
+  const services = readManifest(opts.manifestPath).services;
+  // Build the resolver maps the same way hub-server does — read each
+  // module's `.parachute/module.json` from `installDir` and harvest
+  // managementUrl (vault rows) + uiUrl + displayName (non-vault rows).
+  // Per-entry errors land in console.warn so one malformed manifest doesn't
+  // block the regen for everyone else.
+  const managementUrls = new Map<string, string>();
+  const uiUrls = new Map<string, string>();
+  const displayNames = new Map<string, string>();
+  await Promise.all(
+    services.map(async (s) => {
+      if (!s.installDir) return;
+      try {
+        const m = await read(s.installDir);
+        if (!m) return;
+        if (isVaultEntry(s)) {
+          if (m.managementUrl) managementUrls.set(s.name, m.managementUrl);
+        } else {
+          if (m.uiUrl) uiUrls.set(s.name, m.uiUrl);
+          if (m.displayName) displayNames.set(s.name, m.displayName);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`well-known regen: skipping module metadata for ${s.name}: ${msg}`);
+      }
+    }),
+  );
+  const doc = buildWellKnown({
+    services,
+    canonicalOrigin: opts.canonicalOrigin,
+    managementUrlFor: (entry) => managementUrls.get(entry.name),
+    uiUrlFor: (entry) => uiUrls.get(entry.name),
+    displayNameFor: (entry) => displayNames.get(entry.name),
+  });
+  writeWellKnownFile(doc, path);
+  return { path, doc };
+}