@aglyn/aglyn 1.0.0-beta.147 → 1.0.0-beta.150

package/src/lib/plugin-manager/plugin-route-metadata.js

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * What a plugin's page says about itself in the `<head>` (AGL-3080).
+ *
+ * A console page that a plugin draws has its head built by the SHELL: the
+ * page is a client component and cannot export metadata, so the nearest
+ * server layout does it, and for every plugin route that layout is the
+ * generic one. It can title a page from the slugs in the URL and nothing
+ * more — which is correct for a hub and wrong for a record. A marketplace
+ * listing shared into Slack unfurled as the same generic console card as
+ * every other listing until the app grew a hand-written route with a layout
+ * of its own, and that route is one of the ~20 that cannot move onto the
+ * generic one while this is the only way to have a card.
+ *
+ * So the plugin declares how to answer for an address under its own route,
+ * and the shell asks.
+ *
+ * ## The head is not a framework's
+ *
+ * A declaration answers a {@link PluginRouteHead} — a title, a description,
+ * an image — and never Next's `Metadata`. Core does not depend on a web
+ * framework and a plugin must not have to; more usefully, how a title,
+ * description and image become `openGraph` and `twitter` tags is the SHELL's
+ * knowledge and the same for every route: which card size degrades without
+ * an image, that defining `openGraph` replaces the root layout's wholesale
+ * so the site name has to be restated. A plugin that wrote those tags itself
+ * would get a different answer per plugin, and the two that got it wrong
+ * would look exactly like the two that got it right until somebody shared a
+ * link.
+ *
+ * ## Absent is a real answer, and so is silence
+ *
+ * `resolve` answers `null` for an address it has nothing to add about — a
+ * hub, a tab, a record it must not describe — and the shell keeps the title
+ * it would have built. That is the same answer as a plugin that declares
+ * nothing at all, deliberately: a head is an enrichment, and a route with no
+ * declaration is the ordinary case rather than a degraded one.
+ *
+ * ⛔ WHICH MAKES THE LOADING ORDER THE WHOLE RISK. This is a runtime
+ * registry, and an unfilled one answers "nothing to add" for every address —
+ * silently, and indistinguishably from the honest answer. A layout that asked
+ * before loading the plugin's server surface would drop every card it was
+ * built to produce and stay green. A registry is nonetheless the right shape
+ * here, and a compiled table is not: the answer depends on the DOCUMENT
+ * behind the address, so it cannot be compiled, and the reader is a server
+ * layout that already awaits — so it can load the surface first, which is
+ * what `pluginRouteHead` in the console does and what the app's
+ * `*-is-registered` spec holds it to.
+ *
+ * ## One route, one owner
+ *
+ * A route belongs to the plugin that serves it, so a second plugin's
+ * declaration for the same route is refused naming both and the incumbent
+ * keeps answering. The same plugin declaring again — a hot reload, a second
+ * surface — replaces its own.
+ *
+ * Server-side: reached by its own subpath, never through
+ * `plugin-manager/index.ts`. What a published page does not need, it must
+ * not import.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_ROUTE_METADATA = definePluginServiceContract('core.route-metadata', {
+    multiple: true
+});
+/**
+ * Declares how a plugin answers for addresses under one of its routes. The
+ * owner is the loader's marker when a register fn is running, else
+ * `options.pluginId`.
+ */ export function registerPluginRouteMetadata(declaration, options) {
+    var _ref, _ref1, _getRegisteringPluginId;
+    var _declaration_route;
+    const key = (_ref = (_declaration_route = declaration.route) == null ? void 0 : _declaration_route.trim().replace(/^\/+/, '')) != null ? _ref : '';
+    if (!key) throw new Error('a plugin route metadata declaration needs a route');
+    if (typeof declaration.resolve !== 'function') {
+        throw new Error(`route metadata for "${key}" needs a resolve function`);
+    }
+    const pluginId = ((_ref1 = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref1 : '').trim();
+    const incumbent = resolvePluginServices(PLUGIN_ROUTE_METADATA).find((entry)=>entry.key === key);
+    if (incumbent && pluginId && incumbent.pluginId !== pluginId) {
+        throw new Error(`route metadata for "${key}" is already declared by ` + `"${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_ROUTE_METADATA, _extends({}, declaration, {
+        route: key
+    }), _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, {
+        key
+    }));
+}
+/** The declaration for one route, or `null` when nobody declared one. */ export function pluginRouteMetadata(route) {
+    const key = String(route != null ? route : '').trim().replace(/^\/+/, '');
+    const entry = resolvePluginServices(PLUGIN_ROUTE_METADATA).find((one)=>one.key === key);
+    return entry ? _extends({}, entry.impl, {
+        pluginId: entry.pluginId
+    }) : null;
+}
+/**
+ * What one address says about itself, or `null` when nothing does.
+ *
+ * ⚠️ A DECLARATION THAT THROWS COSTS THE PAGE NOTHING. The head is an
+ * enrichment of a page that renders without it, and a layout's metadata
+ * rejecting fails the route — so the failure is logged and the shell falls
+ * back to the title it built itself.
+ *
+ * ⛔ It asks the registry as it stands. A caller that has not loaded the
+ * plugins' server surfaces gets `null` for every address, which is the same
+ * answer as a route nobody declared — see the module docblock.
+ */ export async function resolvePluginRouteHead(route, segments) {
+    const declared = pluginRouteMetadata(route);
+    if (!declared) return null;
+    try {
+        var _ref;
+        return (_ref = await declared.resolve(segments)) != null ? _ref : null;
+    } catch (error) {
+        console.error(`[route-metadata] "${declared.pluginId}" failed to answer for ` + `${route}/${segments.join('/')}`, error);
+        return null;
+    }
+}
+/** Every declared route, with its plugin, in registration order. */ export function listPluginRouteMetadata() {
+    return resolvePluginServices(PLUGIN_ROUTE_METADATA).map((entry)=>_extends({}, entry.impl, {
+            pluginId: entry.pluginId
+        }));
+}
+
+//# sourceMappingURL=plugin-route-metadata.js.map

package/src/lib/plugin-manager/plugin-route-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-route-metadata.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * What a plugin's page says about itself in the `<head>` (AGL-3080).\n *\n * A console page that a plugin draws has its head built by the SHELL: the\n * page is a client component and cannot export metadata, so the nearest\n * server layout does it, and for every plugin route that layout is the\n * generic one. It can title a page from the slugs in the URL and nothing\n * more — which is correct for a hub and wrong for a record. A marketplace\n * listing shared into Slack unfurled as the same generic console card as\n * every other listing until the app grew a hand-written route with a layout\n * of its own, and that route is one of the ~20 that cannot move onto the\n * generic one while this is the only way to have a card.\n *\n * So the plugin declares how to answer for an address under its own route,\n * and the shell asks.\n *\n * ## The head is not a framework's\n *\n * A declaration answers a {@link PluginRouteHead} — a title, a description,\n * an image — and never Next's `Metadata`. Core does not depend on a web\n * framework and a plugin must not have to; more usefully, how a title,\n * description and image become `openGraph` and `twitter` tags is the SHELL's\n * knowledge and the same for every route: which card size degrades without\n * an image, that defining `openGraph` replaces the root layout's wholesale\n * so the site name has to be restated. A plugin that wrote those tags itself\n * would get a different answer per plugin, and the two that got it wrong\n * would look exactly like the two that got it right until somebody shared a\n * link.\n *\n * ## Absent is a real answer, and so is silence\n *\n * `resolve` answers `null` for an address it has nothing to add about — a\n * hub, a tab, a record it must not describe — and the shell keeps the title\n * it would have built. That is the same answer as a plugin that declares\n * nothing at all, deliberately: a head is an enrichment, and a route with no\n * declaration is the ordinary case rather than a degraded one.\n *\n * ⛔ WHICH MAKES THE LOADING ORDER THE WHOLE RISK. This is a runtime\n * registry, and an unfilled one answers \"nothing to add\" for every address —\n * silently, and indistinguishably from the honest answer. A layout that asked\n * before loading the plugin's server surface would drop every card it was\n * built to produce and stay green. A registry is nonetheless the right shape\n * here, and a compiled table is not: the answer depends on the DOCUMENT\n * behind the address, so it cannot be compiled, and the reader is a server\n * layout that already awaits — so it can load the surface first, which is\n * what `pluginRouteHead` in the console does and what the app's\n * `*-is-registered` spec holds it to.\n *\n * ## One route, one owner\n *\n * A route belongs to the plugin that serves it, so a second plugin's\n * declaration for the same route is refused naming both and the incumbent\n * keeps answering. The same plugin declaring again — a hot reload, a second\n * surface — replaces its own.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`. What a published page does not need, it must\n * not import.\n */\n\nimport type { ResolvedSocialImage } from '../app-utils/social-image'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/** What one address under a plugin's route says about itself. */\nexport interface PluginRouteHead {\n  /**\n   * The page's own title, before the shell's scope and brand are affixed.\n   * Absent leaves the title the shell built from the URL.\n   */\n  title?: string\n  /** One or two sentences. Already cut to whatever budget the owner keeps. */\n  description?: string\n  /**\n   * The card image, already resolved and absolute —\n   * `resolveSocialImage` answers exactly this shape. A crawler reads it out\n   * of band, so a relative URL is not a card, it is a broken one.\n   */\n  image?: ResolvedSocialImage\n}\n\nexport interface PluginRouteMetadataDeclaration {\n  /**\n   * The plugin's own console route, as its `contributes.console.routes`\n   * spells it and without the leading slash: `marketplace`.\n   */\n  route: string\n  /**\n   * Answers for one address under that route. The segments are what follows\n   * the route itself — `['listing-1']` for `/acme/marketplace/listing-1` —\n   * so a declaration reads the address it understands and answers `null` for\n   * every other, including the route's own hub.\n   *\n   * ⚠️ IT RUNS ON THE RENDER PATH and must never throw: an unhandled\n   * rejection in a layout's metadata fails the whole route, and this route's\n   * job is to serve its page whether or not the card resolves. The shell\n   * catches anyway, because a plugin's mistake must not cost a page.\n   */\n  resolve(segments: readonly string[]): Promise<PluginRouteHead | null>\n}\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginRouteMetadata = PluginRouteMetadataDeclaration & {\n  pluginId: string\n}\n\nexport const PLUGIN_ROUTE_METADATA =\n  definePluginServiceContract<PluginRouteMetadataDeclaration>(\n    'core.route-metadata',\n    { multiple: true },\n  )\n\n/**\n * Declares how a plugin answers for addresses under one of its routes. The\n * owner is the loader's marker when a register fn is running, else\n * `options.pluginId`.\n */\nexport function registerPluginRouteMetadata(\n  declaration: PluginRouteMetadataDeclaration,\n  options?: { pluginId?: string },\n): void {\n  const key = declaration.route?.trim().replace(/^\\/+/, '') ?? ''\n  if (!key) throw new Error('a plugin route metadata declaration needs a route')\n  if (typeof declaration.resolve !== 'function') {\n    throw new Error(`route metadata for \"${key}\" needs a resolve function`)\n  }\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_ROUTE_METADATA).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `route metadata for \"${key}\" is already declared by ` +\n        `\"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(\n    PLUGIN_ROUTE_METADATA,\n    { ...declaration, route: key },\n    {\n      ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n      key,\n    },\n  )\n}\n\n/** The declaration for one route, or `null` when nobody declared one. */\nexport function pluginRouteMetadata(\n  route: string,\n): ResolvedPluginRouteMetadata | null {\n  const key = String(route ?? '')\n    .trim()\n    .replace(/^\\/+/, '')\n  const entry = resolvePluginServices(PLUGIN_ROUTE_METADATA).find(\n    (one) => one.key === key,\n  )\n  return entry ? { ...entry.impl, pluginId: entry.pluginId } : null\n}\n\n/**\n * What one address says about itself, or `null` when nothing does.\n *\n * ⚠️ A DECLARATION THAT THROWS COSTS THE PAGE NOTHING. The head is an\n * enrichment of a page that renders without it, and a layout's metadata\n * rejecting fails the route — so the failure is logged and the shell falls\n * back to the title it built itself.\n *\n * ⛔ It asks the registry as it stands. A caller that has not loaded the\n * plugins' server surfaces gets `null` for every address, which is the same\n * answer as a route nobody declared — see the module docblock.\n */\nexport async function resolvePluginRouteHead(\n  route: string,\n  segments: readonly string[],\n): Promise<PluginRouteHead | null> {\n  const declared = pluginRouteMetadata(route)\n  if (!declared) return null\n  try {\n    return (await declared.resolve(segments)) ?? null\n  } catch (error) {\n    console.error(\n      `[route-metadata] \"${declared.pluginId}\" failed to answer for ` +\n        `${route}/${segments.join('/')}`,\n      error,\n    )\n    return null\n  }\n}\n\n/** Every declared route, with its plugin, in registration order. */\nexport function listPluginRouteMetadata(): ResolvedPluginRouteMetadata[] {\n  return resolvePluginServices(PLUGIN_ROUTE_METADATA).map((entry) => ({\n    ...entry.impl,\n    pluginId: entry.pluginId,\n  }))\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_ROUTE_METADATA","multiple","registerPluginRouteMetadata","declaration","options","key","route","trim","replace","Error","resolve","pluginId","incumbent","find","entry","pluginRouteMetadata","String","one","impl","resolvePluginRouteHead","segments","declared","error","console","join","listPluginRouteMetadata","map"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DC;AAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA4C1B,OAAO,MAAMC,wBACXH,4BACE,uBACA;IAAEI,UAAU;AAAK,GAClB;AAEH;;;;CAIC,GACD,OAAO,SAASC,4BACdC,WAA2C,EAC3CC,OAA+B;cAObR,OAAAA;QALNO;IAAZ,MAAME,eAAMF,qBAAAA,YAAYG,KAAK,qBAAjBH,mBAAmBI,IAAI,GAAGC,OAAO,CAAC,QAAQ,sBAAO;IAC7D,IAAI,CAACH,KAAK,MAAM,IAAII,MAAM;IAC1B,IAAI,OAAON,YAAYO,OAAO,KAAK,YAAY;QAC7C,MAAM,IAAID,MAAM,CAAC,oBAAoB,EAAEJ,IAAI,0BAA0B,CAAC;IACxE;IACA,MAAMM,WAAW,EAACf,SAAAA,0BAAAA,oCAAAA,0BAA4BQ,2BAAAA,QAASO,QAAQ,YAA7Cf,QAAiD,IAAIW,IAAI;IAC3E,MAAMK,YAAYb,sBAAsBC,uBAAuBa,IAAI,CACjE,CAACC,QAAUA,MAAMT,GAAG,KAAKA;IAE3B,IAAIO,aAAaD,YAAYC,UAAUD,QAAQ,KAAKA,UAAU;QAC5D,MAAM,IAAIF,MACR,CAAC,oBAAoB,EAAEJ,IAAI,yBAAyB,CAAC,GACnD,CAAC,CAAC,EAAEO,UAAUD,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;IAEtD;IACAb,sBACEE,uBACA,aAAKG;QAAaG,OAAOD;QACzB,aACMD,CAAAA,2BAAAA,QAASO,QAAQ,IAAG;QAAEA,UAAUP,QAAQO,QAAQ;IAAC,IAAI,CAAC;QAC1DN;;AAGN;AAEA,uEAAuE,GACvE,OAAO,SAASU,oBACdT,KAAa;IAEb,MAAMD,MAAMW,OAAOV,gBAAAA,QAAS,IACzBC,IAAI,GACJC,OAAO,CAAC,QAAQ;IACnB,MAAMM,QAAQf,sBAAsBC,uBAAuBa,IAAI,CAC7D,CAACI,MAAQA,IAAIZ,GAAG,KAAKA;IAEvB,OAAOS,QAAQ,aAAKA,MAAMI,IAAI;QAAEP,UAAUG,MAAMH,QAAQ;SAAK;AAC/D;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,eAAeQ,uBACpBb,KAAa,EACbc,QAA2B;IAE3B,MAAMC,WAAWN,oBAAoBT;IACrC,IAAI,CAACe,UAAU,OAAO;IACtB,IAAI;YACM;QAAR,QAAQ,OAAA,MAAMA,SAASX,OAAO,CAACU,qBAAvB,OAAqC;IAC/C,EAAE,OAAOE,OAAO;QACdC,QAAQD,KAAK,CACX,CAAC,kBAAkB,EAAED,SAASV,QAAQ,CAAC,uBAAuB,CAAC,GAC7D,GAAGL,MAAM,CAAC,EAAEc,SAASI,IAAI,CAAC,MAAM,EAClCF;QAEF,OAAO;IACT;AACF;AAEA,kEAAkE,GAClE,OAAO,SAASG;IACd,OAAO1B,sBAAsBC,uBAAuB0B,GAAG,CAAC,CAACZ,QAAW,aAC/DA,MAAMI,IAAI;YACbP,UAAUG,MAAMH,QAAQ;;AAE5B"}

package/src/lib/plugin-manager/record-captured-contact.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * How a door hands somebody it just met to whichever plugin keeps people
+ * (AGL-3080).
+ *
+ * `capturePluginContact` is the contract; this is the three things every
+ * door calling it has to get right, in one place so no door has to remember
+ * them. It lives in core rather than in an app because the doors are not all
+ * in one place: a form submission is a core route in the tenant app, a
+ * newsletter signup and a membership registration are commerce's, a booking
+ * request is bookings'. A plugin may not import an app, so a wrapper that
+ * lived in one would be a wrapper the plugin doors had to copy — and a copy
+ * is where the two halves of this behaviour would drift.
+ *
+ * ## It makes sure somebody is listening, without slowing down the case where
+ * somebody already is
+ *
+ * `capturePluginContact` answers `null` when no plugin keeps people, and the
+ * plugin that does registers itself from the server declarations each app
+ * runs at boot. That boot step is wrapped in a `catch` — a declaration that
+ * fails to load must not cost every route — so a boot that went wrong leaves
+ * a process where every capture answers `null` and no contact is ever
+ * written, with one line in a log nobody is reading.
+ *
+ * So the writer is looked up FIRST, synchronously, and handed the capture
+ * with no await in between. That matters for more than speed: every caller
+ * is fire-and-forget, and a door that awaited anything before reaching the
+ * writer would hand the capture to a request that may already have returned.
+ * Only when no writer answers does this run the app's boot step and try once
+ * more — repairing the broken-boot case rather than just reporting it.
+ *
+ * The boot step itself is the app's, because the list of plugins to declare
+ * is generated per app and core may not import a plugin. The app hands it
+ * over at boot with {@link registerPluginDeclarationsRepair}. An app that has
+ * not — or a process that never ran its instrumentation at all — loses the
+ * repair and keeps every other behaviour here, which is the honest outcome:
+ * a process that ran no boot step has bigger silences than this one.
+ *
+ * ## It tells the difference between the two silences
+ *
+ * `null` is "this workspace has no record system", which is a real and quiet
+ * answer for a workspace with the record plugin switched off. It is ALSO what
+ * a broken registration looks like, and the two are indistinguishable from
+ * here. So it is logged rather than ignored: a workspace that should be
+ * keeping contacts and has silently stopped is the failure mode this seam can
+ * produce, and a line naming the site is what turns an unreproducible support
+ * ticket into a one-minute answer. A refusal is different again — the owner
+ * considered this person and declined, for a reason it states — and is logged
+ * as itself.
+ *
+ * ⚠️ IT NEVER THROWS, and callers use it fire-and-forget. Every door has
+ * already done the thing it is recording; losing the submission, the signup
+ * or the booking over the contact would be the larger failure.
+ *
+ * Server-side: reached by its own subpath, never through
+ * `plugin-manager/index.ts`.
+ */
+import { type PluginContactCaptureRequest, type PluginContactCaptured } from './plugin-contact-capture';
+/**
+ * The app offers its boot step, so a capture that finds nobody can run it.
+ *
+ * Called at boot from the app's own instrumentation, beside the declarations
+ * themselves and BEFORE them — this is a plain assignment that cannot fail,
+ * and the failure it exists to repair is the one immediately after it. The
+ * app passes a function rather than core importing the generated manifest,
+ * which core may not do: the manifest names every plugin.
+ *
+ * Idempotent and last-one-wins; an app registers exactly once per process.
+ */
+export declare function registerPluginDeclarationsRepair(run: () => Promise<void>): void;
+/** Only for specs: forgets the registered boot step. */
+export declare function resetPluginDeclarationsRepairForTests(): void;
+export declare function recordCapturedContact(request: PluginContactCaptureRequest): Promise<PluginContactCaptured | null>;
+export default recordCapturedContact;

package/src/lib/plugin-manager/record-captured-contact.js

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * How a door hands somebody it just met to whichever plugin keeps people
+ * (AGL-3080).
+ *
+ * `capturePluginContact` is the contract; this is the three things every
+ * door calling it has to get right, in one place so no door has to remember
+ * them. It lives in core rather than in an app because the doors are not all
+ * in one place: a form submission is a core route in the tenant app, a
+ * newsletter signup and a membership registration are commerce's, a booking
+ * request is bookings'. A plugin may not import an app, so a wrapper that
+ * lived in one would be a wrapper the plugin doors had to copy — and a copy
+ * is where the two halves of this behaviour would drift.
+ *
+ * ## It makes sure somebody is listening, without slowing down the case where
+ * somebody already is
+ *
+ * `capturePluginContact` answers `null` when no plugin keeps people, and the
+ * plugin that does registers itself from the server declarations each app
+ * runs at boot. That boot step is wrapped in a `catch` — a declaration that
+ * fails to load must not cost every route — so a boot that went wrong leaves
+ * a process where every capture answers `null` and no contact is ever
+ * written, with one line in a log nobody is reading.
+ *
+ * So the writer is looked up FIRST, synchronously, and handed the capture
+ * with no await in between. That matters for more than speed: every caller
+ * is fire-and-forget, and a door that awaited anything before reaching the
+ * writer would hand the capture to a request that may already have returned.
+ * Only when no writer answers does this run the app's boot step and try once
+ * more — repairing the broken-boot case rather than just reporting it.
+ *
+ * The boot step itself is the app's, because the list of plugins to declare
+ * is generated per app and core may not import a plugin. The app hands it
+ * over at boot with {@link registerPluginDeclarationsRepair}. An app that has
+ * not — or a process that never ran its instrumentation at all — loses the
+ * repair and keeps every other behaviour here, which is the honest outcome:
+ * a process that ran no boot step has bigger silences than this one.
+ *
+ * ## It tells the difference between the two silences
+ *
+ * `null` is "this workspace has no record system", which is a real and quiet
+ * answer for a workspace with the record plugin switched off. It is ALSO what
+ * a broken registration looks like, and the two are indistinguishable from
+ * here. So it is logged rather than ignored: a workspace that should be
+ * keeping contacts and has silently stopped is the failure mode this seam can
+ * produce, and a line naming the site is what turns an unreproducible support
+ * ticket into a one-minute answer. A refusal is different again — the owner
+ * considered this person and declined, for a reason it states — and is logged
+ * as itself.
+ *
+ * ⚠️ IT NEVER THROWS, and callers use it fire-and-forget. Every door has
+ * already done the thing it is recording; losing the submission, the signup
+ * or the booking over the contact would be the larger failure.
+ *
+ * Server-side: reached by its own subpath, never through
+ * `plugin-manager/index.ts`.
+ */ import { pluginContactCaptureWriter } from "./plugin-contact-capture.js";
+/** The app's boot-time declarations step, when it has offered one. */ let repair = null;
+/**
+ * The app offers its boot step, so a capture that finds nobody can run it.
+ *
+ * Called at boot from the app's own instrumentation, beside the declarations
+ * themselves and BEFORE them — this is a plain assignment that cannot fail,
+ * and the failure it exists to repair is the one immediately after it. The
+ * app passes a function rather than core importing the generated manifest,
+ * which core may not do: the manifest names every plugin.
+ *
+ * Idempotent and last-one-wins; an app registers exactly once per process.
+ */ export function registerPluginDeclarationsRepair(run) {
+    repair = run;
+}
+/** Only for specs: forgets the registered boot step. */ export function resetPluginDeclarationsRepairForTests() {
+    repair = null;
+}
+export async function recordCapturedContact(request) {
+    const where = `${request.interaction.source} on ${request.hostId}`;
+    const found = pluginContactCaptureWriter();
+    if (found) return await handedTo(found.writer, request, where);
+    // Nobody answers. Either this workspace keeps no records, or the boot step
+    // that registers the writer failed and every capture in this process has
+    // been going nowhere. Run it and ask again — the registration memoizes its
+    // own promise, so this is one attempt per process and not one per capture.
+    if (repair) {
+        try {
+            await repair();
+        } catch (error) {
+            console.error(`[capture] plugin declarations failed before ${where}`, error);
+        }
+    }
+    const late = pluginContactCaptureWriter();
+    if (!late) {
+        console.warn(`[capture] no plugin keeps people, so the ${where} recorded nobody. ` + 'Expected when the record plugin is off for this workspace; a bug otherwise.');
+        return null;
+    }
+    console.warn(`[capture] the ${where} found no writer until it registered one itself — ` + 'the boot-time declarations did not run in this process.');
+    return await handedTo(late.writer, request, where);
+}
+/** One capture, with the two failures a door must not be made to handle. */ async function handedTo(writer, request, where) {
+    try {
+        const verdict = await writer.capture(request);
+        if (verdict.ok === false) {
+            console.warn(`[capture] ${where} was refused (${verdict.reason})`);
+        }
+        return verdict;
+    } catch (error) {
+        // The contract says a writer RETURNS its refusals, so reaching here means
+        // one broke its own contract. It still costs the door nothing.
+        console.error(`[capture] ${where} threw`, error);
+        return null;
+    }
+}
+export default recordCapturedContact;
+
+//# sourceMappingURL=record-captured-contact.js.map

package/src/lib/plugin-manager/record-captured-contact.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/record-captured-contact.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * How a door hands somebody it just met to whichever plugin keeps people\n * (AGL-3080).\n *\n * `capturePluginContact` is the contract; this is the three things every\n * door calling it has to get right, in one place so no door has to remember\n * them. It lives in core rather than in an app because the doors are not all\n * in one place: a form submission is a core route in the tenant app, a\n * newsletter signup and a membership registration are commerce's, a booking\n * request is bookings'. A plugin may not import an app, so a wrapper that\n * lived in one would be a wrapper the plugin doors had to copy — and a copy\n * is where the two halves of this behaviour would drift.\n *\n * ## It makes sure somebody is listening, without slowing down the case where\n * somebody already is\n *\n * `capturePluginContact` answers `null` when no plugin keeps people, and the\n * plugin that does registers itself from the server declarations each app\n * runs at boot. That boot step is wrapped in a `catch` — a declaration that\n * fails to load must not cost every route — so a boot that went wrong leaves\n * a process where every capture answers `null` and no contact is ever\n * written, with one line in a log nobody is reading.\n *\n * So the writer is looked up FIRST, synchronously, and handed the capture\n * with no await in between. That matters for more than speed: every caller\n * is fire-and-forget, and a door that awaited anything before reaching the\n * writer would hand the capture to a request that may already have returned.\n * Only when no writer answers does this run the app's boot step and try once\n * more — repairing the broken-boot case rather than just reporting it.\n *\n * The boot step itself is the app's, because the list of plugins to declare\n * is generated per app and core may not import a plugin. The app hands it\n * over at boot with {@link registerPluginDeclarationsRepair}. An app that has\n * not — or a process that never ran its instrumentation at all — loses the\n * repair and keeps every other behaviour here, which is the honest outcome:\n * a process that ran no boot step has bigger silences than this one.\n *\n * ## It tells the difference between the two silences\n *\n * `null` is \"this workspace has no record system\", which is a real and quiet\n * answer for a workspace with the record plugin switched off. It is ALSO what\n * a broken registration looks like, and the two are indistinguishable from\n * here. So it is logged rather than ignored: a workspace that should be\n * keeping contacts and has silently stopped is the failure mode this seam can\n * produce, and a line naming the site is what turns an unreproducible support\n * ticket into a one-minute answer. A refusal is different again — the owner\n * considered this person and declined, for a reason it states — and is logged\n * as itself.\n *\n * ⚠️ IT NEVER THROWS, and callers use it fire-and-forget. Every door has\n * already done the thing it is recording; losing the submission, the signup\n * or the booking over the contact would be the larger failure.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`.\n */\n\nimport {\n  pluginContactCaptureWriter,\n  type PluginContactCaptureRequest,\n  type PluginContactCaptureWriter,\n  type PluginContactCaptured,\n} from './plugin-contact-capture'\n\n/** The app's boot-time declarations step, when it has offered one. */\nlet repair: (() => Promise<void>) | null = null\n\n/**\n * The app offers its boot step, so a capture that finds nobody can run it.\n *\n * Called at boot from the app's own instrumentation, beside the declarations\n * themselves and BEFORE them — this is a plain assignment that cannot fail,\n * and the failure it exists to repair is the one immediately after it. The\n * app passes a function rather than core importing the generated manifest,\n * which core may not do: the manifest names every plugin.\n *\n * Idempotent and last-one-wins; an app registers exactly once per process.\n */\nexport function registerPluginDeclarationsRepair(run: () => Promise<void>): void {\n  repair = run\n}\n\n/** Only for specs: forgets the registered boot step. */\nexport function resetPluginDeclarationsRepairForTests(): void {\n  repair = null\n}\n\nexport async function recordCapturedContact(\n  request: PluginContactCaptureRequest,\n): Promise<PluginContactCaptured | null> {\n  const where = `${request.interaction.source} on ${request.hostId}`\n  const found = pluginContactCaptureWriter()\n  if (found) return await handedTo(found.writer, request, where)\n\n  // Nobody answers. Either this workspace keeps no records, or the boot step\n  // that registers the writer failed and every capture in this process has\n  // been going nowhere. Run it and ask again — the registration memoizes its\n  // own promise, so this is one attempt per process and not one per capture.\n  if (repair) {\n    try {\n      await repair()\n    } catch (error) {\n      console.error(`[capture] plugin declarations failed before ${where}`, error)\n    }\n  }\n  const late = pluginContactCaptureWriter()\n  if (!late) {\n    console.warn(\n      `[capture] no plugin keeps people, so the ${where} recorded nobody. ` +\n        'Expected when the record plugin is off for this workspace; a bug otherwise.',\n    )\n    return null\n  }\n  console.warn(\n    `[capture] the ${where} found no writer until it registered one itself — ` +\n      'the boot-time declarations did not run in this process.',\n  )\n  return await handedTo(late.writer, request, where)\n}\n\n/** One capture, with the two failures a door must not be made to handle. */\nasync function handedTo(\n  writer: PluginContactCaptureWriter,\n  request: PluginContactCaptureRequest,\n  where: string,\n): Promise<PluginContactCaptured | null> {\n  try {\n    const verdict = await writer.capture(request)\n    if (verdict.ok === false) {\n      console.warn(`[capture] ${where} was refused (${verdict.reason})`)\n    }\n    return verdict\n  } catch (error) {\n    // The contract says a writer RETURNS its refusals, so reaching here means\n    // one broke its own contract. It still costs the door nothing.\n    console.error(`[capture] ${where} threw`, error)\n    return null\n  }\n}\n\nexport default recordCapturedContact\n"],"names":["pluginContactCaptureWriter","repair","registerPluginDeclarationsRepair","run","resetPluginDeclarationsRepairForTests","recordCapturedContact","request","where","interaction","source","hostId","found","handedTo","writer","error","console","late","warn","verdict","capture","ok","reason"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDC,GAED,SACEA,0BAA0B,QAIrB,8BAA0B;AAEjC,oEAAoE,GACpE,IAAIC,SAAuC;AAE3C;;;;;;;;;;CAUC,GACD,OAAO,SAASC,iCAAiCC,GAAwB;IACvEF,SAASE;AACX;AAEA,sDAAsD,GACtD,OAAO,SAASC;IACdH,SAAS;AACX;AAEA,OAAO,eAAeI,sBACpBC,OAAoC;IAEpC,MAAMC,QAAQ,GAAGD,QAAQE,WAAW,CAACC,MAAM,CAAC,IAAI,EAAEH,QAAQI,MAAM,EAAE;IAClE,MAAMC,QAAQX;IACd,IAAIW,OAAO,OAAO,MAAMC,SAASD,MAAME,MAAM,EAAEP,SAASC;IAExD,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,2EAA2E;IAC3E,IAAIN,QAAQ;QACV,IAAI;YACF,MAAMA;QACR,EAAE,OAAOa,OAAO;YACdC,QAAQD,KAAK,CAAC,CAAC,4CAA4C,EAAEP,OAAO,EAAEO;QACxE;IACF;IACA,MAAME,OAAOhB;IACb,IAAI,CAACgB,MAAM;QACTD,QAAQE,IAAI,CACV,CAAC,yCAAyC,EAAEV,MAAM,kBAAkB,CAAC,GACnE;QAEJ,OAAO;IACT;IACAQ,QAAQE,IAAI,CACV,CAAC,cAAc,EAAEV,MAAM,kDAAkD,CAAC,GACxE;IAEJ,OAAO,MAAMK,SAASI,KAAKH,MAAM,EAAEP,SAASC;AAC9C;AAEA,0EAA0E,GAC1E,eAAeK,SACbC,MAAkC,EAClCP,OAAoC,EACpCC,KAAa;IAEb,IAAI;QACF,MAAMW,UAAU,MAAML,OAAOM,OAAO,CAACb;QACrC,IAAIY,QAAQE,EAAE,KAAK,OAAO;YACxBL,QAAQE,IAAI,CAAC,CAAC,UAAU,EAAEV,MAAM,cAAc,EAAEW,QAAQG,MAAM,CAAC,CAAC,CAAC;QACnE;QACA,OAAOH;IACT,EAAE,OAAOJ,OAAO;QACd,0EAA0E;QAC1E,+DAA+D;QAC/DC,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEP,MAAM,MAAM,CAAC,EAAEO;QAC1C,OAAO;IACT;AACF;AAEA,eAAeT,sBAAqB"}