deploy-vir 3.2.0 → 3.4.0

package/dist/config.d.ts

@@ -1,5 +1,5 @@
-import { type MaybePromise } from '@augment-vir/common';
-import { type DeployResult } from './git.js';
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type Commit, type DeployResult } from './git.js';
 /**
  * The full deploy-vir config object.
  *
@@ -18,9 +18,10 @@ export type DeployVirConfig = {
 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.
+     * completed successfully. Fires once per branch deploy. May optionally return values that
+     * modify the resulting notification message.
      */
-    postAccept?: ((params: Readonly<PostAcceptHookParams>) => MaybePromise<void>) | undefined;
+    postAccept?: ((params: Readonly<PostAcceptHookParams>) => MaybePromise<PostAcceptHookResult | void | undefined>) | undefined;
 };
 /**
  * Params passed to a {@link DeployVirHooks.postAccept} hook.
@@ -34,7 +35,24 @@ export type PostAcceptHookParams = {
     toBranch: string;
     remoteName: string;
     deployResult: Readonly<DeployResult>;
+    /**
+     * All commits included in this deploy (the commits being pushed from `fromBranch` to
+     * `toBranch`).
+     */
+    newCommits: ReadonlyArray<Readonly<Commit>>;
 };
+/**
+ * Optional values that a {@link DeployVirHooks.postAccept} hook can return to augment the resulting
+ * notification message.
+ *
+ * @category Config
+ */
+export type PostAcceptHookResult = PartialWithUndefined<{
+    /** Inserted into the notification immediately after the "<X> Pushed" header line. */
+    prependToNotification: string;
+    /** Appended to the very end of the notification message. */
+    appendToNotification: string;
+}>;
 /**
  * All available targets for sending notifications to.
  *

package/dist/git.js

@@ -100,16 +100,15 @@ export async function pushDeploy(git, branchConfig, repoConfig, remoteName, noti
                 after: afterCommit,
             },
         };
-        if (hooks?.postAccept) {
-            await hooks.postAccept({
-                branchConfig,
-                deployResult,
-                fromBranch,
-                remoteName,
-                repoConfig,
-                toBranch,
-            });
-        }
+        const hookResult = (await hooks?.postAccept?.({
+            branchConfig,
+            deployResult,
+            fromBranch,
+            newCommits: commitsAhead,
+            remoteName,
+            repoConfig,
+            toBranch,
+        })) || undefined;
         const resolvedNotifications = resolveNotifications({
             branchConfig,
             enableNotifications,
@@ -120,6 +119,7 @@ export async function pushDeploy(git, branchConfig, repoConfig, remoteName, noti
             await sendNotifications(resolvedNotifications, {
                 branchConfig,
                 deployResult,
+                hookResult: hookResult || undefined,
                 repoConfig,
             });
         }

package/dist/notifications/notification-params.d.ts

@@ -1,4 +1,4 @@
-import { type DeployVirBranchConfig, type DeployVirRepoConfig, type NotificationConfig, type NotificationTarget } from '../config.js';
+import { type DeployVirBranchConfig, type DeployVirRepoConfig, type NotificationConfig, type NotificationTarget, type PostAcceptHookResult } from '../config.js';
 import { type DeployResult } from '../git.js';
 /**
  * Params for sending a notification.
@@ -12,4 +12,5 @@ export type NotificationParams<Target extends NotificationTarget = NotificationT
     notification: Readonly<Extract<NotificationConfig, {
         target: Target;
     }>>;
+    hookResult?: Readonly<PostAcceptHookResult> | undefined;
 };

package/dist/notifications/slack.d.ts

@@ -5,4 +5,4 @@ export { type ChatPostMessageArguments } from '@slack/web-api';
  *
  * @category Internal
  */
-export declare function sendNotificationToSlack({ deployResult: { deployCommits: { deployedCommits, overwrittenCommits }, branchStatus: { after, before }, toBranchName, }, notification, repoConfig, }: Readonly<NotificationParams>): Promise<void>;
+export declare function sendNotificationToSlack({ deployResult: { deployCommits: { deployedCommits, overwrittenCommits }, branchStatus: { after, before }, toBranchName, }, hookResult, notification, repoConfig, }: Readonly<NotificationParams>): Promise<void>;

package/dist/notifications/slack.js

