@simplysf/simply-cicd-core 0.2.2 → 0.4.0

package/lib/deploy/deployProject.js

@@ -0,0 +1,114 @@
+/*
+ * 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 { isSubscriberPackageVersionId } from '@simplysf/simply-core';
+import { logger } from '../logger.js';
+import { runDeployStage } from './runDeployStage.js';
+import { installDeployPackageDependencies, printDeploymentSummary, runDeployApexTests, runDeploymentSteps, } from './deployCommon.js';
+async function installPackageById(packageId, alias, upgradeType) {
+    await execa('sf', [
+        'package',
+        'install',
+        '--apex-compile',
+        'package',
+        '--package',
+        packageId,
+        '--target-org',
+        alias ?? '',
+        '--wait',
+        '120',
+        '--upgrade-type',
+        upgradeType,
+        '--no-prompt',
+    ], { stdio: 'inherit' });
+}
+async function installProjectPackageFromSubscriberId(subscriberPackageVersionId, alias, upgradeType) {
+    logger.info(`Installing package version from --subscriber-package-version-id: ${subscriberPackageVersionId}`);
+    await installPackageById(subscriberPackageVersionId, alias, upgradeType);
+    logger.success(`Successfully installed package ${subscriberPackageVersionId}.`);
+}
+async function installProjectPackageFromGitTag(alias, upgradeType) {
+    logger.info('Checking for package version in git tag...');
+    try {
+        const { stdout: currentTagRaw } = await execa('git', ['tag', '--points-at', 'HEAD']);
+        const currentTag = currentTagRaw.split('\n')[0].trim();
+        if (!currentTag) {
+            logger.info('No git tag found at HEAD. Skipping main package installation.');
+            return;
+        }
+        logger.info(`Found git tag ${currentTag}, checking for package ID...`);
+        const { stdout: tagAnnotation } = await execa('git', ['tag', '-l', '-n1', currentTag]);
+        const parts = tagAnnotation.trim().split(/\s+/);
+        if (parts.length <= 1) {
+            logger.info(`Git tag ${currentTag} has no annotation. Skipping main package installation.`);
+            return;
+        }
+        const packageId = parts.slice(1).join(' ');
+        if (!isSubscriberPackageVersionId(packageId)) {
+            logger.info('No 04t package version found in git tag annotation. Skipping main package installation.');
+            return;
+        }
+        logger.info(`Found package ID ${packageId} in tag. Installing...`);
+        await installPackageById(packageId, alias, upgradeType);
+        logger.success(`Successfully installed package ${packageId} from git tag.`);
+    }
+    catch (error) {
+        logger.warn(`Could not determine package version from git tag: ${error.message}. Skipping main package installation.`);
+    }
+}
+/**
+ * Installs the project's own package into the target org: prioritizes `--subscriber-package-version-id`
+ * if given, else looks for a `04t...` package ID annotated on the git tag pointing at HEAD.
+ */
+async function installProjectPackage(config) {
+    const { alias, subscriberPackageVersionId, upgradeType = 'Mixed' } = config;
+    logger.info('Installing main package...');
+    if (subscriberPackageVersionId && isSubscriberPackageVersionId(subscriberPackageVersionId)) {
+        await installProjectPackageFromSubscriberId(subscriberPackageVersionId, alias, upgradeType);
+    }
+    else {
+        await installProjectPackageFromGitTag(alias, upgradeType);
+    }
+}
+/**
+ * Runs a single-package "project" deployment stage: `install-packaged` installs dependencies plus
+ * the project's own package, `run-apex-tests` delegates to the shared Apex test runner, and every
+ * other stage runs through the resumable deployment-steps loop against `config/deploy.json`.
+ */
+export async function deployProject(options) {
+    const { stage, ...config } = options;
+    await runDeployStage(stage, options, async () => {
+        if (stage === 'install-packaged') {
+            await installDeployPackageDependencies(config);
+            await installProjectPackage(config);
+        }
+        else if (stage === 'run-apex-tests') {
+            await runDeployApexTests(config);
+        }
+        else {
+            const { deployProgress } = await runDeploymentSteps({
+                ...config,
+                isProjectDeployment: true,
+                stage,
+                deployConfigFile: config.deployConfigFile ?? 'config/deploy.json',
+                deployProgressFile: config.deployProgressFile ?? 'DEPLOY_PROGRESS.json',
+                deployRulesFile: config.deployRulesFile ?? 'config/deploy-rules.json',
+            });
+            printDeploymentSummary(deployProgress, stage);
+        }
+    });
+}
+//# sourceMappingURL=deployProject.js.map

