deploy-vir 3.0.1 → 3.2.0

package/dist/cli/cli.js

@@ -48,7 +48,7 @@ export async function runDeployVir(args, config) {
         const branchConfig = assertWrap.isDefined(repoConfig.deploys.find((deploy) => deploy.deployName === args.deployName, `Failed to find a deploy named '${args.deployName}' in repo '${args.repoName}'.`));
         const remoteName = await getGitRemoteName(git, repoConfig);
         log.faint(`Remote: ${remoteName}`);
-        await pushDeploy(git, branchConfig, repoConfig, remoteName, config.notifications, args.bypassConfirmation);
+        await pushDeploy(git, branchConfig, repoConfig, remoteName, config.notifications, args.bypassConfirmation, config.hooks);
     }
     catch (error) {
         if (error instanceof KnownError) {

package/dist/config.d.ts

@@ -1,3 +1,5 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type DeployResult } from './git.js';
 /**
  * The full deploy-vir config object.
  *
@@ -6,6 +8,32 @@
 export type DeployVirConfig = {
     repos: DeployVirRepoConfig[];
     notifications?: NotificationConfig[] | undefined;
+    hooks?: DeployVirHooks | undefined;
+};
+/**
+ * Hooks to run at various points during a deploy.
+ *
+ * @category Config
+ */
+export type DeployVirHooks = {
+    /**
+     * Runs after the user accepts (or bypasses confirmation for) a deploy and the push has
+     * completed successfully. Fires once per branch deploy.
+     */
+    postAccept?: ((params: Readonly<PostAcceptHookParams>) => MaybePromise<void>) | undefined;
+};
+/**
+ * Params passed to a {@link DeployVirHooks.postAccept} hook.
+ *
+ * @category Config
+ */
+export type PostAcceptHookParams = {
+    repoConfig: Readonly<DeployVirRepoConfig>;
+    branchConfig: Readonly<DeployVirBranchConfig>;
+    fromBranch: string;
+    toBranch: string;
+    remoteName: string;
+    deployResult: Readonly<DeployResult>;
 };
 /**
  * All available targets for sending notifications to.
@@ -52,6 +80,15 @@ export type SlackNotificationConfig = {
  * @category Config
  */
 export type NotificationConfig = SlackNotificationConfig;
+/**
+ * A deploy-level notification override. Same as {@link NotificationConfig} but `webhookUrl` is
+ * optional — when omitted, the first matching top-level notification's `webhookUrl` is used.
+ *
+ * @category Config
+ */
+export type DeployNotificationConfig = Omit<SlackNotificationConfig, 'webhookUrl'> & {
+    webhookUrl?: string | undefined;
+};
 /**
  * A repo config for deploying.
  *
@@ -97,6 +134,13 @@ export type DeployVirBranchConfig = {
         enableNotifications?: boolean | undefined;
     }[];
     enableNotifications?: boolean | undefined;
+    /**
+     * Deploy-level notification overrides. When set, these are used instead of the top-level
+     * notifications. If a notification here omits `webhookUrl`, the first top-level notification
+     * with the same `target` provides it. Setting this also implicitly enables notifications for
+     * this deploy.
+     */
+    notifications?: DeployNotificationConfig[] | undefined;
 };
 /**
  * Define a type safe deploy-vir config.

package/dist/git.d.ts

@@ -1,5 +1,5 @@
 import { type DefaultLogFields, type ListLogLine, type SimpleGit } from 'simple-git';
-import { type DeployVirBranchConfig, type DeployVirRepoConfig, type NotificationConfig } from './config.js';
+import { type DeployVirBranchConfig, type DeployVirHooks, type DeployVirRepoConfig, type NotificationConfig } from './config.js';
 /**
  * Find the git remote's name, or create a new one.
  *
@@ -45,4 +45,4 @@ export type DeployResult = {
  *
  * @category Internal
  */
