@simplysf/simply-cicd-core 0.2.2 → 0.3.1

package/lib/flags/env.js

@@ -0,0 +1,81 @@
+/*
+ * 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.
+ */
+/**
+ * Coerce a string or boolean to a boolean. `'true'`/`'false'` are recognised
+ * case- and whitespace-insensitively; anything else is `false`.
+ *
+ * Environment variables are always strings, unlike the boolean flags oclif parses natively, so
+ * any flag with an env-var fallback needs this on the env side.
+ *
+ * @param value - The raw flag or environment value.
+ * @returns The coerced boolean.
+ */
+export function parseBooleanString(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true') {
+        return true;
+    }
+    if (normalized === 'false') {
+        return false;
+    }
+    return false;
+}
+/**
+ * Resolve a string setting with CLI flag > environment variable > fallback precedence.
+ *
+ * Several settings accept more than one environment variable — a `SIMPLY_CICD_`-prefixed name of
+ * our own plus whatever the CI provider already exports — so the env side takes a list, tried in
+ * order.
+ *
+ * @param flagValue - The parsed CLI flag, if the caller passed one.
+ * @param envVars - Candidate environment values, most specific first.
+ * @param fallback - Used when neither the flag nor any environment variable is set.
+ * @returns The resolved value.
+ */
+export function resolveString(flagValue, envVars, fallback = '') {
+    return flagValue ?? envVars.find((value) => value !== undefined) ?? fallback;
+}
+/**
+ * {@link resolveString} for settings with no default, where "unset" is meaningful.
+ *
+ * @param flagValue - The parsed CLI flag, if the caller passed one.
+ * @param envVars - Candidate environment values, most specific first.
+ * @returns The resolved value, or `undefined` if nothing supplied one.
+ */
+export function resolveOptionalString(flagValue, envVars) {
+    return flagValue ?? envVars.find((value) => value !== undefined);
+}
+/**
+ * Resolve a boolean setting with CLI flag > environment variable > fallback precedence.
+ *
+ * The flag is checked for `undefined` rather than falsiness, so an explicit `--no-…` stays
+ * distinguishable from an unset flag and still beats the environment.
+ *
+ * @param flagValue - The parsed CLI flag, if the caller passed one.
+ * @param envVar - The environment value, coerced via {@link parseBooleanString}.
+ * @param fallback - Used when neither the flag nor the environment variable is set.
+ * @returns The resolved boolean.
+ */
+export function resolveBoolean(flagValue, envVar, fallback) {
+    if (flagValue !== undefined) {
+        return flagValue;
+    }
+    return envVar !== undefined ? parseBooleanString(envVar) : fallback;
+}
+//# sourceMappingURL=env.js.map

package/lib/flags/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/flags/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAE9C,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAC3B,SAA6B,EAC7B,OAAkC,EAClC,QAAQ,GAAG,EAAE;IAEb,OAAO,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,IAAI,QAAQ,CAAC;AAC/E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAA6B,EAC7B,OAAkC;IAElC,OAAO,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,SAA8B,EAAE,MAA0B,EAAE,QAAiB;IAC1G,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACtE,CAAC"}

package/lib/git.d.ts

@@ -0,0 +1,32 @@
+import type { VcsProvider } from './vcs/index.js';
+import { VersionTagFormat } from './build/versionTagFormat.js';
+export type Deployment = {
+    name: string;
+    slug: string;
+    ref?: string;
+};
+export type CloneRepoOptions = {
+    ciJobToken: string;
+    vcsProvider: VcsProvider;
+};
+/**
+ * The git tag a dependency pinned at `versionPart` was recorded under. `1.2.3-4` and `1.2.3.4` are
+ * rendered through the project's version tag format, on the assumption that dependencies share the
+ * project's tag convention (a deployment's explicit `ref` covers one that doesn't). Anything else,
+ * e.g. `1.2.3-LATEST`, keeps the original `v<pin>` reading.
+ */
+export declare function toDependencyRef(versionPart: string, versionTagFormat: VersionTagFormat): string;
+/**
+ * Clones a repository based on deployment metadata and options. If a specific branch or tag
+ * (ref) is not specified, it attempts to deduce the ref from package dependencies in
+ * `sfdx-project.json` in the current working directory.
+ */
+export declare function cloneRepo(deployment: Deployment, options: CloneRepoOptions): Promise<string>;
+/**
+ * Adds a temporary authenticated git remote for CI push/tag operations. Returns the remote's alias.
+ *
+ * The alias is keyed on the pipeline ID, so a retried job, or a later job in the same pipeline that
+ * lands on a runner reusing the working copy (`GIT_STRATEGY: fetch`), finds it already present. In
+ * that case the existing remote's URL is overwritten instead, which also refreshes the token.
+ */
+export declare function addGitRemote(ciPipelineId: string, accessToken: string, ciProjectPath: string, vcsProvider: VcsProvider): Promise<string>;