package/lib/deploy/deployProject.js.map

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

package/lib/deploy/runDeployStage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Run one deployment stage inside the shared banner/timing/error frame.
+ *
+ * Both deployment styles bracket a stage the same way: announce it, install the deployment
+ * plugins, run it, then report how long it took — or, on failure, report the elapsed time and the
+ * failing job before rethrowing. Only the middle step differs between them.
+ *
+ * @param stage - The stage name, as it appears in the banner.
+ * @param options - The stage's full options, logged verbatim when `debug` is set.
+ * @param runStage - The stage's actual work.
+ * @throws Whatever `runStage` throws, after logging it. The error is never swallowed — the CI job
+ * still has to fail.
+ */
+export declare function runDeployStage(stage: string, options: {
+    debug?: boolean;
+}, runStage: () => Promise<void>): Promise<void>;

package/lib/deploy/runDeployStage.js

@@ -0,0 +1,65 @@
+/*
+ * 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 chalk from 'chalk';
+import { logger } from '../logger.js';
+import { installDeploymentPlugins } from '../sfPlugins.js';
+/** Width of the `=` rules that bracket each stage's banner in the job log. */
+const BANNER_WIDTH = 80;
+/** @returns Seconds elapsed since `startTime`, to two decimal places. */
+function elapsedSeconds(startTime) {
+    return Number(((Date.now() - startTime) / 1000).toFixed(2));
+}
+/** Writes a rule-bracketed banner, the shape every stage boundary uses in the job log. */
+function banner(write, message) {
+    logger.raw('\n' + '='.repeat(BANNER_WIDTH));
+    write(message);
+    logger.raw('='.repeat(BANNER_WIDTH) + '\n');
+}
+/**
+ * Run one deployment stage inside the shared banner/timing/error frame.
+ *
+ * Both deployment styles bracket a stage the same way: announce it, install the deployment
+ * plugins, run it, then report how long it took — or, on failure, report the elapsed time and the
+ * failing job before rethrowing. Only the middle step differs between them.
+ *
+ * @param stage - The stage name, as it appears in the banner.
+ * @param options - The stage's full options, logged verbatim when `debug` is set.
+ * @param runStage - The stage's actual work.
+ * @throws Whatever `runStage` throws, after logging it. The error is never swallowed — the CI job
+ * still has to fail.
+ */
+export async function runDeployStage(stage, options, runStage) {
+    banner(logger.info, `>>> Starting Deployment Stage: ${chalk.bold(stage)} <<<`);
+    const startTime = Date.now();
+    try {
+        if (options.debug) {
+            logger.debug(`Incoming parameters: ${stage}`, options);
+        }
+        await installDeploymentPlugins(options.debug);
+        await runStage();
+        banner(logger.success, `Completed stage ${chalk.bold(stage)} in ${elapsedSeconds(startTime)}s`);
+    }
+    catch (error) {
+        // Deployment-step failures carry the job they came from; anything else just has a message.
+        const job = error.job;
+        logger.raw('\n' + '='.repeat(BANNER_WIDTH));
+        logger.error(`Failed stage ${chalk.bold(stage)}${job ? ` for ${chalk.bold(job)}` : ''} after ${elapsedSeconds(startTime)}s`);
+        logger.raw(error.message);
+        logger.raw('='.repeat(BANNER_WIDTH) + '\n');
+        throw error;
+    }
+}
+//# sourceMappingURL=runDeployStage.js.map

