@simplysf/simply-cicd-core 0.2.2 → 0.4.0

package/lib/schemas/deployRules.js

@@ -0,0 +1,40 @@
+/*
+ * 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 { z } from 'zod';
+export const deployStageSchema = z.enum(['unpackagedDeploy', 'postDeploy', 'preDestructive', 'postDestructive']);
+const deployRuleSchema = z
+    .object({
+    deploymentName: z.string().optional(),
+    deploymentSlug: z.string().optional(),
+    requireStages: z.array(deployStageSchema),
+})
+    .strict()
+    .superRefine((rule, ctx) => {
+    if (rule.deploymentName === undefined && rule.deploymentSlug === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Each rule must specify a "deploymentName" or "deploymentSlug".',
+            path: [],
+        });
+    }
+});
+/** Zod equivalent of the original `deploy-rules.schema.json`. */
+export const deployRulesSchema = z
+    .object({
+    rules: z.array(deployRuleSchema),
+})
+    .strict();
+//# sourceMappingURL=deployRules.js.map

package/lib/schemas/deployRules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployRules.js","sourceRoot":"","sources":["../../src/schemas/deployRules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAEjH,MAAM,gBAAgB,GAAG,CAAC;KACvB,MAAM,CAAC;IACN,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC;CAC1C,CAAC;KACD,MAAM,EAAE;KACR,WAAW,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;IACzB,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QAC3E,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,OAAO,EAAE,gEAAgE;YACzE,IAAI,EAAE,EAAE;SACT,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,iEAAiE;AACjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;CACjC,CAAC;KACD,MAAM,EAAE,CAAC"}

package/lib/sfApex.d.ts

@@ -0,0 +1,22 @@
+export type HasApexTestsOptions = {
+    debugMode?: boolean;
+};
+export type RunApexTestsOptions = {
+    alias?: string;
+    testLevel?: string;
+    testSuite?: string;
+    wait?: string;
+    debugMode?: boolean;
+};
+/**
+ * Checks if there are any Apex test classes defined in the package directories, by reading
+ * `sfdx-project.json` to identify the package directories and searching each recursively
+ * (case-insensitively) for `@isTest` in `.cls` files.
+ */
+export declare function hasApexTests(options?: HasApexTestsOptions): Promise<boolean>;
+/**
+ * Runs Apex tests in the specified target Salesforce organization. First checks that any Apex
+ * tests exist before initiating the run. Test results are written to `./test-results/apex` in
+ * JUnit and JSON formats. If tests fail, a detailed failure report is printed and this throws.
+ */
+export declare function runApexTests(options: RunApexTestsOptions): Promise<void>;

package/lib/sfApex.js

