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

package/dist/esm/companion/application-documentation/application-administration-documentation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Who may perform each administrative action in THIS application.
+ *
+ * The roles page lists the roles and what each is for; it could not say which role may actually
+ * invite a person, change their access or move a team, because that lives on the operations —
+ * every one of which declares the roles it accepts. An administrator's first question ("can a
+ * manager do this, or does it need an owner?") therefore had no answer anywhere in the portal, and
+ * the pages fell back on prose about least privilege.
+ *
+ * The projection joins two things the companion already holds: the admitted operations for the
+ * membership and organization-unit resources, and the application's own role labels. It is a
+ * matrix of what this application publishes, not a restatement of the framework's defaults.
+ */
+export declare const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF: "source:companion-projection:application-administration";
+export declare const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION = 1;
+export interface ApplicationAdministrationActionSource {
+    /** What the action does, in the words the API reference uses for the same operation. */
+    readonly action: string;
+    /**
+     * Labels of the organization roles that may perform it, in the application's own words.
+     * Empty means the operation declares no role gate — see `openToEveryMember`.
+     */
+    readonly roleLabels: readonly string[];
+    /**
+     * True when the operation declares no required role. That is a real, intentional state (any
+     * authenticated member of the organization may call it), not a gap in the projection, so it is
+     * said explicitly rather than shown as an empty cell.
+     */
+    readonly openToEveryMember: boolean;
+}
+export interface ApplicationAdministrationDocumentationSource {
+    readonly memberActions: readonly ApplicationAdministrationActionSource[];
+    readonly organizationUnitActions: readonly ApplicationAdministrationActionSource[];
+}
+/** Named presentations a page may request with `{{APPLICATION_ADMINISTRATION:<selector>}}`. */
+export declare enum ApplicationAdministrationPresentation {
+    /** Membership actions — invite, change access, suspend, remove — against the roles that may do them. */
+    MEMBER_ACTIONS = "memberActions",
+    /** Organization-unit actions against the roles that may do them. */
+    ORGANIZATION_UNIT_ACTIONS = "organizationUnitActions"
+}
+export interface ApplicationAdministrationDocumentationFact {
+    readonly sourceRef: string;
+    readonly sourceVersion: number;
+    readonly presentations: Readonly<Record<ApplicationAdministrationPresentation, string>>;
+}
+/**
+ * Projects the administrative matrix. A pure function of the source, so two runs over the same
+ * application produce identical bytes.
+ */
+export declare function projectApplicationAdministrationDocumentation(source: ApplicationAdministrationDocumentationSource): ApplicationAdministrationDocumentationFact;
+//# sourceMappingURL=application-administration-documentation.d.ts.map

package/dist/esm/companion/application-documentation/application-administration-documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-administration-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-administration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mDAAmD,EAAG,wDAAiE,CAAC;AACrI,eAAO,MAAM,uDAAuD,IAAI,CAAC;AAEzE,MAAM,WAAW,qCAAqC;IACpD,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,aAAa,EAAE,SAAS,qCAAqC,EAAE,CAAC;IACzE,QAAQ,CAAC,uBAAuB,EAAE,SAAS,qCAAqC,EAAE,CAAC;CACpF;AAED,+FAA+F;AAC/F,oBAAY,qCAAqC;IAC/C,wGAAwG;IACxG,cAAc,kBAAkB;IAChC,oEAAoE;IACpE,yBAAyB,4BAA4B;CACtD;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,qCAAqC,EAAE,MAAM,CAAC,CAAC,CAAC;CACzF;AAoBD;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,4CAA4C,GACnD,0CAA0C,CAoB5C"}

package/dist/esm/companion/application-documentation/application-administration-documentation.js

@@ -0,0 +1,58 @@
+/**
+ * Who may perform each administrative action in THIS application.
+ *
+ * The roles page lists the roles and what each is for; it could not say which role may actually
+ * invite a person, change their access or move a team, because that lives on the operations —
+ * every one of which declares the roles it accepts. An administrator's first question ("can a
+ * manager do this, or does it need an owner?") therefore had no answer anywhere in the portal, and
+ * the pages fell back on prose about least privilege.
+ *
+ * The projection joins two things the companion already holds: the admitted operations for the
+ * membership and organization-unit resources, and the application's own role labels. It is a
+ * matrix of what this application publishes, not a restatement of the framework's defaults.
+ */
+export const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-administration';
+export const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION = 1;
+/** Named presentations a page may request with `{{APPLICATION_ADMINISTRATION:<selector>}}`. */
+export var ApplicationAdministrationPresentation;
+(function (ApplicationAdministrationPresentation) {
+    /** Membership actions — invite, change access, suspend, remove — against the roles that may do them. */
+    ApplicationAdministrationPresentation["MEMBER_ACTIONS"] = "memberActions";
+    /** Organization-unit actions against the roles that may do them. */
+    ApplicationAdministrationPresentation["ORGANIZATION_UNIT_ACTIONS"] = "organizationUnitActions";
+})(ApplicationAdministrationPresentation || (ApplicationAdministrationPresentation = {}));
+function actionsTable(actions, emptyMessage) {
+    if (actions.length === 0)
+        return emptyMessage;
+    const rows = actions
+        .map((action) => {
+        const who = action.openToEveryMember
+            ? 'Any active member of the organization'
+            : action.roleLabels.length === 0
+                ? 'Not published for organization roles'
+                : action.roleLabels.join(', ');
+        return `| ${action.action} | ${who} |`;
+    })
+        .join('\n');
+    return `| Action | Who may perform it |\n| --- | --- |\n${rows}\n\nA role higher in the inheritance chain can do everything the roles below it can, so a role that is not named here may still qualify through the role it includes. The operation contract in the API reference is authoritative for one exact call.`;
+}
+/**
+ * Projects the administrative matrix. A pure function of the source, so two runs over the same
+ * application produce identical bytes.
+ */
+export function projectApplicationAdministrationDocumentation(source) {
+    for (const action of [...source.memberActions, ...source.organizationUnitActions]) {
+        if (action.action.trim().length === 0) {
+            throw new Error('application administration projection received an action with no description');
+        }
+    }
+    return {
+        sourceRef: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF,
+        sourceVersion: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION,
+        presentations: Object.freeze({
+            [ApplicationAdministrationPresentation.MEMBER_ACTIONS]: actionsTable(source.memberActions, 'This application publishes no membership administration operations, so member access is managed outside this documentation.'),
+            [ApplicationAdministrationPresentation.ORGANIZATION_UNIT_ACTIONS]: actionsTable(source.organizationUnitActions, 'This application does not publish organization units, so there are no unit administration actions.'),
+        }),
+    };
+}
+//# sourceMappingURL=application-administration-documentation.js.map

