@simplysf/simply-cicd-core 0.2.1 → 0.3.1

package/lib/build/publishUtamPageObjects.d.ts

@@ -0,0 +1,50 @@
+export type NpmAccess = 'public' | 'restricted';
+export type PublishUtamPageObjectsOptions = {
+    /** The packaging Dev Hub's alias. Must already be authenticated. */
+    packagingDevhub: string;
+    subscriberPackageVersionId?: string;
+    /** Overrides `plugins.simply.utam.packageName`. */
+    npmPackageName?: string;
+    npmRegistry?: string;
+    npmAccess?: NpmAccess;
+    /** Overrides the dist-tag derived from the git tag's suffix. */
+    npmDistTag?: string;
+    ciCommitRefName?: string;
+    packageReleaseBranchPrefix?: string;
+    /** npm spec of the UTAM compiler to install into the staging directory. */
+    utamVersion?: string;
+    /** Compile and `npm pack`, but don't publish. */
+    dryRun?: boolean;
+    /** Dotenv file to append the published name and version to. */
+    out?: string;
+    /** Dotenv file to read `SUBSCRIBER_PACKAGE_VERSION_ID` from. */
+    envFile?: string;
+    debug?: boolean;
+    disabled?: boolean;
+};
+export type PublishUtamPageObjectsResult = {
+    skipped: boolean;
+    published: boolean;
+    /** True when this exact version was already on the registry, so nothing needed publishing. */
+    alreadyPublished?: boolean;
+    packageName?: string;
+    version?: string;
+    distTag?: string;
+    /** Path to the packed tarball, on `--dry-run` only. */
+    tarball?: string;
+};
+/**
+ * Compile the project's UTAM page objects for one package version and publish them as an npm
+ * package whose version is derived from the Salesforce version number.
+ *
+ * Runs after `create-package-version`, whose `04t` it takes as input, so that every Unlocked
+ * Package version has a corresponding page-object package a UI-test suite can pin to. See
+ * `docs/design/0037-utam-page-objects-publish.md` for the reasoning, particularly the version
+ * mapping and why the compiler config is generated per build rather than read from the repo.
+ *
+ * Skips (without failing) when the package didn't change, when the job is disabled, when no `04t`
+ * can be found, when the project authors no page objects, or when this exact version is already on
+ * the registry. Everything past those guards throws on failure: a missing page-object package would
+ * silently break every UI test pinned to that version.
+ */
+export declare function publishUtamPageObjects(options: PublishUtamPageObjectsOptions): Promise<PublishUtamPageObjectsResult>;

package/lib/build/publishUtamPageObjects.js