package/lib/deploy/runDeployStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runDeployStage.js","sourceRoot":"","sources":["../../src/deploy/runDeployStage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,yEAAyE;AACzE,SAAS,cAAc,CAAC,SAAiB;IACvC,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,0FAA0F;AAC1F,SAAS,MAAM,CAAC,KAAgC,EAAE,OAAe;IAC/D,MAAM,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5C,KAAK,CAAC,OAAO,CAAC,CAAC;IACf,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAa,EACb,OAA4B,EAC5B,QAA6B;IAE7B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,kCAAkC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAE/E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,CAAC,KAAK,CAAC,wBAAwB,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;QACzD,CAAC;QAED,MAAM,wBAAwB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,QAAQ,EAAE,CAAC;QAEjB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAClG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,2FAA2F;QAC3F,MAAM,GAAG,GAAI,KAAkC,CAAC,GAAG,CAAC;QAEpD,MAAM,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,CACV,gBAAgB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,cAAc,CAAC,SAAS,CAAC,GAAG,CAC/G,CAAC;QACF,MAAM,CAAC,GAAG,CAAE,KAAe,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;QAE5C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/deploy/stageOptions.d.ts

@@ -0,0 +1,49 @@
+import type { DeployHappySoupOptions } from './deployHappySoup.js';
+import type { DeployProjectOptions } from './deployProject.js';
+/** The parsed flag values of a "project" deployment stage command, keyed by kebab-case flag name. */
+export type ProjectStageFlagValues = {
+    'ci-job-token': string;
+    alias: string;
+    debug: boolean;
+    'deploy-config-file': string;
+    'deploy-progress-file': string;
+    'deploy-rules-file': string;
+    'start-from'?: string;
+    'test-level'?: string;
+    'test-suite'?: string;
+    tests?: string;
+    'vcs-host'?: string;
+    'vcs-provider': DeployProjectOptions['vcsProvider'];
+};
+/**
+ * The parsed flag values of a "happy-soup" deployment stage command, keyed by kebab-case flag name.
+ *
+ * `--deploy-config-file` is optional here where the project flags make it required, because
+ * happy-soup falls back to deriving one from `--source-branch-name`.
+ */
+export type HappySoupStageFlagValues = Omit<ProjectStageFlagValues, 'deploy-config-file' | 'test-suite'> & {
+    'deploy-config-file'?: string;
+    'source-branch-name'?: string;
+};
+/**
+ * Map a project stage command's parsed flags onto {@link DeployProjectOptions}.
+ *
+ * The kebab-case flag names and camelCase option names are a straight one-to-one rename, and it
+ * was written out identically in every stage command.
+ *
+ * @param stage - The stage this command runs.
+ * @param flags - The command's parsed flags.
+ * @returns The options to hand to `deployProject()`.
+ */
+export declare function toProjectStageOptions(stage: string, flags: ProjectStageFlagValues): DeployProjectOptions;
+/**
+ * Map a happy-soup stage command's parsed flags onto {@link DeployHappySoupOptions}.
+ *
+ * Same shape as {@link toProjectStageOptions}, trading `--test-suite` (which happy-soup stages
+ * don't accept) for `--source-branch-name`.
+ *
+ * @param stage - The stage this command runs.
+ * @param flags - The command's parsed flags.
+ * @returns The options to hand to `deployHappySoup()`.
+ */
+export declare function toHappySoupStageOptions(stage: string, flags: HappySoupStageFlagValues): DeployHappySoupOptions;

