@tahminator/pipeline 1.0.89 → 1.0.90-beta.gc63a80f4

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
@@ -48,6 +185,7 @@ import {
   VersioningClient,
   LocalPostgresClient,
   LocalRedisClient,
+  NotionClient,
 } from "@tahminator/pipeline";
 ```
 
@@ -67,6 +205,7 @@ Jump to client documentation
 - [`VersioningClient`](#versioningclient)
 - [`LocalPostgresClient`](#localpostgresclient)
 - [`LocalRedisClient`](#localredisclient)
+- [`NotionClient`](#notionclient)
 
 <!-- tocstop -->
 
@@ -511,3 +650,26 @@ async function main() {
 
 await main();
 ```
+
+### `NotionClient`
+
+Look up a page in a Notion database by its `ID` (`unique_id`) field and update its fields.
+
+The integration must be connected to the database (`...` -> `Connections`). The database must have exactly one data source with an `ID` property, since `ID` values are only unique per data source.
+
+```ts
+const notion = new NotionClient({
+  auth: {
+    token: process.env.NOTION_TOKEN!,
+  },
+  // database ID or URL
+  databaseId: process.env.NOTION_DATABASE_ID!,
+});
+
+// for an ID displayed as `TASK-123`, pass `123`; returns `null` if no page matches
+const page = await notion.getPageByUniqueId(123);
+
+if (page?.hasField("Status")) {
+  await page.saveField("Status", { status: { name: "Done" } });
+}
+```

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export * from "./postgres";
 export * from "./redis";
 export * from "./utils";
 export * from "./versioning";
+export * from "./notion";

package/dist/index.js

@@ -10,3 +10,4 @@ export * from "./postgres";
 export * from "./redis";
 export * from "./utils";
 export * from "./versioning";
+export * from "./notion";

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/dist/notion/client.d.ts

@@ -0,0 +1,21 @@
+import type { NotionClientOpts } from "./types";
+import { NotionPageObject } from "./page";
+/**
+ * Interface with a single Notion database: look up its pages by their `ID` field & update their fields.
+ *
+ * @note the database must have exactly one data source with an `ID` (`unique_id`) property, since `ID`
+ * values are only unique within a single data source.
+ */
+export declare class NotionClient {
+    private readonly client;
+    private readonly databaseId;
+    private dataSource?;
+    constructor(opts: NotionClientOpts);
+    /**
+     * Returns the page whose `ID` (`unique_id`) field equals `id`, or `null` if none exists.
+     * For an ID displayed as `TASK-123`, pass `123`.
+     */
+    getPageByUniqueId(id: number): Promise<NotionPageObject | null>;
+    private getDataSource;
+    private resolveDataSource;
+}

package/dist/notion/client.js

@@ -0,0 +1,71 @@
+import { Client, extractDatabaseId, isFullDatabase, isFullDataSource, isFullPage, } from "@notionhq/client";
+import { NotionPageObject } from "./page";
+/**
+ * Interface with a single Notion database: look up its pages by their `ID` field & update their fields.
+ *
+ * @note the database must have exactly one data source with an `ID` (`unique_id`) property, since `ID`
+ * values are only unique within a single data source.
+ */
+export class NotionClient {
+    client;
+    databaseId;
+    dataSource;
+    constructor(opts) {
+        this.client = new Client({ auth: opts.auth.token });
+        this.databaseId = extractDatabaseId(opts.databaseId) ?? opts.databaseId;
+    }
+    /**
+     * Returns the page whose `ID` (`unique_id`) field equals `id`, or `null` if none exists.
+     * For an ID displayed as `TASK-123`, pass `123`.
+     */
+    async getPageByUniqueId(id) {
+        const { dataSourceId, uniqueIdProperty } = await this.getDataSource();
+        const { results } = await this.client.dataSources.query({
+            data_source_id: dataSourceId,
+            filter: {
+                property: uniqueIdProperty,
+                unique_id: { equals: id },
+            },
+            page_size: 1,
+        });
+        const page = results.find(isFullPage);
+        return page ? new NotionPageObject(this.client, page) : null;
+    }
+    getDataSource() {
+        this.dataSource ??= this.resolveDataSource().catch((e) => {
+            this.dataSource = undefined;
+            throw e;
+        });
+        return this.dataSource;
+    }
+    async resolveDataSource() {
+        const database = await this.client.databases.retrieve({
+            database_id: this.databaseId,
+        });
+        if (!isFullDatabase(database)) {
+            throw new Error(`Notion database ${this.databaseId} is not accessible by this integration`);
+        }
+        const dataSources = await Promise.all(database.data_sources.map(({ id }) => this.client.dataSources.retrieve({ data_source_id: id })));
+        const resolved = dataSources.flatMap((dataSource) => {
+            if (!isFullDataSource(dataSource))
+                return [];
+            const uniqueIdProperty = Object.values(dataSource.properties).find((property) => property.type === "unique_id");
+            return uniqueIdProperty ?
+                [
+                    {
+                        dataSourceId: dataSource.id,
+                        uniqueIdProperty: uniqueIdProperty.name,
+                    },
+                ]
+                : [];
+        });
+        const [only, ...rest] = resolved;
+        if (!only) {
+            throw new Error(`Notion database ${this.databaseId} has no "ID" (unique_id) property`);
+        }
+        if (rest.length > 0) {
+            throw new Error(`Notion database ${this.databaseId} has ${resolved.length} data sources with an "ID" (unique_id) property; exactly one is supported`);
+        }
+        return only;
+    }
+}