@@ -0,0 +1,169 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { readSfdxProject } from '@simplysf/simply-core';
+import { runSf } from './exec/sfCli.js';
+import { logger } from './logger.js';
+/**
+ * Checks if there are any Apex test classes defined in the package directories, by reading
+ * `sfdx-project.json` to identify the package directories and searching each recursively
+ * (case-insensitively) for `@isTest` in `.cls` files.
+ */
+export async function hasApexTests(options) {
+    let packageDirs = ['force-app'];
+    try {
+        const sfdxProjectJson = await readSfdxProject();
+        packageDirs = sfdxProjectJson.packageDirectories.map((d) => d.path).filter((p) => Boolean(p));
+    }
+    catch {
+        if (options?.debugMode) {
+            logger.warn('Could not read sfdx-project.json to identify package directories. Using default force-app.');
+        }
+    }
+    for (const dir of packageDirs) {
+        try {
+            // eslint-disable-next-line no-await-in-loop -- stops at the first directory with a match
+            await execa('grep', ['-q', '-r', '-i', '--include=*.cls', '@isTest\\b', dir]);
+            return true;
+        }
+        catch (error) {
+            if (options?.debugMode) {
+                const err = error;
+                logger.log(`No Apex tests found in ${dir} or an error occurred during search.`, err.shortMessage);
+            }
+        }
+    }
+    return false;
+}
+/** Kicks off the `sf apex test run`, swallowing any failure so the run's artifacts (namely the
+ * test run ID file) can still be inspected afterward to distinguish an execution failure from a
+ * genuine test failure. */
+async function executeTestRun(args) {
+    try {
+        await runSf(args, { stdio: 'pipe' });
+        return undefined;
+    }
+    catch (e) {
+        return e;
+    }
+}
+/** Reads the test run ID that `sf apex test run` writes out. If that fails, prefers surfacing
+ * the run's own execution error (if any) since a missing ID file is usually just a symptom of it. */
+async function resolveTestRunId(testRunIdFile, execError) {
+    try {
+        return (await fs.readFile(testRunIdFile, 'utf-8')).trim();
+    }
+    catch (readIdError) {
+        if (execError) {
+            logger.error('Apex test run failed.', execError.shortMessage);
+            throw execError;
+        }
+        logger.error(`Failed to read test run ID from ${testRunIdFile}.`, readIdError.message);
+        throw readIdError;
+    }
+}
+function reportFailingTests(failingTests) {
+    logger.raw('\n' + '='.repeat(80));
+    logger.raw(`❌ APEX TEST FAILURE REPORT (${failingTests.length} failures found)`);
+    logger.raw('='.repeat(80));
+    failingTests.forEach((t, index) => {
+        logger.raw(`\n[${index + 1}/${failingTests.length}] ❌ ${t.FullName ?? 'Unknown test'}`);
+        logger.raw(`    Message:     ${t.Message ? t.Message.trim().replace(/\n/g, '\n                 ') : 'N/A'}`);
+        if (t.StackTrace) {
+            logger.raw(`    Stack Trace: ${t.StackTrace.trim().replace(/\n/g, '\n                 ')}`);
+        }
+        logger.raw('-'.repeat(80));
+    });
+    logger.raw();
+}
+/** Reads and reports on the JUnit/JSON result file for a completed test run, returning the run's
+ * outcome. A read/parse failure here prefers surfacing the run's own execution error (if any). */
+async function processTestResults(resultFilePath, execError) {
+    try {
+        const resultsContent = await fs.readFile(resultFilePath, 'utf-8');
+        const results = JSON.parse(resultsContent);
+        const testRunOutcome = results.summary?.outcome;
+        if (testRunOutcome !== 'Failed') {
+            logger.success('Apex tests completed successfully.');
+            return testRunOutcome;
+        }
+        logger.error('Apex test run failed.');
+        const failingTests = results.tests ? results.tests.filter((t) => t.Outcome === 'Fail') : [];
+        if (failingTests.length > 0) {
+            reportFailingTests(failingTests);
+        }
+        else {
+            logger.warn('Test run was marked as failed, but no individual test failures were found. This could indicate a compile error or issue.');
+        }
+        return testRunOutcome;
+    }
+    catch (fileError) {
+        logger.error(`Failed to read or parse test result file at ${resultFilePath}.`, fileError.message);
+        if (execError) {
+            throw execError;
+        }
+        throw fileError;
+    }
+}
+/**
+ * Runs Apex tests in the specified target Salesforce organization. First checks that any Apex
+ * tests exist before initiating the run. Test results are written to `./test-results/apex` in
+ * JUnit and JSON formats. If tests fail, a detailed failure report is printed and this throws.
+ */
+export async function runApexTests(options) {
+    const { alias, testLevel = 'RunLocalTests', testSuite, wait = '60' } = options;
+    if (!(await hasApexTests(options))) {
+        logger.warn('No Apex test classes found. Skipping Apex tests.');
+        return;
+    }
+    logger.info('Running Apex tests...');
+    const testResultsDir = './test-results/apex';
+    await fs.mkdir(testResultsDir, { recursive: true });
+    const args = [
+        'apex',
+        'test',
+        'run',
+        '--code-coverage',
+        '--result-format',
+        'junit',
+        '--output-dir',
+        testResultsDir,
+        '--wait',
+        wait,
+    ];
+    if (alias) {
+        args.push('--target-org', alias);
+    }
+    if (testSuite) {
+        args.push('--suite-names', testSuite);
+    }
+    else {
+        args.push('--test-level', testLevel);
+    }
+    const execError = await executeTestRun(args);
+    const testRunId = await resolveTestRunId(path.join(testResultsDir, 'test-run-id.txt'), execError);
+    let testRunOutcome;
+    if (testRunId) {
+        const resultFilePath = path.join(testResultsDir, `test-result-${testRunId}.json`);
+        testRunOutcome = await processTestResults(resultFilePath, execError);
+    }
+    if (testRunOutcome === 'Failed') {
+        throw new Error('Apex test run included failures.');
+    }
+}
+//# sourceMappingURL=sfApex.js.map

package/lib/sfApex.js.map

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

package/lib/sfAuth.d.ts