package/dist/esm/companion/application-documentation/application-administration-documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-administration-documentation.js","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-administration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mDAAmD,GAAG,wDAAiE,CAAC;AACrI,MAAM,CAAC,MAAM,uDAAuD,GAAG,CAAC,CAAC;AAuBzE,+FAA+F;AAC/F,MAAM,CAAN,IAAY,qCAKX;AALD,WAAY,qCAAqC;IAC/C,wGAAwG;IACxG,yEAAgC,CAAA;IAChC,oEAAoE;IACpE,8FAAqD,CAAA;AACvD,CAAC,EALW,qCAAqC,KAArC,qCAAqC,QAKhD;AAQD,SAAS,YAAY,CACnB,OAAyD,EACzD,YAAoB;IAEpB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IAC9C,MAAM,IAAI,GAAG,OAAO;SACjB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACd,MAAM,GAAG,GAAG,MAAM,CAAC,iBAAiB;YAClC,CAAC,CAAC,uCAAuC;YACzC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;gBAC9B,CAAC,CAAC,sCAAsC;gBACxC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,KAAK,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC;IACzC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,mDAAmD,IAAI,wPAAwP,CAAC;AACzT,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6CAA6C,CAC3D,MAAoD;IAEpD,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,GAAG,MAAM,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAClF,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IACD,OAAO;QACL,SAAS,EAAE,mDAAmD;QAC9D,aAAa,EAAE,uDAAuD;QACtE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC;YAC3B,CAAC,qCAAqC,CAAC,cAAc,CAAC,EAAE,YAAY,CAClE,MAAM,CAAC,aAAa,EACpB,6HAA6H,CAC9H;YACD,CAAC,qCAAqC,CAAC,yBAAyB,CAAC,EAAE,YAAY,CAC7E,MAAM,CAAC,uBAAuB,EAC9B,oGAAoG,CACrG;SACF,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Who may perform each administrative action in THIS application.\n *\n * The roles page lists the roles and what each is for; it could not say which role may actually\n * invite a person, change their access or move a team, because that lives on the operations —\n * every one of which declares the roles it accepts. An administrator's first question (\"can a\n * manager do this, or does it need an owner?\") therefore had no answer anywhere in the portal, and\n * the pages fell back on prose about least privilege.\n *\n * The projection joins two things the companion already holds: the admitted operations for the\n * membership and organization-unit resources, and the application's own role labels. It is a\n * matrix of what this application publishes, not a restatement of the framework's defaults.\n */\nexport const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-administration' as const;\nexport const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION = 1;\n\nexport interface ApplicationAdministrationActionSource {\n  /** What the action does, in the words the API reference uses for the same operation. */\n  readonly action: string;\n  /**\n   * Labels of the organization roles that may perform it, in the application's own words.\n   * Empty means the operation declares no role gate — see `openToEveryMember`.\n   */\n  readonly roleLabels: readonly string[];\n  /**\n   * True when the operation declares no required role. That is a real, intentional state (any\n   * authenticated member of the organization may call it), not a gap in the projection, so it is\n   * said explicitly rather than shown as an empty cell.\n   */\n  readonly openToEveryMember: boolean;\n}\n\nexport interface ApplicationAdministrationDocumentationSource {\n  readonly memberActions: readonly ApplicationAdministrationActionSource[];\n  readonly organizationUnitActions: readonly ApplicationAdministrationActionSource[];\n}\n\n/** Named presentations a page may request with `{{APPLICATION_ADMINISTRATION:<selector>}}`. */\nexport enum ApplicationAdministrationPresentation {\n  /** Membership actions — invite, change access, suspend, remove — against the roles that may do them. */\n  MEMBER_ACTIONS = 'memberActions',\n  /** Organization-unit actions against the roles that may do them. */\n  ORGANIZATION_UNIT_ACTIONS = 'organizationUnitActions',\n}\n\nexport interface ApplicationAdministrationDocumentationFact {\n  readonly sourceRef: string;\n  readonly sourceVersion: number;\n  readonly presentations: Readonly<Record<ApplicationAdministrationPresentation, string>>;\n}\n\nfunction actionsTable(\n  actions: readonly ApplicationAdministrationActionSource[],\n  emptyMessage: string,\n): string {\n  if (actions.length === 0) return emptyMessage;\n  const rows = actions\n    .map((action) => {\n      const who = action.openToEveryMember\n        ? 'Any active member of the organization'\n        : action.roleLabels.length === 0\n          ? 'Not published for organization roles'\n          : action.roleLabels.join(', ');\n      return `| ${action.action} | ${who} |`;\n    })\n    .join('\\n');\n  return `| Action | Who may perform it |\\n| --- | --- |\\n${rows}\\n\\nA role higher in the inheritance chain can do everything the roles below it can, so a role that is not named here may still qualify through the role it includes. The operation contract in the API reference is authoritative for one exact call.`;\n}\n\n/**\n * Projects the administrative matrix. A pure function of the source, so two runs over the same\n * application produce identical bytes.\n */\nexport function projectApplicationAdministrationDocumentation(\n  source: ApplicationAdministrationDocumentationSource,\n): ApplicationAdministrationDocumentationFact {\n  for (const action of [...source.memberActions, ...source.organizationUnitActions]) {\n    if (action.action.trim().length === 0) {\n      throw new Error('application administration projection received an action with no description');\n    }\n  }\n  return {\n    sourceRef: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF,\n    sourceVersion: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION,\n    presentations: Object.freeze({\n      [ApplicationAdministrationPresentation.MEMBER_ACTIONS]: actionsTable(\n        source.memberActions,\n        'This application publishes no membership administration operations, so member access is managed outside this documentation.',\n      ),\n      [ApplicationAdministrationPresentation.ORGANIZATION_UNIT_ACTIONS]: actionsTable(\n        source.organizationUnitActions,\n        'This application does not publish organization units, so there are no unit administration actions.',\n      ),\n    }),\n  };\n}\n"]}

