@aifabrix/builder 2.53.1 → 2.54.1

package/templates/channels/slack/integration/README.md

@@ -1,36 +1,259 @@
-# Slack communication channel
+# Slack
 
-Communication external system for **Role Assistants** (workforce transport) **and document approval** — one Slack app, dual surface (plan 455.2).
+Chat with Role Assistants, send notifications, and review documents in Slack.
 
-## What this integration is
+## At a glance
 
-- Slack app manifest install (`channel-slack.json` via `aifabrix channel add slack`)
-- **Workforce:** slash commands (`/assistants`, `/tasks`, `/task`), Events API (DM chat), interactive components
-- **Document approval:** slash commands (`/documents`, `/document`, `/approve`, `/help`), review card block actions, proactive notifications
-- **Command SSOT:** `templates/slack/command_catalog.yaml` + Block Kit JSON under `templates/slack/`; optional install prefix (default `af`) registers `/af-*` aliases
-- Outbound CIP: `slack-messages`, `slack-conversations` (workforce replies, DMs, and approval notifications)
+| | |
+| --- | --- |
+| **System key** | `slack` |
+| **Type** | `custom` |
+| **Datasources** | 5 |
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `application.yaml` | App manifest and `externalIntegration` |
+| `slack-system.yaml` | Auth, API definition, roles |
+| `slack-datasource-interactive.yaml` | Datasource: Slack interactive inbound (**capabilities** here) |
+| `slack-datasource-commands.yaml` | Datasource: Slack slash-command inbound (**capabilities** here) |
+| `slack-datasource-events.yaml` | Datasource: Slack Events API inbound (**capabilities** here) |
+| `slack-datasource-conversations.yaml` | Datasource: Slack Conversations (**capabilities** here) |
+| `slack-datasource-messages.yaml` | Datasource: Slack Messages (**capabilities** here) |
+| `env.template` | Secrets and env placeholders |
+| `slack-deploy.json` | Deploy manifest (`aifabrix json slack`) |
+| `deploy.js` | Deploy helper |
+| `wizard.yaml` | Wizard input |
+| `scenarios/*.yaml` | Governance scenario packs (optional; dataplane-first via `verify-governance` / `governance generate`; expert YAML via `governance download` / `upload`) |
+| `rbac.yaml` | Roles and permissions |
+
+## Typical workflow
+
+1. **Login** — `aifabrix login` (controller URL set via `aifabrix auth config` if needed).
+2. **Change config** — edit JSON/YAML under `integration/slack/`, or extend with `aifabrix wizard --app slack`.
+3. **Adjust operations** — use `aifabrix datasource capability …` to copy, add, or remove **capabilities** (see below).
+4. **Check locally** — `aifabrix validate slack` and `aifabrix datasource validate` on files you touched.
+5. **Align manifest** — `aifabrix repair slack` after bigger edits.
+6. **Publish** — see [Publish and credentials](#publish-and-credentials) (`upload`, `deploy`, or `credential push`).
+7. **Certify** — run [Enterprise AI Certification](#enterprise-ai-certification) (`verify-operations` → `verify-trust` → `verify-governance` → `lifecycle`).
+8. **Protection** (optional) — dimension grants in `integration/.protection/` — see [Protection manifests](#protection-manifests).
+
+Rollback an experiment: `datasource capability remove …` → validate → upload/deploy again.
+
+## Publish and credentials
+
+| Command | What it does |
+| --- | --- |
+| `aifabrix upload slack` | Publishes local integration files to the dataplane (refreshes `slack-deploy.json` from sources) and pushes credential secrets from `integration/slack/.env` (when present). |
+| `aifabrix upload slack --force` | Same publish path when the interface or datasource schema changed in ways **deploy cannot accept yet**; bypasses active-schema replacement guards. Read the CLI warning before use. |
+| `aifabrix deploy slack` | Deploys via the controller pipeline. Does **not** replace a full upload for credential secrets — run `upload` or `credential push` when `.env` changed. |
+| `aifabrix credential push slack` | Pushes `KV_*` values from `.env` only (no manifest publish). |
+
+```bash
+aifabrix upload slack
+# or secrets only:
+aifabrix credential push slack
+
+# Breaking schema / interface change — deploy blocked; publish for dev iteration
+aifabrix validate slack
+aifabrix upload slack --force
+```
+
+## Protection manifests
+
+Protection rules live in **`integration/.protection/`** at the **repository root** (sibling to `integration/slack/`, not inside this app folder). One manifest per **datasource key** (`spec.datasourceKey`). Use YAML or JSON; store expressions only — no secrets in Git.
+
+```bash
+# From repo root (where integration/ lives)
+aifabrix protection create slack-interactive --type country-sales
+aifabrix protection validate slack-interactive
+aifabrix protection upload slack-interactive
+
+# Batch (entire folder)
+aifabrix validate .protection
+aifabrix upload .protection
+```
+
+See `aifabrix protection --help` for flags (`--no-sync` on upload skips datasource sync after upload only).
+
+## Capabilities (per datasource)
+
+Each `*-datasource-*` file lists **capabilities**: named slices that tie together HTTP/API definitions and execution steps. Use the CLI to clone or drop them safely instead of editing huge JSON by hand.
+
+**After any change:** run `aifabrix datasource validate <file-or-key>` (or `aifabrix validate slack` for the whole app).
+
+| Command | What it does |
+| --- | --- |
+| `datasource capability copy` | Clone one capability to a new name (`--from` / `--as`). Supports `--dry-run`, `--overwrite`, backups. If `exposed.profiles.<from>` exists, it’s copied to `exposed.profiles.<as>`. |
+| `datasource capability create` (or `add`) | New capability from `--from`, `--template`, or `--openapi-operation`. |
+| `datasource capability remove` | Remove one capability (`--capability`; optional `--profile`). Use `--dry-run` first. |
+| `datasource capability validate` | Schema check for the file or one `--capability`. |
+| `datasource capability diff` | Compare two files for one capability. |
+| `datasource capability edit` | Edit one capability’s API definition, runtime steps, or exposure profile in your editor (TTY). |
+| `datasource capability relate` | Link this datasource to another (foreign-key style metadata). See `--help` for flags. |
+
+Short alias (recommended): `af ds cap <command> …`  
+Full command: `aifabrix datasource capability <command> …`
+
+Examples (use the first datasource from the Files table):
+
+```bash
+# Preview cloning "create" to "createBasic" (no write)
+af ds cap copy slack-interactive --from create --as createBasic --dry-run
+
+# Apply the copy, then validate
+af ds cap copy slack-interactive --from create --as createBasic
+af ds validate slack-interactive
+
+# Remove a capability you no longer need
+af ds cap remove slack-interactive --capability createBasic --dry-run
+```
+
+For flags, run `af ds cap <command> --help`.
+
+## Per-datasource debug ladder
+
+Start with one datasource and iterate until it’s stable (architect / CI — use [Enterprise AI Certification](#enterprise-ai-certification) for the product path).
+
+```bash
+af ds validate slack-interactive
+af ds test slack-interactive --debug --sync
+af ds test-integration slack-interactive --sync
+af ds test-e2e slack-interactive --debug --sync
+```
+
+## Secrets
+
+Store values the CLI expects (no secrets in Git):
+
+```bash
+aifabrix secret set slack/signingSecret <your value>   # KV_SLACK_SIGNINGSECRET
+aifabrix secret set slack/botToken <your value>   # KV_SLACK_BOTTOKEN
+aifabrix secret set slack/clientSecret <your value>   # KV_SLACK_CLIENTSECRET
+```
 
-## What this integration is not
+## Repair
 
-- **Not** channel listing / user directory sync (`slack-channels`, `slack-users` are out of scope for this scaffold).
+Keeps filenames, lists, and deploy manifest in sync after manual edits.
 
-## Endpoints
+```bash
+aifabrix repair slack
+```
+
+Useful flags: `--dry-run`, `--auth <method>`, `--rbac`, `--expose`, `--sync`, `--test`.
 
-Registered at `/api/v1/external/systems/slack/`:
+## Enterprise AI Certification
 
-| Path | Purpose |
+Product-facing commands that prove operational readiness, AI trust, governance enforcement, and an **Enterprise AI Certification** report. Run after [publish](#publish-and-credentials).
+
+| Command | What it proves |
 | --- | --- |
-| `/commands` | Slash commands (workforce + document approval) |
-| `/events` | Events API |
-| `/interactive` | Block actions (approve, reject, metadata) |
-| `/notifications` | Proactive messages |
-| `/documents` | Document review Block Kit payload |
-| `/bot-config` | Bot configuration |
+| `aifabrix verify-operations slack` | Operational readiness — orchestrates validate, unit test, integration, and E2E for the whole system |
+| `aifabrix verify-trust slack` | AI business context confidence (semantic agent metadata; not live vendor API calls) |
+| `aifabrix verify-governance slack` | **Recommended** — publish (unless `--no-sync`), generate scenario packs on the dataplane, then verify ABAC visibility per subject |
+| `aifabrix governance generate slack` | Granular: generate packs only (after protection + sync) |
+| `aifabrix governance verify slack` | Granular: verify only (active packs on dataplane, or `--pack` for local YAML override) |
+| `aifabrix lifecycle slack` | Certification report from persisted pillar results on the dataplane |
+
+**Recommended order:** `upload` → `verify-operations` → `verify-trust` → `verify-governance` → `lifecycle`
+
+Integration validation packs live under `integration/slack/scenarios/` (YAML per datasource). Prefer **`verify-governance`** (dataplane-first) after identity sync, protection upload, and `datasource load`. Granular: `governance generate` then `governance verify`. Expert YAML: `governance download` / `governance upload` (424.0 schema; pre-424 files fail with a hint to regenerate). **`governance download`** is read-only and does not publish this folder.
+
+```bash
+aifabrix upload slack
+
+aifabrix verify-operations slack
+aifabrix verify-operations slack -v
+
+aifabrix verify-trust slack -v
+aifabrix verify-trust slack --no-sync --revalidate
+
+# Governance pillar (replace <email> with a subject from your scenario pack)
+aifabrix verify-governance slack --subject-email <email> -v
+aifabrix verify-governance slack --subject-email <email> --no-sync
+
+# Granular governance (debugging)
+aifabrix governance generate slack --subject-email <email>
+aifabrix governance verify slack -v
+
+# Report only (GET persisted results)
+aifabrix lifecycle slack
+aifabrix lifecycle slack -v
+
+# Run missing verify steps, publish local files, then print report
+aifabrix lifecycle slack --run
+aifabrix lifecycle slack --run --no-sync
+```
+
+**Prerequisites:** `aifabrix login`, dataplane reachable, config published (`upload`). Governance also needs identity sync, protection upload, `datasource load` for fixture records, at least one `--subject-email` or `--subject-user-id`, and `governance:evaluate` on your token. Run `aifabrix verify-governance --help` for flags.
+
+**Single-datasource trust** (same semantic check as system `verify-trust`, one key):
+
+```bash
+aifabrix datasource verify-trust slack-interactive --app slack -v
+```
+
+Common flags: `-v` / `--verbose`, `-d` / `--debug` (trust), `--no-sync` (skip pre-run upload), `--json` (machine-readable envelope).
+
+## Debug and low-level tests
 
-## Workflow
+Advanced commands for architects and CI. Prefer [Enterprise AI Certification](#enterprise-ai-certification) for integrator proof unless you need step-by-step debugging.
+
+| Command | Network | Notes |
+| --- | --- | --- |
+| `aifabrix validate slack` | Off | Schemas and files only |
+| `aifabrix test slack` | Off | Local checks |
+| `aifabrix test-integration slack` | On | Needs login + dataplane |
+| `aifabrix test-e2e slack` | On | E2E for every datasource; uploads local files first unless `--no-sync` |
+
+System-level tests publish local integration files before the run (same path as `upload`). Use **`--no-sync`** to validate against config already on the dataplane.
+
+```bash
+aifabrix test-e2e slack --no-sync -d
+```
+
+Single datasource E2E:
+
+```bash
+# Slack interactive inbound
+aifabrix datasource test-e2e slack-interactive --app slack
+
+# Slack slash-command inbound
+aifabrix datasource test-e2e slack-commands --app slack
+
+# Slack Events API inbound
+aifabrix datasource test-e2e slack-events --app slack
+
+# Slack Conversations
+aifabrix datasource test-e2e slack-conversations --app slack
+
+# Slack Messages
+aifabrix datasource test-e2e slack-messages --app slack
+
+```
+
+Common flags: `-v` / `--verbose`, `-d` / `--debug`, `--no-async` (datasource E2E only), `--no-sync` (skip pre-run upload on system `test-e2e`).
+
+Debug logs (when using `--debug` on datasource commands) are written under `integration/slack/logs/` — use `aifabrix datasource log-test`, `log-integration`, `log-e2e`, or `log-trust` to inspect the latest file for each type.
+
+## Deploy
 
 ```bash
-aifabrix channel add slack --name "Your Assistant" --probe
+aifabrix deploy slack
 ```
 
-Optional low-level: `channel scaffold` / `upload`. Publish template changes: `make sync-json` in dataplane → `aifabrix-builder/templates/channels/slack/integration/`.
+## Remove app
+
+```bash
+aifabrix delete slack
+```
+
+## When something fails
+
+- **Validation errors** — Fix JSON/schema issues; run `aifabrix validate slack` and `aifabrix datasource validate` on the file you changed.
+- **Deploy blocked by schema changes** — When the interface changed and deploy rejects the update, validate locally then `aifabrix upload slack --force` to publish for dev iteration (see [Publish and credentials](#publish-and-credentials)).
+- **Auth** — `aifabrix auth config` + `aifabrix login` before upload, deploy, remote tests, or certification.
+- **Certification gaps** — Run pillars in order (`verify-operations` → `verify-trust` → `verify-governance`), then `aifabrix lifecycle slack -v` for per-datasource breakdown; use `lifecycle --run` to execute missing steps and refresh the report.
+- **Governance upload rejected** — Local `scenarios/*.yaml` must meet the 424.0 pack schema; use `verify-governance` or `governance generate` instead of hand-editing old YAML.
+- **Wrong folder** — Run CLI from the project root (where `integration/slack/` lives).

package/templates/channels/slack/integration/application.json

@@ -1,18 +1,55 @@
 {
   "app": {
     "key": "slack",
-    "displayName": "slack assistant channel",
-    "description": "Assistant communication channel — upload then channel add",
+    "displayName": "Slack",
+    "description": "Chat with Role Assistants, send notifications, and review documents in Slack.",
     "type": "external"
   },
   "externalIntegration": {
     "schemaBasePath": "./",
-    "systems": ["slack-system.json"],
+    "systems": [
+      "slack-system.json"
+    ],
     "dataSources": [
-      "slack-datasource-messages.json",
-      "slack-datasource-conversations.json"
+      "slack-datasource-interactive.json",
+      "slack-datasource-commands.json",
+      "slack-datasource-events.json",
+      "slack-datasource-conversations.json",
+      "slack-datasource-messages.json"
     ],
     "autopublish": true,
     "version": "1.0.0"
-  }
-}
+  },
+  "configuration": [
+    {
+      "name": "ENABLE_PROACTIVE_MESSAGING",
+      "value": "true",
+      "location": "variable",
+      "required": false
+    },
+    {
+      "name": "ENABLE_CHANNEL_NOTIFICATIONS",
+      "value": "true",
+      "location": "variable",
+      "required": false
+    },
+    {
+      "name": "ENABLE_DIRECT_MESSAGES",
+      "value": "true",
+      "location": "variable",
+      "required": false
+    },
+    {
+      "name": "ENABLE_MODALS",
+      "value": "true",
+      "location": "variable",
+      "required": false
+    },
+    {
+      "name": "ENABLE_SHORTCUTS",
+      "value": "true",
+      "location": "variable",
+      "required": false
+    }
+  ]
+}

package/templates/channels/slack/integration/env.template

@@ -19,11 +19,20 @@
 #   aifabrix secret set slack/botToken "xoxb-..." --shared
 #   aifabrix secret set slack/clientSecret "<value>" --shared
 
-# Required — webhook signature verification (438.3 inbound)
-KV_SLACK_SIGNINGSECRET=kv://slack/signingSecret
+# Signing secret, bot token, and client secret are written to this app's .env
+# (`KV_SLACK_*` plain values) by channel add / portal install, then pushed to
+# the dataplane secret store. Do not require them here: missing secrets must not
+# block publishing the communication system or the Slack app manifest.
+# KV_SLACK_SIGNINGSECRET=kv://slack/signingSecret
+# KV_SLACK_BOTTOKEN=kv://slack/botToken
+# KV_SLACK_CLIENTSECRET=kv://slack/clientSecret
+
+# Lab defaults so `aifabrix upload slack` works without extra shell env.
+ENABLE_PROACTIVE_MESSAGING=true
+ENABLE_CHANNEL_NOTIFICATIONS=true
+ENABLE_DIRECT_MESSAGES=true
+ENABLE_MODALS=true
+ENABLE_SHORTCUTS=true
+
 
-# Required — outbound Slack Web API (post message, etc.)
-KV_SLACK_BOTTOKEN=kv://slack/botToken
 
-# Optional — OAuth app client secret
-KV_SLACK_CLIENTSECRET=kv://slack/clientSecret

package/templates/channels/slack/integration/openapi/openapi.json

@@ -0,0 +1,126 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Slack inbound python CIP",
+    "version": "1.0.0",
+    "description": "Contract surface for Slack inbound python CIP. Vendor Request URLs are POST /api/v1/webhooks/slack/{datasourceKey}; these paths are CIP operation ids."
+  },
+  "paths": {
+    "/inbound/commands": {
+      "post": {
+        "operationId": "slackCommandsCreate",
+        "summary": "Accept an inbound Slack slash-command payload",
+        "x-aifabrix-capability": "create",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelInboundCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Inbound handler record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelInboundCreateResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/inbound/interactive": {
+      "post": {
+        "operationId": "slackInteractiveCreate",
+        "summary": "Accept an inbound Slack interactive payload",
+        "x-aifabrix-capability": "create",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelInboundCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Inbound handler record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelInboundCreateResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/inbound/events": {
+      "post": {
+        "operationId": "slackEventsCreate",
+        "summary": "Accept an inbound Slack Events API payload",
+        "x-aifabrix-capability": "create",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelInboundCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Inbound handler record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelInboundCreateResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "ChannelInboundCreateRequest": {
+        "type": "object",
+        "description": "CIP create body. payload is the vendor webhook JSON after signature validation.",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      },
+      "ChannelInboundCreateResponse": {
+        "type": "object",
+        "description": "Normalized inbound handler record for fieldMappings.",
+        "required": ["channel", "action", "outcome"],
+        "properties": {
+          "channel": { "type": "string" },
+          "action": { "type": "string" },
+          "outcome": { "type": "string" },
+          "externalId": { "type": "string" },
+          "response": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      }
+    }
+  }
+}

package/templates/channels/slack/integration/rbac.json

@@ -0,0 +1,84 @@
+{
+  "roles": [
+    {
+      "name": "Everyone",
+      "value": "aifabrix-everyone",
+      "description": "Authenticated-user consume access for Enterprise LLM and platform search (not a Role Assistant)",
+      "groups": [
+        "AI-Fabrix-Everyone"
+      ]
+    }
+  ],
+  "permissions": [
+    {
+      "name": "message:list",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: message:list"
+    },
+    {
+      "name": "message:create",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: message:create"
+    },
+    {
+      "name": "message:update",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: message:update"
+    },
+    {
+      "name": "message:delete",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: message:delete"
+    },
+    {
+      "name": "slack-commands:create",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: slack-commands:create"
+    },
+    {
+      "name": "slack-interactive:create",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: slack-interactive:create"
+    },
+    {
+      "name": "slack-events:create",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: slack-events:create"
+    },
+    {
+      "name": "conversation:list",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: conversation:list"
+    },
+    {
+      "name": "conversation:get",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: conversation:get"
+    },
+    {
+      "name": "conversation:create",
+      "roles": [
+        "aifabrix-everyone"
+      ],
+      "description": "Permission: conversation:create"
+    }
+  ]
+}