package/lib/deploy/stageOptions.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Map a project stage command's parsed flags onto {@link DeployProjectOptions}.
+ *
+ * The kebab-case flag names and camelCase option names are a straight one-to-one rename, and it
+ * was written out identically in every stage command.
+ *
+ * @param stage - The stage this command runs.
+ * @param flags - The command's parsed flags.
+ * @returns The options to hand to `deployProject()`.
+ */
+export function toProjectStageOptions(stage, flags) {
+    return {
+        stage,
+        ciJobToken: flags['ci-job-token'],
+        alias: flags.alias,
+        debug: flags.debug,
+        deployConfigFile: flags['deploy-config-file'],
+        deployProgressFile: flags['deploy-progress-file'],
+        deployRulesFile: flags['deploy-rules-file'],
+        startFrom: flags['start-from'],
+        testLevel: flags['test-level'],
+        testSuite: flags['test-suite'],
+        tests: flags.tests,
+        vcsHost: flags['vcs-host'],
+        vcsProvider: flags['vcs-provider'],
+    };
+}
+/**
+ * Map a happy-soup stage command's parsed flags onto {@link DeployHappySoupOptions}.
+ *
+ * Same shape as {@link toProjectStageOptions}, trading `--test-suite` (which happy-soup stages
+ * don't accept) for `--source-branch-name`.
+ *
+ * @param stage - The stage this command runs.
+ * @param flags - The command's parsed flags.
+ * @returns The options to hand to `deployHappySoup()`.
+ */
+export function toHappySoupStageOptions(stage, flags) {
+    return {
+        stage,
+        ciJobToken: flags['ci-job-token'],
+        alias: flags.alias,
+        debug: flags.debug,
+        deployConfigFile: flags['deploy-config-file'],
+        deployProgressFile: flags['deploy-progress-file'],
+        deployRulesFile: flags['deploy-rules-file'],
+        sourceBranchName: flags['source-branch-name'],
+        startFrom: flags['start-from'],
+        testLevel: flags['test-level'],
+        tests: flags.tests,
+        vcsHost: flags['vcs-host'],
+        vcsProvider: flags['vcs-provider'],
+    };
+}
+//# sourceMappingURL=stageOptions.js.map

package/lib/deploy/stageOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stageOptions.js","sourceRoot":"","sources":["../../src/deploy/stageOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgCH;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,KAA6B;IAChF,OAAO;QACL,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC;QACjC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,gBAAgB,EAAE,KAAK,CAAC,oBAAoB,CAAC;QAC7C,kBAAkB,EAAE,KAAK,CAAC,sBAAsB,CAAC;QACjD,eAAe,EAAE,KAAK,CAAC,mBAAmB,CAAC;QAC3C,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;QAC9B,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;QAC9B,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;QAC9B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC;QAC1B,WAAW,EAAE,KAAK,CAAC,cAAc,CAAC;KACnC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,KAA+B;IACpF,OAAO;QACL,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC;QACjC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,gBAAgB,EAAE,KAAK,CAAC,oBAAoB,CAAC;QAC7C,kBAAkB,EAAE,KAAK,CAAC,sBAAsB,CAAC;QACjD,eAAe,EAAE,KAAK,CAAC,mBAAmB,CAAC;QAC3C,gBAAgB,EAAE,KAAK,CAAC,oBAAoB,CAAC;QAC7C,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;QAC9B,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;QAC9B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC;QAC1B,WAAW,EAAE,KAAK,CAAC,cAAc,CAAC;KACnC,CAAC;AACJ,CAAC"}

package/lib/deploy/validate.d.ts

@@ -0,0 +1,11 @@
+export type ValidateDeployFilesOptions = {
+    deployConfigFile?: string;
+    deployRulesFile?: string;
+    sourceBranchName?: string;
+};
+/**
+ * Validates the deployment config and deployment rules files against their JSON schemas.
+ * Each is validated independently: a missing file is skipped (warned, not fatal), but a malformed
+ * or schema-invalid file throws.
+ */
+export declare function validateDeployFiles(options: ValidateDeployFilesOptions): Promise<void>;