package/dist/esm/companion/application-documentation/application-authentication-documentation.d.ts

@@ -0,0 +1,76 @@
+import { AuthMethod } from '@wildo-ai/saas-models';
+/**
+ * What THIS application actually asks of a person signing in.
+ *
+ * The engine catalogue can only say which sign-in methods exist. Three pages printed that
+ * catalogue and warned the reader it was "not a promise", which is honest and useless: a Wonder
+ * Todos reader was shown SMS codes and external identity providers the application never enables,
+ * and was told nothing about the password rules, the lockout, the session lifetime or how many
+ * recovery codes an enrolment hands out — all of which are configured, and all of which the
+ * companion can read.
+ *
+ * Policy is per user type by construction (`UserTypeAuthPolicy`), so the projection is too. A user
+ * type is shown by its configured key, not by an invented display name: the key is what the
+ * application calls that kind of account, and there is no label source that could say otherwise.
+ */
+export declare const APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_REF: "source:companion-projection:application-authentication";
+export declare const APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_VERSION = 1;
+export interface ApplicationUserTypeAuthenticationSource {
+    /** The application's own key for this kind of account, for example `member` or `admin`. */
+    readonly userTypeKey: string;
+    /** Methods this application enables for the user type, in the engine's declaration order. */
+    readonly enabledMethods: readonly AuthMethod[];
+    readonly multifactor: {
+        readonly required: boolean;
+        readonly strongRequired: boolean;
+        readonly enrollmentGracePeriodDays: number;
+        readonly passkeyExemptFromMultifactor: boolean;
+        /** When set, the only second factors this application accepts. */
+        readonly acceptableMethods?: readonly AuthMethod[];
+    };
+    readonly password: {
+        readonly minLength: number;
+        readonly maxLength: number;
+        readonly requireUppercase: boolean;
+        readonly requireLowercase: boolean;
+        readonly requireNumbers: boolean;
+        readonly requireSpecialChars: boolean;
+        /** Days before a password must be changed. `0` means it does not expire. */
+        readonly expiryDays: number;
+    };
+    readonly session: {
+        readonly durationMinutes: number;
+        readonly maxConcurrentSessions?: number;
+    };
+    readonly lockout: {
+        readonly maxLoginAttempts: number;
+        readonly lockoutDurationMinutes: number;
+        readonly progressive: boolean;
+        readonly maxProgressiveLockoutHours: number;
+    };
+}
+export interface ApplicationAuthenticationDocumentationSource {
+    readonly userTypes: readonly ApplicationUserTypeAuthenticationSource[];
+}
+/** Named presentations a page may request with `{{APPLICATION_AUTHENTICATION:<selector>}}`. */
+export declare enum ApplicationAuthenticationPresentation {
+    /** The sign-in methods this application enables, per user type. */
+    ENABLED_SIGN_IN_METHODS = "enabledSignInMethods",
+    /** Whether a second factor is required, which ones count, and what enrolment hands out. */
+    MULTIFACTOR_POLICY = "multifactorPolicy",
+    /** The password rules a person must satisfy. */
+    PASSWORD_RULES = "passwordRules",
+    /** How long a session lasts and what a run of failed attempts costs. */
+    SESSION_AND_LOCKOUT = "sessionAndLockout"
+}
+export interface ApplicationAuthenticationDocumentationFact {
+    readonly sourceRef: string;
+    readonly sourceVersion: number;
+    readonly presentations: Readonly<Record<ApplicationAuthenticationPresentation, string>>;
+}
+/**
+ * Projects the application's authentication policy into the presentations a page may request.
+ * A pure function of the source, so two runs over the same application produce identical bytes.
+ */
+export declare function projectApplicationAuthenticationDocumentation(source: ApplicationAuthenticationDocumentationSource): ApplicationAuthenticationDocumentationFact;
+//# sourceMappingURL=application-authentication-documentation.d.ts.map

package/dist/esm/companion/application-documentation/application-authentication-documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-authentication-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-authentication-documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA8D,MAAM,uBAAuB,CAAC;AAG/G;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mDAAmD,EAAG,wDAAiE,CAAC;AACrI,eAAO,MAAM,uDAAuD,IAAI,CAAC;AAEzE,MAAM,WAAW,uCAAuC;IACtD,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,cAAc,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;QACjC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;QAC3C,QAAQ,CAAC,4BAA4B,EAAE,OAAO,CAAC;QAC/C,kEAAkE;QAClE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;KACpD,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;QACjC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;QACtC,4EAA4E;QAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;QACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;QAC9B,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;KAC7C,CAAC;CACH;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,SAAS,EAAE,SAAS,uCAAuC,EAAE,CAAC;CACxE;AAED,+FAA+F;AAC/F,oBAAY,qCAAqC;IAC/C,mEAAmE;IACnE,uBAAuB,yBAAyB;IAChD,2FAA2F;IAC3F,kBAAkB,sBAAsB;IACxC,gDAAgD;IAChD,cAAc,kBAAkB;IAChC,wEAAwE;IACxE,mBAAmB,sBAAsB;CAC1C;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,qCAAqC,EAAE,MAAM,CAAC,CAAC,CAAC;CACzF;AAoED;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,4CAA4C,GACnD,0CAA0C,CAmB5C"}

package/dist/esm/companion/application-documentation/application-authentication-documentation.js

