@tahminator/pipeline 1.0.88 → 1.0.89-beta.g8f9210df

package/README.md

@@ -30,6 +30,143 @@ bun run src/index.ts
 > [!WARNING]
 > This repository is iterating quickly & as such may have rough edges. I will always be happy to respond to & fix any issues anyone may have :)
 
+## Slash commands action
+
+Use [`actions/commands`](./actions/commands/README.md) to run your repository's workflows from PR comments such as `/merge` or `/ai`.
+
+Before using it:
+
+- Add the GitHub App ID and private key as repository secrets.
+- Include `yargs` and your loader's dependencies in `.github/scripts/package.json`.
+- Replace `<published-commit-sha>` with the reviewed pipeline commit you want to use.
+
+Choose one command source: a hardcoded list or a Bun script.
+
+|              | Hardcoded                              | Dynamic                                          |
+| ------------ | -------------------------------------- | ------------------------------------------------ |
+| Input        | `COMMANDS`                             | `DYNAMIC_COMMANDS_BUN_SCRIPT`                    |
+| Command list | Written directly in the workflow.      | Printed to stdout by a Bun script.               |
+| Source       | Default-branch workflow configuration. | Script from the authorized PR head.              |
+| Best for     | A fixed list of commands.              | Computing the list from repository code or data. |
+
+Both use the same permission checks and dispatch to repository-owned command workflows.
+
+### Examples
+
+Create these two files to add a `/hello` command that replies to the PR.
+
+**`.github/workflows/slash.yml`**
+
+```yaml
+name: Slash Command Dispatch
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+
+jobs:
+  dispatch:
+    if: >-
+      github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # please set these to keep this workflow secure
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - uses: tahminator/pipeline/actions/setup@<published-commit-sha>
+        with:
+          LINT_CI: false
+
+      - uses: tahminator/pipeline/actions/commands@<published-commit-sha>
+        with:
+          APP_ID: ${{ secrets._GITHUB_APP_APP_ID }}
+          PRIVATE_KEY: ${{ secrets._GITHUB_APP_PEM_CONTENT }}
+          COMMANDS: |
+            hello
+            merge
+```
+
+**`.github/workflows/hello-command.yml`**
+
+```yaml
+name: Hello command
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: Repository where the command was posted
+        required: true
+        type: string
+      comment-id:
+        description: ID of the slash-command comment
+        required: true
+        type: string
+      prId:
+        description: Pull request number
+        required: true
+        type: string
+      author:
+        description: Username that posted the command
+        required: true
+        type: string
+
+permissions:
+  pull-requests: write
+
+jobs:
+  hello:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Reply to the PR
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          script: |
+            const { prId, author } = context.payload.inputs;
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: Number(prId),
+              body: `Hello @${author}! This command ran from \`${context.ref}\`.`,
+            });
+```
+
+Once both files are on the default branch, a user with write access can comment `/hello` on an open, same-repository PR. The dispatcher runs `hello-command.yml` from the PR branch, and the handler replies with that branch's name. Replace the reply step with your command's work.
+
+### Commands from a Bun script
+
+Keep the same trigger, trusted checkout, and setup steps. Replace the final action step with:
+
+```yaml
+- uses: tahminator/pipeline/actions/commands@<published-commit-sha>
+  with:
+    APP_ID: ${{ secrets._GITHUB_APP_APP_ID }}
+    PRIVATE_KEY: ${{ secrets._GITHUB_APP_PEM_CONTENT }}
+    DYNAMIC_COMMANDS_BUN_SCRIPT: .github/scripts/src/load-slash-commands/index.ts
+```
+
+Create that file and print the available command names:
+
+```ts
+const commands = ["merge", "ai", "copy"];
+console.log(commands.join("\n"));
+```
+
+Print only command names to stdout, separated by newlines or commas. Use `console.error` for logs. Empty or invalid output, or a nonzero exit, fails the action.
+
+The action checks write access and rejects forks before loading this script from the PR head. Run `setup` first to provide Bun and dependencies; this action installs nothing.
+
+> [!IMPORTANT]
+> Do not check out the PR head and install its dependencies before calling this action. The gate cannot protect earlier workflow steps. Keep pre-authorization setup on trusted code, as in the example.
+
+See the [action documentation](./actions/commands/README.md) for GitHub App permissions and the full dispatch contract.
+
 ## Available Clients
 
 ```ts