package/lib/git.js

@@ -0,0 +1,106 @@
+/*
+ * 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 path from 'node:path';
+import { execa } from 'execa';
+import { getDefaultPackageDirectory, readSfdxProject } from '@simplysf/simply-core';
+import { logger } from './logger.js';
+import { VersionTagFormat, VersionTagFormatError } from './build/versionTagFormat.js';
+/**
+ * The git tag a dependency pinned at `versionPart` was recorded under. `1.2.3-4` and `1.2.3.4` are
+ * rendered through the project's version tag format, on the assumption that dependencies share the
+ * project's tag convention (a deployment's explicit `ref` covers one that doesn't). Anything else,
+ * e.g. `1.2.3-LATEST`, keeps the original `v<pin>` reading.
+ */
+export function toDependencyRef(versionPart, versionTagFormat) {
+    const match = /^(?<version>\d+\.\d+\.\d+)[-.](?<build>\d+)$/.exec(versionPart);
+    if (match?.groups) {
+        return versionTagFormat.render(`${match.groups.version}.${match.groups.build}`);
+    }
+    return `v${versionPart}`;
+}
+/**
+ * Clones a repository based on deployment metadata and options. If a specific branch or tag
+ * (ref) is not specified, it attempts to deduce the ref from package dependencies in
+ * `sfdx-project.json` in the current working directory.
+ */
+export async function cloneRepo(deployment, options) {
+    const { name, slug } = deployment;
+    let { ref } = deployment;
+    if (!ref) {
+        try {
+            const project = await readSfdxProject();
+            const defaultPackageDir = getDefaultPackageDirectory(project);
+            if (defaultPackageDir?.dependencies) {
+                const dependency = defaultPackageDir.dependencies.find((dep) => dep.package?.startsWith(`${name}@`));
+                if (dependency?.package) {
+                    const versionPart = dependency.package.split('@')[1];
+                    if (versionPart) {
+                        ref = toDependencyRef(versionPart, VersionTagFormat.fromProject(project));
+                    }
+                }
+            }
+        }
+        catch (e) {
+            // A misconfigured format is the project's error to fix, not a reason to quietly clone the
+            // dependency's default branch instead.
+            if (e instanceof VersionTagFormatError) {
+                throw e;
+            }
+            const err = e;
+            if (err.code !== 'ENOENT') {
+                logger.warn(`Could not deduce ref from sfdx-project.json for ${name}: ${err.message}`);
+            }
+        }
+    }
+    const repoUrl = options.vcsProvider.buildCiCloneUrl(options.ciJobToken, slug);
+    const targetDir = path.join(process.cwd(), name);
+    await fs.rm(targetDir, { recursive: true, force: true });
+    const refMessage = ref ? `#${ref}` : ' (default branch)';
+    logger.info(`Cloning ${slug}${refMessage} into ${name}`);
+    try {
+        const cloneArgs = ['clone', '--depth', '1'];
+        if (ref) {
+            cloneArgs.push('-b', ref);
+        }
+        cloneArgs.push(repoUrl, name);
+        await execa('git', cloneArgs);
+        return targetDir;
+    }
+    catch (e) {
+        logger.error(`Failed to clone ${slug}${refMessage}.`);
+        throw e;
+    }
+}
+/**
+ * Adds a temporary authenticated git remote for CI push/tag operations. Returns the remote's alias.
+ *
+ * The alias is keyed on the pipeline ID, so a retried job, or a later job in the same pipeline that
+ * lands on a runner reusing the working copy (`GIT_STRATEGY: fetch`), finds it already present. In
+ * that case the existing remote's URL is overwritten instead, which also refreshes the token.
+ */
+export async function addGitRemote(ciPipelineId, accessToken, ciProjectPath, vcsProvider) {
+    if (!accessToken) {
+        throw new Error('accessToken is required for Git remote operations.');
+    }
+    const remoteAlias = `GITREMOTE${ciPipelineId}`;
+    const remoteUrl = vcsProvider.buildAuthenticatedRemoteUrl(accessToken, ciProjectPath);
+    const { stdout: existingRemotes } = await execa('git', ['remote']);
+    const remoteExists = existingRemotes.split(/\r?\n/).includes(remoteAlias);
+    await execa('git', ['remote', remoteExists ? 'set-url' : 'add', remoteAlias, remoteUrl]);
+    return remoteAlias;
+}
+//# sourceMappingURL=git.js.map