@@ -0,0 +1,116 @@
+import { MFA_BACKUP_CODE_CHARACTER_LENGTH, MFA_BACKUP_CODE_CONTRACT } from '@wildo-ai/saas-models';
+import { authenticationMethodConsumerWords } from '@wildo-ai/saas-specifications/companion';
+/**
+ * What THIS application actually asks of a person signing in.
+ *
+ * The engine catalogue can only say which sign-in methods exist. Three pages printed that
+ * catalogue and warned the reader it was "not a promise", which is honest and useless: a Wonder
+ * Todos reader was shown SMS codes and external identity providers the application never enables,
+ * and was told nothing about the password rules, the lockout, the session lifetime or how many
+ * recovery codes an enrolment hands out — all of which are configured, and all of which the
+ * companion can read.
+ *
+ * Policy is per user type by construction (`UserTypeAuthPolicy`), so the projection is too. A user
+ * type is shown by its configured key, not by an invented display name: the key is what the
+ * application calls that kind of account, and there is no label source that could say otherwise.
+ */
+export const APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-authentication';
+export const APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_VERSION = 1;
+/** Named presentations a page may request with `{{APPLICATION_AUTHENTICATION:<selector>}}`. */
+export var ApplicationAuthenticationPresentation;
+(function (ApplicationAuthenticationPresentation) {
+    /** The sign-in methods this application enables, per user type. */
+    ApplicationAuthenticationPresentation["ENABLED_SIGN_IN_METHODS"] = "enabledSignInMethods";
+    /** Whether a second factor is required, which ones count, and what enrolment hands out. */
+    ApplicationAuthenticationPresentation["MULTIFACTOR_POLICY"] = "multifactorPolicy";
+    /** The password rules a person must satisfy. */
+    ApplicationAuthenticationPresentation["PASSWORD_RULES"] = "passwordRules";
+    /** How long a session lasts and what a run of failed attempts costs. */
+    ApplicationAuthenticationPresentation["SESSION_AND_LOCKOUT"] = "sessionAndLockout";
+})(ApplicationAuthenticationPresentation || (ApplicationAuthenticationPresentation = {}));
+function methodNames(methods) {
+    if (methods.length === 0)
+        return 'None';
+    return methods.map((method) => authenticationMethodConsumerWords(method).name).join(', ');
+}
+function userTypeCell(userType) {
+    return `\`${userType.userTypeKey}\``;
+}
+function enabledSignInMethodsMarkdown(source) {
+    const rows = source.userTypes
+        .map((userType) => `| ${userTypeCell(userType)} | ${methodNames(userType.enabledMethods)} |`)
+        .join('\n');
+    return `| Account kind | Sign-in methods this application enables |\n| --- | --- |\n${rows}\n\nAn organization can narrow this further for its own people — for example by requiring its single sign-on — so the sign-in screen remains the last word on what you can use right now.`;
+}
+function multifactorPolicyMarkdown(source) {
+    const rows = source.userTypes.map((userType) => {
+        const { multifactor } = userType;
+        const required = multifactor.required
+            ? multifactor.strongRequired ? 'Required, and a phishing-resistant method is required' : 'Required'
+            : 'Optional';
+        const grace = multifactor.required && multifactor.enrollmentGracePeriodDays > 0
+            ? `${multifactor.enrollmentGracePeriodDays} day${multifactor.enrollmentGracePeriodDays === 1 ? '' : 's'} to enrol`
+            : multifactor.required ? 'No grace period' : '—';
+        const accepted = multifactor.acceptableMethods === undefined
+            ? 'Any second factor enabled above'
+            : methodNames(multifactor.acceptableMethods);
+        const passkey = multifactor.passkeyExemptFromMultifactor ? 'Yes' : 'No';
+        return `| ${userTypeCell(userType)} | ${required} | ${grace} | ${accepted} | ${passkey} |`;
+    }).join('\n');
+    const codes = `Enrolling an authenticator app also hands you **${MFA_BACKUP_CODE_CONTRACT.codeCount} recovery codes** of ${MFA_BACKUP_CODE_CHARACTER_LENGTH} characters each. ${MFA_BACKUP_CODE_CONTRACT.singleUse ? 'Each code works once and is gone when used' : 'Codes may be reused'}; the application stores only a hash of them, so nobody can read them back to you. Enrolling again replaces the whole set.`;
+    return `| Account kind | Second factor | Enrolment window | Accepted as a second factor | Passkey counts on its own |\n| --- | --- | --- | --- | --- |\n${rows}\n\n${codes}`;
+}
+function passwordRulesMarkdown(source) {
+    const rows = source.userTypes.map((userType) => {
+        const { password } = userType;
+        const classes = [
+            password.requireUppercase ? 'an uppercase letter' : null,
+            password.requireLowercase ? 'a lowercase letter' : null,
+            password.requireNumbers ? 'a digit' : null,
+            password.requireSpecialChars ? 'a special character' : null,
+        ].filter((requirement) => requirement !== null);
+        const composition = classes.length === 0 ? 'No character requirement' : `Must contain ${classes.join(', ')}`;
+        const expiry = password.expiryDays > 0 ? `Every ${password.expiryDays} days` : 'Never expires';
+        return `| ${userTypeCell(userType)} | ${password.minLength}–${password.maxLength} characters | ${composition} | ${expiry} |`;
+    }).join('\n');
+    return `| Account kind | Length | Composition | Change required |\n| --- | --- | --- | --- |\n${rows}`;
+}
+function sessionAndLockoutMarkdown(source) {
+    const rows = source.userTypes.map((userType) => {
+        const { session, lockout } = userType;
+        const concurrent = session.maxConcurrentSessions === undefined
+            ? 'Not limited'
+            : `${session.maxConcurrentSessions} at a time`;
+        const progressive = lockout.progressive
+            ? `, lengthening with each further run up to ${lockout.maxProgressiveLockoutHours} hours`
+            : '';
+        const lock = `${lockout.maxLoginAttempts} failed attempts lock the account for ${lockout.lockoutDurationMinutes} minutes${progressive}`;
+        return `| ${userTypeCell(userType)} | ${session.durationMinutes} minutes | ${concurrent} | ${lock} |`;
+    }).join('\n');
+    return `| Account kind | Session lasts | Concurrent sessions | Failed sign-ins |\n| --- | --- | --- | --- |\n${rows}\n\nA session ends when its time runs out, when you sign out, or when the application invalidates it — changing a password does exactly that, on every device.`;
+}
+/**
+ * Projects the application's authentication policy into the presentations a page may request.
+ * A pure function of the source, so two runs over the same application produce identical bytes.
+ */
+export function projectApplicationAuthenticationDocumentation(source) {
+    if (source.userTypes.length === 0) {
+        throw new Error('application authentication projection requires at least one declared user type');
+    }
+    for (const userType of source.userTypes) {
+        if (userType.userTypeKey.trim().length === 0) {
+            throw new Error('application authentication projection received a user type with no key');
+        }
+    }
+    return {
+        sourceRef: APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_REF,
+        sourceVersion: APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_VERSION,
+        presentations: Object.freeze({
+            [ApplicationAuthenticationPresentation.ENABLED_SIGN_IN_METHODS]: enabledSignInMethodsMarkdown(source),
+            [ApplicationAuthenticationPresentation.MULTIFACTOR_POLICY]: multifactorPolicyMarkdown(source),
+            [ApplicationAuthenticationPresentation.PASSWORD_RULES]: passwordRulesMarkdown(source),
+            [ApplicationAuthenticationPresentation.SESSION_AND_LOCKOUT]: sessionAndLockoutMarkdown(source),
+        }),
+    };
+}
+//# sourceMappingURL=application-authentication-documentation.js.map

