@wildo-ai/saas-technical-doc 1.1.2 → 1.1.4

package/dist/esm/companion/manual-controller-route-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-controller-route-projection.js","sourceRoot":"","sources":["../../../src/companion/manual-controller-route-projection.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The application's manually mounted controller routes, projected into the same shape the resource\n * registry produces — so they reach the generated API reference through the existing generator with\n * no change to it.\n *\n * ## The gap this closes\n *\n * A Wildo application serves two disjoint families of HTTP routes. The RESOURCE REGISTRY builds one\n * family from the resource configurations, and every mechanism downstream projects that family and\n * only that family. The other family is mounted by hand, controller by controller, from\n * `MANUAL_CONTROLLER_ROUTES_URLS`: sign-in, token refresh, MFA, passkeys, SAML, the OAuth 2.0\n * authorization-server endpoints, the Model Context Protocol and Agent2Agent doors, file transfer,\n * i18n labels, charts.\n *\n * Nothing projected the second family. Measured 2026-09-09 across the four committed documents of\n * the two dogfood applications — 439, 576, 146 and 160 paths — **not one contained a single path\n * under `/auth`**. The reference explained the three credential formats every operation accepts and\n * never published the endpoint that issues one. Worse, four operation-header descriptions in the\n * same document told a reader the step-up token is \"obtained from `POST /api/v1/auth/reauth`\", a\n * path that document does not contain: the reference already pointed at this hole and could not\n * fill it.\n *\n * ## Why this lives HERE and not in the companion projector\n *\n * The companion's `openapi-generation-input` projector walks the APPLICATION's resolved registry, so\n * it must run inside the introspection subprocess with the app's schema graph loaded. This\n * projection needs none of that: the manual routes are the ENGINE's own contract, identical in every\n * generated application, and the catalog that describes them is a static table in\n * `@wildo-ai/saas-models`. Keeping it beside the generator makes it a pure function of framework\n * knowledge — testable on its own, like `SECURITY_SCHEMES` and the API-conventions markdown that\n * already live here — instead of one more thing the subprocess owns.\n *\n * ## Why the generator needed no change\n *\n * `generateOpenApiDocuments` is a pure function over `OpenApiGenerationInput`. It groups by\n * `resourceIdentifier`, keys path items on `path` + `httpVerb`, and emits whatever identity a\n * projection carries; it has no opinion about where a projected operation came from. So a manual\n * route reaches the document as an ordinary `OperationProjection` whose `resourceIdentifier` is its\n * documentation GROUP, accompanied by a matching `ResourceTag` — which is the join the renderer's\n * conservation check makes.\n *\n * ## What a manual projection deliberately does NOT carry\n *\n * `requestBodySchema` and `responseBodySchema` stay `null`. Those bodies are Zod schemas declared\n * inside backend controllers, in a package neither this one nor the introspection subprocess loads;\n * hand-copying them into the catalog would create a second copy of a contract with nothing checking\n * the two agree — the drift this repository refuses everywhere else. Each catalog entry authors a\n * `responseStatuses` row instead (without one the generator emits a bare `204 No Content`, which is\n * wrong for almost every route here) and describes its payload in prose. That is an honest account of\n * what is known, and it is strictly better than a reference in which the endpoint does not exist.\n * Projecting the real schemas is a later, larger change that must first move them into a shared\n * module.\n */\n\nimport {\n  HttpMethod,\n  MAIN_API_BASE_PATH,\n  MANUAL_CONTROLLER_ROUTE_DOCUMENTATION,\n  MANUAL_CONTROLLER_ROUTE_GROUP_DESCRIPTIONS,\n  MANUAL_CONTROLLER_ROUTES_URLS,\n  ManualControllerRouteAuthentication,\n  ManualControllerRouteGroup,\n  ManualControllerRouteKey,\n  ManualControllerRoutePublication,\n} from '@wildo-ai/saas-models';\n\nimport {\n  ENGINE_RESOURCE_SUB_DOMAIN_DOCUMENTATION,\n  EngineResourceSubDomain,\n} from '@wildo-ai/saas-specifications';\n\nimport { OpenApiSection } from '../openapi/openapi-generation-output.schemas';\nimport {\n  createOpenApiOperationIdentity,\n  OperationProjectionAuthenticationMode,\n  OperationProjectionHttpVerb,\n  OperationProjectionPrimaryScope,\n  OperationProjectionVariantType,\n  type OperationAccessDocumentation,\n  type OperationProjection,\n  type ResourceTag,\n} from './operation-projection.schemas';\n\n/** Catalog vocabulary → the projection's own authentication vocabulary. Total over the source enum. */\nconst MANUAL_ROUTE_AUTHENTICATION_MODES: Record<ManualControllerRouteAuthentication, OperationProjectionAuthenticationMode> = {\n  [ManualControllerRouteAuthentication.PUBLIC]: OperationProjectionAuthenticationMode.PUBLIC,\n  [ManualControllerRouteAuthentication.ANONYMOUS_SESSION]: OperationProjectionAuthenticationMode.ANONYMOUS_SESSION,\n  [ManualControllerRouteAuthentication.AUTHENTICATED]: OperationProjectionAuthenticationMode.AUTHENTICATED,\n  [ManualControllerRouteAuthentication.ANONYMOUS_OR_AUTHENTICATED]: OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED,\n};\n\n/**\n * `HttpMethod` → the OpenAPI path-item key.\n *\n * `HttpMethod.OPTIONS` is deliberately excluded. OpenAPI does define an `options` path-item key, but\n * no manual route mounts one — CORS preflight is answered by middleware rather than by a route — so\n * admitting it here would be inventing a case. A catalog entry that named `OPTIONS` fails to compile\n * against this map, which is the right moment to find out.\n */\nconst MANUAL_ROUTE_HTTP_VERBS: Record<Exclude<HttpMethod, HttpMethod.OPTIONS>, OperationProjectionHttpVerb> = {\n  [HttpMethod.GET]: OperationProjectionHttpVerb.GET,\n  [HttpMethod.POST]: OperationProjectionHttpVerb.POST,\n  [HttpMethod.PUT]: OperationProjectionHttpVerb.PUT,\n  [HttpMethod.PATCH]: OperationProjectionHttpVerb.PATCH,\n  [HttpMethod.DELETE]: OperationProjectionHttpVerb.DELETE,\n};\n\n/**\n * Express `:param` → OpenAPI `{param}`.\n *\n * The resource lane never needs this: its URL builder already emits brace form. The manual registry\n * is the backend's own mount table, written the way Express reads it, so the conversion belongs at\n * this boundary rather than in the registry — which the router consumes verbatim and must not have\n * rewritten under it.\n */\nexport function toOpenApiPathTemplate(expressPath: string): string {\n  return expressPath.replace(/:([A-Za-z0-9_]+)/gu, '{$1}');\n}\n\n/**\n * The operation identifier for one manual route — derived, never authored.\n *\n * `buildOperationId` composes `<verb><Resource>` and drops the resource noun when the verb phrase\n * already contains it. Starting the identifier WITH the group name is what triggers that drop, so\n * `AUTH_IDENTIFY` in the `authentication` group reads `authenticationIdentify` rather than the\n * stuttering `authIdentifyAuthentication`. Derived rather than authored so a route key added\n * tomorrow gets a coherent, stable id without anybody having to think about it.\n */\nexport function manualRouteOperationIdentifier(routeKey: string, group: ManualControllerRouteGroup): string {\n  const words = routeKey.toLowerCase().split('_').filter((word) => word.length > 0);\n  return group + words.map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join('');\n}\n\n/**\n * The API-reference group each manual-route group belongs to — the SAME vocabulary the engine's own\n * resources are classified by.\n *\n * ## Why these join the engine's categories instead of forming their own\n *\n * A tag with no category is not merely ungrouped: `applyApiReferenceResourceCategories` REFUSES the\n * publication of any application that declares `apiReferenceResourceCategories` at all, naming every\n * tag no category claims. So six uncategorised groups would have turned \"the auth endpoints are\n * missing from the reference\" into \"the reference does not publish\", for every application with an\n * authored taxonomy — a worse failure than the one this projection fixes.\n *\n * Categorising them as their OWN groups was the alternative and is rejected: the renderer groups by\n * category, so `authentication` (54 routes) would sit as a sibling of `auth` (the SSO, SCIM, session\n * and token RESOURCES), and a reader looking for authentication would find it split across two\n * adjacent headings for no reason they could see. The endpoint that issues a token and the resource\n * that configures how tokens are issued belong under one heading.\n *\n * TOTAL over {@link ManualControllerRouteGroup}: a new group is a compile error until it is placed.\n * That is the same guarantee the route catalog itself carries, and for the same reason — a group\n * that nobody remembered to classify is a publication failure in an application nobody has run yet.\n */\nexport const MANUAL_ROUTE_GROUP_SUB_DOMAINS: Record<ManualControllerRouteGroup, EngineResourceSubDomain> = {\n  // Sessions, MFA, SSO and consumable tokens — the sub-domain's own words.\n  [ManualControllerRouteGroup.AUTHENTICATION]: EngineResourceSubDomain.AUTH,\n  // The application acting as an OAuth 2.0 authorization server. Opposite direction from signing in,\n  // same subject: `auth` names OAuth explicitly, and its OAuth-client resources are the records\n  // these endpoints authenticate.\n  [ManualControllerRouteGroup.IDENTITY_PROVIDER]: EngineResourceSubDomain.AUTH,\n  // \"…and what they may delegate\" is `auth`'s own scope, and the provider-credential resources this\n  // group mints live there too.\n  [ManualControllerRouteGroup.CONNECTED_ACCOUNTS]: EngineResourceSubDomain.AUTH,\n  // MCP and A2A are the doors autonomous software knocks on; `flows-actors` is \"work that runs:\n  // flows, actors, tasks, agents\".\n  [ManualControllerRouteGroup.AGENT_INTERFACES]: EngineResourceSubDomain.FLOWS_ACTORS,\n  // \"Uploaded bytes and the metadata that links them to a domain row\" — and these routes address a\n  // stored file by its own id, so they belong beside the file metadata resources.\n  [ManualControllerRouteGroup.FILE_TRANSFER]: EngineResourceSubDomain.FILES,\n  // Reads a client makes about THIS APPLICATION: its resolved features, its labels, its chart data.\n  // `applications` is the sub-domain whose subject is the application itself; `features` is about\n  // the feature RECORDS, which are resources of their own.\n  [ManualControllerRouteGroup.APPLICATION_RUNTIME]: EngineResourceSubDomain.APPLICATIONS,\n};\n\nfunction manualRouteGroupCategory(group: ManualControllerRouteGroup) {\n  const subDomain = MANUAL_ROUTE_GROUP_SUB_DOMAINS[group];\n  const documentation = ENGINE_RESOURCE_SUB_DOMAIN_DOCUMENTATION[subDomain];\n  return { id: subDomain, label: documentation.label, description: documentation.description };\n}\n\n/**\n * Every PUBLISHED manual route as an `OperationProjection`, plus the `ResourceTag` for each group\n * that contributed one.\n *\n * Pure and argument-free: the manual route table is framework knowledge, identical in every\n * generated application, so there is nothing about a particular application to pass in. Withheld\n * routes are skipped here and nowhere else — the catalog is the single place a publication decision\n * is recorded, and it requires a written reason for each one.\n */\nexport function projectManualControllerRouteOperations(): {\n  operations: OperationProjection[];\n  resourceTags: ResourceTag[];\n} {\n  const operations: OperationProjection[] = [];\n  const usedGroups = new Set<ManualControllerRouteGroup>();\n\n  for (const routeKey of Object.values(ManualControllerRouteKey)) {\n    const documentation = MANUAL_CONTROLLER_ROUTE_DOCUMENTATION[routeKey];\n    if (documentation.publication !== ManualControllerRoutePublication.PUBLISHED) continue;\n    usedGroups.add(documentation.group);\n\n    const path = `${MAIN_API_BASE_PATH}${toOpenApiPathTemplate(MANUAL_CONTROLLER_ROUTES_URLS[routeKey])}`;\n    const baseOperationIdentifier = manualRouteOperationIdentifier(routeKey, documentation.group);\n    const access: OperationAccessDocumentation = {\n      authenticationMode: MANUAL_ROUTE_AUTHENTICATION_MODES[documentation.authentication],\n      authenticationSummary: documentation.authenticationSummary,\n      /*\n       * Empty on purpose. A manual route is not gated by the resource role vocabulary — its\n       * authorization is enforced inside its own handler, and for most of them there is no role at\n       * all because the caller has no session yet. Inventing a role here would put a requirement in\n       * the reference that no role table backs, which is worse than saying nothing.\n       */\n      roleRequirements: [],\n    };\n\n    for (const method of documentation.methods) {\n      const httpVerb = MANUAL_ROUTE_HTTP_VERBS[method];\n      /*\n       * One key can mount several methods — RFC 7592 defines ONE client-configuration endpoint whose\n       * method selects the operation, and `/mcp` answers three. `operationId` must be unique across\n       * the document, so the verb becomes a qualifier exactly when there is more than one method; a\n       * single-method route keeps the clean name.\n       */\n      const operationKey = documentation.methods.length > 1\n        ? `${baseOperationIdentifier}_${method}`\n        : baseOperationIdentifier;\n\n      operations.push({\n        resourceIdentifier: documentation.group,\n        operationKey,\n        baseOperationIdentifier,\n        variantKey: null,\n        variantType: OperationProjectionVariantType.API_CALL,\n        httpVerb,\n        path,\n        /*\n         * Inert in the generator — sectioning is `consumerApiSection` and security is `access` — but\n         * the projection contract requires it. `APPLICATION` is the truthful answer for every manual\n         * route, including the two whose URL carries an organization segment: there the organization\n         * is an argument to the call, not the scope the caller is acting within.\n         */\n        primaryScope: OperationProjectionPrimaryScope.APPLICATION,\n        /*\n         * Never the administration section. These routes are how ANY caller authenticates, connects\n         * or discovers, so filing them under application administration would move sign-in out of\n         * the document integrators actually read.\n         */\n        consumerApiSection: OpenApiSection.API_REFERENCE,\n        identity: createOpenApiOperationIdentity({\n          resourceIdentifier: documentation.group,\n          baseOperationIdentifier,\n          variantKey: null,\n          variantType: OperationProjectionVariantType.API_CALL,\n          httpVerb,\n          path,\n        }),\n        roles: [],\n        access,\n        /*\n         * These surfaces accept an API key wherever they accept a bearer token; nothing narrows any\n         * of them to a bearer-only lane, so removing the API-key alternative would document a\n         * refusal the runtime does not make.\n         */\n        isApiKeyAccessDisabled: false,\n        /* Optimistic locking is a resource-repository capability. No manual route has one. */\n        acceptsIfMatch: false,\n        summary: documentation.summary,\n        description: documentation.description,\n        requestBodySchema: null,\n        responseBodySchema: null,\n        responseStatuses: [{ code: documentation.successStatus.code, meaning: documentation.successStatus.meaning }],\n      });\n    }\n  }\n\n  const resourceTags: ResourceTag[] = [...usedGroups]\n    .sort((left, right) => left.localeCompare(right, 'en-US'))\n    .map((group) => ({\n      name: group,\n      description: MANUAL_CONTROLLER_ROUTE_GROUP_DESCRIPTIONS[group],\n      category: manualRouteGroupCategory(group),\n    }));\n\n  return { operations, resourceTags };\n}\n"]}

