@wairon/cli 5.1.1-dev.68 → 5.1.1-dev.69

package/dist/index.js

@@ -3458,6 +3458,7 @@ __export(src_exports, {
   PatternRefSchema: () => PatternRefSchema,
   PortalAuthSchema: () => PortalAuthSchema,
   PortalAuthSchemeSchema: () => PortalAuthSchemeSchema,
+  PortalMountSchema: () => PortalMountSchema,
   PortalTypeSchema: () => PortalTypeSchema,
   ProfileSelectionSubjectSchema: () => ProfileSelectionSubjectSchema,
   ProjectConfigSchema: () => ProjectConfigSchema,
@@ -5369,6 +5370,24 @@ var PortalAuthSchema = import_zod8.z.object({
   description: import_zod8.z.string().optional(),
   example: import_zod8.z.string().optional()
 });
+var PortalMountSchema = import_zod8.z.object({
+  /** The mounted Portal's component id. */
+  portal: import_zod8.z.string(),
+  /**
+   * The path prefixes this listener routes to the portal. A path lies under a
+   * prefix when it EQUALS it or continues it past a slash — so `/` covers the
+   * root itself and nothing else, which is what lets an app shell sit at `GET /`
+   * without swallowing every other route.
+   */
+  prefixes: import_zod8.z.array(import_zod8.z.string()),
+  /**
+   * The router entry the listener calls to hand the portal its request,
+   * exported by the PORTAL's own file (so export-conformance holds that file to
+   * it). Absent when the listener calls the portal's contract methods directly,
+   * route by route — then there is no entry to name.
+   */
+  via: import_zod8.z.string().optional()
+});
 var ComponentSpecSchema = import_zod8.z.object({
   id: SpecIdSchema,
   name: import_zod8.z.string(),
@@ -5388,6 +5407,13 @@ var ComponentSpecSchema = import_zod8.z.object({
   auth: PortalAuthSchema.optional(),
   /** Portal-only: capability → component.method dispatch table (see DispatchBindingSchema). */
   dispatch: import_zod8.z.array(DispatchBindingSchema).optional(),
+  /**
+   * Portal-only: the portals this LISTENER serves (see PortalMountSchema).
+   * Declaring the field — even as an empty array — is what marks a portal as a
+   * listener: the one kind of portal the host starts directly, so nothing else
+   * needs to mount it. Absent means "a portal something else must serve".
+   */
+  mounts: import_zod8.z.array(PortalMountSchema).optional(),
   /** Store-only: whether held state survives restart (see DurabilitySchema). */
   durability: DurabilitySchema.optional(),
   /** Orchestrator-only: what the logic may depend on; unset means a workflow (see DependencyClassSchema). */
@@ -11567,7 +11593,7 @@ function defaultTargetConfig(type) {
     enabled: true
   };
 }
-var WAIRON_VERSION = "5.1.1-dev.68";
+var WAIRON_VERSION = "5.1.1-dev.69";
 var GITHUB_REPO = "SYW-Apps/Waffle-AIron";
 var ARCHITECT_AGENT_ID = "agent-architect";
 var ARCHITECT_TEMPLATE_ID = "architect";
@@ -15331,6 +15357,84 @@ var lifecycleRule = {
   }
 };
 
+// src/core/rules/wiring/portal-mounts.ts
+function liesUnder(path28, prefix) {
+  return path28 === prefix || path28.startsWith(prefix + "/");
+}
+var portalMountsRule = {
+  name: "portal-mounts",
+  description: "Which listener serves which portal: a portal's routes are its methods' endpoint bindings, but nothing said which listener hands it its requests, so a portal no listener serves was unreachable without anyone noticing, and the call that mounts one crossed a boundary no contract described. A listener Portal declares its mounts \u2014 each a portal, the path prefixes routed to it, and optionally the router entry it calls \u2014 and this rule checks them against the tree: a mount must name a Portal, every HTTP endpoint of a mounted portal must lie under one of its prefixes, and every portal with HTTP endpoints must be mounted by some listener unless it is one. A path lies under a prefix when it equals it or continues it past a slash, so `/` covers only the root. Whether the named entry is really exported is the code's question, and export-conformance asks it.",
+  codes: [
+    {
+      code: "MOUNT_TARGET_NOT_PORTAL",
+      defaultSeverity: "error",
+      summary: "A listener mounts something that is not a Portal \u2014 an unknown component, or one whose type cannot serve routes"
+    },
+    {
+      code: "ENDPOINT_OUTSIDE_MOUNT",
+      defaultSeverity: "warning",
+      summary: "A mounted portal declares an HTTP endpoint under none of the prefixes its listener routes to it \u2014 a route the contract promises that no request can reach"
+    },
+    {
+      code: "UNMOUNTED_PORTAL",
+      defaultSeverity: "warning",
+      summary: "A portal declares HTTP endpoints but no listener mounts it and it declares no mounts of its own \u2014 a whole surface nothing serves"
+    }
+  ],
+  check(ctx) {
+    const httpRoutesOf = (compId) => {
+      const routes = [];
+      for (const method of ctx.interfaceMethodsOf(compId)) {
+        const ep = method.endpoint;
+        if (ep?.transport === "HTTP") routes.push({ method: method.name, verb: ep.method, path: ep.path });
+      }
+      return routes;
+    };
+    const mounted = /* @__PURE__ */ new Set();
+    for (const listener of ctx.components) {
+      if (listener.componentType !== "Portal" || !listener.mounts) continue;
+      const listenerDraft = ctx.isComponentDraft(listener.id);
+      for (const mount of listener.mounts) {
+        const target = ctx.componentMap.get(mount.portal);
+        if (!target || target.componentType !== "Portal") {
+          ctx.addIssue(
+            "error",
+            "MOUNT_TARGET_NOT_PORTAL",
+            target ? `Listener "${listener.id}" mounts "${mount.portal}" under ${mount.prefixes.map((p) => `"${p}"`).join(", ") || "no prefixes"}, but "${target.id}" is a ${target.componentType} \u2014 only a Portal serves routes, so this mount routes requests to nothing.` : `Listener "${listener.id}" mounts "${mount.portal}" under ${mount.prefixes.map((p) => `"${p}"`).join(", ") || "no prefixes"}, but no component "${mount.portal}" exists \u2014 this mount routes requests to nothing.`,
+            listener.id,
+            listenerDraft || (target ? ctx.isComponentDraft(target.id) : false)
+          );
+          continue;
+        }
+        mounted.add(target.id);
+        for (const route of httpRoutesOf(target.id)) {
+          if (mount.prefixes.some((prefix) => liesUnder(route.path, prefix))) continue;
+          ctx.addIssue(
+            "warning",
+            "ENDPOINT_OUTSIDE_MOUNT",
+            `Portal "${target.id}" binds "${route.method}" to ${route.verb} ${route.path}, but listener "${listener.id}" routes it only ${mount.prefixes.map((p) => `"${p}"`).join(", ") || "no prefixes at all"} \u2014 a route the contract promises that no request through this listener can reach. A path lies under a prefix when it equals it or continues it past a slash. Add the prefix to the mount, or move the endpoint under one it already routes.`,
+            listener.id,
+            listenerDraft || ctx.isComponentDraft(target.id)
+          );
+        }
+      }
+    }
+    for (const portal of ctx.components) {
+      if (portal.componentType !== "Portal") continue;
+      if (portal.mounts !== void 0 || mounted.has(portal.id)) continue;
+      const routes = httpRoutesOf(portal.id);
+      if (routes.length === 0) continue;
+      ctx.addIssue(
+        "warning",
+        "UNMOUNTED_PORTAL",
+        `Portal "${portal.id}" declares ${routes.length} HTTP endpoint(s), but no listener mounts it and it declares no mounts of its own \u2014 a whole surface nothing serves. Mount it on the listener that routes its requests, or, if it IS a listener the host starts directly, declare its mounts (an empty list says it serves only its own routes).`,
+        portal.id,
+        ctx.isComponentDraft(portal.id)
+      );
+    }
+  }
+};
+
 // src/core/rules/narrative-graph-projector.ts
 var methodKey = (compId, methodName) => `${compId}#${methodName}`;
 function stepEdges(step, ctx, followRegisterEdges) {
@@ -17109,7 +17213,7 @@ var unclaimedSourceRule = {
 var NOTHING_PROMISED = /* @__PURE__ */ new Set();
 var exportConformanceRule = {
   name: "export-conformance",
-  description: "Code-to-contract for the SURFACE: does this file publish anything the components it realizes never promised, that another component then takes? The rest of the conformance set reads contract-to-code \u2014 it asks whether the code holds what a spec claims \u2014 so a file could export whatever it liked under a component's name and nothing looked. That is one half of the same hole as a contract promising a parameter it never passes. A method's `exportedVia` names the export a consumer imports to REACH it \u2014 the value that composes it, which `symbol` cannot name because `symbol` names the function inside \u2014 and a declared handle the file does not actually export is itself a finding, so naming one can never become a free-text suppression. Both questions are asked only of a file read at exact grade, and a taker counts only when its own import specifier resolves to the file it is accused of taking from: below that nothing separates an export from a mention, or a shared word from a shared module.",
+  description: "Code-to-contract for the SURFACE: does this file publish anything the components it realizes never promised, that another component then takes? The rest of the conformance set reads contract-to-code \u2014 it asks whether the code holds what a spec claims \u2014 so a file could export whatever it liked under a component's name and nothing looked. That is one half of the same hole as a contract promising a parameter it never passes. A method's `exportedVia` names the export a consumer imports to REACH it \u2014 the value that composes it, which `symbol` cannot name because `symbol` names the function inside \u2014 and a listener's mount names the router entry it calls to hand a portal its requests; both are declared publication, and a declared handle the file does not actually export is itself a finding, so naming one can never become a free-text suppression. Both questions are asked only of a file read at exact grade, and a taker counts only when its own import specifier resolves to the file it is accused of taking from: below that nothing separates an export from a mention, or a shared word from a shared module.",
   codes: [
     {
       code: "UNDECLARED_EXPORT",
@@ -17122,7 +17226,7 @@ var exportConformanceRule = {
     {
       code: "UNREALIZED_EXPORT_HANDLE",
       defaultSeverity: "warning",
-      summary: "An implementation method declares an `exportedVia` handle its own source file does not export \u2014 the spec names a published route to the method that nobody can import"
+      summary: "A declared publication handle \u2014 a method's `exportedVia`, or the router entry a listener mounts a portal through \u2014 names an export its own source file does not have: the spec names a route to the code that nobody can import"
       // Deliberately NOT carryable, and so it hands over no `parts`: a wrong
       // handle is one string to correct, and a parking space for it could
       // only ever be a parking space for a lie.
@@ -17168,6 +17272,30 @@ var exportConformanceRule = {
         draftContext
       );
     }
+    for (const listener of ctx.components) {
+      if (listener.componentType !== "Portal") continue;
+      for (const mount of listener.mounts ?? []) {
+        const handle = mount.via;
+        if (!handle) continue;
+        const portal = ctx.componentMap.get(mount.portal);
+        if (!portal) continue;
+        const files = realization.filesOf(portal.id).map(pathKey);
+        const exact = files.filter((file) => {
+          const facts = code.factsAt(file);
+          return !!facts && facts.status === "analyzed" && facts.analysisGrade === "exact";
+        });
+        const exporters = exact.filter((file) => code.factsAt(file).exportedNames.includes(handle));
+        for (const file of exporters) promise(file, handle);
+        if (exporters.length > 0 || exact.length === 0 || exact.length < files.length) continue;
+        ctx.addIssue(
+          "warning",
+          "UNREALIZED_EXPORT_HANDLE",
+          `Listener "${listener.id}" mounts portal "${portal.id}" through "${handle}", but ${files.map((f) => `"${f}"`).join(", ")} \u2014 the file(s) realizing "${portal.id}" \u2014 export no such name. A mount's \`via\` names the router entry the listener calls to hand the portal its requests, published by the portal's own files, so one they do not publish promises a route nobody can import. It allows nothing either: every export of those files is still read against the contracts. Name the entry the portal's file actually exports, export it, or drop \`via\` if the listener calls the portal's contract methods directly.`,
+          listener.id,
+          ctx.isComponentDraft(listener.id) || ctx.isComponentDraft(portal.id)
+        );
+      }
+    }
     for (const type of ctx.types) {
       if (!type.sourcePath) continue;
       promise(type.sourcePath, type.symbol ?? type.name);
@@ -18486,6 +18614,9 @@ var SDD_RULES = [
   dispatchTableBindingsRule,
   dispatchStepRoutingRule,
   lifecycleRule,
+  // Which listener serves which portal: another declared edge into a
+  // component, so its validity reads beside dispatch and lifecycle.
+  portalMountsRule,
   // The declared entrypoint's own prose before the walk that its declaration
   // silences, then the walk, then the types no walk can reach.
   invokedByDescriptionRule,
@@ -21126,6 +21257,10 @@ function stripNamespaceFromComponent(spec, prefix) {
     dispatch: spec.dispatch?.map((b) => ({
       ...b,
       component: relativizeId(b.component, prefix)
+    })),
+    mounts: spec.mounts?.map((m) => ({
+      ...m,
+      portal: relativizeId(m.portal, prefix)
     }))
   };
 }
@@ -21276,6 +21411,7 @@ function rewriteSpecRefs(raw, remap) {
     rewriteEach(raw.dependsOn, "component");
     rewriteEach(raw.owns, "component");
     for (const binding of entries(raw.dispatch)) rewritePair(binding, "component", "method");
+    for (const mount of entries(raw.mounts)) rewrite(mount, "portal", "component");
   } else if (kind === "subsystem") {
     for (const entrypoint of entries(raw.lifecycle)) rewritePair(entrypoint, "component", "method");
     rewritePublished(raw.publicInterfaces);
@@ -21330,6 +21466,9 @@ function identityKeyOf(field, item) {
   switch (field) {
     case "dispatch":
       return str(o.capability);
+    // A listener mounts each portal once, so the portal IS the mount's identity.
+    case "mounts":
+      return str(o.portal);
     case "lifecycle":
       return `${String(o.phase)} ${String(o.component)} ${String(o.method)}`;
     case "emits":
@@ -21720,6 +21859,12 @@ var SpecWorkspace = class {
         dispatch: comp.dispatch?.map((b) => ({
           ...b,
           component: qualifyId(b.component, namespacePrefix, this.rootSubsystems)
+        })),
+        // A listener's mount names a portal id, qualified like any other
+        // component reference so a chained listener still finds its portals.
+        mounts: comp.mounts?.map((m) => ({
+          ...m,
+          portal: qualifyId(m.portal, namespacePrefix, this.rootSubsystems)
         }))
       }));
       index.interfaces = index.interfaces.map((intf) => ({
@@ -23264,6 +23409,9 @@ var SpecWorkspace = class {
           if (Array.isArray(out.dispatch)) {
             out.dispatch = out.dispatch.map((b) => typeof b?.component === "string" ? { ...b, component: q(b.component) } : b);
           }
+          if (Array.isArray(out.mounts)) {
+            out.mounts = out.mounts.map((m) => typeof m?.portal === "string" ? { ...m, portal: q(m.portal) } : m);
+          }
           break;
         case "interface":
           if (typeof out.component === "string") out.component = q(out.component);
@@ -26644,6 +26792,7 @@ function loadProjectConfig4() {
   PatternRefSchema,
   PortalAuthSchema,
   PortalAuthSchemeSchema,
+  PortalMountSchema,
   PortalTypeSchema,
   ProfileSelectionSubjectSchema,
   ProjectConfigSchema,