package/dist/esm/companion/application-documentation/application-authentication-documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-authentication-documentation.js","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-authentication-documentation.ts"],"names":[],"mappings":"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","sourcesContent":["import { AuthMethod, MFA_BACKUP_CODE_CHARACTER_LENGTH, MFA_BACKUP_CODE_CONTRACT } from '@wildo-ai/saas-models';\nimport { authenticationMethodConsumerWords } from '@wildo-ai/saas-specifications/companion';\n\n/**\n * What THIS application actually asks of a person signing in.\n *\n * The engine catalogue can only say which sign-in methods exist. Three pages printed that\n * catalogue and warned the reader it was \"not a promise\", which is honest and useless: a Wonder\n * Todos reader was shown SMS codes and external identity providers the application never enables,\n * and was told nothing about the password rules, the lockout, the session lifetime or how many\n * recovery codes an enrolment hands out — all of which are configured, and all of which the\n * companion can read.\n *\n * Policy is per user type by construction (`UserTypeAuthPolicy`), so the projection is too. A user\n * type is shown by its configured key, not by an invented display name: the key is what the\n * application calls that kind of account, and there is no label source that could say otherwise.\n */\nexport const APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-authentication' as const;\nexport const APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_VERSION = 1;\n\nexport interface ApplicationUserTypeAuthenticationSource {\n  /** The application's own key for this kind of account, for example `member` or `admin`. */\n  readonly userTypeKey: string;\n  /** Methods this application enables for the user type, in the engine's declaration order. */\n  readonly enabledMethods: readonly AuthMethod[];\n  readonly multifactor: {\n    readonly required: boolean;\n    readonly strongRequired: boolean;\n    readonly enrollmentGracePeriodDays: number;\n    readonly passkeyExemptFromMultifactor: boolean;\n    /** When set, the only second factors this application accepts. */\n    readonly acceptableMethods?: readonly AuthMethod[];\n  };\n  readonly password: {\n    readonly minLength: number;\n    readonly maxLength: number;\n    readonly requireUppercase: boolean;\n    readonly requireLowercase: boolean;\n    readonly requireNumbers: boolean;\n    readonly requireSpecialChars: boolean;\n    /** Days before a password must be changed. `0` means it does not expire. */\n    readonly expiryDays: number;\n  };\n  readonly session: {\n    readonly durationMinutes: number;\n    readonly maxConcurrentSessions?: number;\n  };\n  readonly lockout: {\n    readonly maxLoginAttempts: number;\n    readonly lockoutDurationMinutes: number;\n    readonly progressive: boolean;\n    readonly maxProgressiveLockoutHours: number;\n  };\n}\n\nexport interface ApplicationAuthenticationDocumentationSource {\n  readonly userTypes: readonly ApplicationUserTypeAuthenticationSource[];\n}\n\n/** Named presentations a page may request with `{{APPLICATION_AUTHENTICATION:<selector>}}`. */\nexport enum ApplicationAuthenticationPresentation {\n  /** The sign-in methods this application enables, per user type. */\n  ENABLED_SIGN_IN_METHODS = 'enabledSignInMethods',\n  /** Whether a second factor is required, which ones count, and what enrolment hands out. */\n  MULTIFACTOR_POLICY = 'multifactorPolicy',\n  /** The password rules a person must satisfy. */\n  PASSWORD_RULES = 'passwordRules',\n  /** How long a session lasts and what a run of failed attempts costs. */\n  SESSION_AND_LOCKOUT = 'sessionAndLockout',\n}\n\nexport interface ApplicationAuthenticationDocumentationFact {\n  readonly sourceRef: string;\n  readonly sourceVersion: number;\n  readonly presentations: Readonly<Record<ApplicationAuthenticationPresentation, string>>;\n}\n\nfunction methodNames(methods: readonly AuthMethod[]): string {\n  if (methods.length === 0) return 'None';\n  return methods.map((method) => authenticationMethodConsumerWords(method).name).join(', ');\n}\n\nfunction userTypeCell(userType: ApplicationUserTypeAuthenticationSource): string {\n  return `\\`${userType.userTypeKey}\\``;\n}\n\nfunction enabledSignInMethodsMarkdown(source: ApplicationAuthenticationDocumentationSource): string {\n  const rows = source.userTypes\n    .map((userType) => `| ${userTypeCell(userType)} | ${methodNames(userType.enabledMethods)} |`)\n    .join('\\n');\n  return `| Account kind | Sign-in methods this application enables |\\n| --- | --- |\\n${rows}\\n\\nAn organization can narrow this further for its own people — for example by requiring its single sign-on — so the sign-in screen remains the last word on what you can use right now.`;\n}\n\nfunction multifactorPolicyMarkdown(source: ApplicationAuthenticationDocumentationSource): string {\n  const rows = source.userTypes.map((userType) => {\n    const { multifactor } = userType;\n    const required = multifactor.required\n      ? multifactor.strongRequired ? 'Required, and a phishing-resistant method is required' : 'Required'\n      : 'Optional';\n    const grace = multifactor.required && multifactor.enrollmentGracePeriodDays > 0\n      ? `${multifactor.enrollmentGracePeriodDays} day${multifactor.enrollmentGracePeriodDays === 1 ? '' : 's'} to enrol`\n      : multifactor.required ? 'No grace period' : '—';\n    const accepted = multifactor.acceptableMethods === undefined\n      ? 'Any second factor enabled above'\n      : methodNames(multifactor.acceptableMethods);\n    const passkey = multifactor.passkeyExemptFromMultifactor ? 'Yes' : 'No';\n    return `| ${userTypeCell(userType)} | ${required} | ${grace} | ${accepted} | ${passkey} |`;\n  }).join('\\n');\n  const codes = `Enrolling an authenticator app also hands you **${MFA_BACKUP_CODE_CONTRACT.codeCount} recovery codes** of ${MFA_BACKUP_CODE_CHARACTER_LENGTH} characters each. ${MFA_BACKUP_CODE_CONTRACT.singleUse ? 'Each code works once and is gone when used' : 'Codes may be reused'}; the application stores only a hash of them, so nobody can read them back to you. Enrolling again replaces the whole set.`;\n  return `| Account kind | Second factor | Enrolment window | Accepted as a second factor | Passkey counts on its own |\\n| --- | --- | --- | --- | --- |\\n${rows}\\n\\n${codes}`;\n}\n\nfunction passwordRulesMarkdown(source: ApplicationAuthenticationDocumentationSource): string {\n  const rows = source.userTypes.map((userType) => {\n    const { password } = userType;\n    const classes = [\n      password.requireUppercase ? 'an uppercase letter' : null,\n      password.requireLowercase ? 'a lowercase letter' : null,\n      password.requireNumbers ? 'a digit' : null,\n      password.requireSpecialChars ? 'a special character' : null,\n    ].filter((requirement): requirement is string => requirement !== null);\n    const composition = classes.length === 0 ? 'No character requirement' : `Must contain ${classes.join(', ')}`;\n    const expiry = password.expiryDays > 0 ? `Every ${password.expiryDays} days` : 'Never expires';\n    return `| ${userTypeCell(userType)} | ${password.minLength}–${password.maxLength} characters | ${composition} | ${expiry} |`;\n  }).join('\\n');\n  return `| Account kind | Length | Composition | Change required |\\n| --- | --- | --- | --- |\\n${rows}`;\n}\n\nfunction sessionAndLockoutMarkdown(source: ApplicationAuthenticationDocumentationSource): string {\n  const rows = source.userTypes.map((userType) => {\n    const { session, lockout } = userType;\n    const concurrent = session.maxConcurrentSessions === undefined\n      ? 'Not limited'\n      : `${session.maxConcurrentSessions} at a time`;\n    const progressive = lockout.progressive\n      ? `, lengthening with each further run up to ${lockout.maxProgressiveLockoutHours} hours`\n      : '';\n    const lock = `${lockout.maxLoginAttempts} failed attempts lock the account for ${lockout.lockoutDurationMinutes} minutes${progressive}`;\n    return `| ${userTypeCell(userType)} | ${session.durationMinutes} minutes | ${concurrent} | ${lock} |`;\n  }).join('\\n');\n  return `| Account kind | Session lasts | Concurrent sessions | Failed sign-ins |\\n| --- | --- | --- | --- |\\n${rows}\\n\\nA session ends when its time runs out, when you sign out, or when the application invalidates it — changing a password does exactly that, on every device.`;\n}\n\n/**\n * Projects the application's authentication policy into the presentations a page may request.\n * A pure function of the source, so two runs over the same application produce identical bytes.\n */\nexport function projectApplicationAuthenticationDocumentation(\n  source: ApplicationAuthenticationDocumentationSource,\n): ApplicationAuthenticationDocumentationFact {\n  if (source.userTypes.length === 0) {\n    throw new Error('application authentication projection requires at least one declared user type');\n  }\n  for (const userType of source.userTypes) {\n    if (userType.userTypeKey.trim().length === 0) {\n      throw new Error('application authentication projection received a user type with no key');\n    }\n  }\n  return {\n    sourceRef: APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_REF,\n    sourceVersion: APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_VERSION,\n    presentations: Object.freeze({\n      [ApplicationAuthenticationPresentation.ENABLED_SIGN_IN_METHODS]: enabledSignInMethodsMarkdown(source),\n      [ApplicationAuthenticationPresentation.MULTIFACTOR_POLICY]: multifactorPolicyMarkdown(source),\n      [ApplicationAuthenticationPresentation.PASSWORD_RULES]: passwordRulesMarkdown(source),\n      [ApplicationAuthenticationPresentation.SESSION_AND_LOCKOUT]: sessionAndLockoutMarkdown(source),\n    }),\n  };\n}\n"]}