package/lib/deploy/validate.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { logger } from '../logger.js';
+import { deployConfigSchema } from '../schemas/deployConfig.js';
+import { deployRulesSchema } from '../schemas/deployRules.js';
+import { determineDeployConfigFile, loadValidatedJsonFile } from './deployCommon.js';
+async function validateFile(filePath, schema) {
+    try {
+        await loadValidatedJsonFile(filePath, schema);
+        logger.success(`Validation successful for ${filePath}`);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            logger.warn(`Skipping validation for ${filePath} as it was not found.`);
+            return;
+        }
+        logger.error(`Validation failed for ${filePath}: ${error.message}`);
+        throw error;
+    }
+}
+/**
+ * Validates the deployment config and deployment rules files against their JSON schemas.
+ * Each is validated independently: a missing file is skipped (warned, not fatal), but a malformed
+ * or schema-invalid file throws.
+ */
+export async function validateDeployFiles(options) {
+    const resolvedDeployConfigFile = determineDeployConfigFile(options.sourceBranchName, options.deployConfigFile);
+    if (resolvedDeployConfigFile) {
+        await validateFile(resolvedDeployConfigFile, deployConfigSchema);
+    }
+    else {
+        logger.warn('No deployment config file specified or derivable from --source-branch-name. Skipping validation.');
+    }
+    if (options.deployRulesFile) {
+        await validateFile(options.deployRulesFile, deployRulesSchema);
+    }
+    else {
+        logger.warn('No deployment rules file specified. Skipping validation.');
+    }
+}
+//# sourceMappingURL=validate.js.map

package/lib/deploy/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/deploy/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAQrF,KAAK,UAAU,YAAY,CAAI,QAAgB,EAAE,MAAoB;IACnE,IAAI,CAAC;QACH,MAAM,qBAAqB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,CAAC,OAAO,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC,2BAA2B,QAAQ,uBAAuB,CAAC,CAAC;YACxE,OAAO;QACT,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,yBAAyB,QAAQ,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/E,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAmC;IAC3E,MAAM,wBAAwB,GAAG,yBAAyB,CAAC,OAAO,CAAC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE/G,IAAI,wBAAwB,EAAE,CAAC;QAC7B,MAAM,YAAY,CAAC,wBAAwB,EAAE,kBAAkB,CAAC,CAAC;IACnE,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,kGAAkG,CAAC,CAAC;IAClH,CAAC;IAED,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;QAC5B,MAAM,YAAY,CAAC,OAAO,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC;IACjE,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/lib/env.d.ts

@@ -0,0 +1,9 @@
+export type EnvLogger = {
+    info: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+};
+/**
+ * Appends key-value pairs to a .env style file. If the file exists and its content doesn't end
+ * with a newline, a leading newline is added before appending. Creates the file if it doesn't exist.
+ */
+export declare function appendToEnvFile(filePath: string, variables: Record<string, string | undefined>, log?: EnvLogger): void;

package/lib/env.js

@@ -0,0 +1,47 @@
+/*
+ * 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 fs from 'node:fs';
+/**
+ * Appends key-value pairs to a .env style file. If the file exists and its content doesn't end
+ * with a newline, a leading newline is added before appending. Creates the file if it doesn't exist.
+ */
+export function appendToEnvFile(filePath, variables, log) {
+    const targetLogger = log ?? console;
+    const lines = Object.entries(variables)
+        .filter((entry) => entry[1] !== undefined)
+        .map(([key, value]) => `${key}=${value}`);
+    if (lines.length === 0) {
+        return;
+    }
+    const variablesToAppend = lines.join('\n') + '\n';
+    try {
+        let contentToAppend = variablesToAppend;
+        if (fs.existsSync(filePath)) {
+            const currentContent = fs.readFileSync(filePath, 'utf8');
+            if (currentContent && !currentContent.endsWith('\n')) {
+                contentToAppend = `\n${variablesToAppend}`;
+            }
+        }
+        fs.appendFileSync(filePath, contentToAppend, 'utf8');
+        targetLogger.info(`Variables successfully appended to ${filePath}!`);
+    }
+    catch (error) {
+        const err = error;
+        targetLogger.error(`Error appending to ${filePath}: ${err.message}`);
+        throw err;
+    }
+}
+//# sourceMappingURL=env.js.map