@@ -0,0 +1,283 @@
+/*
+ * 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 os from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import { getDefaultPackageDirectory, readSfdxProject } from '@simplysf/simply-core';
+import { runSfJson } from '../exec/sfCli.js';
+import { appendToEnvFile } from '../env.js';
+import { logger } from '../logger.js';
+import { determineTagSuffix } from './createPackageVersion.js';
+import { getSkipReason } from './skipGuard.js';
+import { VersionTagFormat } from './versionTagFormat.js';
+import { buildCompilerConfig, buildPackageManifest, buildProvenanceLine, findPageObjectSources, readUtamPluginConfig, resolveSubscriberPackageVersionId, toDistTag, toNpmVersion, toUtamCoreRange, toVersionTag, UTAM_PACKAGE_KEY, UTAM_VERSION_KEY, } from './utamPageObjects.js';
+/** The default dotenv file, matching what `create-package-version`/`create-fallback-tag` write. */
+const DEFAULT_ENV_FILE = 'subscriberPackageVersionId.env';
+/** A run that did nothing, in the shape every guard returns. */
+function skip() {
+    return { skipped: true, published: false };
+}
+/**
+ * Whether `spec` already resolves on the target registry.
+ *
+ * A failure is read as "not published" rather than propagated: the overwhelmingly common cause is
+ * the 404 for a version that doesn't exist yet, and any other cause (auth, network) will fail the
+ * publish immediately afterwards with a better message than this check could give.
+ */
+async function isAlreadyPublished(spec, cwd, registry) {
+    const args = ['view', spec, 'version'];
+    if (registry) {
+        args.push('--registry', registry);
+    }
+    try {
+        const { stdout } = await execa('npm', args, { cwd });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install the UTAM compiler into the staging directory and return the version installed alongside
+ * the entry point to run it with.
+ *
+ * Installed at run time rather than declared as a dependency of this plugin: the compiler pulls in
+ * rollup and the whole `@utam/*` family, which every `simply-cicd` user would otherwise carry for a
+ * feature most of them never enable. `lwc-jest` sets the same precedent.
+ */
+async function installCompiler(stagingDir, utamVersion, debug) {
+    logger.info(`Installing the UTAM compiler (utam@${utamVersion})...`);
+    await execa('npm', ['install', '--no-save', '--no-audit', '--no-fund', `utam@${utamVersion}`], {
+        cwd: stagingDir,
+        stdio: debug ? 'inherit' : 'pipe',
+    });
+    const moduleDir = path.join(stagingDir, 'node_modules', 'utam');
+    const manifest = JSON.parse(await fs.readFile(path.join(moduleDir, 'package.json'), 'utf8'));
+    const binRelative = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.utam;
+    if (!manifest.version || !binRelative) {
+        throw new Error(`The installed utam@${utamVersion} declares no version or no "utam" bin entry.`);
+    }
+    logger.info(`Installed utam@${manifest.version}.`);
+    return { version: manifest.version, entry: path.join(moduleDir, binRelative) };
+}
+/** Copy each `.utam.json` into the staged package, preserving its path under the package directory. */
+async function stageSources(sources, pageObjectsRootDir, stagingDir) {
+    for (const source of sources) {
+        const destination = path.join(stagingDir, 'source', path.relative(pageObjectsRootDir, source));
+        // eslint-disable-next-line no-await-in-loop -- a handful of small files; ordering keeps the log readable
+        await fs.mkdir(path.dirname(destination), { recursive: true });
+        // eslint-disable-next-line no-await-in-loop -- as above
+        await fs.copyFile(source, destination);
+    }
+}
+/**
+ * Resolve every input the publish needs, or decide there is nothing to publish.
+ *
+ * Holds the four guards that depend on reading something — the package version ID, the project,
+ * its page objects — so that the caller is left with the flow rather than the lookups.
+ *
+ * @returns `undefined` when a guard says to skip, having already logged why.
+ */
+async function resolveTarget(options) {
+    const envFile = options.envFile ?? DEFAULT_ENV_FILE;
+    const subscriberPackageVersionId = await resolveSubscriberPackageVersionId({
+        flagValue: options.subscriberPackageVersionId,
+        envFile,
+    });
+    if (!subscriberPackageVersionId) {
+        logger.warn(`No package version ID given, in the environment, or in ${envFile}. ` +
+            'This build created no package version, so there are no page objects to publish. Skipping.');
+        return undefined;
+    }
+    const sfdxProjectJson = await readSfdxProject();
+    const defaultPackageDir = getDefaultPackageDirectory(sfdxProjectJson);
+    if (!defaultPackageDir?.path) {
+        throw new Error('A default package directory with a `path` must be specified in sfdx-project.json.');
+    }
+    const pageObjectsRootDir = path.resolve(defaultPackageDir.path);
+    const sources = await findPageObjectSources(pageObjectsRootDir);
+    if (sources.length === 0) {
+        logger.info(`No UTAM page objects found under ${defaultPackageDir.path}. Skipping.`);
+        return undefined;
+    }
+    logger.info(`Found ${sources.length} UTAM page object(s) under ${defaultPackageDir.path}.`);
+    const versionTagFormat = VersionTagFormat.fromProject(sfdxProjectJson);
+    const utamPluginConfig = readUtamPluginConfig(sfdxProjectJson);
+    const npmPackageName = options.npmPackageName ?? utamPluginConfig.packageName;
+    if (!npmPackageName) {
+        throw new Error('No npm package name to publish under. Pass --npm-package-name, or set `plugins.simply.utam.packageName` in sfdx-project.json.');
+    }
+    const { result: report } = await runSfJson([
+        'package',
+        'version',
+        'report',
+        '--package',
+        subscriberPackageVersionId,
+        '--target-dev-hub',
+        options.packagingDevhub,
+        '--json',
+    ]);
+    if (!report.Version) {
+        throw new Error(`Could not read a version number for ${subscriberPackageVersionId} from its package version report.`);
+    }
+    const tagSuffix = determineTagSuffix(defaultPackageDir.branch, options.ciCommitRefName, options.packageReleaseBranchPrefix);
+    return {
+        subscriberPackageVersionId,
+        pageObjectsRootDir,
+        sources,
+        utamPluginConfig,
+        npmPackageName,
+        salesforcePackageName: report.Package2Name ?? defaultPackageDir.package ?? 'package',
+        salesforceVersion: report.Version,
+        version: toNpmVersion(report.Version, tagSuffix),
+        distTag: options.npmDistTag ?? toDistTag(tagSuffix),
+        versionTag: toVersionTag(report.Version, tagSuffix, versionTagFormat),
+        commitSha: report.Tag,
+        pipelineUrl: report.Description,
+    };
+}
+/**
+ * Fill the staging directory with a publishable package: the compiler, its generated config, the
+ * compiled output, the source JSON, and the manifest describing all of it.
+ */
+async function buildStagedPackage(stagingDir, target, options) {
+    const compiler = await installCompiler(stagingDir, options.utamVersion ?? '^3', options.debug ?? false);
+    const baseConfig = target.utamPluginConfig.compilerConfig
+        ? JSON.parse(await fs.readFile(target.utamPluginConfig.compilerConfig, 'utf8'))
+        : undefined;
+    const compilerConfigPath = path.join(stagingDir, 'utam.config.json');
+    await fs.writeFile(compilerConfigPath, JSON.stringify(buildCompilerConfig({
+        pageObjectsRootDir: target.pageObjectsRootDir,
+        stagingDir,
+        npmPackageName: target.npmPackageName,
+        version: target.version,
+        copyright: buildProvenanceLine(target.salesforcePackageName, target.salesforceVersion, target.subscriberPackageVersionId),
+        alias: target.utamPluginConfig.alias,
+        baseConfig,
+    }), null, 2));
+    logger.info('Compiling page objects...');
+    // Run the installed compiler's entry point with this same Node rather than going through npx,
+    // which would be free to reach the network for a package that is already sitting right here.
+    await execa(process.execPath, [compiler.entry, '-c', compilerConfigPath], {
+        cwd: stagingDir,
+        stdio: options.debug ? 'inherit' : 'pipe',
+    });
+    await stageSources(target.sources, target.pageObjectsRootDir, stagingDir);
+    await fs.writeFile(path.join(stagingDir, 'package.json'), `${JSON.stringify(buildPackageManifest({
+        npmPackageName: target.npmPackageName,
+        version: target.version,
+        salesforcePackageName: target.salesforcePackageName,
+        salesforceVersion: target.salesforceVersion,
+        subscriberPackageVersionId: target.subscriberPackageVersionId,
+        versionTag: target.versionTag,
+        commitSha: target.commitSha,
+        pipelineUrl: target.pipelineUrl,
+        utamCoreRange: toUtamCoreRange(compiler.version),
+        projectPeerDependencies: target.utamPluginConfig.peerDependencies,
+    }), null, 2)}\n`);
+}
+/** `npm publish` the staged package, targeting the registry and access level the pipeline asked for. */
+async function publishStaged(stagingDir, distTag, options) {
+    const args = ['publish', '--tag', distTag];
+    if (options.npmRegistry) {
+        args.push('--registry', options.npmRegistry);
+    }
+    if (options.npmAccess) {
+        args.push('--access', options.npmAccess);
+    }
+    await execa('npm', args, { cwd: stagingDir, stdio: options.debug ? 'inherit' : 'pipe' });
+}
+/** `npm pack` the staged package and copy the tarball where a CI job can collect it as an artifact. */
+async function packTarball(stagingDir) {
+    const { stdout } = await execa('npm', ['pack', '--json'], { cwd: stagingDir });
+    const packed = JSON.parse(stdout);
+    const filename = packed[0]?.filename;
+    if (!filename) {
+        throw new Error('npm pack did not report a tarball filename.');
+    }
+    const destination = path.join(process.cwd(), filename);
+    await fs.copyFile(path.join(stagingDir, filename), destination);
+    return destination;
+}
+/**
+ * Compile the project's UTAM page objects for one package version and publish them as an npm
+ * package whose version is derived from the Salesforce version number.
+ *
+ * Runs after `create-package-version`, whose `04t` it takes as input, so that every Unlocked
+ * Package version has a corresponding page-object package a UI-test suite can pin to. See
+ * `docs/design/0037-utam-page-objects-publish.md` for the reasoning, particularly the version
+ * mapping and why the compiler config is generated per build rather than read from the repo.
+ *
+ * Skips (without failing) when the package didn't change, when the job is disabled, when no `04t`
+ * can be found, when the project authors no page objects, or when this exact version is already on
+ * the registry. Everything past those guards throws on failure: a missing page-object package would
+ * silently break every UI test pinned to that version.
+ */
+export async function publishUtamPageObjects(options) {
+    const skipReason = getSkipReason('publish-utam-page-objects');
+    if (skipReason) {
+        logger.warn(skipReason);
+        return skip();
+    }
+    if (options.disabled) {
+        logger.warn('publish-utam-page-objects is disabled. Skipping.');
+        return skip();
+    }
+    const target = await resolveTarget(options);
+    if (!target) {
+        return skip();
+    }
+    const { npmPackageName, version, distTag } = target;
+    const outFile = options.out ?? DEFAULT_ENV_FILE;
+    const publishedKeys = { [UTAM_PACKAGE_KEY]: npmPackageName, [UTAM_VERSION_KEY]: version };
+    logger.info(`Publishing ${npmPackageName}@${version} (dist-tag ${distTag}) for ${target.salesforceVersion}.`);
+    // Never inside the repo: the checkout is what gets compiled, and a generated package.json next to
+    // sfdx-project.json would be picked up by anything else the job runs.
+    const stagingDir = await fs.mkdtemp(path.join(os.tmpdir(), 'simply-cicd-utam-'));
+    if (options.debug) {
+        logger.debug(`Staging directory: ${stagingDir}`);
+    }
+    // Registry auth is the job's to set up, not this command's. Because npm runs from the staging
+    // directory, it sees user, global, and environment config, but never the repo's own .npmrc.
+    try {
+        if (!options.dryRun &&
+            (await isAlreadyPublished(`${npmPackageName}@${version}`, stagingDir, options.npmRegistry))) {
+            logger.info(`${npmPackageName}@${version} is already published. Skipping.`);
+            appendToEnvFile(outFile, publishedKeys);
+            return { skipped: true, published: false, alreadyPublished: true, packageName: npmPackageName, version, distTag };
+        }
+        await buildStagedPackage(stagingDir, target, options);
+        if (options.dryRun) {
+            const tarball = await packTarball(stagingDir);
+            logger.success(`Dry run: packed ${npmPackageName}@${version} to ${tarball}. Nothing was published.`);
+            return { skipped: false, published: false, packageName: npmPackageName, version, distTag, tarball };
+        }
+        await publishStaged(stagingDir, distTag, options);
+        logger.success(`Published ${npmPackageName}@${version} (dist-tag ${distTag}).`);
+        appendToEnvFile(outFile, publishedKeys);
+        return { skipped: false, published: true, packageName: npmPackageName, version, distTag };
+    }
+    finally {
+        if (options.debug) {
+            logger.debug(`Leaving the staging directory in place for inspection: ${stagingDir}`);
+        }
+        else {
+            await fs.rm(stagingDir, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=publishUtamPageObjects.js.map

package/lib/build/publishUtamPageObjects.js.map

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

package/lib/build/pushScratch.d.ts

@@ -0,0 +1,9 @@
+export type PushScratchOptions = {
+    /** Required only when the scratch org's Dev Hub was JWT-authenticated (no refresh token available). */
+    jwtKeyFile?: string;
+    debug?: boolean;
+    ignoreWarnings?: boolean;
+    scratchOrgSourceDir?: string;
+};
+/** Authenticates to the scratch org, strips ECA-related metadata, and pushes source to it. */
+export declare function pushToScratch(options: PushScratchOptions): Promise<void>;

package/lib/build/pushScratch.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { execa } from 'execa';
+import { getDefaultPackageDirectory, readSfdxProject } from '@simplysf/simply-core';
+import { runSf } from '../exec/sfCli.js';
+import { logger } from '../logger.js';
+import { ensureScratchOrgSession } from './scratchOrgAuth.js';
+import { readScratchOrgInfo } from './scratchOrgInfo.js';
+const INCOMPATIBLE_METADATA_PATTERNS = [
+    '*.eca-meta.xml',
+    '*.ecaGlblOauth-meta.xml',
+    '*.ecaOauth-meta.xml',
+    '*.ecaOauthPlcy-meta.xml',
+    '*.ecaPlcy-meta.xml',
+];
+async function removeIncompatibleMetadata() {
+    logger.info('Removing incompatible metadata before push...');
+    for (const pattern of INCOMPATIBLE_METADATA_PATTERNS) {
+        // eslint-disable-next-line no-await-in-loop -- deletions must not race each other on the same tree
+        await execa('find', [process.cwd(), '-type', 'f', '-name', pattern, '-delete']);
+    }
+}
+/** Authenticates to the scratch org, strips ECA-related metadata, and pushes source to it. */
+export async function pushToScratch(options) {
+    logger.info('Pushing source to scratch org...');
+    const scratchOrgInfo = await readScratchOrgInfo();
+    await ensureScratchOrgSession(scratchOrgInfo.authFields, {
+        jwtKeyFile: options.jwtKeyFile,
+        setDefault: true,
+        debug: options.debug,
+    });
+    await removeIncompatibleMetadata();
+    const pushArgs = ['project', 'deploy', 'start', '--ignore-conflicts', '--wait', '120'];
+    if (options.ignoreWarnings) {
+        pushArgs.push('--ignore-warnings');
+    }
+    if (options.scratchOrgSourceDir) {
+        pushArgs.push('--source-dir', options.scratchOrgSourceDir);
+        const seedMetadataDir = getDefaultPackageDirectory(await readSfdxProject())?.seedMetadata?.path;
+        if (seedMetadataDir) {
+            pushArgs.push('--source-dir', seedMetadataDir);
+        }
+    }
+    await runSf(pushArgs, { stdio: 'inherit' });
+    logger.success('Source pushed to scratch org.');
+}
+//# sourceMappingURL=pushScratch.js.map

package/lib/build/pushScratch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pushScratch.js","sourceRoot":"","sources":["../../src/build/pushScratch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,8BAA8B,GAAG;IACrC,gBAAgB;IAChB,yBAAyB;IACzB,qBAAqB;IACrB,yBAAyB;IACzB,oBAAoB;CACrB,CAAC;AAEF,KAAK,UAAU,0BAA0B;IACvC,MAAM,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC7D,KAAK,MAAM,OAAO,IAAI,8BAA8B,EAAE,CAAC;QACrD,mGAAmG;QACnG,MAAM,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAClF,CAAC;AACH,CAAC;AAUD,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA2B;IAC7D,MAAM,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAChD,MAAM,cAAc,GAAG,MAAM,kBAAkB,EAAE,CAAC;IAClD,MAAM,uBAAuB,CAAC,cAAc,CAAC,UAAU,EAAE;QACvD,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,UAAU,EAAE,IAAI;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC;IAEH,MAAM,0BAA0B,EAAE,CAAC;IAEnC,MAAM,QAAQ,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACvF,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;QAChC,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC3D,MAAM,eAAe,GAAG,0BAA0B,CAAC,MAAM,eAAe,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC;QAChG,IAAI,eAAe,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,MAAM,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;AAClD,CAAC"}

package/lib/build/scratchOrgAuth.d.ts

@@ -0,0 +1,18 @@
+import type { ScratchOrgInfo } from './scratchOrgInfo.js';
+export type EnsureScratchOrgSessionOptions = {
+    /** Required only when the scratch org's Dev Hub was JWT-authenticated (no refresh token available). */
+    jwtKeyFile?: string;
+    debug?: boolean;
+    setDefault?: boolean;
+};
+/**
+ * Ensures the scratch org recorded in `SCRATCH_ORG_INFO.json` has a live session, using whichever
+ * renewable credential it actually has.
+ *
+ * A scratch org whose Dev Hub authenticated via web/SFDX auth-url gets its own `refreshToken` at
+ * creation time (Salesforce's OAuth "web server" flow always returns one) — that's used directly
+ * via `@salesforce/core`, no shell-out. A JWT-authenticated Dev Hub never produces a refresh token
+ * (JWT bearer grants don't have one), so that case still falls back to the existing
+ * `authenticateOrg()` JWT re-auth.
+ */
+export declare function ensureScratchOrgSession(authFields: ScratchOrgInfo['authFields'], options: EnsureScratchOrgSessionOptions): Promise<void>;

package/lib/build/scratchOrgAuth.js

@@ -0,0 +1,52 @@
+/*
+ * 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 { AuthInfo, SfError } from '@salesforce/core';
+import { authenticateOrg } from '../sfAuth.js';
+/**
+ * Ensures the scratch org recorded in `SCRATCH_ORG_INFO.json` has a live session, using whichever
+ * renewable credential it actually has.
+ *
+ * A scratch org whose Dev Hub authenticated via web/SFDX auth-url gets its own `refreshToken` at
+ * creation time (Salesforce's OAuth "web server" flow always returns one) — that's used directly
+ * via `@salesforce/core`, no shell-out. A JWT-authenticated Dev Hub never produces a refresh token
+ * (JWT bearer grants don't have one), so that case still falls back to the existing
+ * `authenticateOrg()` JWT re-auth.
+ */
+export async function ensureScratchOrgSession(authFields, options) {
+    const { username, clientId, instanceUrl, refreshToken, clientSecret } = authFields;
+    if (refreshToken) {
+        const authInfo = await AuthInfo.create({
+            oauth2Options: { clientId, clientSecret, refreshToken, loginUrl: instanceUrl },
+        });
+        await authInfo.save();
+        if (options.setDefault) {
+            await authInfo.handleAliasAndDefaultSettings({ setDefault: true, setDefaultDevHub: false });
+        }
+        return;
+    }
+    if (!options.jwtKeyFile) {
+        throw new SfError(`No refresh token available for org ${username} and no --jwt-key-file was provided; cannot re-authenticate.`, 'ScratchOrgReauthError');
+    }
+    await authenticateOrg({
+        username,
+        clientId,
+        instanceUrl,
+        jwtKeyFile: options.jwtKeyFile,
+        setDefault: options.setDefault,
+        debug: options.debug,
+    });
+}
+//# sourceMappingURL=scratchOrgAuth.js.map

package/lib/build/scratchOrgAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratchOrgAuth.js","sourceRoot":"","sources":["../../src/build/scratchOrgAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAU/C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,UAAwC,EACxC,OAAuC;IAEvC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,UAAU,CAAC;IAEnF,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;YACrC,aAAa,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE;SAC/E,CAAC,CAAC;QACH,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,MAAM,QAAQ,CAAC,6BAA6B,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9F,CAAC;QACD,OAAO;IACT,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,OAAO,CACf,sCAAsC,QAAQ,8DAA8D,EAC5G,uBAAuB,CACxB,CAAC;IACJ,CAAC;IAED,MAAM,eAAe,CAAC;QACpB,QAAQ;QACR,QAAQ;QACR,WAAW;QACX,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC;AACL,CAAC"}

package/lib/build/scratchOrgInfo.d.ts

@@ -0,0 +1,14 @@
+export type ScratchOrgInfo = {
+    authFields: {
+        username: string;
+        clientId: string;
+        instanceUrl: string;
+        devHubUsername?: string;
+        /** Present when the owning Dev Hub wasn't JWT-authenticated. */
+        refreshToken?: string;
+        /** Present alongside `refreshToken` for a custom connected app. */
+        clientSecret?: string;
+    };
+};
+/** Reads and parses `SCRATCH_ORG_INFO.json` (written by `build create-scratch`) from the current directory. */
+export declare function readScratchOrgInfo(): Promise<ScratchOrgInfo>;

package/lib/build/scratchOrgInfo.js

@@ -0,0 +1,21 @@
+/*
+ * 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';
+/** Reads and parses `SCRATCH_ORG_INFO.json` (written by `build create-scratch`) from the current directory. */
+export async function readScratchOrgInfo() {
+    return JSON.parse(await fs.readFile('SCRATCH_ORG_INFO.json', 'utf-8'));
+}
+//# sourceMappingURL=scratchOrgInfo.js.map

package/lib/build/scratchOrgInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratchOrgInfo.js","sourceRoot":"","sources":["../../src/build/scratchOrgInfo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAezC,+GAA+G;AAC/G,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAmB,CAAC;AAC3F,CAAC"}

package/lib/build/skipGuard.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a warning message (and thus "should skip") if `job` should be skipped given the current
+ * `PACKAGE_CHANGED` environment variable set by `determine-package-changes` earlier in the
+ * pipeline: scratch-org-lifecycle jobs skip when nothing changed, `create-fallback-tag` skips when
+ * something did (since a real package version will be created instead). Returns `undefined`
+ * (don't skip) otherwise.
+ */
+export declare function getSkipReason(job: string): string | undefined;

package/lib/build/skipGuard.js

@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+/** Jobs that only make sense to run when the package actually changed. */
+const PACKAGE_CHANGED_GATED_JOBS = new Set([
+    'create-scratch',
+    'install-dependencies',
+    'push-scratch',
+    'test-scratch',
+    'delete-scratch',
+    'create-package-version',
+    'publish-utam-page-objects',
+]);
+/**
+ * Returns a warning message (and thus "should skip") if `job` should be skipped given the current
+ * `PACKAGE_CHANGED` environment variable set by `determine-package-changes` earlier in the
+ * pipeline: scratch-org-lifecycle jobs skip when nothing changed, `create-fallback-tag` skips when
+ * something did (since a real package version will be created instead). Returns `undefined`
+ * (don't skip) otherwise.
+ */
+export function getSkipReason(job) {
+    if (PACKAGE_CHANGED_GATED_JOBS.has(job) && process.env.PACKAGE_CHANGED === 'FALSE') {
+        return `No package changes detected (PACKAGE_CHANGED=FALSE). Skipping job: ${job}`;
+    }
+    if (job === 'create-fallback-tag' && process.env.PACKAGE_CHANGED === 'TRUE') {
+        return 'Package changes detected (PACKAGE_CHANGED=TRUE). Skipping fallback tag creation.';
+    }
+    return undefined;
+}
+//# sourceMappingURL=skipGuard.js.map

package/lib/build/skipGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skipGuard.js","sourceRoot":"","sources":["../../src/build/skipGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,0EAA0E;AAC1E,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC;IACzC,gBAAgB;IAChB,sBAAsB;IACtB,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,wBAAwB;IACxB,2BAA2B;CAC5B,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,0BAA0B,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,OAAO,EAAE,CAAC;QACnF,OAAO,sEAAsE,GAAG,EAAE,CAAC;IACrF,CAAC;IAED,IAAI,GAAG,KAAK,qBAAqB,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,MAAM,EAAE,CAAC;QAC5E,OAAO,kFAAkF,CAAC;IAC5F,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/lib/build/testScratch.d.ts

@@ -0,0 +1,15 @@
+export type RunScratchApexTestsOptions = {
+    /** Required only when the scratch org's Dev Hub was JWT-authenticated (no refresh token available). */
+    jwtKeyFile?: string;
+    debug?: boolean;
+    /** Skips just the Apex test run, independent of the job-level --disabled flag. */
+    disableApexTests?: boolean;
+};
+/**
+ * Authenticates to the scratch org and runs its Apex tests.
+ *
+ * The original `--disable-apex-tests` flag was checked against the wrong option name internally
+ * (it re-checked the generic `--disabled` flag), making it a no-op. Here it actually gates the
+ * test run.
+ */
+export declare function runScratchApexTests(options: RunScratchApexTestsOptions): Promise<void>;