package/dist/esm/companion/application-documentation/application-connection-documentation.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The application's own name and the addresses an integrator connects to.
+ *
+ * Engine documentation is written once for every generated application, so it
+ * used to hedge everything an application knows about itself: "the server origin
+ * from this application's API reference", "the address published for this
+ * environment", "the application". Every one of those values is available to the
+ * companion at derivation time, and this projection is how they reach the page.
+ *
+ * The split is deliberate. The APPLICATION supplies what only it knows — its
+ * customer-facing name and the base URLs it publishes. The ENGINE supplies the
+ * paths, because a route is the engine's own contract and an application that
+ * restated it would hold a second copy that can drift (see
+ * `MANUAL_CONTROLLER_ROUTES_URLS`, whose values are mounted under
+ * `MAIN_API_BASE_PATH`). An endpoint appears only when the companion has
+ * observed that the application configures that surface, so a page never
+ * advertises a door this application does not open.
+ */
+export declare const APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_REF: "source:companion-projection:application-connection";
+export declare const APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_VERSION = 1;
+/** One base URL an application publishes for an environment a reader may call. */
+export interface ApplicationConnectionServer {
+    readonly url: string;
+    readonly description?: string;
+}
+/**
+ * What the companion measures about this application. `surfaces` mirrors the
+ * evidence the derivation already computes for applicability gating: the same
+ * observation that decides whether the MCP pages are published decides whether
+ * the MCP endpoint is printed, so a published address and a published page can
+ * never disagree.
+ */
+export interface ApplicationConnectionDocumentationSource {
+    /** The name customers see. The application's `displayName`, else its `appName`. */
+    readonly applicationName: string;
+    /** Base URLs the application publishes, in the order it authored them. Possibly empty. */
+    readonly apiServers: readonly ApplicationConnectionServer[];
+    readonly surfaces: {
+        readonly mcpToolServer: boolean;
+        readonly a2aAgent: boolean;
+    };
+}
+/** Named presentations a page may request with `{{APPLICATION_CONNECTION:<selector>}}`. */
+export declare enum ApplicationConnectionPresentation {
+    /** Every connection detail as one table: base URLs, the API mount, agent endpoints. */
+    CONNECTION_DETAILS = "connectionDetails",
+    /** The base URLs alone, for a page that only needs to say where requests go. */
+    BASE_URLS = "baseUrls",
+    /**
+     * The MCP endpoint sentence. Never empty: an application that exposes no MCP surface gets a
+     * sentence saying so. Projection runs for every unit and gating happens afterwards, so a
+     * presentation that rendered nothing would leave a blank where a suppressed page's prose was,
+     * and would say nothing at all if the page were ever published without its gate.
+     */
+    MCP_ENDPOINT = "mcpEndpoint",
+    /** The A2A agent-card sentence. Never empty, for the same reason as the MCP endpoint. */
+    A2A_AGENT_CARD = "a2aAgentCard"
+}
+/**
+ * Values a page substitutes INSIDE a sample — a JSON client configuration, an HTTP request line —
+ * where a block presentation cannot go. Each is a single string, never markdown.
+ */
+export declare enum ApplicationConnectionInlineValue {
+    /** The first base URL the application publishes, or an explicit stand-in when it publishes none. */
+    BASE_URL = "baseUrl",
+    /** The full MCP endpoint URL a client configures. */
+    MCP_ENDPOINT_URL = "mcpEndpointUrl",
+    /** The full agent-card URL an A2A peer fetches. */
+    AGENT_CARD_URL = "agentCardUrl",
+    /** The full A2A task endpoint URL. */
+    AGENT_TASK_URL = "agentTaskUrl"
+}
+export interface ApplicationConnectionDocumentationFact {
+    readonly sourceRef: string;
+    readonly sourceVersion: number;
+    /** Substituted wherever a page writes the inline application-name token. */
+    readonly applicationName: string;
+    readonly presentations: Readonly<Record<ApplicationConnectionPresentation, string>>;
+    readonly inlineValues: Readonly<Record<ApplicationConnectionInlineValue, string>>;
+}
+/**
+ * Projects the application's connection facts into the presentations a page may
+ * request. Every presentation is a pure function of the source, so two runs over
+ * the same application produce identical bytes.
+ */
+export declare function projectApplicationConnectionDocumentation(source: ApplicationConnectionDocumentationSource): ApplicationConnectionDocumentationFact;
+//# sourceMappingURL=application-connection-documentation.d.ts.map

