@aifabrix/builder 2.52.1 → 2.53.1

package/templates/channels/microsoft-copilot/install.template.md.hbs

@@ -12,24 +12,67 @@ apply for the Runtime MCP delegated scope.
 dist/channels/microsoft-copilot/source/manifest.json
 dist/channels/microsoft-copilot/source/declarativeAgent.json
 dist/channels/microsoft-copilot/source/ai-plugin.json
+dist/channels/microsoft-copilot/source/fi-fi.json
 dist/channels/microsoft-copilot/build/appPackage.{{environment}}.zip
 ```
 
-## Install in Microsoft Teams
+## Three Microsoft records (do not confuse)
 
-1. Open Microsoft Teams using your target Microsoft 365 account.
-2. Select **Apps → Manage your apps**.
-3. Select **Upload an app → Upload a custom app**.
-4. Upload `appPackage.{{environment}}.zip`.
-5. Review the requested permissions and select **Add**.
-6. Open **{{appName}}** from your installed apps.
-7. If prompted, complete **Entra / admin consent** for the Runtime MCP resource (not an AI Fabrix OAuth client login).
+| Record | What it is | Typical ID |
+| --- | --- | --- |
+| **Entra app registration** | Protects the Runtime MCP API. **Client (application) ID** from Entra / Keycloak Trust. | Entra Client (application) ID |
+| **Teams Developer Portal app** | Package definition (`manifest.json.id`) and organisation publish request. | Teams app / manifest ID |
+| **Teams admin centre catalogue** | Approval, availability, policy, published state. | Catalogue entry after org publish |
 
-Upload only the ZIP package. Do not upload individual manifest files or `channel-microsoft-copilot.json`.
+`--oauth-plugin-vault-reference-id` is the **Teams Entra SSO registration / auth-config ID** from Developer Portal Tools → Microsoft Entra SSO. It is **not** the Entra Client (application) ID and **not** a client secret.
 
-If **Upload a custom app** is unavailable, a Teams administrator must enable custom app uploads for your account in the Teams admin center or deploy the package centrally.
+Do **not** configure AI Fabrix OAuth client secrets under Connected Systems → Authentication for this Entra SSO flow.
 
-Do **not** configure AI Fabrix OAuth client secrets in Connected Systems → Authentication for this flow. Entra SSO uses the Teams OAuthPluginVault auth-config id.
+## Package prerequisites (before Import)
+
+1. Generate the channel package with `aifabrix channel add microsoft-copilot`.
+2. Configure Microsoft Entra SSO: **Tools → Microsoft Entra SSO client ID registration** (see table below). Copy the generated registration / auth-config ID.
+3. Re-run packaging so `ai-plugin.json` gets `auth.type = OAuthPluginVault` and `auth.reference_id = <auth-config-id>`:
+
+```bash
+aifabrix channel add microsoft-copilot --name "{{baseName}}" --oauth-plugin-vault-reference-id "<auth-config-id>"
+```
+
+Keep any `webApplicationInfo` the portal binds for Entra SSO — do not strip it on re-import.
+
+Upload **only** the ZIP package. Do not upload individual source files or `channel-microsoft-copilot.json`.
+
+## Install and publish
+
+1. Open [Teams Developer Portal](https://dev.teams.microsoft.com/).
+2. Click **Import an app** → import `appPackage.{{environment}}.zip`. Preserve the generated stable `manifest.json.id`. Do not create an unrelated new Teams app.
+3. Developer Portal → selected app → **Publish to your org** → Distribute / submit.
+4. Teams admin approves in [Teams admin centre → Manage apps](https://admin.teams.microsoft.com/policies/manage-apps) (Manage apps → search → allow). Expect **Published** / **Unblocked** per organisation policy. Allow several minutes for propagation.
+5. Open **Teams** → **Apps** (**Built for your org**), click **{{appName}}**, **Add** the application, then choose **Open with Copilot**.
+6. In Copilot, click **Show my role assistants** and run the command.
+7. Confirm Runtime MCP and governed tools using this guide, then re-run with `--probe` after organisation publish:
+
+```bash
+aifabrix channel add {{channelTarget}} --name "{{baseName}}" --oauth-plugin-vault-reference-id "{{{oauthPluginVaultReferenceId}}}" --probe
+```
+
+8. After the app is available under **Built for your org**, re-run:
+
+```bash
+aifabrix channel add {{channelTarget}} --name "{{appName}}"
+```
+
+This is a **tenant-private organisation publish**. Microsoft Store app validation is not the Runtime/MCP functional test for this integration.
+
+Do **not** use Developer Portal **Preview in Teams** as the normal organisation installation test (it sideloads and may be blocked by tenant policy).
+
+### Optional sideloading for development
+
+Use **Upload a custom app** or **Preview in Teams** only if tenant policy permits custom app uploads. Sideloading is **not** required for central organisation publishing. A policy failure such as “Uploading custom apps is not allowed” does **not** mean the organisation-published package is invalid.
+
+## Activate languages
+
+The package includes `localizationInfo` with **en-us** (default) and **fi-fi** (`fi-fi.json`). After import in Developer Portal, open the app → **Languages** (or localization) and **activate** additional languages you need for the organisation. Re-import an updated ZIP if you regenerate translations.
 
 ## Runtime connection contract
 
@@ -37,10 +80,11 @@ Do **not** configure AI Fabrix OAuth client secrets in Connected Systems → Aut
 - **Remote MCP URL:** `{{{mcpUrl}}}`
 - **Transport:** `{{runtimeTransport}}`
 - **Auth mode:** `{{runtimeAuthMode}}` (Entra SSO / trustedIssuer; controller exchanges the Microsoft user token)
-- **Plugin auth:** `OAuthPluginVault` · Teams auth-config reference id `{{oauthPluginVaultReferenceId}}`
+- **Plugin auth:** `OAuthPluginVault` · Teams auth-config reference id `{{{oauthPluginVaultReferenceId}}}`
 {{#if entraIssuer}}- **Entra issuer (from Trust source):** `{{{entraIssuer}}}`{{/if}}
-- **Delegated scopes:** {{#each scopes}}`{{this}}` {{else}}*(missing — package not install-ready)*{{/each}}
-- **Install ready:** {{#if installReady}}yes{{else}}no{{#if discoveryBlocker}} ({{discoveryBlocker}}){{/if}}{{/if}}
+- **Delegated scopes:** {{#if entraSsoScope}}`{{entraSsoScope}}`{{else}}{{#each scopes}}`{{this}}` {{else}}*(set Runtime MCP delegated scopes on Trust source `microsoft-entra-id` `allowedScopes` — not openid/profile alone)*{{/each}}{{/if}}
+- **Package / Runtime ready:** {{#if packageReady}}yes{{else}}no{{#if packageBlocker}} ({{packageBlocker}}){{/if}}{{/if}}
+- **Microsoft publication:** {{#if microsoftPublicationPending}}pending — Developer Portal import → Publish to your org → Teams admin approval{{else}}cleared{{/if}}
 - **Governed tools expected:**
 {{#each layerBToolNames}}
   - `{{this}}`
@@ -52,6 +96,7 @@ Do **not** configure AI Fabrix OAuth client secrets in Connected Systems → Aut
 
 - README / install guide: `INSTALL.md`
 - Package ZIP: `build/appPackage.{{environment}}.zip`
+
 ## Assistant catalog
 
 Runtime lists the assistants available to the signed-in user from:
@@ -60,14 +105,21 @@ Runtime lists the assistants available to the signed-in user from:
 
 ## Probe truthfulness
 
-- `builderValidated` means package files, ZIP structure, hashes, and secret checks passed.
-- `runtimeValidated` means Runtime MCP is reachable and its tool boundary checks passed.
-- `requiresMicrosoftAdmin` means Microsoft-side installation or approval remains incomplete. A user may install the package directly when their Teams custom-app policy permits it; otherwise, Teams administrator action is required.
+- `builderValidated` — package files, ZIP structure, hashes, and secret checks passed.
+- `runtimeValidated` — Runtime MCP is reachable and tool-boundary checks passed.
+- `requiresMicrosoftAdmin` — organisation publish / Teams admin approval is still pending. This is **not** a sideload requirement and is separate from package/Runtime readiness.
 
-## Validate after Teams installation
+`--force` regenerates the package artifacts. microsoft-copilot does not create Fabrix oauth2 channel credentials for Entra SSO.
 
-```bash
-aifabrix channel add {{channelTarget}} --name "{{baseName}}" --oauth-plugin-vault-reference-id "{{oauthPluginVaultReferenceId}}" --probe
-```
+## Delete / remove from the organisation
 
-`--force` regenerates the package artifacts. microsoft-copilot does not create Fabrix oauth2 channel credentials for Entra SSO.
+Use this when replacing the app, cleaning a failed publish, or removing **{{appName}}** entirely. Delete in this order so catalogue and Developer Portal records stay consistent.
+
+1. Open [Teams admin centre → Manage apps](https://admin.teams.microsoft.com/policies/manage-apps).
+2. Search for **{{appName}}**, open the app, open the action menu, choose **Delete**, and confirm.
+3. Open [Teams Developer Portal → Apps](https://dev.teams.microsoft.com/apps).
+4. Find the app in the list, open **…** (Actions) → **Delete**, and confirm by typing the app name.
+5. Open [Microsoft Entra SSO client ID registration](https://dev.teams.microsoft.com/tools/entra-configuration).
+6. Find the registration for this channel (same registration / auth-config used as `--oauth-plugin-vault-reference-id`), open **…** (Actions) → **Delete**, and confirm.
+
+After Microsoft cleanup, delete local package output if needed (`dist/channels/microsoft-copilot/`) and re-run `aifabrix channel add` with a **new** Entra SSO registration / auth-config ID. Do not reuse a deleted registration id.

package/templates/channels/microsoft-copilot/manifest.template.json.hbs

@@ -1,36 +1,51 @@
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.21/MicrosoftTeams.schema.json",
-  "manifestVersion": "1.21",
+  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.27/MicrosoftTeams.schema.json",
   "version": "{{packageVersion}}",
+  "manifestVersion": "1.27",
   "id": "{{packageAppId}}",
   "name": {
     "short": "{{shortName}}",
     "full": "{{fullName}}"
   },
-  "description": {
-    "short": "{{shortDescription}}",
-    "full": "{{fullDescription}}"
-  },
   "developer": {
     "name": "AI Fabrix",
     "websiteUrl": "{{{dataplaneBaseUrl}}}",
     "privacyUrl": "{{{dataplaneBaseUrl}}}/privacy",
     "termsOfUseUrl": "{{{dataplaneBaseUrl}}}/terms"
   },
+  "description": {
+    "short": "{{shortDescription}}",
+    "full": "{{fullDescription}}"
+  },
   "icons": {
-    "color": "color.png",
-    "outline": "outline.png"
+    "outline": "outline.png",
+    "color": "color.png"
   },
   "accentColor": "#0F172A",
+  "validDomains": [
+    "{{runtimeDomain}}"
+  ],
+{{#if webApplicationInfoId}}
+  "webApplicationInfo": {
+    "id": "{{webApplicationInfoId}}",
+    "resource": "{{{webApplicationInfoResource}}}"
+  },
+{{/if}}
+  "localizationInfo": {
+    "defaultLanguageTag": "en-us",
+    "additionalLanguages": [
+      {
+        "languageTag": "fi-fi",
+        "file": "fi-fi.json"
+      }
+    ]
+  },
   "copilotAgents": {
     "declarativeAgents": [
       {
-        "id": "{{packageAppId}}-agent",
-        "file": "declarativeAgent.json"
+        "file": "declarativeAgent.json",
+        "id": "{{packageAppId}}-agent"
       }
     ]
-  },
-  "validDomains": [
-    "{{runtimeDomain}}"
-  ]
+  }
 }

package/templates/channels/microsoft-copilot/oauth-plugin-vault-required.template.md.hbs

@@ -1,6 +1,8 @@
-microsoft-copilot packaging requires `--oauth-plugin-vault-reference-id` with the Teams Entra SSO auth-config id.
+microsoft-copilot packaging requires `--oauth-plugin-vault-reference-id` with the Teams Entra SSO **registration / auth-config ID**.
 
-Register Entra SSO in the Teams Developer Portal **before** packaging (no ZIP needed first), paste the values below, Save, then re-run with the registration id.
+That value is **not** the Entra Client (application) ID and **not** a client secret.
+
+Register Entra SSO in the Teams Developer Portal **before** packaging (no ZIP needed first): paste the values below, Save, copy the registration id, then re-run.
 
 {{> entraSsoRegistration}}
 
@@ -9,3 +11,5 @@ Then:
 ```bash
 aifabrix channel add microsoft-copilot --name "{{baseName}}" --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-registration-id>"
 ```
+
+Next: Developer Portal → Apps → Import app (`appPackage.<env>.zip`) → Publish to your org → Teams admin centre approval. Sideloading is optional and not the organisation path.

package/templates/python/docker-compose.hbs

@@ -39,6 +39,42 @@ services:
       - "traefik.http.routers.{{app.key}}.middlewares={{app.key}}-stripprefix"
       {{/if}}
       {{/unless}}
+      {{#each traefik.passThroughRouters}}
+      {{#if ../traefik.tls}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.entrypoints=websecure"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.tls=true"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.priority=200"
+      {{#if ../traefik.certStore}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.tls.certstore={{../traefik.certStore}}"
+      {{/if}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.entrypoints=web"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.priority=200"
+      {{else}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.entrypoints=web"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.priority=200"
+      {{/if}}
+      {{/each}}
+      {{#unless (eq traefik.path "/")}}
+      {{#each traefik.aliasRouters}}
+      - "traefik.http.middlewares.{{../app.key}}-alias-{{this.id}}-rw.replacepathregex.regex=^{{this.rewriteSource}}(/.*)?$"
+      - "traefik.http.middlewares.{{../app.key}}-alias-{{this.id}}-rw.replacepathregex.replacement={{this.rewriteDest}}$1"
+      {{#if this.stripPrimary}}
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.middlewares={{../app.key}}-alias-{{this.id}}-rw,{{../app.key}}-stripprefix"
+      {{else}}
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.middlewares={{../app.key}}-alias-{{this.id}}-rw"
+      {{/if}}
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.entrypoints=web"
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.priority=200"
+      {{/each}}
+      {{/unless}}
     {{/if}}
     environment:
       - MISO_ENVIRONMENT={{misoEnvironment}}

package/templates/typescript/docker-compose.hbs

@@ -39,6 +39,42 @@ services:
       - "traefik.http.routers.{{app.key}}.middlewares={{app.key}}-stripprefix"
       {{/if}}
       {{/unless}}
+      {{#each traefik.passThroughRouters}}
+      {{#if ../traefik.tls}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.entrypoints=websecure"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.tls=true"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.priority=200"
+      {{#if ../traefik.certStore}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.tls.certstore={{../traefik.certStore}}"
+      {{/if}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.entrypoints=web"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}-http.priority=200"
+      {{else}}
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.entrypoints=web"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-pass-{{this.id}}.priority=200"
+      {{/if}}
+      {{/each}}
+      {{#unless (eq traefik.path "/")}}
+      {{#each traefik.aliasRouters}}
+      - "traefik.http.middlewares.{{../app.key}}-alias-{{this.id}}-rw.replacepathregex.regex=^{{this.rewriteSource}}(/.*)?$"
+      - "traefik.http.middlewares.{{../app.key}}-alias-{{this.id}}-rw.replacepathregex.replacement={{this.rewriteDest}}$1"
+      {{#if this.stripPrimary}}
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.middlewares={{../app.key}}-alias-{{this.id}}-rw,{{../app.key}}-stripprefix"
+      {{else}}
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.middlewares={{../app.key}}-alias-{{this.id}}-rw"
+      {{/if}}
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.rule=Host(`{{../traefik.host}}`) && PathPrefix(`{{this.pathPrefix}}`)"
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.entrypoints=web"
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.service={{../app.key}}"
+      - "traefik.http.routers.{{../app.key}}-alias-{{this.id}}.priority=200"
+      {{/each}}
+      {{/unless}}
     {{/if}}
     environment:
       - MISO_ENVIRONMENT={{misoEnvironment}}