@@ -0,0 +1,19 @@
+export type AuthenticateOrgOptions = {
+    alias?: string;
+    authUrl?: string;
+    clientId?: string;
+    instanceUrl?: string;
+    jwtKeyFile?: string;
+    username?: string;
+    setDefault?: boolean;
+    setDefaultDevHub?: boolean;
+    debug?: boolean;
+};
+export type AuthenticateOrgResult = {
+    success: boolean;
+    username?: string;
+    result?: unknown;
+    message?: string;
+};
+/** Authenticates to a Salesforce organization using either a JWT flow or an SFDX auth URL. */
+export declare function authenticateOrg(options: AuthenticateOrgOptions): Promise<AuthenticateOrgResult>;

package/lib/sfAuth.js

@@ -0,0 +1,78 @@
+/*
+ * 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 { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runSf } from './exec/sfCli.js';
+import { logger } from './logger.js';
+/** Authenticates to a Salesforce organization using either a JWT flow or an SFDX auth URL. */
+export async function authenticateOrg(options) {
+    const { alias, authUrl, clientId, instanceUrl, jwtKeyFile, username, setDefault, setDefaultDevHub, debug } = options;
+    const authEntity = alias ?? username ?? 'unknown org';
+    logger.info(`Authenticating to org: ${authEntity}`);
+    try {
+        let authArgs;
+        if (authUrl) {
+            const tempDir = await mkdtemp(join(tmpdir(), 'sfdx-auth-'));
+            const authUrlFile = join(tempDir, 'auth-url.txt');
+            await writeFile(authUrlFile, authUrl);
+            authArgs = ['org', 'login', 'sfdx-url', '--sfdx-url-file', authUrlFile, '--json'];
+        }
+        else {
+            authArgs = [
+                'login',
+                'org',
+                'jwt',
+                '--username',
+                username ?? '',
+                '--jwt-key-file',
+                jwtKeyFile ?? '',
+                '--client-id',
+                clientId ?? '',
+                '--instance-url',
+                instanceUrl ?? '',
+                '--json',
+            ];
+        }
+        if (alias) {
+            authArgs.push('--alias', alias);
+        }
+        if (setDefault) {
+            authArgs.push('--set-default');
+        }
+        if (setDefaultDevHub) {
+            authArgs.push('--set-default-dev-hub');
+        }
+        const { stdout } = await runSf(authArgs);
+        if (debug) {
+            logger.raw(stdout);
+        }
+        const authResult = JSON.parse(stdout);
+        if (authResult.status > 0) {
+            logger.error(`Authentication failed for ${authEntity}: ${authResult.message ?? 'unknown error'}`);
+            // In cleanup, we don't want to exit the whole process.
+            return { success: false, message: authResult.message, username };
+        }
+        logger.success(`Successfully authenticated to org: ${authEntity}`);
+        return { success: true, username, result: authResult.result };
+    }
+    catch (error) {
+        logger.error(`Authentication failed for ${authEntity}`);
+        logger.error(String(error));
+        throw error; // Re-throw for build steps that should fail hard.
+    }
+}
+//# sourceMappingURL=sfAuth.js.map

package/lib/sfAuth.js.map

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

package/lib/sfConfig.d.ts

@@ -0,0 +1,23 @@
+import type { VcsProviderKind } from './vcs/index.js';
+/** Where a packaged dependency's source lives, for happy-soup story lookups. */
+export type PackageOriginOverride = {
+    vcsProvider: VcsProviderKind;
+    host?: string;
+    projectPath: string;
+};
+/**
+ * Retrieves ALM project keys from the `.sfdevrc.json` configuration file, or falls back to a
+ * provided default. Reads a single or multiple project keys from the configuration, deduplicates
+ * them, and filters out empty values.
+ *
+ * The legacy `jiraProjectKey`/`jiraProjectKeys` fields are still honored, so existing repositories
+ * keep working, but `almProjectKey`/`almProjectKeys` win outright when present — the two sets are
+ * not merged, so a repository migrating one key at a time gets the new value rather than a blend.
+ */
+export declare function getAlmProjectKeys(passedProjectKey?: string): string[];
+/**
+ * Looks up an explicit VCS project override for a package name from `.sfdevrc.json`'s
+ * `packageOriginOverrides`. Returns `undefined` if the file, the field, or an entry for this
+ * package doesn't exist.
+ */
+export declare function getPackageOriginOverride(packageName: string): PackageOriginOverride | undefined;

package/lib/sfConfig.js

