feat: implement basic hook logic

.github/workflows/tests.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install -U pip
-          pip install .
+          pip install -r requirements.txt
           pip install -r requirements/testing.txt
       - name: Run tests
         run: |

README.md

@@ -1,2 +1,101 @@
 # python-slack-hooks
-Helper library implementing the contract between the Slack CLI and Bolt for Python
+
+Helper library implementing the contract between the [Slack CLI](https://api.slack.com/automation/cli) and [Bolt for Python](https://slack.dev/bolt-python/)
+
+## Setup
+
+Before getting started, make sure you have a development workspace where you have permissions to install apps. If you don’t have one set up, go ahead and create one.
+
+### Install the Slack CLI
+
+Install the Slack CLI. Step-by-step instructions can be found in this [Quickstart Guide](https://api.slack.com/automation/cli).
+
+### Install this package
+
+```bash
+# Python 3.6+ required
+python -m venv .venv
+source .venv/bin/activate
+
+pip install -U pip
+pip install slack-cli-hooks
+```
+
+## Creating a Bolt app
+
+Next, we will create a Bolt for Python app in the same directory where we installed `slack-cli-hooks`, define basic information and metadata about our app via an [App Manifest](https://api.slack.com/reference/manifests) (`manifest.json`) and finally create a `slack.json` file that defines the interface between the [Slack CLI](https://api.slack.com/automation/cli) and [Bolt for Python](https://slack.dev/bolt-python/concepts).
+
+### Source code
+
+Create a [Bolt for Python](https://slack.dev/bolt-python/concepts) app in a file named `app.py`.
+
+```python
+import logging
+
+from slack_bolt import App
+from slack_bolt.adapter.socket_mode import SocketModeHandler
+
+logging.basicConfig(level=logging.DEBUG)
+
+app = App()
+
+# Add functionality here
+
+if __name__ == "__main__":
+    SocketModeHandler(app.start(3000)).start()
+```
+
+### Application Configuration
+
+Define your [Application Manifest](https://api.slack.com/reference/manifests) in a `manifest.json` file.
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/slackapi/manifest-schema/main/manifest.schema.json",
+  "_metadata": {
+    "major_version": 1,
+    "minor_version": 1
+  },
+  "display_information": {
+    "name": "most-basic-app"
+  },
+  "outgoing_domains": [],
+  "settings": {
+    "org_deploy_enabled": true,
+    "socket_mode_enabled": true,
+    "token_rotation_enabled": false
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "most-basic-app"
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": ["chat:write"]
+    }
+  }
+}
+```
+
+Define the Slack CLI configuration in a file named `slack.json`.
+
+```json
+{
+  "hooks": {
+    "get-hooks": "python3 -m slack_cli_hooks.hooks.get_hooks"
+  }
+}
+```
+
+Create an empty folder named `.slack`
+
+### Running the app
+
+You should now be able to harness the power of the Slack CLI and Bolt.
+
+Run the app this way:
+
+```zsh
+slack run
+```

requirements/format.txt

@@ -1,6 +1,5 @@
 black==22.8.0; python_version=="3.6"
 black; python_version>"3.6"            # Until we drop Python 3.6 support, we have to stay with this version
-flake8>=5.0.4; python_version=="3.6"
-flake8==6.0.0; python_version>"3.6"
+flake8>=5.0.4, <7;
 pytype; (python_version<"3.11" or python_version>"3.11")
 pytype==2023.11.29; python_version=="3.11"

requirements/testing.txt

@@ -1,3 +1,6 @@
 # pip install -r requirements/testing.txt
 pytest>=6.2.5,<7
 pytest-cov>=3,<4
+Flask>=2.0.3,<4 
+gevent>=22.10.2,<24
+gevent-websocket>=0.10.1,<1

slack_cli_hooks/__init__.py

@@ -0,0 +1,7 @@
+"""
+A Slack CLI hooks implementation in Python to build Bolt Slack apps leveraging the full power of the [Slack CLI](https://api.slack.com/automation/cli/install). Look at our [code examples](https://github.com/slackapi/python-slack-hooks/tree/main/examples) to learn how to build apps using the SLack CLI and Bolt.
+
+* Slack CLI: https://api.slack.com/automation/cli/install
+* Bolt Website: https://slack.dev/bolt-python/
+* GitHub repository: https://github.com/slackapi/python-slack-hooks
+"""  # noqa: E501

slack_cli_hooks/error/__init__.py

@@ -0,0 +1,2 @@
+class CliError(Exception):
+    """General class for cli error"""

slack_cli_hooks/hooks/__init__.py

@@ -0,0 +1,2 @@
+"""Slack CLI contract implementation for Bolt.
+"""

slack_cli_hooks/hooks/get_hooks.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+import json
+from slack_cli_hooks.protocol import Protocol, MessageBoundaryProtocol, DefaultProtocol, protocol_factory
+
+PROTOCOL: Protocol
+EXEC = "python3"
+
+
+hooks_payload = {
+    "hooks": {
+        "get-manifest": f"{EXEC} -m slack_cli_hooks.hooks.get_manifest",
+        "start": f"{EXEC} -m slack_cli_hooks.hooks.start",
+    },
+    "config": {
+        "watcher": {"filter-regex": "^manifest\\.(json)$", "paths": ["."]},
+        "protocol-version": [MessageBoundaryProtocol.name, DefaultProtocol.name],
+        "sdk-managed-connection-enabled": True,
+    },
+}
+
+if __name__ == "__main__":
+    PROTOCOL = protocol_factory()
+    PROTOCOL.respond(json.dumps(hooks_payload))

slack_cli_hooks/hooks/get_manifest.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+import os
+import re
+from typing import List
+
+from slack_cli_hooks.error import CliError
+from slack_cli_hooks.protocol import Protocol, protocol_factory
+
+PROTOCOL: Protocol
+
+EXCLUDED_DIRECTORIES = [
+    "lib",
+    "bin",
+    "include",
+    "node_modules",
+    "packages",
+    "logs",
+    "build",
+    "coverage",
+    "target",
+    "tmp",
+    "test",
+    "tests",
+]
+
+DIRECTORY_IGNORE_REGEX = re.compile(r"(^\.|^\_|^{}$)".format("$|^".join(EXCLUDED_DIRECTORIES)), re.IGNORECASE)
+
+
+def filter_directories(directories: List[str]) -> List[str]:
+    return [directory for directory in directories if not DIRECTORY_IGNORE_REGEX.match(directory)]
+
+
+def find_file_path(path: str, file_name: str) -> str:
+    for root, dirs, files in os.walk(path, topdown=True, followlinks=False):
+        dirs[:] = filter_directories(dirs)
+        if file_name in files:
+            return os.path.join(root, file_name)
+    raise CliError(f"Could not find a {file_name} file")
+
+
+def get_manifest(working_directory: str) -> str:
+    file_path = find_file_path(working_directory, "manifest.json")
+
+    with open(file_path, "r") as manifest:
+        return manifest.read()
+
+
+if __name__ == "__main__":
+    PROTOCOL = protocol_factory()
+    PROTOCOL.respond(get_manifest(os.getcwd()))

slack_cli_hooks/hooks/start.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+import os
+import runpy
+import sys
+
+from slack_cli_hooks.error import CliError
+from slack_cli_hooks.protocol import Protocol, protocol_factory
+
+PROTOCOL: Protocol
+
+DEFAULT_MAIN_FILE = "app.py"
+
+SLACK_CLI_XOXB = "SLACK_CLI_XOXB"
+SLACK_CLI_XAPP = "SLACK_CLI_XAPP"
+SLACK_BOT_TOKEN = "SLACK_BOT_TOKEN"
+SLACK_APP_TOKEN = "SLACK_APP_TOKEN"
+
+
+class EnvVarHandler:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self._is_set = name in os.environ
+
+    def set_default(self, value: str) -> None:
+        if not self._is_set:
+            os.environ[self.name] = value
+
+    def clean(self) -> None:
+        if not self._is_set:
+            os.environ.pop(self.name, None)
+
+
+def validate_env() -> None:
+    if not os.environ.get(SLACK_CLI_XOXB):
+        raise CliError(f"Missing local run bot token ({SLACK_CLI_XOXB}).")
+    if not os.environ.get(SLACK_CLI_XAPP):
+        raise CliError(f"Missing local run app token ({SLACK_CLI_XAPP}).")
+
+
+def get_main_file() -> str:
+    custom_file = os.environ.get("SLACK_APP_PATH")
+    if custom_file:
+        return custom_file
+    return DEFAULT_MAIN_FILE
+
+
+def get_main_path(working_directory: str) -> str:
+    main_file = get_main_file()
+    main_raw_path = os.path.join(working_directory, main_file)
+    return os.path.abspath(main_raw_path)
+
+
+def start(working_directory: str) -> None:
+    validate_env()
+
+    entrypoint_path = get_main_path(working_directory)
+
+    if not os.path.exists(entrypoint_path):
+        raise CliError(f"Could not find {get_main_file()} file")
+
+    parent_package = os.path.dirname(entrypoint_path)
+
+    bot_token_var = EnvVarHandler(SLACK_BOT_TOKEN)
+    app_token_var = EnvVarHandler(SLACK_APP_TOKEN)
+
+    try:
+        bot_token_var.set_default(os.environ[SLACK_CLI_XOXB])
+        app_token_var.set_default(os.environ[SLACK_CLI_XAPP])
+        sys.path.insert(0, parent_package)  # Add parent package to sys path
+
+        runpy.run_path(entrypoint_path, run_name="__main__")
+    finally:
+        sys.path.remove(parent_package)
+        bot_token_var.clean()
+        app_token_var.clean()
+
+
+if __name__ == "__main__":
+    PROTOCOL = protocol_factory()
+    start(os.getcwd())

slack_cli_hooks/protocol/__init__.py

@@ -0,0 +1,24 @@
+import argparse
+import sys
+from typing import List
+from .default_protocol import DefaultProtocol
+from .message_boundary_protocol import MessageBoundaryProtocol
+from .protocol import Protocol
+
+__all__ = [
+    "DefaultProtocol",
+    "MessageBoundaryProtocol",
+    "Protocol",
+]
+
+
+def protocol_factory(argv: List[str] = sys.argv[1:]) -> Protocol:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--protocol", type=str, required=False)
+    parser.add_argument("--boundary", type=str, required=False)
+
+    args, unknown = parser.parse_known_args(args=argv)
+
+    if args.protocol == MessageBoundaryProtocol.name:
+        return MessageBoundaryProtocol(boundary=args.boundary)
+    return DefaultProtocol()

slack_cli_hooks/protocol/default_protocol.py

@@ -0,0 +1,24 @@
+from .protocol import Protocol
+
+
+class DefaultProtocol(Protocol):
+    name: str = "default"
+
+    def debug(self, msg: str, *args, **kwargs):
+        """Nothing will be logged here"""
+        pass
+
+    def info(self, msg: str, *args, **kwargs):
+        """Nothing will be logged here"""
+        pass
+
+    def warning(self, msg: str, *args, **kwargs):
+        """Nothing will be logged here"""
+        pass
+
+    def error(self, msg: str, *args, **kwargs):
+        """Nothing will be logged here"""
+        pass
+
+    def respond(self, data: str):
+        print(data)

slack_cli_hooks/protocol/message_boundary_protocol.py

@@ -0,0 +1,24 @@
+import logging
+from .protocol import Protocol
+
+
+class MessageBoundaryProtocol(Protocol):
+    name: str = "message-boundaries"
+
+    def __init__(self, boundary):
+        self.boundary = boundary
+
+    def debug(self, msg: str, *args, **kwargs):
+        logging.debug(msg, *args, **kwargs)
+
+    def info(self, msg: str, *args, **kwargs):
+        logging.info(msg, *args, **kwargs)
+
+    def warning(self, msg: str, *args, **kwargs):
+        logging.warning(msg, *args, **kwargs)
+
+    def error(self, msg: str, *args, **kwargs):
+        logging.error(msg, *args, **kwargs)
+
+    def respond(self, data: str):
+        print(self.boundary + data + self.boundary)