@simplysf/simply-cicd-core 0.2.2 → 0.3.1

package/lib/build/createPackageVersion.js

@@ -0,0 +1,198 @@
+/*
+ * 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, getPluginConfig, readSfdxProject } from '@simplysf/simply-core';
+import { createVcsProvider } from '../vcs/index.js';
+import { runSf } from '../exec/sfCli.js';
+import { addGitRemote } from '../git.js';
+import { logger } from '../logger.js';
+import { VersionTagFormat } from './versionTagFormat.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 function refIncludesPrefix(ciCommitRefName, packageReleaseBranchPrefix) {
+    return packageReleaseBranchPrefix !== undefined && ciCommitRefName.includes(packageReleaseBranchPrefix);
+}
+function determineBranchArgs(branchAttribute, ciCommitRefName, packageReleaseBranchPrefix) {
+    if (branchAttribute) {
+        return ['--branch', branchAttribute];
+    }
+    if (!refIncludesPrefix(ciCommitRefName, packageReleaseBranchPrefix)) {
+        return ['--branch', ciCommitRefName];
+    }
+    return [];
+}
+/**
+ * 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 function determineTagSuffix(branchAttribute, ciCommitRefName, packageReleaseBranchPrefix) {
+    if (branchAttribute) {
+        return branchAttribute;
+    }
+    if (!ciCommitRefName || refIncludesPrefix(ciCommitRefName, packageReleaseBranchPrefix)) {
+        return undefined;
+    }
+    return ciCommitRefName;
+}
+function resolveMinimumCoverage(codeCoverageMinimum, sfdxProjectJson) {
+    let minCoverage = parseInt(codeCoverageMinimum ?? '75', 10);
+    if (Number.isNaN(minCoverage)) {
+        minCoverage = 75;
+    }
+    const projectMinCoverage = getPluginConfig(sfdxProjectJson, 'plugins.simply.coverageRequirement.minimumCoverageRequired');
+    if (projectMinCoverage) {
+        const parsedProjectMin = parseInt(projectMinCoverage, 10);
+        if (!Number.isNaN(parsedProjectMin)) {
+            minCoverage = parsedProjectMin;
+        }
+    }
+    return minCoverage;
+}
+/**
+ * Logs the package Id (`0Ho…`) recorded under `packageAliases` for the project's top-level `name`,
+ * warning rather than failing when either is missing — the Id is informational only.
+ */
+function logPackageId(sfdxProjectJson) {
+    // `name` isn't a declared SfdxProject property, so it arrives as `unknown` via the index signature.
+    const projectName = typeof sfdxProjectJson.name === 'string' ? sfdxProjectJson.name : undefined;
+    const packageId = projectName ? sfdxProjectJson.packageAliases?.[projectName] : undefined;
+    if (packageId) {
+        logger.info(`Package Id: ${packageId}`);
+    }
+    else {
+        logger.warn(`No package Id found in packageAliases for project name "${projectName ?? ''}" in sfdx-project.json`);
+    }
+}
+async function pollPackageVersionCreation(createRequestId, packagingDevhub) {
+    for (;;) {
+        // eslint-disable-next-line no-await-in-loop -- each poll must wait for the previous one's result before deciding to continue
+        const { stdout: reportStdout } = await runSf([
+            'package',
+            'version',
+            'create',
+            'report',
+            '--package-create-request-id',
+            createRequestId,
+            '--target-dev-hub',
+            packagingDevhub,
+            '--json',
+        ]);
+        const report = JSON.parse(reportStdout).result[0];
+        logger.info(`Polling package creation status: ${report.Status}`);
+        if (report.Status === 'Error') {
+            throw new Error(`Package creation failed: ${report.Error ?? 'unknown error'}`);
+        }
+        if (report.Status === 'Success') {
+            const subscriberPackageVersionId = report.SubscriberPackageVersionId ?? '';
+            logger.success(`Package version created successfully: ${subscriberPackageVersionId}`);
+            return subscriberPackageVersionId;
+        }
+        // eslint-disable-next-line no-await-in-loop -- polling must space requests out; nothing else to do meanwhile
+        await new Promise((resolve) => {
+            setTimeout(resolve, 60_000);
+        });
+    }
+}
+/**
+ * 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 async function createPackageVersion(options) {
+    if (options.ciPipelineSource === 'merge_request_event') {
+        logger.info('Not a release branch build. Skipping package creation.');
+        return;
+    }
+    if (!options.alwaysCreatePackage && !refIncludesPrefix(options.ciCommitRefName, options.packageReleaseBranchPrefix)) {
+        logger.info('Not a release branch build and alwaysCreatePackage is not TRUE. Skipping package creation.');
+        return;
+    }
+    logger.info('Creating new package version...');
+    const vcsProvider = createVcsProvider(options.vcsProvider, {
+        host: options.vcsHost,
+        token: options.projectAccessToken,
+    });
+    const remoteAlias = await addGitRemote(options.ciPipelineId, options.projectAccessToken, options.ciProjectPath, vcsProvider);
+    const sfdxProjectJson = await readSfdxProject();
+    const defaultPackageDir = getDefaultPackageDirectory(sfdxProjectJson);
+    const { definitionFile, package: packageAlias, branch: branchAttribute } = defaultPackageDir ?? {};
+    if (!definitionFile || !packageAlias) {
+        throw new Error('`package` and `definitionFile` must be specified in the default package directory in sfdx-project.json');
+    }
+    // Validated before `sf package version create`, so a bad format can't cost a package version
+    // whose tag then can't be written.
+    const versionTagFormat = VersionTagFormat.fromProject(sfdxProjectJson);
+    logPackageId(sfdxProjectJson);
+    const branchArgs = determineBranchArgs(branchAttribute, options.ciCommitRefName, options.packageReleaseBranchPrefix);
+    const { stdout: createStdout } = await runSf([
+        'package',
+        'version',
+        'create',
+        '--code-coverage',
+        '--package',
+        packageAlias,
+        '--definition-file',
+        definitionFile,
+        '--version-description',
+        options.ciPipelineUrl,
+        '--tag',
+        options.ciCommitSha,
+        '--target-dev-hub',
+        options.packagingDevhub,
+        ...branchArgs,
+        '--installation-key-bypass',
+        '--wait',
+        '0',
+        '--json',
+    ]);
+    const createRequestId = JSON.parse(createStdout).result.Id;
+    logger.info(`Package version creation requested. Request ID: ${createRequestId}`);
+    const subscriberPackageVersionId = await pollPackageVersionCreation(createRequestId, options.packagingDevhub);
+    await fs.writeFile('subscriberPackageVersionId.env', `SUBSCRIBER_PACKAGE_VERSION_ID=${subscriberPackageVersionId}`);
+    const { stdout: versionReportStdout } = await runSf([
+        'package',
+        'version',
+        'report',
+        '--package',
+        subscriberPackageVersionId,
+        '--target-dev-hub',
+        options.packagingDevhub,
+        '--json',
+    ]);
+    const versionReport = JSON.parse(versionReportStdout).result;
+    const codeCoverage = versionReport.CodeCoverage.apexCodeCoveragePercentage;
+    const minCoverage = resolveMinimumCoverage(options.codeCoverageMinimum, sfdxProjectJson);
+    logger.info(`Actual code coverage: ${codeCoverage}%. Required minimum: ${minCoverage}%.`);
+    if (codeCoverage < minCoverage) {
+        throw new Error(`Code coverage of ${codeCoverage}% is less than the required minimum of ${minCoverage}%.`);
+    }
+    const versionTag = versionTagFormat.render(versionReport.Version, determineTagSuffix(branchAttribute, options.ciCommitRefName, options.packageReleaseBranchPrefix));
+    await execa('git', ['tag', '-a', versionTag, '-m', subscriberPackageVersionId]);
+    await execa('git', ['push', remoteAlias, versionTag]);
+    logger.success(`Successfully created and pushed git tag: ${versionTag}`);
+}
+//# sourceMappingURL=createPackageVersion.js.map

package/lib/build/createPackageVersion.js.map

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

package/lib/build/createScratchOrg.d.ts

@@ -0,0 +1,14 @@
+export type ScratchOrgCreateResult = Record<string, unknown>;
+export type CreateScratchOrgOptions = {
+    debug?: boolean;
+    scratchDefinitionFile?: string;
+    scratchDurationDays?: string;
+};
+/**
+ * Creates a scratch org, trying each Dev Hub in order until one has remaining daily capacity.
+ * Writes `SCRATCH_ORG_INFO.json`, best-effort sets a default country, and assigns permission
+ * sets/licenses declared in the default package directory's `packageMetadataAccess`.
+ *
+ * Every Dev Hub alias passed in must already be authenticated by the calling pipeline.
+ */
+export declare function createScratchOrg(options: CreateScratchOrgOptions, devHubAliases: string[]): Promise<ScratchOrgCreateResult>;

