@openparachute/hub 0.5.13-rc.14 → 0.5.13-rc.21

package/src/service-spec.ts

@@ -78,16 +78,6 @@ export function isCanonicalPort(port: number): boolean {
   return port >= CANONICAL_PORT_MIN && port <= CANONICAL_PORT_MAX;
 }
 
-/**
- * Broad shape of a service. Matches the hub's card-kind taxonomy.
- *   "frontend"  a user-facing UI (notes). Safe to expose by default.
- *   "api"       a programmatic surface (vault, channel, scribe). Whether
- *               it's safe to expose depends on `hasAuth`.
- *   "tool"      like "api" but specifically MCP-shaped / agent-callable.
- *               Treated the same as "api" for exposure defaults.
- */
-export type ServiceKind = "api" | "tool" | "frontend";
-
 /**
  * Imperative behaviors that don't fit the static `module.json` schema.
  *
@@ -174,14 +164,6 @@ export interface ServiceSpec {
    * First service boot overwrites the seed with its own authoritative version.
    */
   readonly seedEntry?: () => ServiceEntry;
-  /**
-   * Optional as of hub#327 (Phase A's fold): the validator no longer
-   * inspects `kind`, so synthesized + third-party-manifest specs may
-   * carry `undefined` here. The single read site
-   * (`commands/upgrade.ts: target.spec?.kind === "frontend"`) handles
-   * the absent case via the `=== "frontend"` falsy-fallthrough.
-   */
-  readonly kind?: ServiceKind;
   readonly hasAuth?: boolean;
   readonly urlForEntry?: (entry: ServiceEntry) => string | undefined;
   readonly postInstallFooter?: () => readonly string[];
