@simplysf/simply-cicd-core 0.2.2 → 0.4.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![NPM](https://img.shields.io/npm/v/@simplysf/simply-cicd-core?label=@simplysf/simply-cicd-core)](https://npmjs.com/@simplysf/simply-cicd-core) [![Downloads/week](https://img.shields.io/npm/dw/@simplysf/simply-cicd-core.svg)](https://npmjs.com/@simplysf/simply-cicd-core) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://raw.githubusercontent.com/SimplySF/simply-plugins-core/main/LICENSE.txt)
 
-ALM issue linking (Jira, GitLab Issues) and VCS API clients (GitHub, GitLab). This is not a Salesforce CLI plugin — it's the library layer behind [`@simplysf/simply-cicd`](https://github.com/SimplySF/simply-plugins/tree/main/packages/simply-cicd)'s ALM/VCS integrations, published separately so it can be imported directly by anything that wants the same logic (a bot, a script, a CI job) without pulling in the CLI framework.
+Salesforce CI/CD pipeline stages (build, deploy, notify, sfdx-dependabot), ALM issue linking (Jira, GitLab Issues) and VCS API clients (GitHub, GitLab). This is not a Salesforce CLI plugin — it's the library layer behind [`@simplysf/simply-cicd`](https://github.com/SimplySF/simply-plugins/tree/main/packages/simply-cicd), published separately so it can be imported directly by anything that wants the same logic (a bot, a script, a CI job) without pulling in the CLI framework.
 
-Only `alm/` and `vcs/` moved here — `@simplysf/simply-cicd` itself still owns everything CI-pipeline-shaped (running builds/deploys, shelling to `sf`/`git`, sending pipeline notifications). See [docs/design/0037-simply-cicd-core.md](https://github.com/SimplySF/simply-plugins-core/blob/main/docs/design/0037-simply-cicd-core.md) for the boundary and why the rest stayed behind.
+`@simplysf/simply-cicd` is a thin command layer over this package: its commands parse flags and call the functions below. Only its oclif flag declarations stay in the plugin. See [docs/design/0037-simply-cicd-core.md](https://github.com/SimplySF/simply-plugins-core/blob/main/docs/design/0037-simply-cicd-core.md) for the original `alm/`/`vcs/` split and [docs/design/0053-simply-cicd-core-common.md](https://github.com/SimplySF/simply-plugins-core/blob/main/docs/design/0053-simply-cicd-core-common.md) for the move of everything else.
 
 ## Install
 
@@ -12,10 +12,12 @@ Only `alm/` and `vcs/` moved here — `@simplysf/simply-cicd` itself still owns
 npm install @simplysf/simply-cicd-core
 ```
 
-Requires Node.js `>=22` and either `"type": "module"` or a dynamic `import()` — this package ships ESM only. Zero runtime dependencies — `vcs/`'s GitHub/GitLab clients use the platform `fetch`.
+Requires Node.js `>=22` and either `"type": "module"` or a dynamic `import()` — this package ships ESM only. `vcs/`'s GitHub/GitLab clients use the platform `fetch`. The pipeline stages shell out to the `sf` and `git` binaries (via `execa`), so those must be on `PATH` wherever a stage runs, and they write `[SIMPLY-CICD]`-prefixed progress output to the console.
 
 ## API
 
+### ALM and VCS
+
 Everything below is exported from the package root. Removing or renaming an export is a breaking change; see [`src/index.ts`](src/index.ts).
 
 | Export                             | Description                                                                                                  |
@@ -51,6 +53,33 @@ const gitlab = createVcsProvider('gitlab', { token: process.env.GITLAB_TOKEN });
 const mr = await gitlab.findMergeRequest({ sourceBranch: 'feature/x' });
 ```
 
+### Pipeline stages
+
+The modules `@simplysf/simply-cicd`'s commands run, also exported from the package root. Each stage function takes a plain options object (the camelCase equivalent of the command's flags) and throws on failure. Full signatures are in the [API reference](https://simplysf.github.io/simply-plugins-core/api/simply-cicd-core/readme/).
+
+| Area                               | Main exports                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Build                              | `createScratchOrg`, `deleteScratchOrg`, `cleanupScratchOrgs`, `pushToScratch`, `runScratchApexTests`, `installDependencies`, `createPackageVersion`, `createFallbackTag`, `determinePackageChanges`, `runLwcJest`, `runCheckPermissionSets`, `runFlowDelta`, `runFlexipageDelta`, `publishUtamPageObjects`, `VersionTagFormat` |
+| Deploy                             | `deployProject`, `deployHappySoup`, `runDeployStage`, `validateDeployFiles`, `toProjectStageOptions`, `toHappySoupStageOptions`, plus the `deployCommon` helpers (`runDeploymentSteps`, `loadProgress`, `updateProgress`, `installDeployPackageDependencies`, `runDeployApexTests`, …)                                         |
+| Notify                             | `sendBuildNotification`, `projectNotifyBeforeScript`/`projectNotifyAfterScript`, `happySoupNotifyBeforeScript`/`happySoupNotifyAfterScript`, `getCommitStories`, `getRemoteCommitStories`, `sendNotification`, `renderNotifyTemplate`, `NOTIFY_TEMPLATES`                                                                      |
+| sfdx-dependabot                    | `discoverEligibleProjects`, `processProject`, `applyProjectUpdate`, `updateSfdxProject`                                                                                                                                                                                                                                        |
+| Schemas (zod)                      | `deployConfigSchema`, `deployProgressSchema`, `deployRulesSchema`, `deployStageSchema`                                                                                                                                                                                                                                         |
+| Salesforce org and package lookups | `getPackageVersionReport`, `listInstalledPackages`, `getOrgInstanceUrl`, `getRemainingDailyScratchOrgs` (in-process via `@salesforce/core` / `@salesforce/packaging`, no `sf` needed)                                                                                                                                          |
+| `sf`/`git`/env utilities           | `runSf`, `runSfJson`, `authenticateOrg`, `installPackageDependencies`, `runApexTests`, `installPlugin`, `cloneRepo`, `appendToEnvFile`, `resolveString`/`resolveBoolean`, `logger`                                                                                                                                             |
+
+```ts
+import { deployProject } from '@simplysf/simply-cicd-core';
+
+// The same work `sf simply cicd deploy project install-packaged` does, without the CLI.
+await deployProject({
+  stage: 'install-packaged',
+  alias: 'uat',
+  ciJobToken: process.env.CI_JOB_TOKEN!,
+  vcsProvider: 'gitlab',
+  deployConfigFile: 'config/deploy.json',
+});
+```
+
 ## Issues
 
 Please report any issues at https://github.com/SimplySF/simply-plugins-core/issues

package/lib/build/checkPermissionSets.d.ts

@@ -0,0 +1,22 @@
+import { type PermissionSetCheckResult } from '@simplysf/simply-permissions-core';
+export type RunCheckPermissionSetsOptions = {
+    disabled?: boolean;
+};
+export type PermissionSetBuildFileCheck = {
+    file: string;
+    permissionSet: PermissionSetCheckResult;
+};
+export type RunCheckPermissionSetsResult = {
+    skipped: boolean;
+    files: PermissionSetBuildFileCheck[];
+};
+/**
+ * Finds every permission set build file in the repo and checks the permission set each defines
+ * against the generated file on disk, writing nothing. A repo with no permission set build files is
+ * a skip. Every file is loaded and validated, and names are checked for duplicates across files,
+ * before anything is checked; then every permission set is checked before failing, so one run
+ * reports every stale permission set.
+ *
+ * @throws When any permission set has drifted or is missing, or a permission set build file is invalid.
+ */
+export declare function runCheckPermissionSets(options: RunCheckPermissionSetsOptions): Promise<RunCheckPermissionSetsResult>;

package/lib/build/checkPermissionSets.js

@@ -0,0 +1,102 @@
+/*
+ * 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 { assertUniquePermissionSetNames, checkPermissionSets, findPermissionSetBuildFiles, loadPermissionSetBuildFile, PermissionSetBuildError, } from '@simplysf/simply-permissions-core';
+import { logger } from '../logger.js';
+/** The same text `simply permissions build` reports for each `PermissionSetBuildError` code. */
+function describeBuildError(error) {
+    switch (error.code) {
+        case 'scan-failed':
+            return `Failed to scan the Salesforce project directory: ${error.args[0]}`;
+        case 'invalid-config':
+            return `The configuration file ${error.args[0]} is invalid: ${error.args[1]}`;
+        case 'config-not-found':
+            return `The configuration file ${error.args[0]} does not exist.`;
+        case 'directory-not-found':
+            return `The source directory ${error.args[0]} for permission set ${error.args[1]} does not exist.`;
+        case 'legacy-format':
+            return `${error.args[0]} uses the old format, a "permissionSets" list, which is no longer supported. Split it into one .psbuild.json file per permission set, with each permission set's settings at the top level.`;
+        case 'duplicate-name':
+            return `Permission set ${error.args[0]} is defined by both ${error.args[1]} and ${error.args[2]}. Each permission set must be defined by exactly one .psbuild.json file.`;
+    }
+}
+/** Logs `message` and throws it, keeping the build error as the cause. */
+function fail(message, cause) {
+    logger.error(message);
+    throw new Error(message, { cause });
+}
+/** Loads every file in order, naming the file in any validation error, then checks names are unique across files. */
+async function loadFiles(files) {
+    const entries = [];
+    for (const file of files) {
+        logger.info(`Loading permission set build file ${file}...`);
+        try {
+            // eslint-disable-next-line no-await-in-loop -- files are loaded in order so the first invalid one is the one reported
+            entries.push({ file, spec: await loadPermissionSetBuildFile(file) });
+        }
+        catch (error) {
+            if (error instanceof PermissionSetBuildError) {
+                fail(`Permission set build file ${file}: ${describeBuildError(error)}`, error);
+            }
+            throw error;
+        }
+    }
+    try {
+        assertUniquePermissionSetNames(entries);
+    }
+    catch (error) {
+        if (error instanceof PermissionSetBuildError) {
+            fail(describeBuildError(error), error);
+        }
+        throw error;
+    }
+    return entries;
+}
+/**
+ * Finds every permission set build file in the repo and checks the permission set each defines
+ * against the generated file on disk, writing nothing. A repo with no permission set build files is
+ * a skip. Every file is loaded and validated, and names are checked for duplicates across files,
+ * before anything is checked; then every permission set is checked before failing, so one run
+ * reports every stale permission set.
+ *
+ * @throws When any permission set has drifted or is missing, or a permission set build file is invalid.
+ */
+export async function runCheckPermissionSets(options) {
+    if (options.disabled) {
+        logger.warn('check-permission-sets is disabled. Skipping.');
+        return { skipped: true, files: [] };
+    }
+    const files = await findPermissionSetBuildFiles();
+    if (files.length === 0) {
+        logger.warn('No permission set build files found. Skipping.');
+        return { skipped: true, files: [] };
+    }
+    const entries = await loadFiles(files);
+    const results = await checkPermissionSets(entries.map(({ spec }) => spec));
+    const checks = entries.map(({ file }, i) => ({ file, permissionSet: results[i] }));
+    const stale = checks.filter(({ permissionSet }) => permissionSet.status !== 'up-to-date');
+    for (const { file, permissionSet } of stale) {
+        logger.error(`${permissionSet.name} ${permissionSet.status} ${permissionSet.path} (${file})`);
+    }
+    if (stale.length > 0) {
+        logger.log('Regenerate with: sf simply permissions build');
+        const message = `${stale.length} of ${checks.length} permission set(s) have drifted from their source metadata or are missing.`;
+        logger.error(message);
+        throw new Error(message);
+    }
+    logger.success(`All ${checks.length} permission set(s) are up to date.`);
+    return { skipped: false, files: checks };
+}
+//# sourceMappingURL=checkPermissionSets.js.map

package/lib/build/checkPermissionSets.js.map

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

package/lib/build/cleanupScratchOrgs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cleans up scratch orgs older than 3 hours from every given Dev Hub.
+ *
+ * Every Dev Hub alias passed in must already be authenticated by the calling pipeline.
+ */
+export declare function cleanupScratchOrgs(devHubAliases: string[]): Promise<void>;

package/lib/build/cleanupScratchOrgs.js

@@ -0,0 +1,91 @@
+/*
+ * 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 path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { runSf } from '../exec/sfCli.js';
+import { logger } from '../logger.js';
+import { resolveDevHubs } from './devHubs.js';
+async function cleanupScratchOrgsForHub(hubUsername) {
+    logger.info(`Querying for scratch orgs in ${hubUsername}...`);
+    const csvFile = path.join(process.cwd(), `${hubUsername}_orgs.csv`);
+    try {
+        const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+        const query = `SELECT Id FROM ActiveScratchOrg WHERE CreatedDate < ${threeHoursAgo}`;
+        const { stdout } = await runSf([
+            'data',
+            'query',
+            '--query',
+            query,
+            '--result-format',
+            'csv',
+            '--target-org',
+            hubUsername,
+        ]);
+        await fs.writeFile(csvFile, stdout);
+        const fileContent = await fs.readFile(csvFile, 'utf-8');
+        // Fixed: the original split on '' (individual characters), so this line count was
+        // effectively always > 1 for any non-empty CSV and the "no old scratch orgs" branch below
+        // was unreachable. Splitting on newlines actually counts CSV rows.
+        const lines = fileContent.trim().split('\n');
+        if (lines.length > 1) {
+            logger.info(`Found ${lines.length - 1} old scratch orgs in ${hubUsername}. Deleting...`);
+            await runSf([
+                'data',
+                'bulk',
+                'delete',
+                '--sobject',
+                'ActiveScratchOrg',
+                '--file',
+                csvFile,
+                '--target-org',
+                hubUsername,
+                '--wait',
+                '30',
+            ], {
+                stdio: 'inherit',
+            });
+        }
+        else {
+            logger.info(`No old scratch orgs found in ${hubUsername}.`);
+        }
+    }
+    catch (error) {
+        logger.error(`Failed to cleanup scratch orgs for ${hubUsername}:`, error.shortMessage);
+    }
+    finally {
+        try {
+            await fs.unlink(csvFile);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Cleans up scratch orgs older than 3 hours from every given Dev Hub.
+ *
+ * Every Dev Hub alias passed in must already be authenticated by the calling pipeline.
+ */
+export async function cleanupScratchOrgs(devHubAliases) {
+    logger.info('Starting cleanup of old scratch orgs...');
+    const devHubs = await resolveDevHubs(devHubAliases);
+    for (const hub of devHubs) {
+        // eslint-disable-next-line no-await-in-loop -- cleanup runs per hub sequentially, matching the original
+        await cleanupScratchOrgsForHub(hub.username);
+    }
+    logger.success('Scratch org cleanup complete.');
+}
+//# sourceMappingURL=cleanupScratchOrgs.js.map

package/lib/build/cleanupScratchOrgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupScratchOrgs.js","sourceRoot":"","sources":["../../src/build/cleanupScratchOrgs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,KAAK,UAAU,wBAAwB,CAAC,WAAmB;IACzD,MAAM,CAAC,IAAI,CAAC,gCAAgC,WAAW,KAAK,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,WAAW,WAAW,CAAC,CAAC;IACpE,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9E,MAAM,KAAK,GAAG,uDAAuD,aAAa,EAAE,CAAC;QACrF,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC;YAC7B,MAAM;YACN,OAAO;YACP,SAAS;YACT,KAAK;YACL,iBAAiB;YACjB,KAAK;YACL,cAAc;YACd,WAAW;SACZ,CAAC,CAAC;QACH,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,WAAW,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxD,kFAAkF;QAClF,0FAA0F;QAC1F,mEAAmE;QACnE,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,GAAG,CAAC,wBAAwB,WAAW,eAAe,CAAC,CAAC;YACzF,MAAM,KAAK,CACT;gBACE,MAAM;gBACN,MAAM;gBACN,QAAQ;gBACR,WAAW;gBACX,kBAAkB;gBAClB,QAAQ;gBACR,OAAO;gBACP,cAAc;gBACd,WAAW;gBACX,QAAQ;gBACR,IAAI;aACL,EACD;gBACE,KAAK,EAAE,SAAS;aACjB,CACF,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,gCAAgC,WAAW,GAAG,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CACV,sCAAsC,WAAW,GAAG,EACnD,KAAmC,CAAC,YAAY,CAClD,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,YAAY;QACd,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,aAAuB;IAC9D,MAAM,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,aAAa,CAAC,CAAC;IAEpD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,wGAAwG;QACxG,MAAM,wBAAwB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;AAClD,CAAC"}

package/lib/build/createFallbackTag.d.ts

@@ -0,0 +1,24 @@
+import { type VcsProviderKind } from '../vcs/index.js';
+export type CreateFallbackTagOptions = {
+    ciCommitRefName: string;
+    ciProjectPath: string;
+    projectAccessToken: string;
+    ciPipelineId: string;
+    lastTag?: string;
+    out?: string;
+    debug?: boolean;
+    vcsHost?: string;
+    vcsProvider: VcsProviderKind;
+};
+export type CreateFallbackTagResult = {
+    created: boolean;
+    tag?: string;
+    packageId?: string;
+};
+/**
+ * Creates and pushes a fallback git tag that increments the suffix of the last release tag and
+ * annotates it with the previous package version's `04t` ID, for builds that didn't produce a new
+ * package version. Soft no-ops (does not throw) when HEAD already carries a version tag, or when no
+ * last tag, or no valid package ID within it, can be found — a build with nothing to fall back to just has nothing to do here.
+ */
+export declare function createFallbackTag(options: CreateFallbackTagOptions): Promise<CreateFallbackTagResult>;

package/lib/build/createFallbackTag.js

@@ -0,0 +1,147 @@
+/*
+ * 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 { getDefaultPackageDirectory, isSubscriberPackageVersionId, readSfdxProject, } from '@simplysf/simply-core';
+import { createVcsProvider } from '../vcs/index.js';
+import { addGitRemote } from '../git.js';
+import { logger } from '../logger.js';
+import { VersionTagFormat } from './versionTagFormat.js';
+/**
+ * The project's version tag format and the glob for its current `major.minor.patch`. An unreadable
+ * `sfdx-project.json` falls back to `SIMPLY_CICD_VERSION_TAG_FORMAT` or the default format; an
+ * invalid format still throws.
+ */
+async function resolveTagContext() {
+    let project;
+    try {
+        project = await readSfdxProject();
+    }
+    catch {
+        const versionTagFormat = VersionTagFormat.fromProject(undefined);
+        const tagMatchPattern = versionTagFormat.matchPattern();
+        logger.info(`Could not read version prefix from sfdx-project.json. Defaulting to match pattern ${tagMatchPattern}`);
+        return { versionTagFormat, tagMatchPattern };
+    }
+    const versionTagFormat = VersionTagFormat.fromProject(project);
+    return {
+        versionTagFormat,
+        tagMatchPattern: versionTagFormat.matchPattern(getDefaultPackageDirectory(project)?.versionNumber),
+    };
+}
+/**
+ * Resolves the last tag to increment: the explicit `--last-tag`, if given, otherwise the closest
+ * reachable tag matching the project's version prefix. Returns `''` (not a thrown error) when no
+ * tag can be found, either because none exists yet or because `git describe` fails outright — a
+ * fix from the original, where an unguarded `git describe` call meant "no tags yet" crashed the
+ * whole job instead of soft-exiting the way "no valid package ID in the tag" already did.
+ */
+async function resolveLastTag(explicitLastTag, tagMatchPattern) {
+    if (explicitLastTag) {
+        return explicitLastTag;
+    }
+    try {
+        const { stdout } = await execa('git', ['describe', '--tags', '--abbrev=0', '--match', tagMatchPattern]);
+        return stdout.trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Version tags already pointing at HEAD. `create-package-version` tags the commit it just built, and
+ * the documented pipeline runs `create-fallback-tag` right after it in the same job, so a non-empty
+ * result means this commit already has a real package version and needs no fallback. It also keeps a
+ * retried job from stacking a second fallback tag on a commit that already got one.
+ */
+async function findVersionTagsAtHead(tagMatchPattern) {
+    try {
+        const { stdout } = await execa('git', ['tag', '--points-at', 'HEAD', '--list', tagMatchPattern]);
+        return stdout.split(/\r?\n/).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+function extractPackageId(tagAnnotation) {
+    const parts = tagAnnotation.trim().split(/\s+/);
+    return parts.find((part) => isSubscriberPackageVersionId(part) && (part.length === 15 || part.length === 18)) ?? '';
+}
+/**
+ * The last tag with its trailing `-<n>` fallback counter incremented, or `-1` appended. For a tag in
+ * the project's format, only a counter **after** the rendered version counts, so the build number of
+ * a format like `v{MAJOR}.{MINOR}.{PATCH}-{BUILD}` is never mistaken for one: `v1.2.3-4` becomes
+ * `v1.2.3-4-1`, not `v1.2.3-5`. Tags that don't match the format (older three-part tags, an explicit
+ * `--last-tag`) keep the original rule.
+ */
+function computeNextTag(lastTag, versionTagFormat) {
+    const parsed = versionTagFormat.parseTag(lastTag);
+    if (parsed) {
+        const counter = /^(?:(?<base>.*)-)?(?<n>\d+)$/.exec(parsed.rest)?.groups;
+        if (!counter) {
+            return `${lastTag}-1`;
+        }
+        const base = counter.base ? `${parsed.versionTag}-${counter.base}` : parsed.versionTag;
+        return `${base}-${parseInt(counter.n, 10) + 1}`;
+    }
+    const match = /^(?<baseVersion>v.*)-(?<suffix>\d+)$/.exec(lastTag);
+    const baseVersion = match?.groups?.baseVersion ?? lastTag;
+    const currentN = match?.groups?.suffix ? parseInt(match.groups.suffix, 10) : 0;
+    return `${baseVersion}-${currentN + 1}`;
+}
+/**
+ * Creates and pushes a fallback git tag that increments the suffix of the last release tag and
+ * annotates it with the previous package version's `04t` ID, for builds that didn't produce a new
+ * package version. Soft no-ops (does not throw) when HEAD already carries a version tag, or when no
+ * last tag, or no valid package ID within it, can be found — a build with nothing to fall back to just has nothing to do here.
+ */
+export async function createFallbackTag(options) {
+    logger.info('Starting fallback tagging process...');
+    const outFile = options.out ?? 'subscriberPackageVersionId.env';
+    const { versionTagFormat, tagMatchPattern } = await resolveTagContext();
+    const tagsAtHead = await findVersionTagsAtHead(tagMatchPattern);
+    if (tagsAtHead.length > 0) {
+        logger.info(`HEAD is already tagged (${tagsAtHead.join(', ')}). No fallback tag needed.`);
+        return { created: false };
+    }
+    const lastTag = await resolveLastTag(options.lastTag, tagMatchPattern);
+    if (!lastTag) {
+        logger.warn('No previous tag found to increment.');
+        return { created: false };
+    }
+    const { stdout: tagAnnotation } = await execa('git', ['tag', '-l', '-n1', lastTag]);
+    const packageId = extractPackageId(tagAnnotation);
+    if (!packageId) {
+        logger.warn(`Could not find a valid 04t package ID in the annotation of last tag: ${lastTag}`);
+        return { created: false };
+    }
+    logger.info(`Found last tag: ${lastTag} with package ID: ${packageId}`);
+    const nextTag = computeNextTag(lastTag, versionTagFormat);
+    logger.info(`Next fallback tag determined: ${nextTag}`);
+    const vcsProvider = createVcsProvider(options.vcsProvider, {
+        host: options.vcsHost,
+        token: options.projectAccessToken,
+    });
+    const remoteAlias = await addGitRemote(options.ciPipelineId, options.projectAccessToken, options.ciProjectPath, vcsProvider);
+    logger.info(`Tagging commit with tag: ${nextTag}`);
+    await execa('git', ['tag', '-a', nextTag, '-m', packageId]);
+    await execa('git', ['push', remoteAlias, nextTag]);
+    logger.success(`Successfully created and pushed tag: ${nextTag}`);
+    await fs.writeFile(outFile, `SUBSCRIBER_PACKAGE_VERSION_ID=${packageId}\n`, 'utf-8');
+    logger.success(`Wrote package version ID to ${outFile}`);
+    return { created: true, tag: nextTag, packageId };
+}
+//# sourceMappingURL=createFallbackTag.js.map

package/lib/build/createFallbackTag.js.map

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

package/lib/build/createPackageVersion.d.ts

@@ -0,0 +1,42 @@
+import { type VcsProviderKind } from '../vcs/index.js';
+/**
+ * Whether this build's ref is a release-branch build.
+ *
+ * Exported for `publishUtamPageObjects`, which derives its npm version from the same
+ * release-vs-feature-branch decision this module makes for the git tag.
+ */
+export declare function refIncludesPrefix(ciCommitRefName: string, packageReleaseBranchPrefix?: string): boolean;
+/**
+ * The suffix appended to this build's version tag: the package's `branch` attribute, else the CI ref
+ * unless this is a release-branch build, which gets none. A build with neither a `branch` attribute
+ * nor a ref is treated like a release build, the only reading that doesn't produce a tag ending in
+ * `-undefined`.
+ *
+ * Exported because `publishUtamPageObjects` derives its npm version from the same suffix, so that
+ * the published page-object version reads like the tag rather than being a second, parallel rule.
+ */
+export declare function determineTagSuffix(branchAttribute: string | undefined, ciCommitRefName: string | undefined, packageReleaseBranchPrefix?: string): string | undefined;
+export type CreatePackageVersionOptions = {
+    ciCommitRefName: string;
+    ciCommitSha: string;
+    ciPipelineId: string;
+    ciPipelineSource?: string;
+    ciPipelineUrl: string;
+    ciProjectPath: string;
+    projectAccessToken: string;
+    /** The packaging DevHub's alias. Must already be authenticated. */
+    packagingDevhub: string;
+    debug?: boolean;
+    alwaysCreatePackage?: boolean;
+    packageReleaseBranchPrefix?: string;
+    codeCoverageMinimum?: string;
+    vcsHost?: string;
+    vcsProvider: VcsProviderKind;
+};
+/**
+ * Creates a new package version for the default package directory, verifies it meets minimum code
+ * coverage, and creates/pushes a version-tracking git tag. No-ops (without error) when the pipeline
+ * was triggered by a merge request, or when this isn't a release-branch build and
+ * `alwaysCreatePackage` wasn't requested.
+ */
+export declare function createPackageVersion(options: CreatePackageVersionOptions): Promise<void>;