package/dist/notion/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client";
+export * from "./page";
+export * from "./types";

package/dist/notion/index.js

@@ -0,0 +1,3 @@
+export * from "./client";
+export * from "./page";
+export * from "./types";

package/dist/notion/page.d.ts

@@ -0,0 +1,32 @@
+import type { Client, PageObjectResponse } from "@notionhq/client";
+import type { NotionPagePropertyUpdate } from "./types";
+/**
+ * Wraps a single Notion page (a row in a database) and allows reading & updating its fields.
+ */
+export declare class NotionPageObject {
+    private readonly client;
+    private page;
+    constructor(client: Client, page: PageObjectResponse);
+    get id(): string;
+    get url(): string;
+    /**
+     * Raw property values of the page, keyed by field name. Reflects the latest successful `saveField`.
+     */
+    get properties(): PageObjectResponse["properties"];
+    /**
+     * @returns `true` if the page has a field (property) named `name`.
+     */
+    hasField(name: string): boolean;
+    /**
+     * Persist a new value for the field `name` to Notion.
+     *
+     * @example
+     * ```ts
+     * await page.saveField("Status", { status: { name: "Done" } });
+     * await page.saveField("PR", { url: "https://github.com/tahminator/pipeline/pull/1" });
+     * ```
+     *
+     * @throws if the page has no field named `name`.
+     */
+    saveField(name: string, value: NotionPagePropertyUpdate): Promise<void>;
+}

package/dist/notion/page.js

@@ -0,0 +1,53 @@
+import { isFullPage } from "@notionhq/client";
+/**
+ * Wraps a single Notion page (a row in a database) and allows reading & updating its fields.
+ */
+export class NotionPageObject {
+    client;
+    page;
+    constructor(client, page) {
+        this.client = client;
+        this.page = page;
+    }
+    get id() {
+        return this.page.id;
+    }
+    get url() {
+        return this.page.url;
+    }
+    /**
+     * Raw property values of the page, keyed by field name. Reflects the latest successful `saveField`.
+     */
+    get properties() {
+        return this.page.properties;
+    }
+    /**
+     * @returns `true` if the page has a field (property) named `name`.
+     */
+    hasField(name) {
+        return Object.hasOwn(this.page.properties, name);
+    }
+    /**
+     * Persist a new value for the field `name` to Notion.
+     *
+     * @example
+     * ```ts
+     * await page.saveField("Status", { status: { name: "Done" } });
+     * await page.saveField("PR", { url: "https://github.com/tahminator/pipeline/pull/1" });
+     * ```
+     *
+     * @throws if the page has no field named `name`.
+     */
+    async saveField(name, value) {
+        if (!this.hasField(name)) {
+            throw new Error(`Notion page ${this.page.id} has no field named "${name}"`);
+        }
+        const updated = await this.client.pages.update({
+            page_id: this.page.id,
+            properties: { [name]: value },
+        });
+        if (isFullPage(updated)) {
+            this.page = updated;
+        }
+    }
+}

package/dist/notion/types.d.ts

@@ -0,0 +1,19 @@
+import type { UpdatePageParameters } from "@notionhq/client";
+/**
+ * Value accepted by Notion when updating a single page property, e.g. `{ checkbox: true }`.
+ */
+export type NotionPagePropertyUpdate = NonNullable<UpdatePageParameters["properties"]>[string];
+export type NotionClientOpts = {
+    auth: {
+        /**
+         * Internal integration secret from https://www.notion.so/profile/integrations
+         *
+         * @note the integration must be added to the database via `...` -> `Connections`.
+         */
+        token: string;
+    };
+    /**
+     * Database ID or URL, e.g. the 32-char ID in `https://www.notion.so/<workspace>/<databaseId>?v=...`
+     */
+    databaseId: string;
+};

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.89",
+  "version": "1.0.90-beta.gc63a80f4",
   "repository": {
     "url": "git+https://github.com/tahminator/pipeline.git"
   },
@@ -47,6 +47,7 @@
     "typescript": "^5"
   },
   "dependencies": {
+    "@notionhq/client": "^5.27.0",
     "@octokit/auth-app": "^8.2.0",
     "@octokit/rest": "^22.0.1",
     "@pulumi/pulumi": "^3.258.0",