woml-cli 1.0.1

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "woml-cli",
+  "version": "1.0.1",
+  "description": "WOML workflow automation runtime and command-line interface",
+  "author": "Mohamed Ali Ben Othmen",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dali-benothmen/woml.git",
+    "directory": "woml-cli"
+  },
+  "homepage": "https://github.com/dali-benothmen/woml#readme",
+  "bugs": {
+    "url": "https://github.com/dali-benothmen/woml/issues"
+  },
+  "type": "module",
+  "bin": {
+    "woml": "./dist/cli.js"
+  },
+  "files": [
+    "dist/cli.js",
+    "dist/script-host.js",
+    "dist/script-host-worker.js",
+    "dist/notification-provider-host.js",
+    "dist/custom-notification-provider-host.js",
+    "dist/custom-notification-provider-worker.js",
+    "dist/cli.js.map",
+    "dist/script-host.js.map",
+    "dist/script-host-worker.js.map",
+    "dist/notification-provider-host.js.map",
+    "dist/custom-notification-provider-host.js.map",
+    "dist/custom-notification-provider-worker.js.map",
+    "slack/README.md",
+    "slack/manifest.json",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "optionalDependencies": {
+    "@woml-org/cli-darwin-x64": "1.0.1",
+    "@woml-org/cli-darwin-arm64": "1.0.1",
+    "@woml-org/cli-win32-x64-msvc": "1.0.1",
+    "@woml-org/cli-win32-arm64-msvc": "1.0.1",
+    "@woml-org/cli-linux-x64-gnu": "1.0.1",
+    "@woml-org/cli-linux-arm64-gnu": "1.0.1"
+  }
+}

package/slack/README.md

@@ -0,0 +1,132 @@
+# WOML Slack Setup
+
+This is the one-time workspace setup for WOML Slack approvals and Slack
+triggers. WOML uses Socket Mode, so it does not need a public callback URL or
+`woml serve`.
+
+## Install the app
+
+1. In Slack's app management page, choose **Create New App → From an app
+   manifest** and paste `manifest.json` from this directory.
+2. Install the app to the workspace. The manifest requests the scopes used for
+   approval messages, channel lookup, app mentions, and direct messages.
+3. Under **Basic Information → App-Level Tokens**, generate an app token with
+   the `connections:write` scope.
+4. Copy the **Bot User OAuth Token** (`xoxb-...`) and the **App-Level Token**
+   (`xapp-...`) into WOML's protected secret store:
+
+   ```text
+   woml secrets set SLACK_BOT_TOKEN
+   woml secrets set SLACK_APP_TOKEN
+   ```
+
+   Enter each value only at the hidden prompt. Do not place either token in a
+   `.woml` file, shell argument, environment committed to source control, or
+   chat message.
+
+After changing any Bot Token Scope, choose **Reinstall to Workspace** and copy
+the Bot User OAuth Token from that same Slack app again. The installed token,
+not merely the permissions displayed in the app editor, is what Slack checks.
+Its Bot Token Scopes must include:
+
+```text
+chat:write
+chat:write.public
+app_mentions:read
+channels:read
+groups:read
+im:history
+```
+
+`channels:history` does not replace `channels:read`. WOML uses
+`conversations.list` to resolve a readable `#channel` alias. Supplying a stable
+Slack conversation ID (`C...` or `G...`) bypasses that name lookup, but does not
+replace the permission required to post or the requirement to invite the app
+to a private channel.
+
+## Choose channels
+
+Public channel aliases such as `#woml-testing` work with the manifest as-is.
+For a private channel, invite the WOML app to that channel first. Slack channel
+IDs (`C...` or `G...`) are the most stable option and avoid name lookup.
+
+```xml
+<notify>
+  <slack
+    channels="#woml-testing"
+    bot-token="{{secrets.SLACK_BOT_TOKEN}}"
+    app-token="{{secrets.SLACK_APP_TOKEN}}"
+  />
+</notify>
+```
+
+Then run the workflow normally:
+
+```text
+woml run workflow.woml
+```
+
+The repository includes `examples/slackApprovalWorkflow.woml` as a live smoke
+test. Change its `channels` value to a channel in your workspace before running
+it.
+
+The terminal remains attached while Socket Mode waits for a reviewer. Clicking
+Approve or Reject in any delivered channel resolves the one shared approval,
+updates all delivered messages, and continues only the selected WOML route.
+
+## Define a Slack trigger
+
+```xml
+<triggers>
+  <slack
+    id="agentMessage"
+    events="app-mention,direct-message"
+    channels="woml-testing,agent-support"
+    bot-token="{{secrets.SLACK_BOT_TOKEN}}"
+    app-token="{{secrets.SLACK_APP_TOKEN}}"
+  />
+</triggers>
+```
+
+WOML validates and compiles this definition into Model v7. Keep
+`woml run workflow.woml` active, then mention the app in a listed channel or
+send it a direct message. A valid message starts one durable workflow run and
+is available to scripts as:
+
+```js
+context.payload.type
+context.payload.text
+context.payload.userId
+context.payload.channelId
+context.payload.messageTs
+context.payload.threadTs
+context.payload.teamId
+```
+
+Channel filters apply to app mentions; direct messages remain accepted when
+`direct-message` is enabled. Repeating the same Slack event does not execute a
+second run. After changing scopes or event subscriptions, reinstall the app to
+the workspace and refresh the stored bot token.
+
+The repository includes `examples/slackTriggerWorkflow.woml`, configured for
+`#woml-testing`. Edit that channel filter if your workspace uses another name.
+
+## Common failures
+
+- `WOML_SLACK_AUTH_FAILED`: replace a revoked, expired, or wrong token.
+- `WOML_SLACK_PERMISSION_DENIED`: verify the scopes above under **Bot Token
+  Scopes**, reinstall the app, refresh the stored `xoxb-...` token, and ensure
+  the app belongs to a private destination. When Slack returns safe scope
+  metadata, WOML prints the failed operation, missing scopes, granted scopes,
+  destination, and reinstall action directly in the terminal.
+- `WOML_SLACK_DESTINATION_INVALID`: verify the channel name/ID and app
+  visibility.
+- `WOML_SLACK_RATE_LIMITED`: WOML follows Slack's `Retry-After` value through
+  its durable retry policy.
+- `WOML_SLACK_TRIGGER_SCOPE_MISSING`: add the missing scopes, reinstall the
+  app, and refresh the stored token.
+- `WOML_SLACK_TRIGGER_UNAVAILABLE`: keep WOML active and restore Socket Mode;
+  an event is not acknowledged before durable admission, so Slack may redeliver
+  it safely.
+- `WOML_NOTIFICATION_DELIVERY_AMBIGUOUS`: the connection ended after a send
+  may have reached Slack. WOML fails closed instead of creating a duplicate.

package/slack/manifest.json

@@ -0,0 +1,39 @@
+{
+  "display_information": {
+    "name": "WOML Approvals",
+    "description": "Approve or reject WOML workflow runs from Slack.",
+    "background_color": "#4f46e5"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "WOML",
+      "always_online": false
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "chat:write",
+        "chat:write.public",
+        "app_mentions:read",
+        "channels:read",
+        "groups:read",
+        "im:history"
+      ]
+    }
+  },
+  "settings": {
+    "event_subscriptions": {
+      "bot_events": [
+        "app_mention",
+        "message.im"
+      ]
+    },
+    "interactivity": {
+      "is_enabled": true
+    },
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": true,
+    "token_rotation_enabled": false
+  }
+}