package/lib/git.js.map

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

package/lib/happySoup/resolveOriginProject.d.ts

@@ -0,0 +1,22 @@
+import { type VcsProviderKind } from '../vcs/index.js';
+/** Where a packaged dependency's source lives, resolved for a happy-soup story lookup. */
+export type ResolvedOriginProject = {
+    vcsProvider: VcsProviderKind;
+    host: string;
+    projectPath: string;
+};
+/**
+ * Parses a CI pipeline URL — as stored in `sf package version report`'s `Description` field by
+ * `createPackageVersion` at build time — into the VCS project that built it. Recognizes GitLab
+ * pipeline URLs and GitHub Actions run URLs. Returns `undefined` if the URL doesn't match either
+ * shape (or isn't a URL at all), e.g. for a package version created outside this pipeline.
+ */
+export declare function parseOriginPipelineUrl(pipelineUrl: string): ResolvedOriginProject | undefined;
+/**
+ * Resolves which VCS project a packaged dependency's source lives in, for a happy-soup story
+ * lookup. Checks `.sfdevrc.json`'s `packageOriginOverrides` first (for packages whose origin can't
+ * be parsed, e.g. externally-vendored ones), then falls back to parsing the target version's
+ * origin pipeline URL. Returns `undefined` (never throws) if neither resolves — callers must treat
+ * that package's stories as unavailable and continue, not fail the notification.
+ */
+export declare function resolvePackageOrigin(packageName: string, targetDescription: string | undefined): ResolvedOriginProject | undefined;

package/lib/happySoup/resolveOriginProject.js