@@ -0,0 +1,82 @@
+/*
+ * 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';
+import { logger } from './logger.js';
+/** Reads and parses `.sfdevrc.json`, or returns `undefined` if it's missing or invalid. */
+function readSfDevRcConfig() {
+    try {
+        if (!fs.existsSync('.sfdevrc.json')) {
+            return undefined;
+        }
+        return JSON.parse(fs.readFileSync('.sfdevrc.json', 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Collects a single-key and multi-key field into one deduplicated, non-empty list. */
+function collectKeys(single, multiple) {
+    const keys = [];
+    if (single) {
+        keys.push(single);
+    }
+    if (Array.isArray(multiple)) {
+        keys.push(...multiple);
+    }
+    return [...new Set(keys.filter(Boolean))];
+}
+/**
+ * Retrieves ALM project keys from the `.sfdevrc.json` configuration file, or falls back to a
+ * provided default. Reads a single or multiple project keys from the configuration, deduplicates
+ * them, and filters out empty values.
+ *
+ * The legacy `jiraProjectKey`/`jiraProjectKeys` fields are still honored, so existing repositories
+ * keep working, but `almProjectKey`/`almProjectKeys` win outright when present — the two sets are
+ * not merged, so a repository migrating one key at a time gets the new value rather than a blend.
+ */
+export function getAlmProjectKeys(passedProjectKey) {
+    let projectKeys = [];
+    try {
+        if (fs.existsSync('.sfdevrc.json')) {
+            const content = fs.readFileSync('.sfdevrc.json', 'utf8');
+            const config = JSON.parse(content);
+            projectKeys = collectKeys(config.almProjectKey, config.almProjectKeys);
+            if (projectKeys.length === 0) {
+                const legacyKeys = collectKeys(config.jiraProjectKey, config.jiraProjectKeys);
+                if (legacyKeys.length > 0) {
+                    logger.warn('The .sfdevrc.json fields "jiraProjectKey" and "jiraProjectKeys" are deprecated. Rename them to "almProjectKey" and "almProjectKeys"; the old names will be removed in a future release.');
+                    projectKeys = legacyKeys;
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore and fall back to the passed command-line project key.
+    }
+    if (projectKeys.length > 0) {
+        return projectKeys;
+    }
+    return passedProjectKey ? [passedProjectKey] : [];
+}
+/**
+ * Looks up an explicit VCS project override for a package name from `.sfdevrc.json`'s
+ * `packageOriginOverrides`. Returns `undefined` if the file, the field, or an entry for this
+ * package doesn't exist.
+ */
+export function getPackageOriginOverride(packageName) {
+    return readSfDevRcConfig()?.packageOriginOverrides?.[packageName];
+}
+//# sourceMappingURL=sfConfig.js.map

package/lib/sfConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfConfig.js","sourceRoot":"","sources":["../src/sfConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAwBrC,2FAA2F;AAC3F,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;YACpC,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAkB,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,SAAS,WAAW,CAAC,MAA0B,EAAE,QAA8B;IAC7E,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,gBAAyB;IACzD,IAAI,WAAW,GAAa,EAAE,CAAC;IAC/B,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;YACzD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAC;YAEpD,WAAW,GAAG,WAAW,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;YAEvE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC7B,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;gBAC9E,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CACT,yLAAyL,CAC1L,CAAC;oBACF,WAAW,GAAG,UAAU,CAAC;gBAC3B,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,OAAO,iBAAiB,EAAE,EAAE,sBAAsB,EAAE,CAAC,WAAW,CAAC,CAAC;AACpE,CAAC"}

package/lib/sfOrg.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The org's instance URL, e.g. `https://my-domain.my.salesforce.com`.
+ *
+ * @param aliasOrUsername - The org to look up. Omit (or pass `''`) to use the default target org.
+ */
+export declare function getOrgInstanceUrl(aliasOrUsername?: string): Promise<string>;
+/**
+ * How many more scratch orgs the Dev Hub may create today (its `DailyScratchOrgs` limit), or
+ * `undefined` when the org doesn't report that limit.
+ *
+ * @param hubAliasOrUsername - The Dev Hub. Must already be authenticated.
+ */
+export declare function getRemainingDailyScratchOrgs(hubAliasOrUsername: string): Promise<number | undefined>;

package/lib/sfOrg.js

@@ -0,0 +1,39 @@
+/*
+ * 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 { Org } from '@salesforce/core';
+/**
+ * The org's instance URL, e.g. `https://my-domain.my.salesforce.com`.
+ *
+ * @param aliasOrUsername - The org to look up. Omit (or pass `''`) to use the default target org.
+ */
+export async function getOrgInstanceUrl(aliasOrUsername) {
+    // Callers pass '' for "no --alias given", which `sf org display --target-org ''` treated as the
+    // default target org; Org.create only does that for undefined.
+    const org = await Org.create({ aliasOrUsername: aliasOrUsername === '' ? undefined : aliasOrUsername });
+    return org.getConnection().instanceUrl;
+}
+/**
+ * How many more scratch orgs the Dev Hub may create today (its `DailyScratchOrgs` limit), or
+ * `undefined` when the org doesn't report that limit.
+ *
+ * @param hubAliasOrUsername - The Dev Hub. Must already be authenticated.
+ */
+export async function getRemainingDailyScratchOrgs(hubAliasOrUsername) {
+    const org = await Org.create({ aliasOrUsername: hubAliasOrUsername });
+    const limits = (await org.getConnection().limits());
+    return limits.DailyScratchOrgs?.Remaining;
+}
+//# sourceMappingURL=sfOrg.js.map

package/lib/sfOrg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfOrg.js","sourceRoot":"","sources":["../src/sfOrg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,eAAwB;IAC9D,gGAAgG;IAChG,+DAA+D;IAC/D,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,eAAe,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;IACxG,OAAO,GAAG,CAAC,aAAa,EAAE,CAAC,WAAW,CAAC;AACzC,CAAC;AAID;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,kBAA0B;IAC3E,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,CAAyB,CAAC;IAC5E,OAAO,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC;AAC5C,CAAC"}

package/lib/sfPackages.d.ts

@@ -0,0 +1,63 @@
+import { type PackageInstallType, type PackageInstallUpgradeType, type PackageToInstall } from '@simplysf/simply-package-core';
+import { type PackageVersionReportResult } from '@salesforce/packaging';
+import type { UpgradedPackage } from './schemas/deployProgress.js';
+export type { PackageInstallUpgradeType, PackageToInstall };
+export type InstallPackageDependenciesConfig = {
+    /** Alias or username of the target org. Omit to use the default target org. */
+    alias?: string;
+    /** Minutes to wait for each package install to complete. */
+    wait?: string;
+    installType?: PackageInstallType;
+    /** What happens to components an unlocked package upgrade removes. */
+    upgradeType?: PackageInstallUpgradeType;
+};
+export type { PackageVersionReportResult };
+/**
+ * Installs the Salesforce package dependencies defined in `sfdx-project.json` into the target org,
+ * in-process via `@simplysf/simply-package-core`. The org must already be authenticated; every
+ * confirmation is auto-approved, as befits a pipeline.
+ *
+ * @returns The install outcome for every resolved dependency, including the ones skipped.
+ */
+export declare function installPackageDependencies(config?: InstallPackageDependenciesConfig): Promise<PackageToInstall[]>;
+export type ResolveUpgradedPackagesConfig = {
+    /** The packaging DevHub's alias. Must already be authenticated. */
+    packagingDevhub?: string;
+};
+/**
+ * The Dev Hub's report for one package version: what `sf package version report --json` returns,
+ * including the computed `Version` (`major.minor.patch.build`), `Tag`, `Description` and
+ * `CodeCoverage`.
+ *
+ * Unlike the CLI, `CodeCoverage` is `null` (not `'N/A'`) for a version that skipped validation or
+ * belongs to an org-dependent package.
+ *
+ * @param packageVersionId - A `04t` subscriber package version ID (or `05i` package version ID).
+ * @param devHubAliasOrUsername - The Dev Hub that owns the package. Must already be authenticated.
+ * @throws {SfError} If the Dev Hub can't be resolved or the version doesn't exist.
+ */
+export declare function getPackageVersionReport(packageVersionId: string, devHubAliasOrUsername: string): Promise<PackageVersionReportResult>;
+/** One row of {@link listInstalledPackages}: the fields `sf package installed list --json` returns. */
+export type InstalledPackage = {
+    Id: string;
+    SubscriberPackageId: string;
+    SubscriberPackageName?: string;
+    SubscriberPackageNamespace?: string;
+    SubscriberPackageVersionId?: string;
+    SubscriberPackageVersionName?: string;
+    /** `major.minor.patch.build`. */
+    SubscriberPackageVersionNumber?: string;
+};
+/**
+ * The packages installed in an org, shaped like `sf package installed list --json`'s result rows.
+ *
+ * @param aliasOrUsername - The org to inspect. Must already be authenticated.
+ */
+export declare function listInstalledPackages(aliasOrUsername: string): Promise<InstalledPackage[]>;
+/**
+ * For every package an {@link installPackageDependencies} run upgraded, fetches the previous and
+ * target version's `sf package version report` (for the origin commit SHA and pipeline URL). A
+ * package whose version report can't be resolved is skipped with a warning rather than failing the
+ * whole deployment — this data only feeds a later notification.
+ */
+export declare function resolveUpgradedPackages(installResults: PackageToInstall[], config: ResolveUpgradedPackagesConfig): Promise<UpgradedPackage[]>;