From ffafaf4f5e598b0cfaecb2a4b862f94b8603f30d Mon Sep 17 00:00:00 2001 From: William Bergamin Date: Mon, 8 Jan 2024 12:31:18 -0500 Subject: [PATCH] add symbolic link to readme (#79) --- README.md | 126 +------------------------------------------------- src/README.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+), 125 deletions(-) mode change 100644 => 120000 README.md create mode 100644 src/README.md diff --git a/README.md b/README.md deleted file mode 100644 index 66e7dbd..0000000 --- a/README.md +++ /dev/null @@ -1,125 +0,0 @@ -# deno-slack-hooks - -This library is intended to be used in applications running on Slack's -next-generation application platform, focused on remixable units of -functionality encapsulated as ephemeral functions. It implements the -communication contract between the [Slack CLI][cli] and any Slack app -development SDKs. - -## Overview - -This library enables inter-process communication between the -[Slack CLI tool][cli] and apps authored for Slack's -[next-generation platform][nextgen]. The CLI delegates various tasks to the -application SDK by means of invoking a process and expecting specific kinds of -responses in the process' resultant stdout. For a full list of these tasks, -check out the [Supported Scripts](#supported-scripts) section. - -## Requirements - -This library requires a recent (at least 1.22) version of -[deno](https://deno.land). - -Any invocations of this library require additional -[deno permissions](https://deno.land/manual/getting_started/permissions), -depending on which of the [Supported Scripts](#supported-scripts) is being -invoked. - -## Supported Scripts - -The hooks currently provided by this repo are `build`, `start`, `check-update`, -`install-update`, `get-trigger`, and `get-manifest`. - -| Hook Name | CLI Command | Description | -| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `build` | `slack deploy` | Bundles any functions with Deno into an output directory that's compatible with the Run on Slack runtime. Implemented in `build.ts`. | -| `check-update` | `slack upgrade` | Checks the App's SDK dependencies to determine whether or not any of your libraries need to be updated. Implemented in `check_update.ts`. | -| `get-manifest` | `slack manifest` | Converts a `manifest.json`, `manifest.js`, or `manifest.ts` file into a valid manifest JSON payload. Implemented in `get_manifest.ts`. | -| `get-hooks` | All | Fetches the list of available hooks for the CLI from this repository. Implemented in `mod.ts`. | -| `get-trigger` | `slack trigger create` | Converts a specified `json`, `js`, or `ts` file into a valid trigger JSON payload to be uploaded by the CLI to the `workflows.triggers.create` Slack API endpoint. Implemented in `get_trigger.ts`. | -| `install-update` | `slack upgrade` | Prompts the user to automatically update any dependencies that need to be updated based on the result of the `check-update` hook. Implemented in `install_update.ts`. | -| `start` | `slack run` | While developing and locally running a deno-slack-based application, the CLI manages a socket connection with Slack's backend and delegates to this hook for invoking the correct application function for relevant events incoming via this connection. For more information, see the [deno-slack-runtime](https://github.com/slackapi/deno-slack-runtime) repository's details on `local-run`. | - -### Check Update Script Usage - -The `check_update.ts` file is executed as a Deno program and takes no arguments. - -#### Example - -```bash -deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/check_update.ts -``` - -### Get Hooks Script Usage - -The `mod.ts` file is executed as a Deno program and takes no arguments. - -#### Example - -```bash -deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/mod.ts -``` - -### Get Trigger Script Usage - -The `get_trigger.ts` file is executed as a Deno program and takes one required -argument: - -| Arguments | Description | -| ---------- | --------------------------------------------------------------------------------------------------------------------- | -| `--source` | Absolute or relative path to your target trigger file. The trigger object must be exported as default from this file. | - -#### Example - -```bash -deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/get_trigger.ts --source="./trigger.ts" -``` - -### Install Update Script Usage - -The `install_update.ts` file is executed as a Deno program and takes no -arguments. - -#### Example - -```bash -deno run -q --config=deno.jsonc --allow-run --allow-read --allow-write --allow-net https://deno.land/x/deno_slack_hooks/install_update.ts -``` - -## Script Overrides Usage - -If you find yourself needing to override a hook script specified by this -library, you can do so in your Slack app's `/slack.json` file! Just specify a -new script for the hook in question. All supported hooks can be overwritten. - -Below is an example `/slack.json` file that overrides the `build` script to -point to your local repo for development purposes. It's using an implicit -"latest" version of the script, -but we suggest pinning it to whatever the latest version is. - -```json -{ - "hooks": { - "get-hooks": "deno run -q --allow-read --allow-net https://deno.land/x/deno_slack_hooks/mod.ts", - "build": "deno run -q --config=deno.jsonc --allow-read --allow-write --allow-net --allow-run file:////mod.ts" - } -} -``` - -The [Slack CLI][cli] will automatically know to pick up your local hook -definition and use that instead of what's defined by this library. - -This can also be used to change the flags sent to the `deno run` command if you -decide to change the location of your config file, or switch to an import map -instead. - ---- - -### Getting Help - -We welcome contributions from everyone! Please check out our -[Contributor's Guide](.github/CONTRIBUTING.md) for how to contribute in a -helpful and collaborative way. - -[cli]: https://github.com/slackapi/slack-cli -[nextgen]: https://api.slack.com/automation diff --git a/README.md b/README.md new file mode 120000 index 0000000..351df1d --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +src/README.md \ No newline at end of file diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..3d7456a --- /dev/null +++ b/src/README.md @@ -0,0 +1,125 @@ +# deno-slack-hooks + +This library is intended to be used in applications running on Slack's +next-generation application platform, focused on remixable units of +functionality encapsulated as ephemeral functions. It implements the +communication contract between the [Slack CLI][cli] and any Slack app +development SDKs. + +## Overview + +This library enables inter-process communication between the +[Slack CLI tool][cli] and apps authored for Slack's +[next-generation platform][nextgen]. The CLI delegates various tasks to the +application SDK by means of invoking a process and expecting specific kinds of +responses in the process' resultant stdout. For a full list of these tasks, +check out the [Supported Scripts](#supported-scripts) section. + +## Requirements + +This library requires a recent (at least 1.22) version of +[deno](https://deno.land). + +Any invocations of this library require additional +[deno permissions](https://deno.land/manual/getting_started/permissions), +depending on which of the [Supported Scripts](#supported-scripts) is being +invoked. + +## Supported Scripts + +The hooks currently provided by this repo are `build`, `start`, `check-update`, +`install-update`, `get-trigger`, and `get-manifest`. + +| Hook Name | CLI Command | Description | +| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `build` | `slack deploy` | Bundles any functions with Deno into an output directory that's compatible with the Run on Slack runtime. Implemented in `build.ts`. | +| `check-update` | `slack upgrade` | Checks the App's SDK dependencies to determine whether or not any of your libraries need to be updated. Implemented in `check_update.ts`. | +| `get-manifest` | `slack manifest` | Converts a `manifest.json`, `manifest.js`, or `manifest.ts` file into a valid manifest JSON payload. Implemented in `get_manifest.ts`. | +| `get-hooks` | All | Fetches the list of available hooks for the CLI from this repository. Implemented in `mod.ts`. | +| `get-trigger` | `slack trigger create` | Converts a specified `json`, `js`, or `ts` file into a valid trigger JSON payload to be uploaded by the CLI to the `workflows.triggers.create` Slack API endpoint. Implemented in `get_trigger.ts`. | +| `install-update` | `slack upgrade` | Prompts the user to automatically update any dependencies that need to be updated based on the result of the `check-update` hook. Implemented in `install_update.ts`. | +| `start` | `slack run` | While developing and locally running a deno-slack-based application, the CLI manages a socket connection with Slack's backend and delegates to this hook for invoking the correct application function for relevant events incoming via this connection. For more information, see the [deno-slack-runtime](https://github.com/slackapi/deno-slack-runtime) repository's details on `local-run`. | + +### Check Update Script Usage + +The `check_update.ts` file is executed as a Deno program and takes no arguments. + +#### Example + +```bash +deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/check_update.ts +``` + +### Get Hooks Script Usage + +The `mod.ts` file is executed as a Deno program and takes no arguments. + +#### Example + +```bash +deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/mod.ts +``` + +### Get Trigger Script Usage + +The `get_trigger.ts` file is executed as a Deno program and takes one required +argument: + +| Arguments | Description | +| ---------- | --------------------------------------------------------------------------------------------------------------------- | +| `--source` | Absolute or relative path to your target trigger file. The trigger object must be exported as default from this file. | + +#### Example + +```bash +deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/get_trigger.ts --source="./trigger.ts" +``` + +### Install Update Script Usage + +The `install_update.ts` file is executed as a Deno program and takes no +arguments. + +#### Example + +```bash +deno run -q --config=deno.jsonc --allow-run --allow-read --allow-write --allow-net https://deno.land/x/deno_slack_hooks/install_update.ts +``` + +## Script Overrides Usage + +If you find yourself needing to override a hook script specified by this +library, you can do so in your Slack app's `/slack.json` file! Just specify a +new script for the hook in question. All supported hooks can be overwritten. + +Below is an example `/slack.json` file that overrides the `build` script to +point to your local repo for development purposes. It's using an implicit +"latest" version of the script, +but we suggest pinning it to whatever the latest version is. + +```json +{ + "hooks": { + "get-hooks": "deno run -q --allow-read --allow-net https://deno.land/x/deno_slack_hooks/mod.ts", + "build": "deno run -q --config=deno.jsonc --allow-read --allow-write --allow-net --allow-run file:////mod.ts" + } +} +``` + +The [Slack CLI][cli] will automatically know to pick up your local hook +definition and use that instead of what's defined by this library. + +This can also be used to change the flags sent to the `deno run` command if you +decide to change the location of your config file, or switch to an import map +instead. + +--- + +### Getting Help + +We welcome contributions from everyone! Please check out our +[Contributor's Guide](https://github.com/slackapi/deno-slack-hooks/blob/main/.github/CONTRIBUTING.md) +for how to contribute in a helpful and collaborative way. + +[cli]: https://github.com/slackapi/slack-cli +[nextgen]: https://api.slack.com/automation