@simplysf/simply-cicd-core 0.2.2 → 0.4.0

package/lib/notify/buildNotification.js

@@ -0,0 +1,176 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { promises as fs } from 'node:fs';
+import { execa } from 'execa';
+import { isSubscriberPackageVersionId, readSfdxProject } from '@simplysf/simply-core';
+import { createAlmProvider } from '../alm/index.js';
+import { VersionTagFormat } from '../build/versionTagFormat.js';
+import { logger } from '../logger.js';
+import { NOT_AVAILABLE, renderIssuesFromCommitLog } from './getCommitStories.js';
+import { renderNotifyTemplate } from './renderTemplate.js';
+import { sendNotification } from './sendNotification.js';
+/** The file `build create-package-version` writes the new version's `04t` ID to. */
+export const SUBSCRIBER_PACKAGE_VERSION_ID_FILE = 'subscriberPackageVersionId.env';
+/**
+ * The `04t` ID of a package version created in this job: the explicit value if given, otherwise the
+ * one `build create-package-version` wrote to {@link SUBSCRIBER_PACKAGE_VERSION_ID_FILE}. `undefined`
+ * when the job created none.
+ */
+export async function resolveBuiltSubscriberPackageVersionId(explicit) {
+    if (explicit) {
+        return explicit;
+    }
+    let content;
+    try {
+        content = await fs.readFile(SUBSCRIBER_PACKAGE_VERSION_ID_FILE, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const value = /^SUBSCRIBER_PACKAGE_VERSION_ID=(?<id>\S+)\s*$/m.exec(content)?.groups?.id;
+    return value && isSubscriberPackageVersionId(value) ? value : undefined;
+}
+/** Fetches the tags, and the full history when the CI clone is shallow, so tags can be described and diffed. */
+export async function fetchVersionHistory() {
+    const { stdout } = await execa('git', ['rev-parse', '--is-shallow-repository']);
+    const unshallow = stdout.trim() === 'true' ? ['--unshallow'] : [];
+    await execa('git', ['fetch', ...unshallow, '--tags', '--quiet']);
+}
+/**
+ * The tag at `HEAD` that `build create-package-version` annotated with `subscriberPackageVersionId`.
+ * Matching on the annotation rather than the name works for any version tag format or suffix.
+ */
+export async function findPackageVersionTag(subscriberPackageVersionId) {
+    const { stdout } = await execa('git', [
+        'tag',
+        '--points-at',
+        'HEAD',
+        '--format=%(refname:short)%09%(contents:subject)',
+    ]);
+    return stdout
+        .split(/\r?\n/)
+        .map((line) => line.split('\t'))
+        .find(([, subject]) => subject?.trim() === subscriberPackageVersionId)?.[0];
+}
+/** The nearest version tag, in the project's format, before `versionTag`. `undefined` for a package's first version. */
+export async function findPreviousVersionTag(versionTag) {
+    const project = await readSfdxProject().catch(() => undefined);
+    const glob = VersionTagFormat.fromProject(project).matchPattern();
+    try {
+        const { stdout } = await execa('git', ['describe', '--tags', '--abbrev=0', '--match', glob, `${versionTag}^`]);
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves the new version's tag, the previous version's tag, and the issue references in between.
+ * Never throws: anything it can't resolve comes back as `N/A`, because a notification shouldn't be
+ * what fails a build.
+ */
+export async function getPackageVersionHistory(subscriberPackageVersionId, options) {
+    const history = { ...NOT_AVAILABLE, versionTag: 'N/A', previousVersionTag: 'N/A' };
+    try {
+        await fetchVersionHistory();
+        const versionTag = await findPackageVersionTag(subscriberPackageVersionId);
+        if (!versionTag) {
+            logger.warn(`No tag at HEAD is annotated with ${subscriberPackageVersionId}.`);
+            return history;
+        }
+        history.versionTag = versionTag;
+        const previousVersionTag = await findPreviousVersionTag(versionTag);
+        if (!previousVersionTag) {
+            logger.info(`No version tag before ${versionTag}. Skipping stories.`);
+            return history;
+        }
+        history.previousVersionTag = previousVersionTag;
+        const { stdout: commits } = await execa('git', ['log', '--pretty=oneline', `${previousVersionTag}..${versionTag}`]);
+        if (commits) {
+            Object.assign(history, renderIssuesFromCommitLog(commits, options.almProjectKey, {
+                almBaseUrl: options.almBaseUrl,
+                almProvider: createAlmProvider(options.almProvider ?? 'jira'),
+            }));
+        }
+    }
+    catch (error) {
+        logger.warn(`Could not resolve package version history: ${error.message}`);
+        if (options.debug) {
+            logger.error(String(error));
+        }
+    }
+    return history;
+}
+/**
+ * Posts a failure card for a failed build job, or a package version card for a successful job that
+ * created a package version. Any other job result sends nothing.
+ */
+export async function sendBuildNotification(options) {
+    const { ciJobStatus } = options;
+    const templateData = {
+        refName: options.ciCommitRefName,
+        pipelineUrl: options.ciPipelineUrl,
+        pipelineId: options.ciPipelineId,
+        projectTitle: options.ciProjectTitle,
+        jobName: options.ciJobName,
+        stage: options.ciJobStage,
+        stories: 'N/A',
+        storiesLinked: 'N/A',
+    };
+    let templateName;
+    if (ciJobStatus === 'failed') {
+        templateName = 'build-failure-notification';
+    }
+    else if (ciJobStatus === 'success') {
+        const subscriberPackageVersionId = await resolveBuiltSubscriberPackageVersionId(options.subscriberPackageVersionId);
+        if (!subscriberPackageVersionId) {
+            logger.info('No package version was created in this job. Skipping notification.');
+            return { sent: false };
+        }
+        templateName = 'build-package-version-notification';
+        logger.info(`Gathering stories for package version ${subscriberPackageVersionId}...`);
+        const history = await getPackageVersionHistory(subscriberPackageVersionId, options);
+        Object.assign(templateData, {
+            subscriberPackageVersionId,
+            packageVersion: history.versionTag,
+            packageVersionPrevious: history.previousVersionTag,
+            stories: history.stories,
+            storiesLinked: history.storiesWithUrl,
+        });
+    }
+    else {
+        logger.info(`No notification logic for job status: ${ciJobStatus ?? 'unknown'}`);
+        return { sent: false };
+    }
+    const payload = {
+        content: renderNotifyTemplate(templateName, templateData),
+        refName: options.ciCommitRefName,
+        pipelineId: options.ciPipelineId,
+        pipelineUrl: options.ciPipelineUrl,
+        projectTitle: options.ciProjectTitle,
+        jobName: options.ciJobName,
+        jobStage: options.ciJobStage,
+        jobStatus: ciJobStatus,
+        stories: templateData.stories,
+        storiesLinked: templateData.storiesLinked,
+        packageVersionPrevious: templateData.packageVersionPrevious,
+        packageVersion: templateData.packageVersion,
+        subscriberPackageVersionId: templateData.subscriberPackageVersionId,
+    };
+    await sendNotification(options.teamsWebhookUrl, payload);
+    return { sent: true };
+}
+//# sourceMappingURL=buildNotification.js.map

package/lib/notify/buildNotification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildNotification.js","sourceRoot":"","sources":["../../src/notify/buildNotification.ts"],"names":[],"mappings":"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"}

package/lib/notify/getCommitStories.d.ts

@@ -0,0 +1,30 @@
+import { type AlmProvider } from '../alm/index.js';
+export type CommitStories = {
+    stories: string;
+    storiesWithUrl: string;
+};
+export type GetCommitStoriesOptions = {
+    debug?: boolean;
+    /**
+     * Base URL the issue reference is appended to, e.g. `https://jira.example.com/browse` for Jira or
+     * `https://gitlab.com/group/project/-/issues` for GitLab Issues. Links are omitted if not provided.
+     */
+    almBaseUrl?: string;
+    /** The tracker to recognize references for. Defaults to Jira. */
+    almProvider?: AlmProvider;
+};
+export declare const NOT_AVAILABLE: CommitStories;
+/**
+ * Hands a commit log to the configured `AlmProvider` to recognize its own reference format, and
+ * returns both a plain string and (if `almBaseUrl` is provided) an HTML list with hyperlinks.
+ * Shared by the local-git (`getCommitStories`) and remote-API (`getRemoteCommitStories`) lookups so
+ * the ALM-provider glue isn't duplicated between them.
+ */
+export declare function renderIssuesFromCommitLog(commitLog: string, almProjectKey: string | undefined, options?: GetCommitStoriesOptions): CommitStories;
+/**
+ * Retrieves issue references from the commit logs between two tags/commits. Fetches the git
+ * history, hands the commit messages to the configured `AlmProvider` to recognize and render its
+ * own reference format, and returns both a plain string and (if `almBaseUrl` is provided) an HTML
+ * list with hyperlinks.
+ */
+export declare function getCommitStories(previousVersion: string | undefined, targetVersion: string | undefined, almProjectKey: string | undefined, options?: GetCommitStoriesOptions): Promise<CommitStories>;

package/lib/notify/getCommitStories.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { execa } from 'execa';
+import { createAlmProvider } from '../alm/index.js';
+import { getAlmProjectKeys } from '../sfConfig.js';
+import { logger } from '../logger.js';
+export const NOT_AVAILABLE = { stories: 'N/A', storiesWithUrl: 'N/A' };
+/**
+ * Hands a commit log to the configured `AlmProvider` to recognize its own reference format, and
+ * returns both a plain string and (if `almBaseUrl` is provided) an HTML list with hyperlinks.
+ * Shared by the local-git (`getCommitStories`) and remote-API (`getRemoteCommitStories`) lookups so
+ * the ALM-provider glue isn't duplicated between them.
+ */
+export function renderIssuesFromCommitLog(commitLog, almProjectKey, options) {
+    const almProvider = options?.almProvider ?? createAlmProvider('jira');
+    const issues = almProvider.extractIssues(commitLog, getAlmProjectKeys(almProjectKey));
+    if (issues.length === 0) {
+        return NOT_AVAILABLE;
+    }
+    const { plain, html } = almProvider.render(issues, options?.almBaseUrl);
+    return { stories: plain, storiesWithUrl: html };
+}
+/**
+ * Retrieves issue references from the commit logs between two tags/commits. Fetches the git
+ * history, hands the commit messages to the configured `AlmProvider` to recognize and render its
+ * own reference format, and returns both a plain string and (if `almBaseUrl` is provided) an HTML
+ * list with hyperlinks.
+ */
+export async function getCommitStories(previousVersion, targetVersion, almProjectKey, options) {
+    if (!previousVersion ||
+        !targetVersion ||
+        previousVersion === 'N/A' ||
+        targetVersion === 'N/A' ||
+        previousVersion === targetVersion) {
+        return NOT_AVAILABLE;
+    }
+    try {
+        await execa('git', ['fetch', '--unshallow', '--prune', '--tags', '--quiet']);
+        const { stdout: commits } = await execa('git', [
+            'log',
+            '--pretty=oneline',
+            `${previousVersion}...${targetVersion}`,
+        ]);
+        if (!commits) {
+            return NOT_AVAILABLE;
+        }
+        return renderIssuesFromCommitLog(commits, almProjectKey, options);
+    }
+    catch (error) {
+        logger.error(`Error getting commit stories: ${error.message}`);
+        if (options?.debug) {
+            logger.error(String(error));
+        }
+        return NOT_AVAILABLE;
+    }
+}
+//# sourceMappingURL=getCommitStories.js.map

package/lib/notify/getCommitStories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getCommitStories.js","sourceRoot":"","sources":["../../src/notify/getCommitStories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAoB,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAetC,MAAM,CAAC,MAAM,aAAa,GAAkB,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AAEtF;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAiB,EACjB,aAAiC,EACjC,OAAiC;IAEjC,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,WAAW,CAAC,aAAa,CAAC,SAAS,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC;IAEtF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACxE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,eAAmC,EACnC,aAAiC,EACjC,aAAiC,EACjC,OAAiC;IAEjC,IACE,CAAC,eAAe;QAChB,CAAC,aAAa;QACd,eAAe,KAAK,KAAK;QACzB,aAAa,KAAK,KAAK;QACvB,eAAe,KAAK,aAAa,EACjC,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;QAC7E,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE;YAC7C,KAAK;YACL,kBAAkB;YAClB,GAAG,eAAe,MAAM,aAAa,EAAE;SACxC,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,aAAa,CAAC;QACvB,CAAC;QAED,OAAO,yBAAyB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,iCAAkC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1E,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YACnB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC;AACH,CAAC"}

package/lib/notify/getRemoteCommitStories.d.ts

@@ -0,0 +1,10 @@
+import type { VcsProjectRef, VcsProvider } from '../vcs/index.js';
+import { type CommitStories, type GetCommitStoriesOptions } from './getCommitStories.js';
+/**
+ * Retrieves issue references from the commit log between two refs in a *remote* VCS project —
+ * the happy-soup equivalent of `getCommitStories`, for packaged dependencies whose source isn't
+ * the current pipeline's own repo, so there's no local git history to read. Fetches the commit
+ * log via `vcsProvider.compareRefs`, then hands it to the same `AlmProvider` rendering used by the
+ * local-git lookup.
+ */
+export declare function getRemoteCommitStories(vcsProvider: VcsProvider, project: VcsProjectRef, prevTag: string | undefined, targetTag: string | undefined, almProjectKey: string | undefined, options?: GetCommitStoriesOptions): Promise<CommitStories>;

package/lib/notify/getRemoteCommitStories.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { logger } from '../logger.js';
+import { NOT_AVAILABLE, renderIssuesFromCommitLog, } from './getCommitStories.js';
+/**
+ * Retrieves issue references from the commit log between two refs in a *remote* VCS project —
+ * the happy-soup equivalent of `getCommitStories`, for packaged dependencies whose source isn't
+ * the current pipeline's own repo, so there's no local git history to read. Fetches the commit
+ * log via `vcsProvider.compareRefs`, then hands it to the same `AlmProvider` rendering used by the
+ * local-git lookup.
+ */
+export async function getRemoteCommitStories(vcsProvider, project, prevTag, targetTag, almProjectKey, options) {
+    if (!prevTag || !targetTag || prevTag === targetTag) {
+        return NOT_AVAILABLE;
+    }
+    try {
+        const commits = await vcsProvider.compareRefs(project, prevTag, targetTag);
+        if (commits.length === 0) {
+            return NOT_AVAILABLE;
+        }
+        const commitLog = commits.map((commit) => commit.message).join('\n');
+        return renderIssuesFromCommitLog(commitLog, almProjectKey, options);
+    }
+    catch (error) {
+        logger.error(`Error getting remote commit stories: ${error.message}`);
+        if (options?.debug) {
+            logger.error(String(error));
+        }
+        return NOT_AVAILABLE;
+    }
+}
+//# sourceMappingURL=getRemoteCommitStories.js.map

package/lib/notify/getRemoteCommitStories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRemoteCommitStories.js","sourceRoot":"","sources":["../../src/notify/getRemoteCommitStories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EACL,aAAa,EACb,yBAAyB,GAG1B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,WAAwB,EACxB,OAAsB,EACtB,OAA2B,EAC3B,SAA6B,EAC7B,aAAiC,EACjC,OAAiC;IAEjC,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACpD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QAE3E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,aAAa,CAAC;QACvB,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrE,OAAO,yBAAyB,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,wCAAyC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACjF,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YACnB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC;AACH,CAAC"}

package/lib/notify/happySoupNotification.d.ts

@@ -0,0 +1,26 @@
+import { type AlmProviderKind } from '../alm/index.js';
+export type NotifyHappySoupResult = {
+    sent: boolean;
+};
+export type NotifyHappySoupOptions = {
+    ciCommitRefName?: string;
+    ciEnvironmentName?: string;
+    ciJobName?: string;
+    ciJobStage?: string;
+    ciJobStatus?: string;
+    ciPipelineId?: string;
+    ciPipelineUrl?: string;
+    teamsWebhookUrl?: string[];
+    notifyOnCompletion: boolean;
+    deployProgressFile?: string;
+    almBaseUrl?: string;
+    almProjectKey?: string;
+    almProvider?: AlmProviderKind;
+    ciJobToken?: string;
+    projectAccessToken?: string;
+    debug?: boolean;
+};
+/** Posts a "starting stage" card to Teams. */
+export declare function happySoupNotifyBeforeScript(options: NotifyHappySoupOptions): Promise<NotifyHappySoupResult>;
+/** Posts a stage (or final) success/failure card to Teams, depending on `--notify-on-completion`. */
+export declare function happySoupNotifyAfterScript(options: NotifyHappySoupOptions): Promise<NotifyHappySoupResult>;

package/lib/notify/happySoupNotification.js

@@ -0,0 +1,140 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createAlmProvider } from '../alm/index.js';
+import { createVcsProvider } from '../vcs/index.js';
+import { loadProgress } from '../deploy/deployCommon.js';
+import { resolvePackageOrigin } from '../happySoup/resolveOriginProject.js';
+import { logger } from '../logger.js';
+import { NOT_AVAILABLE } from './getCommitStories.js';
+/** Compares by value rather than by reference, so a mocked/reconstructed `NOT_AVAILABLE` still counts. */
+function isNotAvailable(result) {
+    return result.stories === NOT_AVAILABLE.stories && result.storiesWithUrl === NOT_AVAILABLE.storiesWithUrl;
+}
+import { getRemoteCommitStories } from './getRemoteCommitStories.js';
+import { renderNotifyTemplate } from './renderTemplate.js';
+import { sendNotification } from './sendNotification.js';
+/**
+ * Resolves stories for one upgraded package: tries the CI job token first, falling back to a
+ * personal/project access token if the job token can't read the origin repo (a job token is
+ * typically scoped to its own project only, unless the target project has explicitly allowlisted
+ * it). Since a "no stories found" result is indistinguishable from "couldn't read the repo" once
+ * `getRemoteCommitStories` has swallowed the error, any non-`NOT_AVAILABLE` result from either
+ * attempt wins; if both come back `NOT_AVAILABLE`, that's the final answer either way.
+ */
+async function resolvePackageStories(upgradedPackage, options, almProvider) {
+    const origin = resolvePackageOrigin(upgradedPackage.packageName, upgradedPackage.targetDescription);
+    if (!origin) {
+        if (options.debug) {
+            logger.debug(`Could not resolve the origin repo for package ${upgradedPackage.packageName}.`);
+        }
+        return NOT_AVAILABLE;
+    }
+    const tokens = [];
+    if (options.ciJobToken) {
+        tokens.push({ token: options.ciJobToken, tokenKind: 'job' });
+    }
+    if (options.projectAccessToken) {
+        tokens.push({ token: options.projectAccessToken, tokenKind: 'personal' });
+    }
+    let result = NOT_AVAILABLE;
+    for (const { token, tokenKind } of tokens) {
+        const vcsProvider = createVcsProvider(origin.vcsProvider, { host: origin.host, token, tokenKind });
+        // eslint-disable-next-line no-await-in-loop -- try the job token first; only fall back to a personal/project access token if it came back empty
+        result = await getRemoteCommitStories(vcsProvider, origin.projectPath, upgradedPackage.prevTag, upgradedPackage.targetTag, options.almProjectKey, { almProvider, almBaseUrl: options.almBaseUrl, debug: options.debug });
+        if (!isNotAvailable(result)) {
+            break;
+        }
+    }
+    return result;
+}
+/** Resolves stories for every upgraded package recorded in the deploy progress file. */
+async function resolveUpgradedPackageStories(options) {
+    const deployProgressFile = options.deployProgressFile ?? 'DEPLOY_PROGRESS.json';
+    const progress = await loadProgress(deployProgressFile);
+    const upgradedPackages = progress.upgradedPackages ?? [];
+    if (upgradedPackages.length === 0) {
+        return [];
+    }
+    const almProvider = createAlmProvider(options.almProvider ?? 'jira');
+    const results = [];
+    for (const upgradedPackage of upgradedPackages) {
+        // eslint-disable-next-line no-await-in-loop -- each package's origin repo may require a separate token/provider; resolving one at a time keeps the fallback logic simple
+        const { storiesWithUrl } = await resolvePackageStories(upgradedPackage, options, almProvider);
+        results.push({ packageName: upgradedPackage.packageName, storiesLinked: storiesWithUrl });
+    }
+    return results;
+}
+/** Posts a "starting stage" card to Teams. */
+export async function happySoupNotifyBeforeScript(options) {
+    const stage = options.ciJobStage ?? 'N/A';
+    const templateData = {
+        stage,
+        environmentName: options.ciEnvironmentName ?? 'N/A',
+        refName: options.ciCommitRefName ?? 'N/A',
+        pipelineUrl: options.ciPipelineUrl ?? '#',
+        pipelineId: options.ciPipelineId ?? 'N/A',
+    };
+    const message = renderNotifyTemplate('happy-soup-starting-stage-notification', templateData);
+    const payload = {
+        content: message,
+        environmentName: options.ciEnvironmentName,
+        refName: options.ciCommitRefName,
+        pipelineId: options.ciPipelineId,
+        pipelineUrl: options.ciPipelineUrl,
+        jobName: options.ciJobName,
+        jobStage: stage,
+        jobStatus: options.ciJobStatus ?? 'running',
+    };
+    await sendNotification(options.teamsWebhookUrl, payload);
+    return { sent: true };
+}
+/** Posts a stage (or final) success/failure card to Teams, depending on `--notify-on-completion`. */
+export async function happySoupNotifyAfterScript(options) {
+    const stage = options.ciJobStage ?? 'N/A';
+    const failed = options.ciJobStatus === 'failed';
+    const templateData = {
+        stage,
+        environmentName: options.ciEnvironmentName ?? 'N/A',
+        refName: options.ciCommitRefName ?? 'N/A',
+        pipelineUrl: options.ciPipelineUrl ?? '#',
+        pipelineId: options.ciPipelineId ?? 'N/A',
+    };
+    if (!failed) {
+        templateData.upgradedPackages = await resolveUpgradedPackageStories(options);
+    }
+    const templateName = options.notifyOnCompletion
+        ? failed
+            ? 'happy-soup-final-failure-notification'
+            : 'happy-soup-final-success-notification'
+        : failed
+            ? 'happy-soup-failure-notification'
+            : 'happy-soup-success-notification';
+    const message = renderNotifyTemplate(templateName, templateData);
+    const payload = {
+        content: message,
+        environmentName: options.ciEnvironmentName,
+        refName: options.ciCommitRefName,
+        pipelineId: options.ciPipelineId,
+        pipelineUrl: options.ciPipelineUrl,
+        jobName: options.ciJobName,
+        jobStage: options.ciJobStage,
+        jobStatus: options.ciJobStatus,
+        upgradedPackages: templateData.upgradedPackages,
+    };
+    await sendNotification(options.teamsWebhookUrl, payload);
+    return { sent: true };
+}
+//# sourceMappingURL=happySoupNotification.js.map

package/lib/notify/happySoupNotification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"happySoupNotification.js","sourceRoot":"","sources":["../../src/notify/happySoupNotification.ts"],"names":[],"mappings":"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"}

package/lib/notify/projectNotification.d.ts

@@ -0,0 +1,46 @@
+import { type AlmProviderKind } from '../alm/index.js';
+export type NotifyProjectResult = {
+    sent: boolean;
+};
+type PrevInstalledPackageVersionParams = {
+    alias?: string;
+    debug: boolean;
+};
+type TargetPackageVersionParams = {
+    /** The packaging DevHub's alias. Must already be authenticated. */
+    packagingDevhub?: string;
+    subscriberPackageVersionId?: string;
+    debug: boolean;
+};
+export type NotifyProjectOptions = {
+    alias?: string;
+    ciCommitRefName?: string;
+    ciEnvironmentName?: string;
+    ciJobName?: string;
+    ciJobStage?: string;
+    ciJobStatus?: string;
+    ciPipelineId?: string;
+    ciPipelineUrl?: string;
+    ciProjectTitle?: string;
+    packagingDevhub?: string;
+    almBaseUrl?: string;
+    almProjectKey?: string;
+    almProvider?: AlmProviderKind;
+    prevInstalledPackageVersion?: string;
+    subscriberPackageVersionId?: string;
+    targetPackageVersion?: string;
+    teamsWebhookUrl?: string[];
+    debug: boolean;
+};
+/** Queries the target org's installed package version. The org must already be authenticated. */
+export declare function resolvePrevInstalledPackageVersion(params: PrevInstalledPackageVersionParams): Promise<string>;
+/** Resolves the released package's version from the packaging DevHub. Returns `undefined` on any failure. */
+export declare function resolveTargetPackageVersionFromDevHub(params: TargetPackageVersionParams): Promise<string | undefined>;
+/** Falls back to the git tag pointing at HEAD when the DevHub can't resolve a target version. */
+export declare function resolveTargetPackageVersionFromGitTag(debug: boolean): Promise<string>;
+export declare function resolveTargetPackageVersion(params: TargetPackageVersionParams): Promise<string>;
+/** Resolves and records the previously installed and target package versions for later stages. */
+export declare function projectNotifyBeforeScript(options: NotifyProjectOptions): Promise<void>;
+/** Posts the deployment result card (with Jira stories on success) to Teams. */
+export declare function projectNotifyAfterScript(options: NotifyProjectOptions): Promise<NotifyProjectResult>;
+export {};