package/dist/internal/commands/helper.d.ts

@@ -0,0 +1,7 @@
+/** Exactly one source: inline names or a repository-owned Bun loader. */
+export declare function parseCommands(input: string, file: string): {
+    commands: string;
+    file: string;
+};
+/** Runs only after the action has checked write permission and rejected fork heads. */
+export declare function loadCommands(file: string, workspace: string): Promise<string>;

package/dist/internal/commands/helper.js

@@ -0,0 +1,44 @@
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+/** Exactly one source: inline names or a repository-owned Bun loader. */
+export function parseCommands(input, file) {
+    if (Boolean(input.trim()) === Boolean(file.trim())) {
+        throw new Error("Set exactly one of COMMANDS or DYNAMIC_COMMANDS_BUN_SCRIPT");
+    }
+    if (file.trim()) {
+        if (/[\r\n]/.test(file) ||
+            path.isAbsolute(file) ||
+            file.split(/[\\/]/).includes("..")) {
+            throw new Error("DYNAMIC_COMMANDS_BUN_SCRIPT must be a repository-relative file path");
+        }
+        return { commands: "", file };
+    }
+    const commands = input.split(/[\s,]+/).filter(Boolean);
+    if (!commands.length ||
+        commands.some((name) => !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(name))) {
+        throw new Error("COMMANDS must contain command names separated by commas or newlines");
+    }
+    return { commands: commands.join("\n"), file: "" };
+}
+/** Runs only after the action has checked write permission and rejected fork heads. */
+export async function loadCommands(file, workspace) {
+    const root = await realpath(workspace);
+    const source = await realpath(path.resolve(root, file));
+    const relative = path.relative(root, source);
+    if (relative.startsWith("..") ||
+        path.isAbsolute(relative) ||
+        !(await stat(source)).isFile()) {
+        throw new Error("The command loader must be a file inside the repository");
+    }
+    const child = Bun.spawn([process.execPath, "run", "--no-install", source], {
+        cwd: root,
+        stdout: "pipe",
+        stderr: "inherit",
+    });
+    const stdout = await new Response(child.stdout).text();
+    const exitCode = await child.exited;
+    if (exitCode !== 0) {
+        throw new Error(`Command loader exited with code ${exitCode}`);
+    }
+    return parseCommands(stdout, "").commands;
+}

package/dist/internal/commands/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/commands/index.js

@@ -0,0 +1,40 @@
+import { appendFile } from "node:fs/promises";
+import yargs from "yargs";
+import { loadCommands, parseCommands } from "./helper";
+const { commands, dynamicCommandsBunScript, file, workspace } = await yargs(process.argv.slice(2))
+    .option("commands", {
+    type: "string",
+    describe: "Hardcoded command names separated by commas or newlines",
+})
+    .option("dynamicCommandsBunScript", {
+    type: "string",
+    describe: "Repository-relative Bun loader path",
+})
+    .option("file", {
+    type: "string",
+    describe: "Execute the previously validated Bun loader",
+})
+    .option("workspace", {
+    type: "string",
+    default: process.env.GITHUB_WORKSPACE,
+    describe: "Repository root for loader execution",
+})
+    .conflicts("file", ["commands", "dynamicCommandsBunScript"])
+    .strict()
+    .parse();
+async function main() {
+    const output = process.env.GITHUB_OUTPUT;
+    if (!output)
+        throw new Error("GITHUB_OUTPUT is required");
+    let result;
+    if (file) {
+        if (!workspace)
+            throw new Error("--workspace or GITHUB_WORKSPACE is required");
+        result = { commands: await loadCommands(file, workspace), file: "" };
+    }
+    else {
+        result = parseCommands(commands ?? "", dynamicCommandsBunScript ?? "");
+    }
+    await appendFile(output, `commands<<__COMMANDS__\n${result.commands}\n__COMMANDS__\nfile=${result.file}\n`);
+}
+await main();

package/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "author": "Tahmid Ahmed",
   "description": "A collection of Bun shell scripts that can be re-used in various CICD pipelines.",
-  "version": "1.0.88",
+  "version": "1.0.89-beta.g8f9210df",
   "repository": {
     "url": "git+https://github.com/tahminator/pipeline.git"
   },