package/dist/esm/companion/openapi-generator.d.ts

@@ -71,6 +71,22 @@ export declare function filterApiCallOperations(operations: ReadonlyArray<Operat
  * single place that decides "drop empty sections from the output."
  */
 export declare function groupOperationsByConsumerApiSection(operations: ReadonlyArray<OperationProjection>): Readonly<Record<OpenApiSection, ReadonlyArray<OperationProjection>>>;
+/**
+ * Which half of an operation a generated component schema models.
+ *
+ * A closed two-member vocabulary, named rather than inlined because the two members are not
+ * symmetric and the difference is worth stating once: a REQUEST schema is what a caller must
+ * SEND and is therefore the contract they are held to, while a RESPONSE schema is what the
+ * application PROMISES to return. Both the schema NAME and its description are derived from
+ * this value, so the member is the single input that decides how an integrator reads the card.
+ *
+ * The member VALUES are the PascalCase suffixes appended to a schema name (`TodosCreateRequest`),
+ * so they are wire-visible in the published OpenAPI document and not free to rename.
+ */
+export declare enum OpenApiComponentSchemaRole {
+    REQUEST = "Request",
+    RESPONSE = "Response"
+}
 /**
  * Public entry point — single function the companion controller
  * calls.

package/dist/esm/companion/openapi-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-generator.d.ts","sourceRoot":"","sources":["../../../../src/companion/openapi-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,EACL,cAAc,EACd,KAAK,uBAAuB,EAE7B,MAAM,8CAA8C,CAAC;AAEtD,OAAO,EAOL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC7C,aAAa,CAAC,mBAAmB,CAAC,CAUpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC7C,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAqBtE;AAkhDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,uBAAuB,CAyBnF"}
+{"version":3,"file":"openapi-generator.d.ts","sourceRoot":"","sources":["../../../src/companion/openapi-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAaH,OAAO,EACL,cAAc,EACd,KAAK,uBAAuB,EAE7B,MAAM,8CAA8C,CAAC;AAEtD,OAAO,EAOL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC7C,aAAa,CAAC,mBAAmB,CAAC,CAUpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC7C,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAqBtE;AAg6CD;;;;;;;;;;;GAWG;AACH,oBAAY,0BAA0B;IACpC,OAAO,YAAY;IACnB,QAAQ,aAAa;CACtB;AAmkBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,uBAAuB,CAyBnF"}