deploy-vir 0.0.2 → 0.1.0

package/README.md

@@ -22,7 +22,7 @@ export default defineDeployVirConfig({
         {
             /** This does not need to match the actual repo name. */
             name: 'whatever',
-            girUrl: 'git@github.com:electrovir/deploy-vir.git',
+            gitUrl: 'git@github.com:electrovir/deploy-vir.git',
             deploys: [
                 {
                     deployName: 'staging',

package/bin.js

@@ -3,6 +3,6 @@
 import {runCliScript} from '@augment-vir/node/dist/index.js';
 import {join} from 'node:path';
 
-const cliPath = join(import.meta.dirname, 'src', 'cli.script.ts');
+const cliPath = join(import.meta.dirname, 'src', 'cli', 'cli.script.ts');
 
 await runCliScript(cliPath, import.meta.filename, 'deploy-vir');

package/dist/cli/cli.js

@@ -27,6 +27,7 @@ export async function runDeployVir(args, config) {
         const repoConfig = assertWrap.isDefined(config.repos.find((repo) => repo.name === args.repoName, `Failed to find a repo config by name '${args.repoName}'`));
         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}`);
         const deployCommits = await pushDeploy(git, branchConfig, remoteName);
         if (config.notifications?.length) {
             await sendNotifications(config.notifications, {

package/dist/config.d.ts

@@ -71,7 +71,7 @@ export type DeployVirRepoConfig = {
      * - 'git@github.com:electrovir/deploy-vir.git'
      * - 'https://github.com/electrovir/deploy-vir.git'
      */
-    girUrl: string;
+    gitUrl: string;
     /**
      * A url to the base commit path for links. The commit hash will be appended to this for links
      * in notifications. If this is omitted, there simply won't be any links.

package/dist/git.d.ts

@@ -5,7 +5,7 @@ import { type DeployVirBranchConfig, type DeployVirRepoConfig } from './config.j
  *
  * @category Internal
  */
-export declare function getGitRemoteName(git: Readonly<SimpleGit>, repoConfig: Readonly<Pick<DeployVirRepoConfig, 'name' | 'girUrl'>>): Promise<string>;
+export declare function getGitRemoteName(git: Readonly<SimpleGit>, repoConfig: Readonly<Pick<DeployVirRepoConfig, 'name' | 'gitUrl'>>): Promise<string>;
 /**
  * A git commit.
  *

package/dist/git.js

@@ -9,9 +9,9 @@ import { KnownError } from './known.error.js';
  */
 export async function getGitRemoteName(git, repoConfig) {
     assert.isTruthy(repoConfig.name, 'Repo config name cannot be empty.');
-    assert.isTruthy(repoConfig.girUrl, 'Repo git URL cannot be empty.');
+    assert.isTruthy(repoConfig.gitUrl, 'Repo git URL cannot be empty.');
     const remotes = await git.getRemotes(true);
-    const remoteMatchByUrl = remotes.find((remote) => remote.refs.fetch === repoConfig.girUrl || remote.refs.push === repoConfig.girUrl);
+    const remoteMatchByUrl = remotes.find((remote) => remote.refs.fetch === repoConfig.gitUrl || remote.refs.push === repoConfig.gitUrl);
     if (remoteMatchByUrl) {
         return remoteMatchByUrl.name;
     }
@@ -22,7 +22,7 @@ export async function getGitRemoteName(git, repoConfig) {
     ]
         .filter(check.isTruthy)
         .join('-');
-    await git.addRemote(newRemoteName, repoConfig.girUrl);
+    await git.addRemote(newRemoteName, repoConfig.gitUrl);
     return newRemoteName;
 }
 /**
@@ -34,6 +34,7 @@ export async function pushDeploy(git, { deployName, fromBranch, toBranch }, remo
     assert.isTruthy(fromBranch, `Deploy '${deployName}' fromBranch cannot be empty.`);
     assert.isTruthy(toBranch, `Deploy '${deployName}' toBranch cannot be empty.`);
     assert.isTruthy(remoteName, 'Remote name cannot be empty.');
+    log.faint(`Pushing ${remoteName}/${fromBranch} to ${toBranch}`);
     await git.fetch(remoteName, fromBranch);
     const pushString = `${remoteName}/${fromBranch}:${toBranch}`;
     /** Get commits that are on {@link toBranch} but not on {@link fromBranch}. */

package/dist/notifications/slack.js

@@ -26,10 +26,10 @@ export async function sendNotificationToSlack({ branchConfig, deployCommits: { d
     const deployedCommitBullets = deployedCommits.map((commit) => formatCommit(repoConfig.commitBaseUrl, commit));
     const overwrittenCommitBullets = overwrittenCommits.map((commit) => formatCommit(repoConfig.commitBaseUrl, commit));
     const deployedCommitBulletsText = deployedCommitBullets
-        .map((bullet) => `• ${bullet}`)
+        .map((bullet) => `- ${bullet}`)
         .join('\n');
     const overwrittenCommitBulletsText = overwrittenCommitBullets.length
-        ? overwrittenCommitBullets.map((bullet) => `• ${bullet}`).join('\n')
+        ? overwrittenCommitBullets.map((bullet) => `- ${bullet}`).join('\n')
         : undefined;
     const blocks = [
         {

package/package.json

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

package/src/cli/cli.script.ts

@@ -0,0 +1,3 @@
+import {runDeployVirCli} from './cli.js';
+
+await runDeployVirCli(process.argv, process.cwd());

package/src/cli/cli.ts

@@ -0,0 +1,81 @@
+import {assertWrap} from '@augment-vir/assert';
+import {extractErrorMessage, log} from '@augment-vir/common';
+import simpleGit from 'simple-git';
+import {type DeployVirConfig} from '../config.js';
+import {getGitRemoteName, pushDeploy} from '../git.js';
+import {KnownError} from '../known.error.js';
+import {sendNotifications} from '../notifications/send-notifications.js';
+
+/**
+ * Run the deploy-vir CLI.
+ *
+ * @category Internal
+ */
+export async function runDeployVirCli(args: ReadonlyArray<string>, cwd = process.cwd()) {
+    const configPath = assertWrap.isTruthy(args[0], 'Missing config path.');
+    const repoName = assertWrap.isTruthy(args[1], 'Missing repo name.');
+    const deployName = assertWrap.isTruthy(args[2], 'Missing deploy name.');
+
+    const config = (await import(configPath)).default;
+
+    await runDeployVir({cwd, deployName, repoName}, config);
+}
+
+/**
+ * Args for {@link runDeployVir}.
+ *
+ * @category Internal
+ */
+export type DeployVirArgs = {
+    /** This must match a repo name in your config. */
+    repoName: string;
+    /** This much match a deploy name in your config. */
+    deployName: string;
+    cwd: string;
+};
+
+/**
+ * Run a deploy.
+ *
+ * @category Main
+ */
+export async function runDeployVir(
+    args: Readonly<DeployVirArgs>,
+    config: Readonly<DeployVirConfig>,
+) {
+    try {
+        const git = simpleGit(args.cwd);
+
+        const repoConfig = assertWrap.isDefined(
+            config.repos.find(
+                (repo) => repo.name === args.repoName,
+                `Failed to find a repo config by name '${args.repoName}'`,
+            ),
+        );
+        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}`);
+
+        const deployCommits = await pushDeploy(git, branchConfig, remoteName);
+
+        if (config.notifications?.length) {
+            await sendNotifications(config.notifications, {
+                branchConfig,
+                deployCommits,
+                repoConfig,
+            });
+        }
+    } catch (error) {
+        if (error instanceof KnownError) {
+            /** If its a known error, don't log the whole stack trace. */
+            log.error(extractErrorMessage(error));
+        } else {
+            log.error(error);
+        }
+    }
+}

package/src/config.ts

@@ -0,0 +1,110 @@
+/**
+ * The full deploy-vir config object.
+ *
+ * @category Config
+ */
+export type DeployVirConfig = {
+    repos: DeployVirRepoConfig[];
+    notifications?: NotificationConfig[] | undefined;
+};
+
+/**
+ * All available targets for sending notifications to.
+ *
+ * @category Internal
+ */
+export enum NotificationTarget {
+    Slack = 'slack',
+}
+
+/**
+ * Notification config for Slack.
+ *
+ * @category Internal
+ */
+export type SlackNotificationConfig = {
+    target: NotificationTarget;
+    /**
+     * Find or create this by going to:
+     *
+     * Apps and workflows > Custom Integrations > Incoming WebHooks
+     */
+    webhookUrl: string;
+    /**
+     * An emoji string for the Webhook's message. If not provided, the Webhook integration's avatar
+     * that you set will be used.
+     */
+    avatarEmoji?: string | undefined;
+    /**
+     * A username for the Webhook's message. If not provided, the Webhook integration's avatar that
+     * you set will be used.
+     */
+    username?: string | undefined;
+    /** A channel for the Webhook's message. If not provided, the Webhook integration */
+    channelName: string | undefined;
+    /**
+     * By default the notification will list out all commits that are getting deployed. This will
+     * turn that off.
+     */
+    hideAllCommits?: boolean | undefined;
+};
+
+/**
+ * Config for a notification when a deploy runs.
+ *
+ * @category Config
+ */
+// eslint-disable-next-line sonarjs/redundant-type-aliases
+export type NotificationConfig = SlackNotificationConfig;
+
+/**
+ * A repo config for deploying.
+ *
+ * @category Config
+ */
+export type DeployVirRepoConfig = {
+    /**
+     * Does not need to match the actual repo name in GitHub, it can just be whatever name you want
+     * to call it for deploy-vir.
+     */
+    name: string;
+    /**
+     * A git URL to the repo.
+     *
+     * @example
+     *
+     * - 'git@github.com:electrovir/deploy-vir.git'
+     * - 'https://github.com/electrovir/deploy-vir.git'
+     */
+    gitUrl: string;
+    /**
+     * A url to the base commit path for links. The commit hash will be appended to this for links
+     * in notifications. If this is omitted, there simply won't be any links.
+     *
+     * @example
+     *
+     * - 'https://github.com/electrovir/deploy-vir/commit'
+     */
+    commitBaseUrl?: string | undefined;
+    deploys: DeployVirBranchConfig[];
+};
+
+/**
+ * A deploy configuration.
+ *
+ * @category Config
+ */
+export type DeployVirBranchConfig = {
+    deployName: string;
+    fromBranch: string;
+    toBranch: string;
+};
+
+/**
+ * Define a type safe deploy-vir config.
+ *
+ * @category Internal
+ */
+export function defineDeployVirConfig(config: Readonly<DeployVirConfig>) {
+    return config;
+}

package/src/git.ts

@@ -0,0 +1,142 @@
+import {assert, check} from '@augment-vir/assert';
+import {extractErrorMessage, log, logColors} from '@augment-vir/common';
+import {askQuestion} from '@augment-vir/node';
+import {type DefaultLogFields, type ListLogLine, type SimpleGit} from 'simple-git';
+import {type DeployVirBranchConfig, type DeployVirRepoConfig} from './config.js';
+import {KnownError} from './known.error.js';
+
+/**
+ * Find the git remote's name, or create a new one.
+ *
+ * @category Internal
+ */
+export async function getGitRemoteName(
+    git: Readonly<SimpleGit>,
+    repoConfig: Readonly<Pick<DeployVirRepoConfig, 'name' | 'gitUrl'>>,
+): Promise<string> {
+    assert.isTruthy(repoConfig.name, 'Repo config name cannot be empty.');
+    assert.isTruthy(repoConfig.gitUrl, 'Repo git URL cannot be empty.');
+
+    const remotes = await git.getRemotes(true);
+
+    const remoteMatchByUrl = remotes.find(
+        (remote) =>
+            remote.refs.fetch === repoConfig.gitUrl || remote.refs.push === repoConfig.gitUrl,
+    );
+
+    if (remoteMatchByUrl) {
+        return remoteMatchByUrl.name;
+    }
+
+    const remoteMatchByNameCount: number = remotes.reduce(
+        (count, remote) => count + (remote.name === repoConfig.name ? 1 : 0),
+        0,
+    );
+
+    const newRemoteName = [
+        repoConfig.name,
+        remoteMatchByNameCount,
+    ]
+        .filter(check.isTruthy)
+        .join('-');
+
+    await git.addRemote(newRemoteName, repoConfig.gitUrl);
+
+    return newRemoteName;
+}
+
+/**
+ * A git commit.
+ *
+ * @category Internal
+ */
+export type Commit = DefaultLogFields & ListLogLine;
+
+/**
+ * All commits involved in a deploy.
+ *
+ * @category Internal
+ */
+export type DeployCommits = {
+    deployedCommits: ReadonlyArray<Readonly<Commit>>;
+    overwrittenCommits: ReadonlyArray<Readonly<Commit>>;
+};
+
+/**
+ * Push the deploy via git.
+ *
+ * @category Internal
+ */
+export async function pushDeploy(
+    git: Readonly<SimpleGit>,
+    {deployName, fromBranch, toBranch}: Readonly<DeployVirBranchConfig>,
+    remoteName: string,
+): Promise<DeployCommits> {
+    assert.isTruthy(fromBranch, `Deploy '${deployName}' fromBranch cannot be empty.`);
+    assert.isTruthy(toBranch, `Deploy '${deployName}' toBranch cannot be empty.`);
+    assert.isTruthy(remoteName, 'Remote name cannot be empty.');
+
+    log.faint(`Pushing ${remoteName}/${fromBranch} to ${toBranch}`);
+
+    await git.fetch(remoteName, fromBranch);
+
+    const pushString = `${remoteName}/${fromBranch}:${toBranch}`;
+
+    /** Get commits that are on {@link toBranch} but not on {@link fromBranch}. */
+    const commitsAhead = (
+        await git.log({
+            from: `${remoteName}/${toBranch}`,
+            to: `${remoteName}/${fromBranch}`,
+        })
+    ).all;
+
+    if (!commitsAhead.length) {
+        throw new KnownError('No commit diff: nothing to deploy!');
+    }
+
+    try {
+        await git.push(remoteName, pushString);
+
+        return {
+            deployedCommits: commitsAhead,
+            overwrittenCommits: [],
+        };
+    } catch (error) {
+        log.error(`Push failed: ${extractErrorMessage(error)}`);
+
+        /** Get commits that are on {@link toBranch} but not on {@link fromBranch}. */
+        const commitsBehind = await git.log({
+            from: `${remoteName}/${fromBranch}`,
+            to: `${remoteName}/${toBranch}`,
+        });
+
+        if (commitsBehind.total > 0) {
+            log.info(
+                `\nThe following ${commitsBehind.total} commit${commitsBehind.total === 1 ? '' : 's'} are on ${logColors.bold}${toBranch}${logColors.reset} but not on ${logColors.bold}${fromBranch}${logColors.reset}:`,
+            );
+            commitsBehind.all.forEach((commit, index) => {
+                log.faint(
+                    `    ${index + 1}. ${commit.hash.slice(0, 7)} (${commit.author_name}) - ${commit.message}`,
+                );
+            });
+        }
+
+        const shouldForcePush = await askQuestion(
+            `\nDo you want to force push ${logColors.bold}${fromBranch}${logColors.reset} to ${logColors.bold}${toBranch}${logColors.reset}?\n\n${logColors.warning}This will overwrite the commits listed above.${logColors.reset} (y/N): `,
+        );
+
+        if (shouldForcePush.toLowerCase() === 'y' || shouldForcePush.toLowerCase() === 'yes') {
+            await git.push(remoteName, pushString, ['--force']);
+            log.warning(
+                `Force pushed ${logColors.bold}${fromBranch}${logColors.reset} to ${logColors.bold}${toBranch}${logColors.reset}.`,
+            );
+        } else {
+            throw new KnownError(`Deploy aborted.`);
+        }
+
+        return {
+            deployedCommits: commitsAhead,
+            overwrittenCommits: commitsBehind.all,
+        };
+    }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './cli/cli.js';
+export * from './config.js';
+export * from './git.js';
+export * from './known.error.js';
+export * from './notifications/notification-params.js';
+export * from './notifications/send-notifications.js';
+export * from './notifications/slack.js';

package/src/known.error.ts

@@ -0,0 +1,8 @@
+/**
+ * A known error that won't get its full stack trace logged.
+ *
+ * @category Internal
+ */
+export class KnownError extends Error {
+    public override readonly name = 'KnownError';
+}

package/src/notifications/notification-params.ts

@@ -0,0 +1,19 @@
+import {
+    type DeployVirBranchConfig,
+    type DeployVirRepoConfig,
+    type NotificationConfig,
+    type NotificationTarget,
+} from '../config.js';
+import {type DeployCommits} from '../git.js';
+
+/**
+ * Params for sending a notification.
+ *
+ * @category Internal
+ */
+export type NotificationParams<Target extends NotificationTarget = NotificationTarget> = {
+    deployCommits: Readonly<DeployCommits>;
+    branchConfig: Readonly<DeployVirBranchConfig>;
+    repoConfig: Readonly<Pick<DeployVirRepoConfig, 'commitBaseUrl'>>;
+    notification: Readonly<Extract<NotificationConfig, {target: Target}>>;
+};

package/src/notifications/send-notifications.ts

@@ -0,0 +1,32 @@
+import {type NotificationConfig, NotificationTarget} from '../config.js';
+import {KnownError} from '../known.error.js';
+import {type NotificationParams} from './notification-params.js';
+import {sendNotificationToSlack} from './slack.js';
+
+/**
+ * Send all configured notifications.
+ *
+ * @category Internal
+ */
+export async function sendNotifications(
+    notifications: ReadonlyArray<Readonly<NotificationConfig>>,
+    {branchConfig, deployCommits, repoConfig}: Readonly<Omit<NotificationParams, 'notification'>>,
+) {
+    await Promise.all(
+        notifications.map(async (notification) => {
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (notification.target === NotificationTarget.Slack) {
+                await sendNotificationToSlack({
+                    deployCommits,
+                    branchConfig,
+                    repoConfig,
+                    notification,
+                });
+            } else {
+                throw new KnownError(
+                    `Unexpected notification target: '${String(notification.target)}'`,
+                );
+            }
+        }),
+    );
+}

package/src/notifications/slack.ts

@@ -0,0 +1,120 @@
+import {addPrefix} from '@augment-vir/common';
+import {type ChatPostMessageArguments} from '@slack/web-api';
+import {joinUrlPaths} from 'url-vir';
+import {type SlackNotificationConfig} from '../config.js';
+import {type Commit} from '../git.js';
+import {type NotificationParams} from './notification-params.js';
+
+export {type ChatPostMessageArguments} from '@slack/web-api';
+
+function truncateString(value: string, truncateAt = 100): string {
+    if (value.length > truncateAt) {
+        return `${value.slice(0, Math.max(0, truncateAt))}...`;
+    } else {
+        return value;
+    }
+}
+
+function formatCommit(baseCommitUrl: string | undefined, commit: Readonly<Commit>) {
+    const commitLine = `${commit.hash.slice(0, 7)} (${commit.author_name}) - ${truncateString(commit.message)}`;
+
+    if (baseCommitUrl) {
+        return `<${joinUrlPaths(baseCommitUrl, commit.hash)}|${commitLine}>`;
+    } else {
+        return commitLine;
+    }
+}
+
+/**
+ * Send a notification to Slack.
+ *
+ * @category Internal
+ */
+export async function sendNotificationToSlack({
+    branchConfig,
+    deployCommits: {deployedCommits, overwrittenCommits},
+    notification,
+    repoConfig,
+}: Readonly<NotificationParams>) {
+    const deployedCommitBullets = deployedCommits.map((commit) =>
+        formatCommit(repoConfig.commitBaseUrl, commit),
+    );
+    const overwrittenCommitBullets = overwrittenCommits.map((commit) =>
+        formatCommit(repoConfig.commitBaseUrl, commit),
+    );
+
+    const deployedCommitBulletsText = deployedCommitBullets
+        .map((bullet) => `- ${bullet}`)
+        .join('\n');
+
+    const overwrittenCommitBulletsText = overwrittenCommitBullets.length
+        ? overwrittenCommitBullets.map((bullet) => `- ${bullet}`).join('\n')
+        : undefined;
+
+    const blocks: any[] = [
+        {
+            type: 'section',
+            text: {
+                type: 'mrkdwn',
+                text: `*${branchConfig.deployName}* Deployed`,
+            },
+        },
+        {
+            type: 'section',
+            text: {
+                type: 'mrkdwn',
+                text: `\n*Deployed Commits*\n${deployedCommitBulletsText}`,
+            },
+        },
+        ...(overwrittenCommitBulletsText
+            ? [
+                  {
+                      type: 'section',
+                      text: {
+                          type: 'mrkdwn',
+                          text: `\n*Overwritten Commits*\n${overwrittenCommitBulletsText}`,
+                      },
+                  },
+              ]
+            : []),
+    ];
+
+    await sendSlackMessage(notification, {
+        attachments: [],
+        channel: addPrefix({value: notification.channelName, prefix: '#'}),
+        blocks,
+    });
+}
+
+async function sendSlackMessage(
+    slackConfig: Readonly<Pick<SlackNotificationConfig, 'avatarEmoji' | 'webhookUrl' | 'username'>>,
+    body: Readonly<ChatPostMessageArguments>,
+) {
+    try {
+        const response = await fetch(slackConfig.webhookUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                ...body,
+                ...(slackConfig.avatarEmoji
+                    ? {
+                          icon_emoji: slackConfig.avatarEmoji,
+                      }
+                    : {}),
+                ...(slackConfig.username
+                    ? {
+                          username: slackConfig.username,
+                      }
+                    : {}),
+            }),
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to send Slack webhook: ${response.status}`);
+        }
+    } catch (error) {
+        console.error('Error sending Slack message:', error);
+    }
+}