package/lib/build/createScratchOrg.js

@@ -0,0 +1,192 @@
+/*
+ * 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 { getDefaultPackageDirectory, readSfdxProject } from '@simplysf/simply-core';
+import { runSf, runSfJson } from '../exec/sfCli.js';
+import { logger } from '../logger.js';
+import { resolveDevHubs } from './devHubs.js';
+async function assignPermissionSets(permissionSets) {
+    if (permissionSets.length === 0) {
+        return;
+    }
+    logger.info('Assigning permission sets...');
+    const args = ['org', 'assign', 'permset', '--json', ...permissionSets.flatMap((ps) => ['--name', ps])];
+    try {
+        const result = await runSfJson(args);
+        if (result.status !== 0) {
+            throw new Error(`Permission set assignment failed: ${JSON.stringify(result.failures)}`);
+        }
+        logger.success('Permission sets assigned successfully.');
+    }
+    catch (e) {
+        logger.error('Error assigning permission sets:', e.message);
+        throw e;
+    }
+}
+async function assignPermissionSetLicenses(licenses) {
+    if (licenses.length === 0) {
+        return;
+    }
+    logger.info('Assigning permission set licenses...');
+    const args = ['org', 'assign', 'permset-license', '--json', ...licenses.flatMap((psl) => ['--name', psl])];
+    try {
+        const result = await runSfJson(args);
+        if (result.status !== 0) {
+            throw new Error(`Permission set license assignment failed: ${JSON.stringify(result.failures)}`);
+        }
+        logger.success('Permission set licenses assigned successfully.');
+    }
+    catch (e) {
+        logger.error('Error assigning permission set licenses:', e.message);
+        throw e;
+    }
+}
+async function assignPermissions(sfdxProjectJson) {
+    const defaultPackageDir = getDefaultPackageDirectory(sfdxProjectJson);
+    const access = defaultPackageDir?.packageMetadataAccess;
+    if (!access) {
+        return;
+    }
+    await assignPermissionSets(access.permissionSets ?? []);
+    await assignPermissionSetLicenses(access.permissionSetLicenses ?? []);
+}
+async function checkHubRemainingScratchOrgs(hubUsername) {
+    const limits = await runSfJson([
+        'org',
+        'list',
+        'limits',
+        '--target-org',
+        hubUsername,
+        '--json',
+    ]);
+    return limits.result.find((l) => l.name === 'DailyScratchOrgs')?.remaining;
+}
+async function trySetDefaultCountry() {
+    try {
+        await runSf(['data', 'query', '--query', 'SELECT CountryCode FROM User', '--json']);
+        logger.info('State/Country picklists detected. Setting default country for user...');
+        await runSf([
+            'data',
+            'update',
+            'record',
+            '--sobject',
+            'User',
+            '--where',
+            "Name='User User'",
+            '--values',
+            "CountryCode='US'",
+        ]);
+        logger.success('Default country set.');
+    }
+    catch {
+        logger.info('State/Country picklists not detected. Skipping default country update.');
+    }
+}
+async function attemptScratchOrgCreation(hub, definitionFile, duration) {
+    const remaining = await checkHubRemainingScratchOrgs(hub.username);
+    if (remaining === undefined || remaining <= 0) {
+        logger.warn(`Dev Hub ${hub.alias} has no remaining scratch orgs. Skipping.`);
+        return undefined;
+    }
+    logger.info(`Attempting to create scratch org with Dev Hub ${hub.alias} (${remaining} remaining).`);
+    const { stdout } = await runSf([
+        'org',
+        'create',
+        'scratch',
+        '--target-dev-hub',
+        hub.username,
+        '--duration-days',
+        duration,
+        '--definition-file',
+        definitionFile,
+        '--wait',
+        '20',
+        '--set-default',
+        '--json',
+    ]);
+    const createResult = JSON.parse(stdout).result;
+    await fs.writeFile('SCRATCH_ORG_INFO.json', JSON.stringify(createResult, null, 2));
+    logger.success(`Scratch org created successfully using Dev Hub ${hub.alias}.`);
+    return createResult;
+}
+function isScratchOrgLimitError(message) {
+    return (message.includes('The signup request failed because this organization has reached its daily scratch org signup limit') || message.includes('LIMIT_EXCEEDED'));
+}
+function extractScratchOrgErrorMessage(error) {
+    const err = error;
+    let errorMessage = err.message;
+    if (err.stdout) {
+        try {
+            const errorResult = JSON.parse(err.stdout);
+            errorMessage = errorResult.message ?? errorMessage;
+            logger.error(errorMessage);
+            if (errorResult.stack) {
+                logger.error(errorResult.stack);
+            }
+        }
+        catch {
+            logger.error(err.stdout);
+        }
+    }
+    else {
+        logger.error(err.message);
+    }
+    return errorMessage;
+}
+/**
+ * Creates a scratch org, trying each Dev Hub in order until one has remaining daily capacity.
+ * Writes `SCRATCH_ORG_INFO.json`, best-effort sets a default country, and assigns permission
+ * sets/licenses declared in the default package directory's `packageMetadataAccess`.
+ *
+ * Every Dev Hub alias passed in must already be authenticated by the calling pipeline.
+ */
+export async function createScratchOrg(options, devHubAliases) {
+    const devHubs = await resolveDevHubs(devHubAliases);
+    const sfdxProjectJson = await readSfdxProject();
+    const defaultPackageDir = getDefaultPackageDirectory(sfdxProjectJson);
+    const definitionFile = defaultPackageDir?.definitionFile ?? options.scratchDefinitionFile;
+    if (!definitionFile) {
+        throw new Error('You must specify a definitionFile in the default package directory in sfdx-project.json');
+    }
+    const duration = options.scratchDurationDays ?? '1';
+    for (const hub of devHubs) {
+        try {
+            // eslint-disable-next-line no-await-in-loop -- each Dev Hub is only attempted after the previous one is exhausted
+            const createResult = await attemptScratchOrgCreation(hub, definitionFile, duration);
+            if (!createResult) {
+                continue;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await trySetDefaultCountry();
+            // eslint-disable-next-line no-await-in-loop
+            await assignPermissions(sfdxProjectJson);
+            return createResult;
+        }
+        catch (error) {
+            logger.error(`Scratch org creation failed with Dev Hub ${hub.alias}:`);
+            const errorMessage = extractScratchOrgErrorMessage(error);
+            if (isScratchOrgLimitError(errorMessage)) {
+                logger.warn(`Dev Hub ${hub.alias} reached its daily limit. Trying next Dev Hub...`);
+                continue;
+            }
+            throw new Error(`Scratch org creation failed with a non-recoverable error using Dev Hub ${hub.alias}.`, {
+                cause: error,
+            });
+        }
+    }
+    throw new Error('Scratch org creation failed for all available Dev Hubs.');
+}
+//# sourceMappingURL=createScratchOrg.js.map

package/lib/build/createScratchOrg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createScratchOrg.js","sourceRoot":"","sources":["../../src/build/createScratchOrg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAoB,MAAM,uBAAuB,CAAC;AACtG,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,cAAc,EAAuB,MAAM,cAAc,CAAC;AAInE,KAAK,UAAU,oBAAoB,CAAC,cAAwB;IAC1D,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO;IACT,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACvG,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAwB,IAAI,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,wCAAwC,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,kCAAkC,EAAG,CAAW,CAAC,OAAO,CAAC,CAAC;QACvE,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED,KAAK,UAAU,2BAA2B,CAAC,QAAkB;IAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3G,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAwB,IAAI,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,6CAA6C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAClG,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,gDAAgD,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,0CAA0C,EAAG,CAAW,CAAC,OAAO,CAAC,CAAC;QAC/E,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,eAA4B;IAC3D,MAAM,iBAAiB,GAAG,0BAA0B,CAAC,eAAe,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,iBAAiB,EAAE,qBAAqB,CAAC;IACxD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IACD,MAAM,oBAAoB,CAAC,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,2BAA2B,CAAC,MAAM,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,KAAK,UAAU,4BAA4B,CAAC,WAAmB;IAC7D,MAAM,MAAM,GAAG,MAAM,SAAS,CAAyD;QACrF,KAAK;QACL,MAAM;QACN,QAAQ;QACR,cAAc;QACd,WAAW;QACX,QAAQ;KACT,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,kBAAkB,CAAC,EAAE,SAAS,CAAC;AAC7E,CAAC;AAED,KAAK,UAAU,oBAAoB;IACjC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,8BAA8B,EAAE,QAAQ,CAAC,CAAC,CAAC;QACpF,MAAM,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;QACrF,MAAM,KAAK,CAAC;YACV,MAAM;YACN,QAAQ;YACR,QAAQ;YACR,WAAW;YACX,MAAM;YACN,SAAS;YACT,kBAAkB;YAClB,UAAU;YACV,kBAAkB;SACnB,CAAC,CAAC;QACH,MAAM,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,IAAI,CAAC,wEAAwE,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAID,KAAK,UAAU,yBAAyB,CACtC,GAAmB,EACnB,cAAsB,EACtB,QAAgB;IAEhB,MAAM,SAAS,GAAG,MAAM,4BAA4B,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnE,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,KAAK,2CAA2C,CAAC,CAAC;QAC7E,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,iDAAiD,GAAG,CAAC,KAAK,KAAK,SAAS,cAAc,CAAC,CAAC;IAEpG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC;QAC7B,KAAK;QACL,QAAQ;QACR,SAAS;QACT,kBAAkB;QAClB,GAAG,CAAC,QAAQ;QACZ,iBAAiB;QACjB,QAAQ;QACR,mBAAmB;QACnB,cAAc;QACd,QAAQ;QACR,IAAI;QACJ,eAAe;QACf,QAAQ;KACT,CAAC,CAAC;IACH,MAAM,YAAY,GAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAwC,CAAC,MAAM,CAAC;IACvF,MAAM,EAAE,CAAC,SAAS,CAAC,uBAAuB,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACnF,MAAM,CAAC,OAAO,CAAC,kDAAkD,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;IAC/E,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,SAAS,sBAAsB,CAAC,OAAe;IAC7C,OAAO,CACL,OAAO,CAAC,QAAQ,CACd,oGAAoG,CACrG,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CACxC,CAAC;AACJ,CAAC;AAED,SAAS,6BAA6B,CAAC,KAAc;IACnD,MAAM,GAAG,GAAG,KAAoC,CAAC;IACjD,IAAI,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC;IAC/B,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAyC,CAAC;YACnF,YAAY,GAAG,WAAW,CAAC,OAAO,IAAI,YAAY,CAAC;YACnD,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAC3B,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;gBACtB,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAQD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC,EAChC,aAAuB;IAEvB,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,aAAa,CAAC,CAAC;IAEpD,MAAM,eAAe,GAAG,MAAM,eAAe,EAAE,CAAC;IAChD,MAAM,iBAAiB,GAAG,0BAA0B,CAAC,eAAe,CAAC,CAAC;IACtE,MAAM,cAAc,GAAG,iBAAiB,EAAE,cAAc,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAC1F,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;IAC7G,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,mBAAmB,IAAI,GAAG,CAAC;IAEpD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,kHAAkH;YAClH,MAAM,YAAY,GAAG,MAAM,yBAAyB,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;YACpF,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,SAAS;YACX,CAAC;YACD,4CAA4C;YAC5C,MAAM,oBAAoB,EAAE,CAAC;YAC7B,4CAA4C;YAC5C,MAAM,iBAAiB,CAAC,eAAe,CAAC,CAAC;YACzC,OAAO,YAAY,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,4CAA4C,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;YACvE,MAAM,YAAY,GAAG,6BAA6B,CAAC,KAAK,CAAC,CAAC;YAC1D,IAAI,sBAAsB,CAAC,YAAY,CAAC,EAAE,CAAC;gBACzC,MAAM,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,KAAK,kDAAkD,CAAC,CAAC;gBACpF,SAAS;YACX,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,0EAA0E,GAAG,CAAC,KAAK,GAAG,EAAE;gBACtG,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;AAC7E,CAAC"}

package/lib/build/deleteScratchOrg.d.ts

@@ -0,0 +1,13 @@
+export type DeleteScratchOrgOptions = {
+    /** Required only when the Dev Hub and/or scratch org were JWT-authenticated (no refresh token available). */
+    jwtKeyFile?: string;
+    debug?: boolean;
+};
+/**
+ * Authenticates to the Dev Hub that owns the scratch org and deletes it.
+ *
+ * `devHubAlias` must already be authenticated by the calling pipeline. Deletion failures are
+ * logged, not thrown, matching the original behavior: a scratch org that fails to delete just
+ * needs manual cleanup later, and shouldn't fail an otherwise-successful pipeline run.
+ */
+export declare function deleteScratchOrg(options: DeleteScratchOrgOptions, devHubAlias: string): Promise<void>;

package/lib/build/deleteScratchOrg.js

@@ -0,0 +1,62 @@
+/*
+ * 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 { runSf } from '../exec/sfCli.js';
+import { logger } from '../logger.js';
+import { authenticateOrg } from '../sfAuth.js';
+import { resolveDevHubs } from './devHubs.js';
+import { ensureScratchOrgSession } from './scratchOrgAuth.js';
+import { readScratchOrgInfo } from './scratchOrgInfo.js';
+/**
+ * Authenticates to the Dev Hub that owns the scratch org and deletes it.
+ *
+ * `devHubAlias` must already be authenticated by the calling pipeline. Deletion failures are
+ * logged, not thrown, matching the original behavior: a scratch org that fails to delete just
+ * needs manual cleanup later, and shouldn't fail an otherwise-successful pipeline run.
+ */
+export async function deleteScratchOrg(options, devHubAlias) {
+    logger.info('Deleting scratch org...');
+    try {
+        const scratchOrgInfo = await readScratchOrgInfo();
+        const [hub] = await resolveDevHubs([devHubAlias]);
+        if (hub.username !== scratchOrgInfo.authFields.devHubUsername) {
+            throw new Error(`--dev-hub ${devHubAlias} (${hub.username}) does not match the Dev Hub that created this scratch org (${scratchOrgInfo.authFields.devHubUsername ?? 'unknown'}).`);
+        }
+        if (hub.privateKeyFile) {
+            // JWT-authenticated Dev Hub: no refresh token exists, so re-mint a session explicitly.
+            // A refresh-token-authenticated Dev Hub needs no action here — @salesforce/core refreshes
+            // its already-persisted session automatically.
+            await authenticateOrg({
+                username: hub.username,
+                clientId: hub.clientId,
+                instanceUrl: hub.instanceUrl,
+                jwtKeyFile: hub.privateKeyFile,
+                setDefaultDevHub: true,
+                debug: options.debug,
+            });
+        }
+        await ensureScratchOrgSession(scratchOrgInfo.authFields, {
+            jwtKeyFile: options.jwtKeyFile,
+            setDefault: true,
+            debug: options.debug,
+        });
+        await runSf(['org', 'delete', 'scratch', '--no-prompt'], { stdio: 'inherit' });
+        logger.success('Scratch org deleted.');
+    }
+    catch (e) {
+        logger.error('Failed to delete scratch org. It may need to be deleted manually.', e.message);
+    }
+}
+//# sourceMappingURL=deleteScratchOrg.js.map

package/lib/build/deleteScratchOrg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteScratchOrg.js","sourceRoot":"","sources":["../../src/build/deleteScratchOrg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAQzD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgC,EAAE,WAAmB;IAC1F,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,MAAM,kBAAkB,EAAE,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,cAAc,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;QAClD,IAAI,GAAG,CAAC,QAAQ,KAAK,cAAc,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CACb,aAAa,WAAW,KAAK,GAAG,CAAC,QAAQ,+DAA+D,cAAc,CAAC,UAAU,CAAC,cAAc,IAAI,SAAS,IAAI,CAClK,CAAC;QACJ,CAAC;QAED,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;YACvB,uFAAuF;YACvF,0FAA0F;YAC1F,+CAA+C;YAC/C,MAAM,eAAe,CAAC;gBACpB,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,UAAU,EAAE,GAAG,CAAC,cAAc;gBAC9B,gBAAgB,EAAE,IAAI;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,uBAAuB,CAAC,cAAc,CAAC,UAAU,EAAE;YACvD,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;QAEH,MAAM,KAAK,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAC/E,MAAM,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,mEAAmE,EAAG,CAAW,CAAC,OAAO,CAAC,CAAC;IAC1G,CAAC;AACH,CAAC"}

package/lib/build/deltaRunner.d.ts

@@ -0,0 +1,73 @@
+import { type VcsProviderKind } from '../vcs/index.js';
+/**
+ * One of the upstream `@syntax-syllogism/flow-delta` diff tools. Each ships a diff binary plus one
+ * reporter binary per platform, named `<binary>-<provider kind>`.
+ */
+export type DeltaTool = {
+    /** The diff binary, e.g. `flow-delta`. */
+    binary: string;
+    /** Glob the diff binary scans. */
+    path: string;
+    /** Output directory used when the caller doesn't name one. */
+    defaultOut: string;
+    /** Sentence-case label for log lines, e.g. `Flow`. */
+    label: string;
+};
+export declare const FLOW_DELTA: DeltaTool;
+export declare const FLEXIPAGE_DELTA: DeltaTool;
+/**
+ * Pipeline context handed to the reporter. Everything is optional: each reporter falls back to its
+ * platform's own CI environment variables, which the child process inherits, for anything we don't
+ * pass explicitly.
+ */
+export type DeltaReporterContext = {
+    /** Which platform's reporter to run. Defaults to `gitlab`. */
+    vcsProvider?: VcsProviderKind;
+    /** Hostname of the VCS instance, used to derive the reporter's `--api-url`. */
+    vcsHost?: string;
+    /** Token the reporter authenticates with when posting the diff. */
+    projectAccessToken?: string;
+    commitSha?: string;
+    /** GitLab: numeric project ID. */
+    ciProjectId?: string;
+    /** GitLab: merge request internal ID. */
+    ciMergeRequestIid?: string;
+    /** GitHub: `owner/repo`. */
+    ciRepository?: string;
+    /** GitHub: pull request number. */
+    ciPullRequestNumber?: string;
+    /** GitHub: Actions run ID, used to build artifact links. */
+    ciRunId?: string;
+    /** GitHub: server URL, for non-github.com instances. */
+    ciServerUrl?: string;
+};
+export type RunDeltaOptions = DeltaReporterContext & {
+    from: string;
+    to: string;
+    out?: string;
+    debug?: boolean;
+};
+/**
+ * Builds the reporter argv for the selected platform. The two reporters take different context
+ * flags — GitLab addresses a merge request by project ID and IID, GitHub a pull request by
+ * `owner/repo` and number — which is the whole reason this is routed through the VCS choice.
+ */
+export declare function buildReporterArgs(kind: VcsProviderKind, out: string, context: DeltaReporterContext): string[];
+/**
+ * Runs a delta tool: the diff binary over the `from..to` range, then the reporter binary for the
+ * selected platform to post the result back to the change request. Does not catch its own errors;
+ * callers decide how to handle them.
+ */
+export declare function runDelta(tool: DeltaTool, options: RunDeltaOptions): Promise<void>;
+export type GenerateDiffOptions = RunDeltaOptions & {
+    disabled?: boolean;
+};
+export type GenerateDiffResult = {
+    skipped: boolean;
+    success: boolean;
+};
+/**
+ * Action-handler wrapper around `runDelta`: checks the job-level skip flag, then runs the delta and
+ * logs (rather than throws) on failure, since a diff-posting step shouldn't fail the build.
+ */
+export declare function generateDiff(tool: DeltaTool, options: GenerateDiffOptions): Promise<GenerateDiffResult>;