package/lib/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,SAA6C,EAC7C,GAAe;IAEf,MAAM,YAAY,GAAG,GAAG,IAAI,OAAO,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;SACpC,MAAM,CAAC,CAAC,KAAK,EAA6B,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;SACpE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC;IAE5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,MAAM,iBAAiB,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAElD,IAAI,CAAC;QACH,IAAI,eAAe,GAAG,iBAAiB,CAAC;QACxC,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,MAAM,cAAc,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACzD,IAAI,cAAc,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrD,eAAe,GAAG,KAAK,iBAAiB,EAAE,CAAC;YAC7C,CAAC;QACH,CAAC;QAED,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;QACrD,YAAY,CAAC,IAAI,CAAC,sCAAsC,QAAQ,GAAG,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAc,CAAC;QAC3B,YAAY,CAAC,KAAK,CAAC,sBAAsB,QAAQ,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACrE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/lib/exec/sfCli.d.ts

@@ -0,0 +1,27 @@
+import { type ExecaChildProcess, type Options } from 'execa';
+/**
+ * Run the Salesforce CLI.
+ *
+ * Everything this package does to an org ultimately shells out to `sf`, and each site was
+ * naming the binary itself. Options are forwarded only when a caller supplies them, so the
+ * underlying `execa()` call keeps the exact arity each site had.
+ *
+ * @param args - Arguments to pass to `sf`.
+ * @param options - Optional `execa` options, e.g. `{ stdio: 'inherit' }` to stream output
+ * straight into the job log.
+ * @returns The completed `execa` result.
+ */
+export declare function runSf(args: string[], options?: Options): ExecaChildProcess;
+/**
+ * Run the Salesforce CLI and parse its `--json` output.
+ *
+ * The caller still passes `--json` in `args` — this doesn't inject it, because which commands
+ * accept it and where it belongs in the argument list varies. What it does replace is the
+ * `JSON.parse(stdout) as SomeShape` written out at each call site.
+ *
+ * @param args - Arguments to pass to `sf`, including `--json`.
+ * @param options - Optional `execa` options.
+ * @returns The parsed payload, typed as the caller asserts.
+ * @throws {SyntaxError} If the command's output isn't valid JSON.
+ */
+export declare function runSfJson<T>(args: string[], options?: Options): Promise<T>;

package/lib/exec/sfCli.js

@@ -0,0 +1,50 @@
+/*
+ * 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';
+/** The `sf` executable, as resolved from `PATH` in the CI job. */
+const SF_BINARY = 'sf';
+/**
+ * Run the Salesforce CLI.
+ *
+ * Everything this package does to an org ultimately shells out to `sf`, and each site was
+ * naming the binary itself. Options are forwarded only when a caller supplies them, so the
+ * underlying `execa()` call keeps the exact arity each site had.
+ *
+ * @param args - Arguments to pass to `sf`.
+ * @param options - Optional `execa` options, e.g. `{ stdio: 'inherit' }` to stream output
+ * straight into the job log.
+ * @returns The completed `execa` result.
+ */
+export function runSf(args, options) {
+    return options ? execa(SF_BINARY, args, options) : execa(SF_BINARY, args);
+}
+/**
+ * Run the Salesforce CLI and parse its `--json` output.
+ *
+ * The caller still passes `--json` in `args` — this doesn't inject it, because which commands
+ * accept it and where it belongs in the argument list varies. What it does replace is the
+ * `JSON.parse(stdout) as SomeShape` written out at each call site.
+ *
+ * @param args - Arguments to pass to `sf`, including `--json`.
+ * @param options - Optional `execa` options.
+ * @returns The parsed payload, typed as the caller asserts.
+ * @throws {SyntaxError} If the command's output isn't valid JSON.
+ */
+export async function runSfJson(args, options) {
+    const { stdout } = await runSf(args, options);
+    return JSON.parse(stdout);
+}
+//# sourceMappingURL=sfCli.js.map

package/lib/exec/sfCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfCli.js","sourceRoot":"","sources":["../../src/exec/sfCli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,OAAO,CAAC;AAEpE,kEAAkE;AAClE,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,IAAc,EAAE,OAAiB;IACrD,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,IAAc,EAAE,OAAiB;IAClE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAE9C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAM,CAAC;AACjC,CAAC"}

package/lib/flags/env.d.ts

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