-export declare function pushDeploy(git: Readonly<SimpleGit>, branchConfig: Readonly<DeployVirBranchConfig>, repoConfig: Readonly<DeployVirRepoConfig>, remoteName: string, notifications: ReadonlyArray<Readonly<NotificationConfig>> | undefined, bypassConfirmation?: boolean): Promise<DeployResult[]>;
+export declare function pushDeploy(git: Readonly<SimpleGit>, branchConfig: Readonly<DeployVirBranchConfig>, repoConfig: Readonly<DeployVirRepoConfig>, remoteName: string, notifications: ReadonlyArray<Readonly<NotificationConfig>> | undefined, bypassConfirmation: boolean | undefined, hooks: Readonly<DeployVirHooks> | undefined): Promise<DeployResult[]>;

package/dist/git.js

@@ -31,7 +31,7 @@ export async function getGitRemoteName(git, repoConfig) {
  *
  * @category Internal
  */
-export async function pushDeploy(git, branchConfig, repoConfig, remoteName, notifications, bypassConfirmation = false) {
+export async function pushDeploy(git, branchConfig, repoConfig, remoteName, notifications, bypassConfirmation = false, hooks) {
     const { deployName, branches } = branchConfig;
     return await awaitedBlockingMap(branches, async ({ fromBranch, toBranch, enableNotifications }) => {
         assert.isTruthy(fromBranch, `Deploy '${deployName}' fromBranch cannot be empty.`);
@@ -100,11 +100,24 @@ export async function pushDeploy(git, branchConfig, repoConfig, remoteName, noti
                 after: afterCommit,
             },
         };
-        if (notifications?.length &&
-            (repoConfig.enableNotifications ||
-                enableNotifications ||
-                branchConfig.enableNotifications)) {
-            await sendNotifications(notifications, {
+        if (hooks?.postAccept) {
+            await hooks.postAccept({
+                branchConfig,
+                deployResult,
+                fromBranch,
+                remoteName,
+                repoConfig,
+                toBranch,
+            });
+        }
+        const resolvedNotifications = resolveNotifications({
+            branchConfig,
+            enableNotifications,
+            globalNotifications: notifications,
+            repoConfig,
+        });
+        if (resolvedNotifications.length) {
+            await sendNotifications(resolvedNotifications, {
                 branchConfig,
                 deployResult,
                 repoConfig,
@@ -113,3 +126,28 @@ export async function pushDeploy(git, branchConfig, repoConfig, remoteName, noti
         return deployResult;
     });
 }
+function resolveNotifications({ branchConfig, enableNotifications, globalNotifications, repoConfig, }) {
+    if (branchConfig.notifications?.length) {
+        return resolveDeployNotifications(branchConfig.notifications, globalNotifications);
+    }
+    const notificationsEnabled = repoConfig.enableNotifications || enableNotifications || branchConfig.enableNotifications;
+    if (notificationsEnabled && globalNotifications?.length) {
+        return [...globalNotifications];
+    }
+    return [];
+}
+function resolveDeployNotifications(deployNotifications, globalNotifications) {
+    return deployNotifications.map((deployNotification) => {
+        if (deployNotification.webhookUrl) {
+            return deployNotification;
+        }
+        const globalWebhookUrl = globalNotifications?.[0]?.webhookUrl;
+        if (!globalWebhookUrl) {
+            throw new KnownError(`Deploy notification for target '${deployNotification.target}' is missing webhookUrl and no top-level notification was found to fall back on.`);
+        }
+        return {
+            ...deployNotification,
+            webhookUrl: globalWebhookUrl,
+        };
+    });
+}

package/dist/notifications/slack.js

@@ -27,7 +27,10 @@ function chunkSectionLines(lines) {
         const latestSection = sectionLines.slice(-1)[0];
         const currentSection = latestSection && latestSection.length + line.length < slackMaxSectionLength
             ? latestSection
-            : pushAndGet(sectionLines, { length: 0, lines: [] });
+            : pushAndGet(sectionLines, {
+                length: 0,
+                lines: [],
+            });
         currentSection.length += line.length;
         currentSection.lines.push(line);
     });
@@ -107,7 +110,10 @@ export async function sendNotificationToSlack({ deployResult: { deployCommits: {
     ];
     await sendSlackMessage(notification, {
         attachments: [],
-        channel: addPrefix({ value: notification.channelName, prefix: '#' }),
+        channel: addPrefix({
+            value: notification.channelName,
+            prefix: '#',
+        }),
         blocks,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "deploy-vir",
-    "version": "3.0.1",
+    "version": "3.2.0",
     "description": "Deploy a branch to another branch with notifications.",
     "keywords": [
         "deploy",
@@ -41,51 +41,51 @@
         "test:update": "npm run test update"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.61.0",
-        "@augment-vir/common": "^31.61.0",
-        "@augment-vir/node": "^31.61.0",
-        "@inquirer/prompts": "^8.2.1",
-        "@slack/web-api": "^7.14.1",
+        "@augment-vir/assert": "^31.68.4",
+        "@augment-vir/common": "^31.68.4",
+        "@augment-vir/node": "^31.68.4",
+        "@inquirer/prompts": "^8.4.2",
+        "@slack/web-api": "^7.15.1",
         "cli-vir": "^1.0.3",
-        "simple-git": "^3.31.1",
+        "simple-git": "^3.36.0",
         "tsx": "^4.21.0",
-        "url-vir": "^2.1.7"
+        "url-vir": "^2.1.8"
     },
     "devDependencies": {
-        "@eslint/eslintrc": "^3.3.3",
+        "@eslint/eslintrc": "^3.3.5",
         "@eslint/js": "^9.39.2",
-        "@stylistic/eslint-plugin": "^5.8.0",
+        "@stylistic/eslint-plugin": "^5.10.0",
         "@stylistic/eslint-plugin-ts": "^4.4.1",
-        "@types/node": "^25.2.3",
-        "@typescript-eslint/eslint-plugin": "^8.56.0",
-        "cspell": "^9.6.4",
-        "dependency-cruiser": "^17.3.8",
-        "esbuild": "^0.27.3",
+        "@types/node": "^25.6.0",
+        "@typescript-eslint/eslint-plugin": "^8.59.0",
+        "cspell": "^10.0.0",
+        "dependency-cruiser": "^17.3.10",
+        "esbuild": "^0.28.0",
         "eslint": "^9.39.2",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-jsdoc": "^62.5.0",
+        "eslint-plugin-jsdoc": "^62.9.0",
         "eslint-plugin-monorepo-cop": "^1.0.2",
-        "eslint-plugin-playwright": "^2.5.1",
+        "eslint-plugin-playwright": "^2.10.2",
         "eslint-plugin-prettier": "^5.5.5",
         "eslint-plugin-require-extensions": "^0.1.3",
-        "eslint-plugin-sonarjs": "^3.0.6",
-        "eslint-plugin-unicorn": "^63.0.0",
+        "eslint-plugin-sonarjs": "^4.0.3",
+        "eslint-plugin-unicorn": "^64.0.0",
         "istanbul-smart-text-reporter": "^1.1.5",
-        "markdown-code-example-inserter": "^3.0.3",
-        "npm-check-updates": "^19.3.2",
+        "markdown-code-example-inserter": "^3.0.5",
+        "npm-check-updates": "^21.0.3",
         "prettier": "~3.3.3",
         "prettier-plugin-interpolated-html-tags": "^2.0.1",
         "prettier-plugin-jsdoc": "^1.8.0",
-        "prettier-plugin-multiline-arrays": "^4.1.4",
+        "prettier-plugin-multiline-arrays": "^4.1.7",
         "prettier-plugin-organize-imports": "^4.3.0",
-        "prettier-plugin-packagejson": "^3.0.0",
+        "prettier-plugin-packagejson": "^3.0.2",
         "prettier-plugin-sort-json": "^4.2.0",
         "prettier-plugin-toml": "^2.0.6",
         "runstorm": "^1.0.0",
-        "typedoc": "^0.28.17",
+        "typedoc": "^0.28.19",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.56.0",
-        "virmator": "^14.5.2"
+        "typescript-eslint": "^8.57.1",
+        "virmator": "^14.12.2"
     },
     "engines": {
         "node": ">=22"

package/src/cli/cli.ts

@@ -112,6 +112,7 @@ export async function runDeployVir(
             remoteName,
             config.notifications,
             args.bypassConfirmation,
+            config.hooks,
         );
     } catch (error) {
         if (error instanceof KnownError) {

package/src/config.ts

@@ -1,3 +1,6 @@
+import {type MaybePromise} from '@augment-vir/common';
+import {type DeployResult} from './git.js';
+
 /**
  * The full deploy-vir config object.
  *
@@ -6,6 +9,34 @@
 export type DeployVirConfig = {
     repos: DeployVirRepoConfig[];
     notifications?: NotificationConfig[] | undefined;
+    hooks?: DeployVirHooks | undefined;
+};
+
+/**
+ * Hooks to run at various points during a deploy.
+ *
+ * @category Config
+ */
+export type DeployVirHooks = {
+    /**
+     * Runs after the user accepts (or bypasses confirmation for) a deploy and the push has
+     * completed successfully. Fires once per branch deploy.
+     */
+    postAccept?: ((params: Readonly<PostAcceptHookParams>) => MaybePromise<void>) | undefined;
+};
+
+/**
+ * Params passed to a {@link DeployVirHooks.postAccept} hook.
+ *
+ * @category Config
+ */
+export type PostAcceptHookParams = {
+    repoConfig: Readonly<DeployVirRepoConfig>;
+    branchConfig: Readonly<DeployVirBranchConfig>;
+    fromBranch: string;
+    toBranch: string;
+    remoteName: string;
+    deployResult: Readonly<DeployResult>;
 };
 
 /**
@@ -57,6 +88,16 @@ export type SlackNotificationConfig = {
 // eslint-disable-next-line sonarjs/redundant-type-aliases
 export type NotificationConfig = SlackNotificationConfig;
 
+/**
+ * A deploy-level notification override. Same as {@link NotificationConfig} but `webhookUrl` is
+ * optional — when omitted, the first matching top-level notification's `webhookUrl` is used.
+ *
+ * @category Config
+ */
+export type DeployNotificationConfig = Omit<SlackNotificationConfig, 'webhookUrl'> & {
+    webhookUrl?: string | undefined;
+};
+
 /**
  * A repo config for deploying.
  *
@@ -103,6 +144,13 @@ export type DeployVirBranchConfig = {
         enableNotifications?: boolean | undefined;
     }[];
     enableNotifications?: boolean | undefined;
+    /**
+     * Deploy-level notification overrides. When set, these are used instead of the top-level
+     * notifications. If a notification here omits `webhookUrl`, the first top-level notification
+     * with the same `target` provides it. Setting this also implicitly enables notifications for
+     * this deploy.
+     */
+    notifications?: DeployNotificationConfig[] | undefined;
 };
 
 /**

package/src/git.ts

@@ -3,7 +3,9 @@ import {awaitedBlockingMap, log, logColors} from '@augment-vir/common';
 import {confirm} from '@inquirer/prompts';
 import {type DefaultLogFields, type ListLogLine, type SimpleGit} from 'simple-git';
 import {
+    type DeployNotificationConfig,
     type DeployVirBranchConfig,
+    type DeployVirHooks,
     type DeployVirRepoConfig,
     type NotificationConfig,
 } from './config.js';
@@ -99,6 +101,7 @@ export async function pushDeploy(
     remoteName: string,
     notifications: ReadonlyArray<Readonly<NotificationConfig>> | undefined,
     bypassConfirmation = false,
+    hooks: Readonly<DeployVirHooks> | undefined,
 ): Promise<DeployResult[]> {
     const {deployName, branches} = branchConfig;
     return await awaitedBlockingMap(
@@ -208,13 +211,26 @@ export async function pushDeploy(
                 },
             };
 
-            if (
-                notifications?.length &&
-                (repoConfig.enableNotifications ||
-                    enableNotifications ||
-                    branchConfig.enableNotifications)
-            ) {
-                await sendNotifications(notifications, {
+            if (hooks?.postAccept) {
+                await hooks.postAccept({
+                    branchConfig,
+                    deployResult,
+                    fromBranch,
+                    remoteName,
+                    repoConfig,
+                    toBranch,
+                });
+            }
+
+            const resolvedNotifications = resolveNotifications({
+                branchConfig,
+                enableNotifications,
+                globalNotifications: notifications,
+                repoConfig,
+            });
+
+            if (resolvedNotifications.length) {
+                await sendNotifications(resolvedNotifications, {
                     branchConfig,
                     deployResult,
                     repoConfig,
@@ -225,3 +241,52 @@ export async function pushDeploy(
         },
     );
 }
+
+function resolveNotifications({
+    branchConfig,
+    enableNotifications,
+    globalNotifications,
+    repoConfig,
+}: Readonly<{
+    branchConfig: Readonly<DeployVirBranchConfig>;
+    enableNotifications: boolean | undefined;
+    globalNotifications: ReadonlyArray<Readonly<NotificationConfig>> | undefined;
+    repoConfig: Readonly<DeployVirRepoConfig>;
+}>): NotificationConfig[] {
+    if (branchConfig.notifications?.length) {
+        return resolveDeployNotifications(branchConfig.notifications, globalNotifications);
+    }
+
+    const notificationsEnabled =
+        repoConfig.enableNotifications || enableNotifications || branchConfig.enableNotifications;
+
+    if (notificationsEnabled && globalNotifications?.length) {
+        return [...globalNotifications];
+    }
+
+    return [];
+}
+
+function resolveDeployNotifications(
+    deployNotifications: ReadonlyArray<Readonly<DeployNotificationConfig>>,
+    globalNotifications: ReadonlyArray<Readonly<NotificationConfig>> | undefined,
+): NotificationConfig[] {
+    return deployNotifications.map((deployNotification): NotificationConfig => {
+        if (deployNotification.webhookUrl) {
+            return deployNotification as NotificationConfig;
+        }
+
+        const globalWebhookUrl = globalNotifications?.[0]?.webhookUrl;
+
+        if (!globalWebhookUrl) {
+            throw new KnownError(
+                `Deploy notification for target '${deployNotification.target}' is missing webhookUrl and no top-level notification was found to fall back on.`,
+            );
+        }
+
+        return {
+            ...deployNotification,
+            webhookUrl: globalWebhookUrl,
+        };
+    });
+}

package/src/notifications/slack.ts

@@ -39,7 +39,10 @@ function chunkSectionLines(lines: ReadonlyArray<string>): string[][] {
         const currentSection =
             latestSection && latestSection.length + line.length < slackMaxSectionLength
                 ? latestSection
-                : pushAndGet(sectionLines, {length: 0, lines: []});
+                : pushAndGet(sectionLines, {
+                      length: 0,
+                      lines: [],
+                  });
         currentSection.length += line.length;
         currentSection.lines.push(line);
     });
@@ -139,7 +142,10 @@ export async function sendNotificationToSlack({
 
     await sendSlackMessage(notification, {
         attachments: [],
-        channel: addPrefix({value: notification.channelName, prefix: '#'}),
+        channel: addPrefix({
+            value: notification.channelName,
+            prefix: '#',
+        }),
         blocks,
     });
 }