Introduce a @slack/cli-hooks package that implements Slack CLI hooks

.github/workflows/ci-build.yml

@@ -11,9 +11,18 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     strategy:
+      fail-fast: false
       matrix:
         node-version: [18.x, 20.x]
-        package: [packages/logger, packages/oauth, packages/rtm-api, packages/socket-mode, packages/types, packages/web-api, packages/webhook]
+        package:
+          - packages/hooks
+          - packages/logger
+          - packages/oauth
+          - packages/rtm-api
+          - packages/socket-mode
+          - packages/types
+          - packages/web-api
+          - packages/webhook
     steps:
     - uses: actions/checkout@v3
     - name: Use Node.js ${{ matrix.node-version }}

packages/hooks/.c8rc.json

@@ -0,0 +1,7 @@
+{
+  "include": ["src/*.js"],
+  "exclude": ["**/*.spec.js"],
+  "reporter": ["lcov"],
+  "all": false,
+  "cache": true
+}

packages/hooks/.eslintignore

@@ -0,0 +1 @@
+../../lint-configs/.eslintignore

packages/hooks/.eslintrc.cjs

@@ -0,0 +1,180 @@
+// SlackAPI JavaScript style
+// ---
+// This style helps maintainers enforce safe and consistent programming practices in this project. It is not meant to be
+// comprehensive on its own or vastly different from existing styles. The goal is to inherit and aggregate as many of
+// the communities' recommended styles for the technologies used as we can. When, and only when, we have a stated need
+// to differentiate, we add more rules (or modify options). Therefore, the fewer rules directly defined in this file,
+// the better.
+//
+// These styles are a subset of the shared JavaScript and TypeScript configurations to only target JavaScript packages.
+
+module.exports = {
+    // This is a root of the project, ESLint should not look through parent directories to find more config
+    root: true,
+
+    ignorePatterns: [
+        // Ignore all build outputs and artifacts (node_modules, dotfiles, and dot directories are implicitly ignored)
+        '/coverage',
+    ],
+
+    // These environments contain lists of global variables which are allowed to be accessed
+    env: {
+        // The target node version (v18) supports all important ES2022 features: https://node.green
+        es2022: true,
+        node: true,
+    },
+
+    extends: [
+        // ESLint's recommended built-in rules: https://eslint.org/docs/rules/
+        'eslint:recommended',
+
+        // Node plugin's recommended rules: https://github.com/mysticatea/eslint-plugin-node
+        'plugin:node/recommended',
+
+        // AirBnB style guide (without React) rules: https://github.com/airbnb/javascript.
+        'airbnb-base',
+
+        // JSDoc plugin's recommended rules
+        'plugin:jsdoc/recommended',
+    ],
+
+    rules: {
+        // JavaScript rules
+        // ---
+        // The top level of this configuration contains rules which apply to JavaScript.
+        //
+        // This section does not contain rules meant to override options or disable rules in the base configurations
+        // (ESLint, Node, AirBnb). Those rules are added in the final override.
+
+        // Eliminate tabs to standardize on spaces for indentation. If you want to use tabs for something other than
+        // indentation, you may need to turn this rule off using an inline config comments.
+        'no-tabs': 'error',
+
+        // Bans use of comma as an operator because it can obscure side effects and is often an accident.
+        'no-sequences': 'error',
+
+        // Disallow the use of process.exit()
+        'node/no-process-exit': 'error',
+
+        // Allow safe references to functions before the declaration.
+        'no-use-before-define': ['error', 'nofunc'],
+
+        // Allow scripts for hooks implementations.
+        'node/shebang': 'off',
+
+        // Allow unlimited classes in a file.
+        'max-classes-per-file': 'off',
+
+        // Disallow invocations of require(). This will help make imports more consistent and ensures a smoother
+        // transition to the best future syntax.
+        'import/no-commonjs': ['error', {
+            allowConditionalRequire: false,
+        }],
+
+        // Don't verify that all named imports are part of the set of named exports for the referenced module. The
+        // TypeScript compiler will already perform this check, so it is redundant.
+        'import/named': 'off',
+        'node/no-missing-import': 'off',
+
+        // Allow use of import and export syntax, despite it not being supported in the node versions. Since this
+        // project is transpiled, the ignore option is used. Overrides node/recommended.
+        'node/no-unsupported-features/es-syntax': ['error', { ignores: ['modules'] }],
+
+        'operator-linebreak': ['error', 'after', {
+            overrides: { '=': 'none' }
+        }],
+    },
+
+    overrides: [
+        {
+            files: ['**/*.js'],
+            rules: {
+                // Override rules
+                // ---
+                // This level of this configuration contains rules which override options or disable rules in the base
+                // configurations in JavaScript.
+
+                // Increase the max line length to 120. The rest of this setting is copied from the AirBnB config.
+                'max-len': ['error', 120, 2, {
+                    ignoreUrls: true,
+                    ignoreComments: false,
+                    ignoreRegExpLiterals: true,
+                    ignoreStrings: true,
+                    ignoreTemplateLiterals: true,
+                }],
+
+                // Restrict the use of backticks to declare a normal string. Template literals should only be used when the
+                // template string contains placeholders. The rest of this setting is copied from the AirBnb config.
+                quotes: ['error', 'single', { avoidEscape: true, allowTemplateLiterals: false }],
+
+                // The server side Slack API uses snake_case for parameters often.
+                //
+                // For mocking and override support, we need to allow snake_case.
+                // Allow leading underscores for parameter names, which is used to acknowledge unused variables in TypeScript.
+                // Also, enforce camelCase naming for variables. Ideally, the leading underscore could be restricted to only
+                // unused parameter names, but this rule isn't capable of knowing when a variable is unused. The camelcase and
+                // no-underscore-dangle rules are replaced with the naming-convention rule because this single rule can serve
+                // both purposes, and it works fine on non-TypeScript code.
+                camelcase: 'error',
+                'no-underscore-dangle': 'error',
+                'no-unused-vars': [
+                    'error',
+                    {
+                        varsIgnorePattern: '^_',
+                        argsIgnorePattern: '^_'
+                    }
+                ],
+
+                // Allow cyclical imports. Turning this rule on is mainly a way to manage the performance concern for linting
+                // time. Our projects are not large enough to warrant this. Overrides AirBnB styles.
+                'import/no-cycle': 'off',
+
+                // Prevent importing submodules of other modules. Using the internal structure of a module exposes
+                // implementation details that can potentially change in breaking ways. Overrides AirBnB styles.
+                'import/no-internal-modules': ['error', {
+                    // Use the following option to set a list of allowable globs in this project.
+                    allow: [
+                        '**/middleware/*', // the src/middleware directory doesn't export a module, it's just a namespace.
+                        '**/receivers/*', // the src/receivers directory doesn't export a module, it's just a namespace.
+                        '**/types/**/*',
+                        '**/types/*', // type heirarchies should be used however one wants
+                    ],
+                }],
+
+                // Remove the minProperties option for enforcing line breaks between braces. The AirBnB config sets this to 4,
+                // which is arbitrary and not backed by anything specific in the style guide. If we just remove it, we can
+                // rely on the max-len rule to determine if the line is too long and then enforce line breaks. Overrides AirBnB
+                // styles.
+                'object-curly-newline': ['error', { multiline: true, consistent: true }],
+            },
+        },
+        {
+            files: ['src/**/*.spec.js'],
+            rules: {
+                // Test-specific rules
+                // ---
+                // Rules that only apply to JavaScript _test_ source files
+
+                // With Mocha as a test framework, it is sometimes helpful to assign
+                // shared state to Mocha's Context object, for example in setup and
+                // teardown test methods. Assigning stub/mock objects to the Context
+                // object via `this` is a common pattern in Mocha. As such, using
+                // `function` over the the arrow notation binds `this` appropriately and
+                // should be used in tests. So: we turn off the prefer-arrow-callback
+                // rule.
+                // See https://github.com/slackapi/bolt-js/pull/1012#pullrequestreview-711232738
+                // for a case of arrow-vs-function syntax coming up for the team
+                'prefer-arrow-callback': 'off',
+                // Using ununamed functions (e.g., null logger) in tests is fine
+                'func-names': 'off',
+                // In tests, don't force constructing a Symbol with a descriptor, as
+                // it's probably just for tests
+                'symbol-description': 'off',
+
+                'node/no-unpublished-import': ['error', {
+                    "allowModules": ["mocha"],
+                }],
+            },
+        },
+    ],
+};