@@ -239,7 +221,6 @@ export function composeServiceSpec(opts: {
     package: packageName,
     manifestName: manifest.manifestName,
     seedEntry: () => seedEntryFromManifest(manifest),
-    kind: manifest.kind,
   };
   if (extras?.init !== undefined) (spec as { init?: readonly string[] }).init = extras.init;
   if (startCmd !== undefined) {
@@ -301,7 +282,6 @@ const NOTES_FALLBACK: FirstPartyFallback = {
     manifestName: "parachute-notes",
     displayName: "Notes",
     tagline: "Notes PWA — daemon deprecated 2026-05-22; install `app` for the current path.",
-    kind: "frontend",
     port: 1942,
     paths: ["/notes"],
     health: "/notes/health",
@@ -331,7 +311,6 @@ const CHANNEL_FALLBACK: FirstPartyFallback = {
     manifestName: "parachute-channel",
     displayName: "Channel",
     tagline: "Notification fan-out across modules.",
-    kind: "api",
     port: 1941,
     paths: ["/channel"],
     health: "/channel/health",
@@ -397,9 +376,6 @@ export interface KnownModule {
   /** Pre-install catalog surfaces use these. After install, services.json wins. */
   readonly displayName: string;
   readonly tagline: string;
-  /** Module kind — needed for `synthesizeManifest` since KNOWN_MODULES doesn't
-   *  carry an embedded manifest. All three current entries are api/tool. */
-  readonly kind: ModuleKind;
   /** Canonical mount paths — used to synthesize a minimal manifest when
    *  module.json is unreadable (legacy install paths, test fixtures). The
    *  module's own `module.json` overrides these once it's installed. */
@@ -412,12 +388,6 @@ export interface KnownModule {
   readonly extras?: FirstPartyExtras;
 }
 
-// Local import-time alias for ModuleKind so the public KnownModule type can
-// reference it without forcing every consumer to import from
-// module-manifest. The same `ModuleKind` type is exported from there for
-// callers that want it directly.
-type ModuleKind = ModuleManifest["kind"];
-
 export const KNOWN_MODULES: Record<string, KnownModule> = {
   vault: {
     short: "vault",
@@ -426,7 +396,6 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     canonicalPort: 1940,
     displayName: "Vault",
     tagline: "Your owner-authenticated MCP knowledge store.",
-    kind: "api",
     canonicalPaths: ["/vault/default"],
     canonicalHealth: "/vault/default/health",
     extras: {
@@ -446,7 +415,6 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     canonicalPort: 1943,
     displayName: "Scribe",
     tagline: "Local audio transcription for vault recordings.",
-    kind: "api",
     canonicalPaths: ["/scribe"],
     canonicalHealth: "/scribe/health",
     canonicalStripPrefix: true,
@@ -481,7 +449,6 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     displayName: "Runner",
     tagline:
       "Vault-as-job-substrate engine — spawns claude -p against vault job notes on schedule.",
-    kind: "tool",
     canonicalPaths: ["/runner", "/.parachute"],
     canonicalHealth: "/runner/healthz",
     canonicalStripPrefix: false,
@@ -507,10 +474,6 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
     // still exists as a back-compat install (CURATED_MODULES still lists
     // `notes`) but `app` is the recommended first install post-vault.
     tagline: "Host module for Parachute UIs — auto-installs Notes on first boot.",
-    // Frontend posture: app's primary surface is serving sub-app UIs under
-    // `/app/<name>/` mounted under one origin (design doc §12). Hub's
-    // exposure-default + supervisor-defaults follow the frontend lane.
-    kind: "frontend",
     canonicalPaths: ["/app", "/.parachute"],
     canonicalHealth: "/app/healthz",
     canonicalStripPrefix: false,
@@ -528,6 +491,35 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
   },
 };
 
+/**
+ * Modules that were once first-party (committed-core or FIRST_PARTY_FALLBACKS)
+ * but have since been retired. Services.json rows under these names are
+ * GC'd on load with a stderr warning.
+ *
+ * Adding a name here is a deliberate retirement signal — operators who
+ * still have the module's daemon running will see the warning + a hint
+ * to stop the daemon. The row reappears if they restart the daemon
+ * (which still self-registers under its old name), but the GC ensures
+ * routing isn't blocked by a stale row.
+ *
+ * Curation rules:
+ *   - Only add an entry when the module is *explicitly* retired (see
+ *     `parachute-patterns/migrations/` + per-module DEPRECATED.md). Don't
+ *     speculate on Phase-2-deprecating modules — they're still serving
+ *     back-compat traffic and adding them here would prematurely break
+ *     legacy operators. `notes` (the daemon) is the canonical
+ *     "deprecating-but-not-retired" case as of 2026-05-22: do not add
+ *     until its Phase 3 retirement lands.
+ *   - Entries stay forever. Removing an entry would let a stale row
+ *     reappear silently on legacy installs.
+ */
+export const RETIRED_MODULES: Record<string, { retiredAt: string; replacement?: string }> = {
+  agent: {
+    retiredAt: "2026-05-20",
+    replacement: "parachute-app or parachute-runner (depending on use case)",
+  },
+};
+
 /**
  * Synthesize a minimal `ModuleManifest` from a KNOWN_MODULES entry. Used as
  * a fallback when `<installDir>/.parachute/module.json` can't be read
@@ -547,7 +539,6 @@ export function synthesizeManifestForKnownModule(km: KnownModule): ModuleManifes
     manifestName: km.manifestName,
     displayName: km.displayName,
     tagline: km.tagline,
-    kind: km.kind,
     port: km.canonicalPort,
     paths: km.canonicalPaths,
     health: km.canonicalHealth,
@@ -560,10 +551,10 @@ export function synthesizeManifestForKnownModule(km: KnownModule): ModuleManifes
 
 /**
  * Effective publicExposure for a service, given what's on its services.json
- * entry. Explicit wins. If absent, derive from the spec: known api/tool
- * services without declared auth fall back to "auth-required"; everything
- * else defaults to "allowed" — so vault, notes, channel and unknown
- * third-party services continue to be exposed without needing to opt in.
+ * entry. Explicit wins. If absent, derive from the spec: services with
+ * declared auth (extras.hasAuth === true, or no hasAuth set) default to
+ * "allowed"; services with extras.hasAuth === false default to
+ * "auth-required". Unknown third-party services default to "allowed".
  *
  * Layer behavior (post-#187 layer-aware proxy):
  *   "allowed"        — reaches all layers (loopback / tailnet / public);
@@ -582,30 +573,17 @@ export function effectivePublicExposure(
   if (entry.publicExposure !== undefined) return entry.publicExposure;
   const short = shortNameForManifest(entry.name);
   if (short === undefined) return "allowed";
-  // FALLBACK path: notes / channel still vendor their kind + extras.
+  // Post hub#301 Phase C/D (`kind` field retired — hub#330), the
+  // exposure-default heuristic collapses to the imperative `extras.hasAuth`
+  // signal: an explicit `hasAuth: false` declaration ("no auth gate
+  // implemented yet") → require auth before exposing; anything else →
+  // allowed. Scribe is the canonical `hasAuth: false` case today.
   const fb = FIRST_PARTY_FALLBACKS[short];
   if (fb) {
-    if (
-      (fb.manifest.kind === "api" || fb.manifest.kind === "tool") &&
-      fb.extras?.hasAuth === false
-    ) {
-      return "auth-required";
-    }
-    return "allowed";
+    return fb.extras?.hasAuth === false ? "auth-required" : "allowed";
   }
-  // KNOWN_MODULES path: vault / scribe / runner. The `kind` lives on
-  // services.json (operator-authoritative after self-register) — if the row
-  // doesn't declare it, fall through to the imperative `extras.hasAuth`
-  // signal which says "no auth gate → require auth before exposing." This
-  // matches the pre-retirement FALLBACK behavior for scribe.
   const km = KNOWN_MODULES[short];
-  if (km && km.extras?.hasAuth === false) {
-    // Only api/tool services hit the "auth-required default" lane —
-    // services.json's `kind` is the authoritative source; absent it,
-    // KNOWN_MODULES doesn't carry `kind` so we assume an api/tool posture
-    // (the three KNOWN_MODULES entries are all api/tool today).
-    return "auth-required";
-  }
+  if (km && km.extras?.hasAuth === false) return "auth-required";
   return "allowed";
 }
 
@@ -650,7 +628,7 @@ export function canonicalPortForManifest(manifestName: string): number | undefin
  *
  * KNOWN_MODULES shorts (vault / scribe / runner — post hub#310 FALLBACK
  * retirement) return a **minimal** spec carrying `package`, `manifestName`,
- * `kind` (best-effort api/tool), and the imperative `extras` fields
+ * and the imperative `extras` fields
  * (`init`, `hasAuth`, `urlForEntry`, `postInstallFooter`). They do NOT carry
  * `startCmd` or `seedEntry` — those come from `<installDir>/.parachute/module.json`
  * at lifecycle time via {@link getSpecFromInstallDir}, since the module
@@ -670,14 +648,13 @@ export function getSpec(short: string): ServiceSpec | undefined {
   const km = KNOWN_MODULES[short];
   if (!km) return undefined;
   // Use the synthesized manifest from KNOWN_MODULES' canonical fields so
-  // downstream consumers (seedEntry, kind-aware exposure, port assignment)
-  // see a coherent spec. Module.json wins at lifecycle time
-  // (`composeKnownModuleSpec`); this synth is the bootstrap shape.
+  // downstream consumers (seedEntry, port assignment) see a coherent spec.
+  // Module.json wins at lifecycle time (`composeKnownModuleSpec`); this
+  // synth is the bootstrap shape.
   const synthManifest = synthesizeManifestForKnownModule(km);
   const spec: ServiceSpec = {
     package: km.package,
     manifestName: km.manifestName,
-    kind: synthManifest.kind,
     seedEntry: () => seedEntryFromManifest(synthManifest),
   };
   if (km.extras?.hasAuth !== undefined) {

package/src/services-manifest.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
+import { RETIRED_MODULES } from "./service-spec.ts";
 
 /**
  * Whether the service is safe to mount on public-facing expose layers.
@@ -17,7 +18,7 @@ import { SERVICES_MANIFEST_PATH } from "./config.ts";
  *                   auth state over `/.parachute/info`.
  *
  * Absent field: the CLI derives a safe default from the service's ServiceSpec
- * (known api/tool services without declared auth → "auth-required"; everything
+ * (services with extras.hasAuth === false → "auth-required"; everything
  * else → "allowed"). Unknown services default to "allowed" for back-compat.
  */
 export type PublicExposure = "allowed" | "loopback" | "auth-required";
@@ -376,12 +377,171 @@ export function readManifest(path: string = SERVICES_MANIFEST_PATH): ServicesMan
       `failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
-  const validated = validateManifest(raw, path);
+  // Retired-module + legacy short-name row cleanup runs BEFORE shape
+  // validation because the bugs they heal (rows that conflict on port with
+  // a current row) would otherwise throw inside `validateManifest`'s
+  // duplicate-port gate. Order matters: drop retired-module rows FIRST so
+  // their absence can unmask a `parachute-<X>` ↔ `<X>` pair underneath that
+  // `dropLegacyShortNameRows` then handles. The reverse order would leave
+  // a retired row that the short-name pass doesn't recognize. Both passes
+  // mutate the raw JSON object's `services` array; we re-validate against
+  // the cleaned shape. See `dropRetiredModuleRows` + `dropLegacyShortNameRows`
+  // for the full discipline.
+  const afterRetired = dropRetiredModuleRows(raw, path);
+  const cleaned = dropLegacyShortNameRows(afterRetired.raw, path);
+  const validated = validateManifest(cleaned.raw, path);
   const migrated = migrateClawToAgent(validated);
-  if (migrated.changed) writeManifest(migrated.manifest, path);
+  const changed = afterRetired.changed || cleaned.changed || migrated.changed;
+  if (changed) writeManifest(migrated.manifest, path);
   return migrated.manifest;
 }
 
+/**
+ * Drop rows whose `name` matches a registered retired module (see
+ * `RETIRED_MODULES` in `service-spec.ts`). Retirement is unconditional —
+ * unlike `dropLegacyShortNameRows`, which only fires when a same-port
+ * manifestName twin is present, this pass drops a retired row whether or
+ * not anything else collides with it. The row is stale by definition: the
+ * module's npm package and daemon are no longer first-party, and leaving
+ * the row in place either (a) routes operators to a no-longer-supported
+ * binary or (b) blocks a current module from claiming the port the retired
+ * row squats on (Aaron's 2026-05-22 reproducer: stale `agent` row at 1946
+ * collided with `parachute-app` self-registering at 1946).
+ *
+ * Per-row stderr warning is operator-actionable: cites the retirement date,
+ * names the replacement module (if any), and includes a one-line shell
+ * snippet for stopping the still-running daemon process. The row reappears
+ * on the next read if the daemon is still up (its self-register writes
+ * back the same name), so the warning steers operators to fully retire
+ * the legacy process, not just hand-edit the file.
+ *
+ * Operates on raw JSON rather than validated entries so a retired row that
+ * shares a port with a current row doesn't trip `validateManifest`'s
+ * duplicate-port gate before this helper runs. Closes hub#334.
+ */
+function dropRetiredModuleRows(raw: unknown, where: string): { raw: unknown; changed: boolean } {
+  if (!raw || typeof raw !== "object") return { raw, changed: false };
+  const services = (raw as Record<string, unknown>).services;
+  if (!Array.isArray(services)) return { raw, changed: false };
+
+  type Dropped = { name: string; retiredAt: string; replacement?: string };
+  const dropped: Dropped[] = [];
+  const nextServices = services.filter((row) => {
+    if (!row || typeof row !== "object") return true;
+    const name = (row as Record<string, unknown>).name;
+    if (typeof name !== "string") return true;
+    const retired = RETIRED_MODULES[name];
+    if (retired === undefined) return true;
+    dropped.push({ name, retiredAt: retired.retiredAt, replacement: retired.replacement });
+    return false;
+  });
+
+  if (dropped.length === 0) return { raw, changed: false };
+
+  for (const d of dropped) {
+    const replacementLine = d.replacement ? ` Replacement: ${d.replacement}.` : "";
+    console.error(
+      `${where}: dropped stale row for retired module '${d.name}' (retired ${d.retiredAt}).${replacementLine} If the ${d.name} daemon is still running, stop it (e.g. \`ps aux | grep ${d.name}\` then \`kill <pid>\`).`,
+    );
+  }
+
+  return {
+    raw: { ...(raw as Record<string, unknown>), services: nextServices },
+    changed: true,
+  };
+}
+
+/**
+ * Drop legacy short-name rows when a same-module manifestName row exists
+ * on the same port. Handles the duplicate-row class introduced when a
+ * module's self-register wrote `name: "<short>"` (e.g. `"app"`) while
+ * hub's install path stamped `name: "parachute-<short>"` (the canonical
+ * manifestName key). The two rows shared a port and tripped the
+ * duplicate-port read gate, leaving operators with an unbootable
+ * services.json until they edited by hand. Aaron hit this on 2026-05-22
+ * with `parachute-app` + `app` after parachute-app#13 + parachute-runner#4
+ * had already fixed the upstream self-register writes; this gate cleans
+ * up legacy state on operators who had already booted the bad code path.
+ *
+ * Detection is structural — no module registry import needed:
+ *   - two rows share a port (NOT the multi-vault carve-out)
+ *   - one row's name matches `parachute-<X>`
+ *   - the other row's name matches `<X>` (same `<X>`)
+ *
+ * When that shape is present, drop the short-named row + log a warning
+ * to stderr so operators see the auto-cleanup the next time they read
+ * services.json (via any CLI command that touches the file). The
+ * manifestName row wins — it carries the hub-stamped fields (installDir,
+ * version after self-register's first overwrite) operators care about.
+ *
+ * Returns the (possibly mutated) raw object + a `changed` flag so the
+ * caller can re-write services.json with the cleaned shape. Operates on
+ * raw JSON rather than validated entries because the duplicate-port row
+ * pair would otherwise throw during validation before this helper had a
+ * chance to run.
+ */
+function dropLegacyShortNameRows(raw: unknown, where: string): { raw: unknown; changed: boolean } {
+  if (!raw || typeof raw !== "object") return { raw, changed: false };
+  const services = (raw as Record<string, unknown>).services;
+  if (!Array.isArray(services)) return { raw, changed: false };
+
+  // Build a port → [rows] index to spot same-port pairs. We only care
+  // about rows that parse to the minimal `{ name, port }` shape — anything
+  // else fails downstream validation anyway and isn't part of the bug
+  // class.
+  type Probe = { name: string; port: number; index: number };
+  const byPort = new Map<number, Probe[]>();
+  services.forEach((row, index) => {
+    if (!row || typeof row !== "object") return;
+    const name = (row as Record<string, unknown>).name;
+    const port = (row as Record<string, unknown>).port;
+    if (typeof name !== "string" || typeof port !== "number") return;
+    const bucket = byPort.get(port) ?? [];
+    bucket.push({ name, port, index });
+    byPort.set(port, bucket);
+  });
+
+  const dropIndices = new Set<number>();
+  for (const bucket of byPort.values()) {
+    if (bucket.length < 2) continue;
+    for (const a of bucket) {
+      for (const b of bucket) {
+        if (a.index === b.index) continue;
+        // a is the "short" candidate, b is the "manifestName" candidate.
+        // The shape rule: b.name === `parachute-${a.name}` and a is not
+        // itself a `parachute-…` name. Both halves matter: without the
+        // second check, `parachute-vault` paired with `parachute-parachute-vault`
+        // would drop the real vault row (no such pair exists today, but
+        // the shape rule keeps the heuristic narrow on principle).
+        if (a.name.startsWith("parachute-")) continue;
+        if (b.name !== `parachute-${a.name}`) continue;
+        dropIndices.add(a.index);
+      }
+    }
+  }
+
+  if (dropIndices.size === 0) return { raw, changed: false };
+
+  const dropped: string[] = [];
+  const nextServices = services.filter((row, index) => {
+    if (!dropIndices.has(index)) return true;
+    if (row && typeof row === "object") {
+      const name = (row as Record<string, unknown>).name;
+      if (typeof name === "string") dropped.push(name);
+    }
+    return false;
+  });
+
+  console.error(
+    `${where}: dropped legacy short-name row(s) [${dropped.join(", ")}] in favor of same-port manifestName row(s). This is the parachute-app#13 / parachute-runner#4 self-register fixup. See parachute-patterns/patterns/services-json-row-conventions.md.`,
+  );
+
+  return {
+    raw: { ...(raw as Record<string, unknown>), services: nextServices },
+    changed: true,
+  };
+}
+
 /**
  * Migrate legacy `claw` entries to `agent` in-place. Paraclaw was renamed
  * to parachute-agent across the ecosystem (npm package, mount path, short