@@ -0,0 +1,61 @@
+/*
+ * 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 { GitHubProvider, GitLabProvider } from '../vcs/index.js';
+import { getPackageOriginOverride } from '../sfConfig.js';
+/** Matches a GitLab CI pipeline URL, e.g. `https://gitlab.com/group/subgroup/project/-/pipelines/12345`. */
+const GITLAB_PIPELINE_PATH = /^\/(?<projectPath>.+)\/-\/pipelines\/\d+/;
+/** Matches a GitHub Actions run URL, e.g. `https://github.com/owner/repo/actions/runs/12345`. */
+const GITHUB_RUN_PATH = /^\/(?<projectPath>[^/]+\/[^/]+)\/actions\/runs\/\d+/;
+/**
+ * Parses a CI pipeline URL — as stored in `sf package version report`'s `Description` field by
+ * `createPackageVersion` at build time — into the VCS project that built it. Recognizes GitLab
+ * pipeline URLs and GitHub Actions run URLs. Returns `undefined` if the URL doesn't match either
+ * shape (or isn't a URL at all), e.g. for a package version created outside this pipeline.
+ */
+export function parseOriginPipelineUrl(pipelineUrl) {
+    let url;
+    try {
+        url = new URL(pipelineUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const gitlabMatch = GITLAB_PIPELINE_PATH.exec(url.pathname);
+    if (gitlabMatch?.groups?.projectPath) {
+        return { vcsProvider: 'gitlab', host: url.host, projectPath: gitlabMatch.groups.projectPath };
+    }
+    const githubMatch = GITHUB_RUN_PATH.exec(url.pathname);
+    if (githubMatch?.groups?.projectPath) {
+        return { vcsProvider: 'github', host: url.host, projectPath: githubMatch.groups.projectPath };
+    }
+    return undefined;
+}
+/**
+ * Resolves which VCS project a packaged dependency's source lives in, for a happy-soup story
+ * lookup. Checks `.sfdevrc.json`'s `packageOriginOverrides` first (for packages whose origin can't
+ * be parsed, e.g. externally-vendored ones), then falls back to parsing the target version's
+ * origin pipeline URL. Returns `undefined` (never throws) if neither resolves — callers must treat
+ * that package's stories as unavailable and continue, not fail the notification.
+ */
+export function resolvePackageOrigin(packageName, targetDescription) {
+    const override = getPackageOriginOverride(packageName);
+    if (override) {
+        const defaultHost = override.vcsProvider === 'gitlab' ? GitLabProvider.defaultHost : GitHubProvider.defaultHost;
+        return { vcsProvider: override.vcsProvider, host: override.host ?? defaultHost, projectPath: override.projectPath };
+    }
+    return targetDescription ? parseOriginPipelineUrl(targetDescription) : undefined;
+}
+//# sourceMappingURL=resolveOriginProject.js.map

package/lib/happySoup/resolveOriginProject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveOriginProject.js","sourceRoot":"","sources":["../../src/happySoup/resolveOriginProject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAwB,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAS1D,4GAA4G;AAC5G,MAAM,oBAAoB,GAAG,0CAA0C,CAAC;AAExE,iGAAiG;AACjG,MAAM,eAAe,GAAG,qDAAqD,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,WAAW,GAAG,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5D,IAAI,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACrC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IAChG,CAAC;IAED,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvD,IAAI,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACrC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IAChG,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAmB,EACnB,iBAAqC;IAErC,MAAM,QAAQ,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC;IACvD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC;QAChH,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC;IACtH,CAAC;IAED,OAAO,iBAAiB,CAAC,CAAC,CAAC,sBAAsB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACnF,CAAC"}

package/lib/index.d.ts

@@ -1,2 +1,53 @@
 export * from './alm/index.js';
 export * from './vcs/index.js';
+export * from './env.js';
+export * from './git.js';
+export * from './logger.js';
+export * from './sfApex.js';
+export * from './sfAuth.js';
+export * from './sfConfig.js';
+export * from './sfPackages.js';
+export * from './sfPlugins.js';
+export * from './build/checkPermissionSets.js';
+export * from './build/cleanupScratchOrgs.js';
+export * from './build/createFallbackTag.js';
+export * from './build/createPackageVersion.js';
+export * from './build/createScratchOrg.js';
+export * from './build/deleteScratchOrg.js';
+export * from './build/deltaRunner.js';
+export * from './build/determinePackageChanges.js';
+export * from './build/devHubs.js';
+export * from './build/flexipageDelta.js';
+export * from './build/flowDelta.js';
+export * from './build/installDependencies.js';
+export * from './build/lwcJest.js';
+export * from './build/publishUtamPageObjects.js';
+export * from './build/pushScratch.js';
+export * from './build/scratchOrgAuth.js';
+export * from './build/scratchOrgInfo.js';
+export * from './build/skipGuard.js';
+export * from './build/testScratch.js';
+export * from './build/utamPageObjects.js';
+export * from './build/versionTagFormat.js';
+export * from './deploy/deployCommon.js';
+export * from './deploy/deployHappySoup.js';
+export * from './deploy/deployProject.js';
+export * from './deploy/runDeployStage.js';
+export * from './deploy/stageOptions.js';
+export * from './deploy/validate.js';
+export * from './exec/sfCli.js';
+export * from './flags/env.js';
+export * from './happySoup/resolveOriginProject.js';
+export * from './notify/buildNotification.js';
+export * from './notify/getCommitStories.js';
+export * from './notify/getRemoteCommitStories.js';
+export * from './notify/happySoupNotification.js';
+export * from './notify/projectNotification.js';
+export * from './notify/renderTemplate.js';
+export * from './notify/sendNotification.js';
+export * from './notify/templates.js';
+export * from './schemas/deployConfig.js';
+export * from './schemas/deployProgress.js';
+export * from './schemas/deployRules.js';
+export * from './sfdxDependabot/dependabotRun.js';
+export * from './sfdxDependabot/updater.js';

package/lib/index.js

@@ -16,12 +16,73 @@
 // Everything exported from this file is this package's public API and is semver-covered: adding an
 // export is a minor/patch change, but removing or renaming one is breaking. `test/index.test.ts`
 // pins the exported-key list down so an accidental removal fails a test instead of silently shipping
-// in a patch release. See docs/design/0037-simply-cicd-core.md for why only `alm/`/`vcs/` are split
-// out from `@simplysf/simply-cicd` (the CLI) — the rest of its `common/` stays behind.
+// in a patch release. See docs/design/0037-simply-cicd-core.md for the original `alm/`/`vcs/` split,
+// and docs/design/0053-simply-cicd-core-common.md for the move of the rest of `@simplysf/simply-cicd`'s
+// `common/` (everything except its oclif flag declarations).
 //
 // `alm/index.ts` and `vcs/index.ts` are themselves complete barrels (they register the built-in
 // providers as an import side effect, same as they did inside `simply-cicd`) — re-exporting them
 // here keeps that registration intact without duplicating either list.
 export * from './alm/index.js';
 export * from './vcs/index.js';
+// shared kernel
+export * from './env.js';
+export * from './git.js';
+export * from './logger.js';
+export * from './sfApex.js';
+export * from './sfAuth.js';
+export * from './sfConfig.js';
+export * from './sfPackages.js';
+export * from './sfPlugins.js';
+// build/
+export * from './build/checkPermissionSets.js';
+export * from './build/cleanupScratchOrgs.js';
+export * from './build/createFallbackTag.js';
+export * from './build/createPackageVersion.js';
+export * from './build/createScratchOrg.js';
+export * from './build/deleteScratchOrg.js';
+export * from './build/deltaRunner.js';
+export * from './build/determinePackageChanges.js';
+export * from './build/devHubs.js';
+export * from './build/flexipageDelta.js';
+export * from './build/flowDelta.js';
+export * from './build/installDependencies.js';
+export * from './build/lwcJest.js';
+export * from './build/publishUtamPageObjects.js';
+export * from './build/pushScratch.js';
+export * from './build/scratchOrgAuth.js';
+export * from './build/scratchOrgInfo.js';
+export * from './build/skipGuard.js';
+export * from './build/testScratch.js';
+export * from './build/utamPageObjects.js';
+export * from './build/versionTagFormat.js';
+// deploy/
+export * from './deploy/deployCommon.js';
+export * from './deploy/deployHappySoup.js';
+export * from './deploy/deployProject.js';
+export * from './deploy/runDeployStage.js';
+export * from './deploy/stageOptions.js';
+export * from './deploy/validate.js';
+// exec/
+export * from './exec/sfCli.js';
+// flags/
+export * from './flags/env.js';
+// happySoup/
+export * from './happySoup/resolveOriginProject.js';
+// notify/
+export * from './notify/buildNotification.js';
+export * from './notify/getCommitStories.js';
+export * from './notify/getRemoteCommitStories.js';
+export * from './notify/happySoupNotification.js';
+export * from './notify/projectNotification.js';
+export * from './notify/renderTemplate.js';
+export * from './notify/sendNotification.js';
+export * from './notify/templates.js';
+// schemas/
+export * from './schemas/deployConfig.js';
+export * from './schemas/deployProgress.js';
+export * from './schemas/deployRules.js';
+// sfdxDependabot/
+export * from './sfdxDependabot/dependabotRun.js';
+export * from './sfdxDependabot/updater.js';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mGAAmG;AACnG,iGAAiG;AACjG,qGAAqG;AACrG,oGAAoG;AACpG,uFAAuF;AACvF,EAAE;AACF,gGAAgG;AAChG,iGAAiG;AACjG,uEAAuE;AAEvE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,mGAAmG;AACnG,iGAAiG;AACjG,qGAAqG;AACrG,qGAAqG;AACrG,wGAAwG;AACxG,6DAA6D;AAC7D,EAAE;AACF,gGAAgG;AAChG,iGAAiG;AACjG,uEAAuE;AAEvE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAE/B,gBAAgB;AAChB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAE/B,SAAS;AACT,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,mCAAmC,CAAC;AAClD,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAE5C,UAAU;AACV,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AAErC,QAAQ;AACR,cAAc,iBAAiB,CAAC;AAEhC,SAAS;AACT,cAAc,gBAAgB,CAAC;AAE/B,aAAa;AACb,cAAc,qCAAqC,CAAC;AAEpD,UAAU;AACV,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AAEtC,WAAW;AACX,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AAEzC,kBAAkB;AAClB,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC"}

package/lib/logger.d.ts

@@ -0,0 +1,10 @@
+/** A logger utility for consistent logging across the simply-cicd package's shared modules. */
+export declare const logger: {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    success: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    log: (message: string, ...args: unknown[]) => void;
+    raw: (...args: unknown[]) => void;
+};

package/lib/logger.js

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+/* eslint-disable no-console -- this module is the sole intended console output surface for simply-cicd's shared modules */
+import chalk from 'chalk';
+import logSymbols from 'log-symbols';
+chalk.level = 1;
+const debugPrefix = chalk.yellow('[DEBUG]');
+const logPrefix = chalk.yellow('[SIMPLY-CICD]');
+const format = (message) => `${logPrefix} ${message}`;
+/** A logger utility for consistent logging across the simply-cicd package's shared modules. */
+export const logger = {
+    debug: (message, ...args) => console.log(`${logPrefix} ${debugPrefix} ${message}`, ...args),
+    info: (message, ...args) => console.log(logSymbols.info, format(message), ...args),
+    success: (message, ...args) => console.log(logSymbols.success, format(message), ...args),
+    warn: (message, ...args) => console.warn(logSymbols.warning, format(message), ...args),
+    error: (message, ...args) => console.error(logSymbols.error, format(message), ...args),
+    log: (message, ...args) => console.log(format(message), ...args),
+    raw: (...args) => console.log(...args),
+};
+//# sourceMappingURL=logger.js.map

package/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,2HAA2H;AAE3H,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,UAAU,MAAM,aAAa,CAAC;AAErC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;AAEhB,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAC5C,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAEhD,MAAM,MAAM,GAAG,CAAC,OAAe,EAAU,EAAE,CAAC,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC;AAEtE,+FAA+F;AAC/F,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAe,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,IAAI,WAAW,IAAI,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC;IACpH,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAe,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC3G,OAAO,EAAE,CAAC,OAAe,EAAE,GAAG,IAAe,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IACjH,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAe,EAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC/G,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAe,EAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC/G,GAAG,EAAE,CAAC,OAAe,EAAE,GAAG,IAAe,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IACzF,GAAG,EAAE,CAAC,GAAG,IAAe,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;CACxD,CAAC"}

package/lib/notify/buildNotification.d.ts

@@ -0,0 +1,53 @@
+import { type AlmProviderKind } from '../alm/index.js';
+import { type CommitStories } from './getCommitStories.js';
+/** The file `build create-package-version` writes the new version's `04t` ID to. */
+export declare const SUBSCRIBER_PACKAGE_VERSION_ID_FILE = "subscriberPackageVersionId.env";
+export type NotifyBuildResult = {
+    sent: boolean;
+};
+export type NotifyBuildOptions = {
+    ciCommitRefName?: string;
+    ciJobName?: string;
+    ciJobStage?: string;
+    ciJobStatus?: string;
+    ciPipelineId?: string;
+    ciPipelineUrl?: string;
+    ciProjectTitle?: string;
+    subscriberPackageVersionId?: string;
+    almBaseUrl?: string;
+    almProjectKey?: string;
+    almProvider?: AlmProviderKind;
+    teamsWebhookUrl?: string[];
+    debug: boolean;
+};
+/** The new package version's git tag and the issue references since the previous one. */
+export type PackageVersionHistory = CommitStories & {
+    versionTag: string;
+    previousVersionTag: string;
+};
+/**
+ * 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 declare function resolveBuiltSubscriberPackageVersionId(explicit?: string): Promise<string | undefined>;
+/** Fetches the tags, and the full history when the CI clone is shallow, so tags can be described and diffed. */
+export declare function fetchVersionHistory(): Promise<void>;
+/**
+ * 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 declare function findPackageVersionTag(subscriberPackageVersionId: string): Promise<string | undefined>;
+/** The nearest version tag, in the project's format, before `versionTag`. `undefined` for a package's first version. */
+export declare function findPreviousVersionTag(versionTag: string): Promise<string | 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 declare function getPackageVersionHistory(subscriberPackageVersionId: string, options: Pick<NotifyBuildOptions, 'almBaseUrl' | 'almProjectKey' | 'almProvider' | 'debug'>): Promise<PackageVersionHistory>;
+/**
+ * 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 declare function sendBuildNotification(options: NotifyBuildOptions): Promise<NotifyBuildResult>;