packages/hooks/.gitignore

@@ -0,0 +1,6 @@
+# Node and NPM stuff
+/node_modules
+package-lock.json
+
+# Coverage carryover
+/coverage

packages/hooks/README.md

@@ -0,0 +1,105 @@
+# Slack CLI Hooks
+
+The `@slack/hooks` package contains scripts that implement the contract between
+the [Slack CLI][cli] and [Bolt for JavaScript][bolt].
+
+## Requirements
+
+This package supports Node v18 and higher. It's highly recommended to use [the
+latest LTS version of Node][node].
+
+An updated version of the Slack CLI is also encouraged while using this package.
+
+## Installation
+
+Add this package as a development dependency for your project with the following
+command:
+
+```sh
+$ npm install --save-dev @slack/hooks
+```
+
+Follow [the installation guide][install] to download the Slack CLI and easily
+run the scripts included in this package.
+
+## Usage
+
+Scripts in this package are used by the Slack CLI when running certain commands.
+
+These scripts are automatically added to the `./node_modules/.bin` directory of
+a project when this package is installed.
+
+### Preparing a project manifest
+
+Define the [manifest of your application][manifest] in a `manifest.json` file:
+
+```json
+{
+  "display_information": {
+    "name": "Hooks"
+  },
+  "settings": {
+    "org_deploy_enabled": true,
+    "socket_mode_enabled": true,
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Hooks"
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": ["chat:write"]
+    }
+  }
+}
+```
+
+Or collect an existing manifest for your app from the **App Manifest** tab on
+[App Config][config].
+
+### Configuring the hooks interface
+
+Configure a Bolt project to use these scripts by creating a `slack.json` file in
+the root directory of your project:
+
+```json
+{
+  "hooks": {
+    "get-hooks": "npx -q --no-install -p @slack/hooks slack-cli-get-hooks"
+  }
+}
+```
+
+### Running the app
+
+With this package configured and the Slack CLI installed, you're ready to run
+your app:
+
+```sh
+$ slack run
+```
+
+## Getting help
+
+If you get stuck, we're here to help. The following are the best ways to get
+assistance working through your issue:
+
+* [Issue Tracker][issues] for questions, feature requests, bug reports and
+  general discussion related to these packages. Try searching before you create
+  a new issue.
+* [Email us][email]: `[email protected]`
+* [Community Slack][community]: a Slack community for developers building all
+  kinds of Slack apps. You can find the maintainers and users of these packages
+  in **#lang-javascript**.
+
+<!-- a collection of links -->
+[bolt]: https://github.com/slackapi/bolt-js
+[cli]: https://api.slack.com/automation/cli
+[community]: https://community.slack.com/
+[config]: https://api.slack.com/apps
+[email]: mailto:[email protected]
+[install]: https://api.slack.com/automation/cli/install
+[issues]: http://github.com/slackapi/node-slack-sdk/issues
+[manifest]: https://api.slack.com/reference/manifests
+[node]: https://github.com/nodejs/Release#release-schedule

packages/hooks/jsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "commonjs",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "checkJs": true,
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+
+    "moduleResolution": "node",
+    "baseUrl": ".",
+    "paths": {
+      "*": ["./types/*"]
+    },
+    "esModuleInterop" : true,
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "jsdoc": {
+    "out": "support/jsdoc",
+    "access": "public"
+  }
+}
+