@@ -41,7 +41,7 @@ function chunkSectionLines(lines) {
  *
  * @category Internal
  */
-export async function sendNotificationToSlack({ deployResult: { deployCommits: { deployedCommits, overwrittenCommits }, branchStatus: { after, before }, toBranchName, }, notification, repoConfig, }) {
+export async function sendNotificationToSlack({ deployResult: { deployCommits: { deployedCommits, overwrittenCommits }, branchStatus: { after, before }, toBranchName, }, hookResult, notification, repoConfig, }) {
     const deployedCommitBullets = deployedCommits.map((commit) => formatCommit(repoConfig.commitBaseUrl, commit));
     const overwrittenCommitBullets = overwrittenCommits.map((commit) => formatCommit(repoConfig.commitBaseUrl, commit));
     const deployedCommitBulletLines = deployedCommitBullets.map((bullet) => `- ${bullet}`);
@@ -62,6 +62,17 @@ export async function sendNotificationToSlack({ deployResult: { deployCommits: {
                 text: `*${setFirstLetterCasing(repoConfig.name, StringCase.Upper)} ${setFirstLetterCasing(toBranchName, StringCase.Upper)}* Pushed`,
             },
         },
+        ...(hookResult?.prependToNotification
+            ? [
+                {
+                    type: 'section',
+                    text: {
+                        type: 'mrkdwn',
+                        text: hookResult.prependToNotification,
+                    },
+                },
+            ]
+            : []),
         {
             type: 'context',
             elements: [
@@ -107,6 +118,17 @@ export async function sendNotificationToSlack({ deployResult: { deployCommits: {
                 }),
             ]
             : []),
+        ...(hookResult?.appendToNotification
+            ? [
+                {
+                    type: 'section',
+                    text: {
+                        type: 'mrkdwn',
+                        text: hookResult.appendToNotification,
+                    },
+                },
+            ]
+            : []),
     ];
     await sendSlackMessage(notification, {
         attachments: [],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "deploy-vir",
-    "version": "3.2.0",
+    "version": "3.4.0",
     "description": "Deploy a branch to another branch with notifications.",
     "keywords": [
         "deploy",

package/src/config.ts

@@ -1,5 +1,5 @@
-import {type MaybePromise} from '@augment-vir/common';
-import {type DeployResult} from './git.js';
+import {type MaybePromise, type PartialWithUndefined} from '@augment-vir/common';
+import {type Commit, type DeployResult} from './git.js';
 
 /**
  * The full deploy-vir config object.
@@ -20,9 +20,14 @@ export type DeployVirConfig = {
 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.
+     * completed successfully. Fires once per branch deploy. May optionally return values that
+     * modify the resulting notification message.
      */
-    postAccept?: ((params: Readonly<PostAcceptHookParams>) => MaybePromise<void>) | undefined;
+    postAccept?:
+        | ((
+              params: Readonly<PostAcceptHookParams>,
+          ) => MaybePromise<PostAcceptHookResult | void | undefined>)
+        | undefined;
 };
 
 /**
@@ -37,8 +42,26 @@ export type PostAcceptHookParams = {
     toBranch: string;
     remoteName: string;
     deployResult: Readonly<DeployResult>;
+    /**
+     * All commits included in this deploy (the commits being pushed from `fromBranch` to
+     * `toBranch`).
+     */
+    newCommits: ReadonlyArray<Readonly<Commit>>;
 };
 
+/**
+ * Optional values that a {@link DeployVirHooks.postAccept} hook can return to augment the resulting
+ * notification message.
+ *
+ * @category Config
+ */
+export type PostAcceptHookResult = PartialWithUndefined<{
+    /** Inserted into the notification immediately after the "<X> Pushed" header line. */
+    prependToNotification: string;
+    /** Appended to the very end of the notification message. */
+    appendToNotification: string;
+}>;
+
 /**
  * All available targets for sending notifications to.
  *

package/src/git.ts

@@ -211,16 +211,16 @@ export async function pushDeploy(
                 },
             };
 
-            if (hooks?.postAccept) {
-                await hooks.postAccept({
+            const hookResult =
+                (await hooks?.postAccept?.({
                     branchConfig,
                     deployResult,
                     fromBranch,
+                    newCommits: commitsAhead,
                     remoteName,
                     repoConfig,
                     toBranch,
-                });
-            }
+                })) || undefined;
 
             const resolvedNotifications = resolveNotifications({
                 branchConfig,
@@ -233,6 +233,7 @@ export async function pushDeploy(
                 await sendNotifications(resolvedNotifications, {
                     branchConfig,
                     deployResult,
+                    hookResult: hookResult || undefined,
                     repoConfig,
                 });
             }

package/src/notifications/notification-params.ts

@@ -3,6 +3,7 @@ import {
     type DeployVirRepoConfig,
     type NotificationConfig,
     type NotificationTarget,
+    type PostAcceptHookResult,
 } from '../config.js';
 import {type DeployResult} from '../git.js';
 
@@ -16,4 +17,5 @@ export type NotificationParams<Target extends NotificationTarget = NotificationT
     branchConfig: Readonly<DeployVirBranchConfig>;
     repoConfig: Readonly<Pick<DeployVirRepoConfig, 'commitBaseUrl' | 'name'>>;
     notification: Readonly<Extract<NotificationConfig, {target: Target}>>;
+    hookResult?: Readonly<PostAcceptHookResult> | undefined;
 };

package/src/notifications/slack.ts

@@ -61,6 +61,7 @@ export async function sendNotificationToSlack({
         branchStatus: {after, before},
         toBranchName,
     },
+    hookResult,
     notification,
     repoConfig,
 }: Readonly<NotificationParams>) {
@@ -92,6 +93,17 @@ export async function sendNotificationToSlack({
                 text: `*${setFirstLetterCasing(repoConfig.name, StringCase.Upper)} ${setFirstLetterCasing(toBranchName, StringCase.Upper)}* Pushed`,
             },
         },
+        ...(hookResult?.prependToNotification
+            ? ([
+                  {
+                      type: 'section',
+                      text: {
+                          type: 'mrkdwn',
+                          text: hookResult.prependToNotification,
+                      },
+                  },
+              ] satisfies KnownBlock[])
+            : []),
         {
             type: 'context',
             elements: [
@@ -138,6 +150,17 @@ export async function sendNotificationToSlack({
                   }),
               ] satisfies KnownBlock[])
             : []),
+        ...(hookResult?.appendToNotification
+            ? ([
+                  {
+                      type: 'section',
+                      text: {
+                          type: 'mrkdwn',
+                          text: hookResult.appendToNotification,
+                      },
+                  },
+              ] satisfies KnownBlock[])
+            : []),
     ];
 
     await sendSlackMessage(notification, {