package/dist/esm/companion/application-documentation/application-connection-documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-connection-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-connection-documentation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,+CAA+C,EAAG,oDAA6D,CAAC;AAC7H,eAAO,MAAM,mDAAmD,IAAI,CAAC;AAErE,kFAAkF;AAClF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wCAAwC;IACvD,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,2FAA2F;AAC3F,oBAAY,iCAAiC;IAC3C,uFAAuF;IACvF,kBAAkB,sBAAsB;IACxC,gFAAgF;IAChF,SAAS,aAAa;IACtB;;;;;OAKG;IACH,YAAY,gBAAgB;IAC5B,yFAAyF;IACzF,cAAc,iBAAiB;CAChC;AAED;;;GAGG;AACH,oBAAY,gCAAgC;IAC1C,oGAAoG;IACpG,QAAQ,YAAY;IACpB,qDAAqD;IACrD,gBAAgB,mBAAmB;IACnC,mDAAmD;IACnD,cAAc,iBAAiB;IAC/B,sCAAsC;IACtC,cAAc,iBAAiB;CAChC;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,iCAAiC,EAAE,MAAM,CAAC,CAAC,CAAC;IACpF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,gCAAgC,EAAE,MAAM,CAAC,CAAC,CAAC;CACnF;AA0DD;;;;GAIG;AACH,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,wCAAwC,GAC/C,sCAAsC,CAwBxC"}

package/dist/esm/companion/application-documentation/application-connection-documentation.js

