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

package/package.json

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

package/src/__tests__/module-manifest.test.ts

@@ -35,7 +35,8 @@ describe("validateModuleManifest", () => {
 
   test("rejects missing required fields", () => {
     expect(() => validateModuleManifest({ ...VALID, name: undefined }, "x")).toThrow(/name/);
-    expect(() => validateModuleManifest({ ...VALID, kind: "weird" }, "x")).toThrow(/kind/);
+    // `kind` is NOT validated as of hub#327 — see the "kind is no longer
+    // validated" suite below for the full behavior surface.
     expect(() => validateModuleManifest({ ...VALID, port: -1 }, "x")).toThrow(/port/);
     expect(() => validateModuleManifest({ ...VALID, port: 99999 }, "x")).toThrow(/port/);
     expect(() => validateModuleManifest({ ...VALID, paths: "not-array" }, "x")).toThrow(/paths/);
@@ -44,6 +45,61 @@ describe("validateModuleManifest", () => {
     );
   });
 
+  // hub#327 (hub#301 Phase A fold): the validator no longer inspects `kind`.
+  // Any value — present, absent, valid string, typo, wrong type — is
+  // accepted. The single downstream read site
+  // (`commands/upgrade.ts: target.spec?.kind === "frontend"`) handles the
+  // absent / non-"frontend" case via falsy-fallthrough into the
+  // backend-proxy default.
+  describe("kind is no longer validated (hub#327)", () => {
+    test("missing kind is accepted and produces an undefined kind", () => {
+      const { kind: _ignored, ...withoutKind } = VALID;
+      const m = validateModuleManifest(withoutKind, "x");
+      expect(m.kind).toBeUndefined();
+    });
+
+    test("explicit kind: 'frontend' passes through unchanged", () => {
+      const m = validateModuleManifest({ ...VALID, kind: "frontend" }, "x");
+      expect(m.kind).toBe("frontend");
+    });
+
+    test("explicit kind: 'api' passes through unchanged", () => {
+      const m = validateModuleManifest({ ...VALID, kind: "api" }, "x");
+      expect(m.kind).toBe("api");
+    });
+
+    test("explicit kind: 'tool' passes through unchanged", () => {
+      const m = validateModuleManifest({ ...VALID, kind: "tool" }, "x");
+      expect(m.kind).toBe("tool");
+    });
+
+    test("invalid kind values are also accepted (validator no longer inspects)", () => {
+      // Per Aaron's direction on #327: stop validating kind. Typos,
+      // novel strings, wrong types — none of them error. The validator
+      // simply doesn't look at the field. Downstream routing branches on
+      // `kind === "frontend"` and falls through gracefully for anything
+      // else (including these), so accepting them is safe.
+      const m1 = validateModuleManifest({ ...VALID, kind: "static" }, "x");
+      expect(m1.kind).toBeUndefined();
+      const m2 = validateModuleManifest({ ...VALID, kind: "backend" }, "x");
+      expect(m2.kind).toBeUndefined();
+      const m3 = validateModuleManifest({ ...VALID, kind: null }, "x");
+      expect(m3.kind).toBeUndefined();
+      const m4 = validateModuleManifest({ ...VALID, kind: 42 }, "x");
+      expect(m4.kind).toBeUndefined();
+    });
+
+    test("routing-relevant kind: 'frontend' still survives the validator (upgrade.ts branch intact)", () => {
+      // Defensive sanity check: the one downstream branch that reads kind
+      // (commands/upgrade.ts checks `target.spec?.kind === "frontend"` to
+      // decide whether to run `bun run build`) keeps working — when a
+      // module DOES declare `kind: "frontend"`, the value reaches that
+      // branch untouched.
+      const m = validateModuleManifest({ ...VALID, kind: "frontend" }, "x");
+      expect(m.kind === "frontend").toBe(true);
+    });
+  });
+
   test("rejects invalid name shape", () => {
     expect(() => validateModuleManifest({ ...VALID, name: "Demo" }, "x")).toThrow(/name/);
     expect(() => validateModuleManifest({ ...VALID, name: "1demo" }, "x")).toThrow(/name/);

package/src/module-manifest.ts

@@ -76,8 +76,17 @@ export interface ModuleManifest {
   readonly displayName?: string;
   /** One-line subtitle rendered under displayName. */
   readonly tagline?: string;
-  /** Drives card vs. iframe vs. launcher in the hub. */
-  readonly kind: ModuleKind;
+  /**
+   * Historically drove card vs. iframe vs. launcher in the hub. As of
+   * hub#301 Phase A's fold (#327) the validator no longer inspects `kind` —
+   * any value, or no value at all, is accepted and passes through untouched.
+   * Routing branches downstream use `=== "frontend"` style checks which
+   * treat undefined/other values as the backend-proxy default (so the
+   * routing remains correct without validator enforcement). New modules
+   * may safely omit the field; existing values are preserved for the
+   * narrow `kind === "frontend"` branch in `commands/upgrade.ts`.
+   */
+  readonly kind?: ModuleKind;
   /** Default loopback port. CLI warns on conflict, doesn't block. */
   readonly port: number;
   /** URL paths the module serves under the hub origin. */
@@ -167,11 +176,19 @@ function asOptionalString(v: unknown, where: string, field: string): string | un
   return v;
 }
 
-function asKind(v: unknown, where: string): ModuleKind {
-  if (v !== "api" && v !== "frontend" && v !== "tool") {
-    throw new ModuleManifestError(`${where}: "kind" must be "api" | "frontend" | "tool"`);
-  }
-  return v;
+/**
+ * Pass-through `kind` reader (hub#301 Phase A fold — #327).
+ *
+ * The validator no longer inspects `kind`. Any value, or no value, is
+ * accepted. We narrow to the canonical `ModuleKind` only when the input is
+ * one of the three known strings — otherwise we drop the field entirely so
+ * downstream `kind === "frontend"` branches fall through to the
+ * backend-proxy default. Author intent (typo, novel value, omission) is no
+ * longer surfaced from this layer; it's not the validator's job anymore.
+ */
+function asKind(v: unknown): ModuleKind | undefined {
+  if (v === "api" || v === "frontend" || v === "tool") return v;
+  return undefined;
 }
 
 function asPort(v: unknown, where: string): number {
@@ -341,9 +358,20 @@ function asDependencies(v: unknown, where: string): Record<string, ModuleDepende
 /**
  * Strict validator. Throws `ModuleManifestError` with the source path so
  * malformed third-party modules get a clear-enough error to fix. Required
- * fields are name, manifestName, kind, port, paths, health.
+ * fields are name, manifestName, port, paths, health. `kind` is no longer
+ * inspected as of hub#301 Phase A's fold (#327) — any value (or none) is
+ * accepted and passes through untouched. See `asKind` for the narrowing
+ * behavior.
+ *
+ * The optional `logger` parameter is retained for forward-compatibility
+ * with future validator soft-warnings, even though the kind soft-warning
+ * it was originally added for has been removed.
  */
-export function validateModuleManifest(raw: unknown, where: string): ModuleManifest {
+export function validateModuleManifest(
+  raw: unknown,
+  where: string,
+  _logger: Pick<Console, "warn"> = console,
+): ModuleManifest {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
     throw new ModuleManifestError(`${where}: root must be an object`);
   }
@@ -356,7 +384,7 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
     );
   }
   const manifestName = asString(m.manifestName, where, "manifestName");
-  const kind = asKind(m.kind, where);
+  const kind = asKind(m.kind);
   const port = asPort(m.port, where);
   const paths = asStringArray(m.paths, where, "paths");
   const health = asHealthPath(m.health, where);
@@ -404,7 +432,8 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
     stripPrefix = m.stripPrefix;
   }
 
-  const out: ModuleManifest = { name, manifestName, kind, port, paths, health };
+  const out: ModuleManifest = { name, manifestName, port, paths, health };
+  if (kind !== undefined) (out as { kind?: ModuleKind }).kind = kind;
   if (displayName !== undefined) (out as { displayName?: string }).displayName = displayName;
   if (tagline !== undefined) (out as { tagline?: string }).tagline = tagline;
   if (startCmd !== undefined) (out as { startCmd?: readonly string[] }).startCmd = startCmd;
@@ -470,8 +499,14 @@ function asPathOrUrl(v: unknown, where: string, field: string): string | undefin
  * absent (caller decides whether that's an error — first-party modules fall
  * back to the vendored manifest; third-party hard-errors). Throws
  * `ModuleManifestError` on parse / validation failure.
+ *
+ * The optional `logger` parameter is retained for forward-compatibility
+ * with future validator soft-warnings. Defaults to `console`.
  */
-export async function readModuleManifest(packageDir: string): Promise<ModuleManifest | null> {
+export async function readModuleManifest(
+  packageDir: string,
+  logger: Pick<Console, "warn"> = console,
+): Promise<ModuleManifest | null> {
   const path = join(packageDir, ".parachute", "module.json");
   let buf: string;
   try {
@@ -488,5 +523,5 @@ export async function readModuleManifest(packageDir: string): Promise<ModuleMani
       `${path}: failed to parse JSON: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
-  return validateModuleManifest(parsed, path);
+  return validateModuleManifest(parsed, path, logger);
 }

package/src/service-spec.ts

@@ -174,7 +174,14 @@ export interface ServiceSpec {
    * First service boot overwrites the seed with its own authoritative version.
    */
   readonly seedEntry?: () => ServiceEntry;
-  readonly kind: ServiceKind;
+  /**
+   * 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[];