@@ -0,0 +1,138 @@
+import { MAIN_API_BASE_PATH, MANUAL_CONTROLLER_ROUTES_URLS, ManualControllerRouteKey } from '@wildo-ai/saas-models';
+/**
+ * The application's own name and the addresses an integrator connects to.
+ *
+ * Engine documentation is written once for every generated application, so it
+ * used to hedge everything an application knows about itself: "the server origin
+ * from this application's API reference", "the address published for this
+ * environment", "the application". Every one of those values is available to the
+ * companion at derivation time, and this projection is how they reach the page.
+ *
+ * The split is deliberate. The APPLICATION supplies what only it knows — its
+ * customer-facing name and the base URLs it publishes. The ENGINE supplies the
+ * paths, because a route is the engine's own contract and an application that
+ * restated it would hold a second copy that can drift (see
+ * `MANUAL_CONTROLLER_ROUTES_URLS`, whose values are mounted under
+ * `MAIN_API_BASE_PATH`). An endpoint appears only when the companion has
+ * observed that the application configures that surface, so a page never
+ * advertises a door this application does not open.
+ */
+export const APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-connection';
+export const APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_VERSION = 1;
+/** Named presentations a page may request with `{{APPLICATION_CONNECTION:<selector>}}`. */
+export var ApplicationConnectionPresentation;
+(function (ApplicationConnectionPresentation) {
+    /** Every connection detail as one table: base URLs, the API mount, agent endpoints. */
+    ApplicationConnectionPresentation["CONNECTION_DETAILS"] = "connectionDetails";
+    /** The base URLs alone, for a page that only needs to say where requests go. */
+    ApplicationConnectionPresentation["BASE_URLS"] = "baseUrls";
+    /**
+     * The MCP endpoint sentence. Never empty: an application that exposes no MCP surface gets a
+     * sentence saying so. Projection runs for every unit and gating happens afterwards, so a
+     * presentation that rendered nothing would leave a blank where a suppressed page's prose was,
+     * and would say nothing at all if the page were ever published without its gate.
+     */
+    ApplicationConnectionPresentation["MCP_ENDPOINT"] = "mcpEndpoint";
+    /** The A2A agent-card sentence. Never empty, for the same reason as the MCP endpoint. */
+    ApplicationConnectionPresentation["A2A_AGENT_CARD"] = "a2aAgentCard";
+})(ApplicationConnectionPresentation || (ApplicationConnectionPresentation = {}));
+/**
+ * Values a page substitutes INSIDE a sample — a JSON client configuration, an HTTP request line —
+ * where a block presentation cannot go. Each is a single string, never markdown.
+ */
+export var ApplicationConnectionInlineValue;
+(function (ApplicationConnectionInlineValue) {
+    /** The first base URL the application publishes, or an explicit stand-in when it publishes none. */
+    ApplicationConnectionInlineValue["BASE_URL"] = "baseUrl";
+    /** The full MCP endpoint URL a client configures. */
+    ApplicationConnectionInlineValue["MCP_ENDPOINT_URL"] = "mcpEndpointUrl";
+    /** The full agent-card URL an A2A peer fetches. */
+    ApplicationConnectionInlineValue["AGENT_CARD_URL"] = "agentCardUrl";
+    /** The full A2A task endpoint URL. */
+    ApplicationConnectionInlineValue["AGENT_TASK_URL"] = "agentTaskUrl";
+})(ApplicationConnectionInlineValue || (ApplicationConnectionInlineValue = {}));
+/** A manual route as a reader must call it: the mount plus the engine-owned path segment. */
+function publicRoutePath(routeKey) {
+    return `${MAIN_API_BASE_PATH}${MANUAL_CONTROLLER_ROUTES_URLS[routeKey]}`;
+}
+function baseUrlsMarkdown(source) {
+    if (source.apiServers.length === 0) {
+        // Honest rather than invented: an application that publishes no base URL cannot have one
+        // printed for it, and the reader is told where the answer actually lives.
+        return `${source.applicationName} does not publish its base URLs in this documentation. Read them from the **Servers** list at the top of the API reference, or ask whoever operates the environment you are calling.`;
+    }
+    const rows = source.apiServers
+        .map((server) => `| \`${server.url}\` | ${server.description ?? 'Published base URL'} |`)
+        .join('\n');
+    return `| Base URL | Environment |\n| --- | --- |\n${rows}`;
+}
+function mcpEndpointMarkdown(source) {
+    if (!source.surfaces.mcpToolServer)
+        return `${source.applicationName} does not publish a Model Context Protocol endpoint.`;
+    return `${source.applicationName} serves its Model Context Protocol endpoint at \`${publicRoutePath(ManualControllerRouteKey.MCP_ENDPOINT)}\`, under the base URL of the environment you are connecting to.`;
+}
+function a2aAgentCardMarkdown(source) {
+    if (!source.surfaces.a2aAgent)
+        return `${source.applicationName} does not publish an agent card.`;
+    return `${source.applicationName} publishes its agent card at \`${publicRoutePath(ManualControllerRouteKey.A2A_AGENT_CARD)}\` and accepts task calls at \`${publicRoutePath(ManualControllerRouteKey.A2A_TASKS)}\`, under the base URL of the environment you are connecting to.`;
+}
+function connectionDetailsMarkdown(source) {
+    const rows = [];
+    for (const server of source.apiServers) {
+        rows.push(`| Base URL${server.description === undefined ? '' : ` (${server.description})`} | \`${server.url}\` |`);
+    }
+    rows.push(`| API mount | \`${MAIN_API_BASE_PATH}\` — every path in the API reference already includes it |`);
+    if (source.surfaces.mcpToolServer) {
+        rows.push(`| MCP endpoint | \`${publicRoutePath(ManualControllerRouteKey.MCP_ENDPOINT)}\` |`);
+    }
+    if (source.surfaces.a2aAgent) {
+        rows.push(`| A2A agent card | \`${publicRoutePath(ManualControllerRouteKey.A2A_AGENT_CARD)}\` |`);
+        rows.push(`| A2A task endpoint | \`${publicRoutePath(ManualControllerRouteKey.A2A_TASKS)}\` |`);
+    }
+    const table = `| What | Value |\n| --- | --- |\n${rows.join('\n')}`;
+    return source.apiServers.length > 0
+        ? table
+        : `${table}\n\nThis application publishes no base URL here; read it from the **Servers** list at the top of the API reference.`;
+}
+/**
+ * The origin a sample should show. An application that publishes no base URL gets an explicit
+ * stand-in rather than a fabricated host: the reader must substitute their own environment, and the
+ * sample says so in the place where the value belongs.
+ */
+function primaryBaseUrl(source) {
+    const first = source.apiServers[0];
+    return first === undefined ? 'https://your-environment.example' : first.url.replace(/\/+$/, '');
+}
+/**
+ * Projects the application's connection facts into the presentations a page may
+ * request. Every presentation is a pure function of the source, so two runs over
+ * the same application produce identical bytes.
+ */
+export function projectApplicationConnectionDocumentation(source) {
+    const applicationName = source.applicationName.trim();
+    if (applicationName.length === 0)
+        throw new Error('application connection projection requires a customer-facing application name');
+    for (const server of source.apiServers) {
+        if (server.url.trim().length === 0)
+            throw new Error('application connection projection received an empty base URL');
+    }
+    const named = { ...source, applicationName };
+    return {
+        sourceRef: APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_REF,
+        sourceVersion: APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_VERSION,
+        applicationName,
+        presentations: Object.freeze({
+            [ApplicationConnectionPresentation.CONNECTION_DETAILS]: connectionDetailsMarkdown(named),
+            [ApplicationConnectionPresentation.BASE_URLS]: baseUrlsMarkdown(named),
+            [ApplicationConnectionPresentation.MCP_ENDPOINT]: mcpEndpointMarkdown(named),
+            [ApplicationConnectionPresentation.A2A_AGENT_CARD]: a2aAgentCardMarkdown(named),
+        }),
+        inlineValues: Object.freeze({
+            [ApplicationConnectionInlineValue.BASE_URL]: primaryBaseUrl(named),
+            [ApplicationConnectionInlineValue.MCP_ENDPOINT_URL]: `${primaryBaseUrl(named)}${publicRoutePath(ManualControllerRouteKey.MCP_ENDPOINT)}`,
+            [ApplicationConnectionInlineValue.AGENT_CARD_URL]: `${primaryBaseUrl(named)}${publicRoutePath(ManualControllerRouteKey.A2A_AGENT_CARD)}`,
+            [ApplicationConnectionInlineValue.AGENT_TASK_URL]: `${primaryBaseUrl(named)}${publicRoutePath(ManualControllerRouteKey.A2A_TASKS)}`,
+        }),
+    };
+}
+//# sourceMappingURL=application-connection-documentation.js.map