@simplysf/simply-cicd-core 0.11.0 → 0.12.0

package/README.md

@@ -59,7 +59,7 @@ The modules `@simplysf/simply-cicd`'s commands run, also exported from the packa
 
 | Area                                  | Main exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Build                                 | `createScratchOrg`, `deleteScratchOrg`, `cleanupScratchOrgs`, `pushToScratch`, `runScratchApexTests`, `installDependencies`, `createPackageVersion`, `createFallbackTag`, `determinePackageChanges`, `runLwcJest`, `runCheckPermissionSets`, `runFlowDelta`, `runFlexipageDelta`, `publishUtamPageObjects`, `VersionTagFormat`                                                                                                                                                                                                                       |
+| Build                                 | `createScratchOrg`, `deleteScratchOrg`, `cleanupScratchOrgs`, `pushToScratch`, `runScratchApexTests`, `installDependencies`, `createPackageVersion`, `createFallbackTag`, `determinePackageChanges`, `runLwcJest`, `runCheckPermissionSets`, `runFlowDelta`, `runFlexipageDelta`, `publishUtamPageObjects`, `publishAerPackage`, `VersionTagFormat`                                                                                                                                                                                                  |
 | Deploy                                | `deployProject`, `deployHappySoup`, `runDeployStage`, `validateDeployFiles`, `toProjectStageOptions`, `toHappySoupStageOptions`, plus the `deployCommon` helpers (`runDeploymentSteps`, `loadProgress`, `updateProgress`, `installDeployPackageDependencies`, `runDeployApexTests`, …)                                                                                                                                                                                                                                                               |
 | Notify                                | `sendBuildNotification`, `projectNotifyBeforeScript`/`projectNotifyAfterScript`, `happySoupNotifyBeforeScript`/`happySoupNotifyAfterScript`, `getCommitStories`, `getRemoteCommitStories`, `sendNotification`, `renderNotifyTemplate`, `NOTIFY_TEMPLATES`                                                                                                                                                                                                                                                                                            |
 | sfdx-dependabot                       | `discoverEligibleProjects`, `processProject`, `applyProjectUpdate`, `updateSfdxProject`                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

package/lib/build/aerBinary.d.ts

@@ -0,0 +1,30 @@
+export type ResolveAerBinaryOptions = {
+    /** `--aer-path`. Must exist when given. */
+    aerPath?: string;
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** Defaults to `os.homedir()`. */
+    homeDir?: string;
+};
+/**
+ * Where `@octoberswimmer/aer-sf-plugin` keeps the aer binary it downloads. Mirrors the plugin's own
+ * `defaultStorageDir`, so a job that already ran `sf aer apex run test --install-aer` is covered.
+ */
+export declare function aerPluginBinaryPath(env: NodeJS.ProcessEnv, platform: NodeJS.Platform, homeDir: string): string;
+/**
+ * Find the aer binary, in the order `@octoberswimmer/aer-sf-plugin` uses: `--aer-path`, then
+ * `AER_BIN`, then the plugin's download cache, then `aer` on `PATH`.
+ *
+ * Unlike the plugin, this never downloads aer. The plugin always takes the latest release, which
+ * would let the published package format change under a pipeline with no change to the pipeline.
+ *
+ * @throws {Error} If `--aer-path` doesn't exist, or no aer binary is found anywhere.
+ */
+export declare function resolveAerBinary(options?: ResolveAerBinaryOptions): Promise<string>;
+/**
+ * @returns The version `aer --version` reports, e.g. `v1.4.45`, or `undefined` if it reports
+ * nothing recognisable. Only used for the log and the result, so it never fails the run.
+ */
+export declare function readAerVersion(aerBinary: string): Promise<string | undefined>;

package/lib/build/aerBinary.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 { constants, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import { logger } from '../logger.js';
+/** Where aer's releases are published, for the not-found hint. */
+const AER_DIST_REPO = 'https://github.com/octoberswimmer/aer-dist';
+async function isExecutable(file) {
+    try {
+        const stat = await fs.stat(file);
+        if (!stat.isFile()) {
+            return false;
+        }
+        // Windows has no execute bit; existence is the best available check there.
+        await fs.access(file, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `@octoberswimmer/aer-sf-plugin` keeps the aer binary it downloads. Mirrors the plugin's own
+ * `defaultStorageDir`, so a job that already ran `sf aer apex run test --install-aer` is covered.
+ */
+export function aerPluginBinaryPath(env, platform, homeDir) {
+    const binary = platform === 'win32' ? 'aer.exe' : 'aer';
+    let dataDir = env.XDG_DATA_HOME ?? path.join(homeDir, '.local', 'share');
+    if (platform === 'win32') {
+        dataDir = env.LOCALAPPDATA ?? path.join(homeDir, 'AppData', 'Local');
+    }
+    else if (platform === 'darwin') {
+        dataDir = path.join(homeDir, 'Library', 'Application Support');
+    }
+    return path.join(dataDir, 'aer-sf-plugin', 'aer-bin', binary);
+}
+async function findOnPath(env, platform) {
+    const pathValue = env.PATH ?? env.Path ?? '';
+    const names = platform === 'win32' ? ['aer.exe', 'aer'] : ['aer'];
+    for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            // eslint-disable-next-line no-await-in-loop -- first match wins, so the search is sequential
+            if (await isExecutable(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Find the aer binary, in the order `@octoberswimmer/aer-sf-plugin` uses: `--aer-path`, then
+ * `AER_BIN`, then the plugin's download cache, then `aer` on `PATH`.
+ *
+ * Unlike the plugin, this never downloads aer. The plugin always takes the latest release, which
+ * would let the published package format change under a pipeline with no change to the pipeline.
+ *
+ * @throws {Error} If `--aer-path` doesn't exist, or no aer binary is found anywhere.
+ */
+export async function resolveAerBinary(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? os.homedir();
+    if (options.aerPath) {
+        if (await isExecutable(options.aerPath)) {
+            return options.aerPath;
+        }
+        throw new Error(`--aer-path is set to "${options.aerPath}", but no executable file is there.`);
+    }
+    if (env.AER_BIN) {
+        if (await isExecutable(env.AER_BIN)) {
+            return env.AER_BIN;
+        }
+        logger.warn(`AER_BIN is set to "${env.AER_BIN}", but no executable file is there. Looking elsewhere.`);
+    }
+    const pluginBinary = aerPluginBinaryPath(env, platform, homeDir);
+    if (await isExecutable(pluginBinary)) {
+        return pluginBinary;
+    }
+    const fromPath = await findOnPath(env, platform);
+    if (fromPath) {
+        return fromPath;
+    }
+    throw new Error(`Could not find the aer binary. Install a pinned release from ${AER_DIST_REPO} and set AER_BIN (or --aer-path) to it, or put aer on PATH.`);
+}
+/**
+ * @returns The version `aer --version` reports, e.g. `v1.4.45`, or `undefined` if it reports
+ * nothing recognisable. Only used for the log and the result, so it never fails the run.
+ */
+export async function readAerVersion(aerBinary) {
+    try {
+        const { stdout } = await execa(aerBinary, ['--version'], { env: { AER_AUTOUPDATE_DISABLED: '1' } });
+        return /v?\d+\.\d+\.\d+\S*/.exec(stdout)?.[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=aerBinary.js.map

package/lib/build/aerBinary.js.map

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

package/lib/build/aerPackage.d.ts

@@ -0,0 +1,64 @@
+import { type SfdxProject } from '@simplysf/simply-core';
+/** The dotenv keys this feature writes, for a downstream job or a consuming repo to fetch by. */
+export declare const AER_PACKAGE_URL_KEY = "AER_PACKAGE_URL";
+export declare const AER_PACKAGE_FILE_KEY = "AER_PACKAGE_FILE";
+export declare const AER_PACKAGE_VERSION_KEY = "AER_PACKAGE_VERSION";
+/** The placeholders a repository URL template may use. */
+export declare const REPOSITORY_URL_PLACEHOLDERS: readonly ["name", "version", "versionNumber", "channel", "namespace", "file"];
+export type RepositoryUrlPlaceholder = (typeof REPOSITORY_URL_PLACEHOLDERS)[number];
+export type RepositoryUrlValues = Record<RepositoryUrlPlaceholder, string>;
+/** `plugins.simply.aer` in `sfdx-project.json`. Every field is optional. */
+export type AerPluginConfig = {
+    /** URL template the `.pkg` is uploaded to and dependencies are downloaded from. */
+    repositoryUrl?: string;
+};
+/** @returns `plugins.simply.aer`, or an empty object when the project declares none. */
+export declare function readAerPluginConfig(project: SfdxProject): AerPluginConfig;
+/**
+ * Reduce a package name or namespace to something aer accepts in a package file name: letters,
+ * digits and underscores, starting with a letter.
+ *
+ * Each run of anything else becomes one underscore, and a name that doesn't start with a letter is
+ * prefixed with `P`. The rule is fixed rather than configurable because a dependent repo has to
+ * compute the same file name to download the package.
+ *
+ * @throws {Error} If nothing usable is left, e.g. for a name made only of punctuation.
+ */
+export declare function toAerIdentifier(raw: string): string;
+/**
+ * The file name an aer package is published and loaded under, `<package>@<namespace>.pkg`.
+ *
+ * A package with no namespace uses its own name as the namespace, since aer requires one.
+ */
+export declare function toAerPackageFile(packageName: string, namespacePrefix: string | null | undefined): {
+    file: string;
+    name: string;
+    namespace: string;
+};
+/**
+ * Fill in a repository URL template.
+ *
+ * Every value is URL-encoded, so `@` in the file name becomes `%40` and `/` in a branch can't add a
+ * path segment. Anything in braces that isn't a known placeholder fails, which also catches a CI
+ * variable such as `${CI_API_V4_URL}` that the shell didn't expand.
+ *
+ * @throws {Error} If the template uses an unknown placeholder, or uses neither `{version}` nor
+ * `{versionNumber}` — every version would then be uploaded to the same URL.
+ */
+export declare function renderRepositoryUrl(template: string, values: RepositoryUrlValues): string;
+/**
+ * Split a `Name: value` header, e.g. `Authorization: Bearer abc`, into its two parts.
+ *
+ * @throws {Error} If there's no colon, the name isn't a valid header name, or the value is empty.
+ * The message never includes the value, which is usually a secret.
+ */
+export declare function parseRepositoryHeader(raw: string): {
+    name: string;
+    value: string;
+};
+/**
+ * Whether there's any Apex under `rootDir` for aer to compile.
+ *
+ * @returns `false` when `rootDir` doesn't exist — a metadata-only package is a skip, not an error.
+ */
+export declare function hasApexSources(rootDir: string): Promise<boolean>;

package/lib/build/aerPackage.js

@@ -0,0 +1,126 @@
+/*
+ * 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 { getPluginConfig } from '@simplysf/simply-core';
+/** The dotenv keys this feature writes, for a downstream job or a consuming repo to fetch by. */
+export const AER_PACKAGE_URL_KEY = 'AER_PACKAGE_URL';
+export const AER_PACKAGE_FILE_KEY = 'AER_PACKAGE_FILE';
+export const AER_PACKAGE_VERSION_KEY = 'AER_PACKAGE_VERSION';
+/**
+ * What aer accepts as each half of a package file name, `<package>@<namespace>.pkg`. aer reads a
+ * package's namespace from its file name and rejects anything else.
+ */
+const AER_IDENTIFIER_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+/** The placeholders a repository URL template may use. */
+export const REPOSITORY_URL_PLACEHOLDERS = [
+    'name',
+    'version',
+    'versionNumber',
+    'channel',
+    'namespace',
+    'file',
+];
+/** @returns `plugins.simply.aer`, or an empty object when the project declares none. */
+export function readAerPluginConfig(project) {
+    return getPluginConfig(project, 'plugins.simply.aer') ?? {};
+}
+/**
+ * Reduce a package name or namespace to something aer accepts in a package file name: letters,
+ * digits and underscores, starting with a letter.
+ *
+ * Each run of anything else becomes one underscore, and a name that doesn't start with a letter is
+ * prefixed with `P`. The rule is fixed rather than configurable because a dependent repo has to
+ * compute the same file name to download the package.
+ *
+ * @throws {Error} If nothing usable is left, e.g. for a name made only of punctuation.
+ */
+export function toAerIdentifier(raw) {
+    const cleaned = raw.trim().replace(/[^A-Za-z0-9_]+/g, '_');
+    const identifier = /^[A-Za-z]/.test(cleaned) ? cleaned : `P${cleaned}`;
+    if (!/[A-Za-z0-9]/.test(cleaned) || !AER_IDENTIFIER_PATTERN.test(identifier)) {
+        throw new Error(`Cannot derive an aer package name from "${raw}": aer needs a name that starts with a letter and contains only letters, digits and underscores.`);
+    }
+    return identifier;
+}
+/**
+ * The file name an aer package is published and loaded under, `<package>@<namespace>.pkg`.
+ *
+ * A package with no namespace uses its own name as the namespace, since aer requires one.
+ */
+export function toAerPackageFile(packageName, namespacePrefix) {
+    const name = toAerIdentifier(packageName);
+    const namespace = namespacePrefix ? toAerIdentifier(namespacePrefix) : name;
+    return { file: `${name}@${namespace}.pkg`, name, namespace };
+}
+/**
+ * Fill in a repository URL template.
+ *
+ * Every value is URL-encoded, so `@` in the file name becomes `%40` and `/` in a branch can't add a
+ * path segment. Anything in braces that isn't a known placeholder fails, which also catches a CI
+ * variable such as `${CI_API_V4_URL}` that the shell didn't expand.
+ *
+ * @throws {Error} If the template uses an unknown placeholder, or uses neither `{version}` nor
+ * `{versionNumber}` — every version would then be uploaded to the same URL.
+ */
+export function renderRepositoryUrl(template, values) {
+    const used = new Set();
+    const rendered = template.replace(/\{([^{}]*)\}/g, (match, key) => {
+        if (!REPOSITORY_URL_PLACEHOLDERS.includes(key)) {
+            throw new Error(`Unknown placeholder ${match} in the aer repository URL. Use any of: ${REPOSITORY_URL_PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}.`);
+        }
+        used.add(key);
+        return encodeURIComponent(values[key]);
+    });
+    if (!used.has('version') && !used.has('versionNumber')) {
+        throw new Error('The aer repository URL must include {version} or {versionNumber}, or every package version would be uploaded to the same URL.');
+    }
+    return rendered;
+}
+/**
+ * Split a `Name: value` header, e.g. `Authorization: Bearer abc`, into its two parts.
+ *
+ * @throws {Error} If there's no colon, the name isn't a valid header name, or the value is empty.
+ * The message never includes the value, which is usually a secret.
+ */
+export function parseRepositoryHeader(raw) {
+    const separator = raw.indexOf(':');
+    const name = separator === -1 ? '' : raw.slice(0, separator).trim();
+    const value = separator === -1 ? '' : raw.slice(separator + 1).trim();
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || value.length === 0) {
+        throw new Error('The aer repository header must look like "Name: value", e.g. "Authorization: Bearer <token>".');
+    }
+    return { name, value };
+}
+/**
+ * Whether there's any Apex under `rootDir` for aer to compile.
+ *
+ * @returns `false` when `rootDir` doesn't exist — a metadata-only package is a skip, not an error.
+ */
+export async function hasApexSources(rootDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(rootDir, { recursive: true, withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+    return entries.some((entry) => entry.isFile() && ['.cls', '.trigger'].includes(path.extname(entry.name)));
+}
+//# sourceMappingURL=aerPackage.js.map

package/lib/build/aerPackage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aerPackage.js","sourceRoot":"","sources":["../../src/build/aerPackage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAoB,MAAM,uBAAuB,CAAC;AAE1E,iGAAiG;AACjG,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AACvD,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D;;;GAGG;AACH,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAEzD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,MAAM;IACN,SAAS;IACT,eAAe;IACf,SAAS;IACT,WAAW;IACX,MAAM;CACE,CAAC;AAYX,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,OAAoB;IACtD,OAAO,eAAe,CAAkB,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC3D,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IAEvE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,KAAK,CACb,2CAA2C,GAAG,kGAAkG,CACjJ,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAAmB,EACnB,eAA0C;IAM1C,MAAM,IAAI,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE5E,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC/D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,MAA2B;IAC/E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE;QACxE,IAAI,CAAE,2BAAiD,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,KAAK,CACb,uBAAuB,KAAK,2CAA2C,2BAA2B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACtI,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,kBAAkB,CAAC,MAAM,CAAC,GAA+B,CAAC,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,+HAA+H,CAChI,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;IACpE,MAAM,KAAK,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEtE,IAAI,CAAC,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,+FAA+F,CAAC,CAAC;IACnH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe;IAClD,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAChF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC5G,CAAC"}

package/lib/build/packageVersionArtifact.d.ts

@@ -0,0 +1,51 @@
+/** The dotenv key `create-package-version` and `create-fallback-tag` both write their `04t` under. */
+export declare const SUBSCRIBER_PACKAGE_VERSION_ID_KEY = "SUBSCRIBER_PACKAGE_VERSION_ID";
+/**
+ * Reduce a git tag suffix to something semver accepts as a prerelease identifier.
+ *
+ * Semver's prerelease alphabet is `[0-9A-Za-z-]`; a branch name's `/` and `.` are the common
+ * offenders, so each run of anything else collapses to a single hyphen.
+ */
+export declare function sanitizePrereleaseId(raw: string): string;
+/**
+ * Map a Salesforce package version onto a semver version.
+ *
+ * The build number becomes the first prerelease identifier and the git tag's suffix, if any, the
+ * second — so `1.2.3.4` on a release branch is `1.2.3-4`, and the same version built from `beta`
+ * is `1.2.3-4.beta`. This is the transformation `sfdx-project.json` already uses for a dependency
+ * pin (`"package": "MyPackage@1.2.3-4"`), not a new convention.
+ *
+ * @throws {Error} If the version isn't `major.minor.patch.build`. Publishing a version derived
+ * from something unrecognised is worse than failing the job.
+ */
+export declare function toNpmVersion(salesforceVersion: string, tagSuffix?: string): string;
+/**
+ * The npm dist-tag for a build: `latest` for a release-branch build, else the sanitized tag suffix,
+ * so `npm install <pkg>@beta` reaches the newest build off the `beta` package branch.
+ */
+export declare function toDistTag(tagSuffix?: string): string;
+/** @returns The last value assigned to `key` in dotenv-shaped `content`, or `undefined`. */
+export declare function readEnvFileValue(content: string, key: string): string | undefined;
+export type ResolveSubscriberPackageVersionIdOptions = {
+    /** `--subscriber-package-version-id`, if passed. */
+    flagValue?: string;
+    /** The environment to read `SUBSCRIBER_PACKAGE_VERSION_ID` from. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Dotenv file to fall back to — the one `create-package-version` wrote earlier in this job. */
+    envFile: string;
+};
+/**
+ * Find the `04t` this run should publish page objects for.
+ *
+ * Three sources, because the command is useful from two pipeline shapes and they surface the value
+ * differently: an explicit flag; `SUBSCRIBER_PACKAGE_VERSION_ID` in the environment, which is how a
+ * *separate* job receives `create-package-version`'s dotenv report artifact; and the dotenv file
+ * itself, which is how the *same* job sees it, since a dotenv report only ever reaches other jobs.
+ *
+ * An explicit flag that isn't a `04t` throws — the caller asked for something specific and got it
+ * wrong. A malformed value discovered rather than passed only warns, and the search continues.
+ *
+ * @returns The ID, or `undefined` when no source has one.
+ * @throws {Error} If `flagValue` is not a subscriber package version ID.
+ */
+export declare function resolveSubscriberPackageVersionId(options: ResolveSubscriberPackageVersionIdOptions): Promise<string | undefined>;

package/lib/build/packageVersionArtifact.js

@@ -0,0 +1,143 @@
+/*
+ * 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 { isSubscriberPackageVersionId } from '@simplysf/simply-core';
+import { logger } from '../logger.js';
+// Helpers for any artifact published per package version (UTAM page objects, aer packages): finding
+// the `04t` a build produced and mapping its Salesforce version number onto a semver version.
+/** The dotenv key `create-package-version` and `create-fallback-tag` both write their `04t` under. */
+export const SUBSCRIBER_PACKAGE_VERSION_ID_KEY = 'SUBSCRIBER_PACKAGE_VERSION_ID';
+/** `sf package version report` returns `Version` as `major.minor.patch.build`, which is not semver. */
+const SALESFORCE_VERSION_PATTERN = /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)\.(?<build>\d+)$/;
+/**
+ * Strip leading and trailing hyphens. Done by index rather than `/^-+|-+$/`, whose trailing
+ * alternative backtracks quadratically on a long run of interior hyphens.
+ */
+function trimHyphens(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value[start] === '-')
+        start++;
+    while (end > start && value[end - 1] === '-')
+        end--;
+    return value.slice(start, end);
+}
+/**
+ * Reduce a git tag suffix to something semver accepts as a prerelease identifier.
+ *
+ * Semver's prerelease alphabet is `[0-9A-Za-z-]`; a branch name's `/` and `.` are the common
+ * offenders, so each run of anything else collapses to a single hyphen.
+ */
+export function sanitizePrereleaseId(raw) {
+    const cleaned = trimHyphens(raw.replace(/[^0-9A-Za-z-]+/g, '-'));
+    // Semver forbids leading zeros in an all-numeric identifier, so a branch literally named `007`
+    // would otherwise produce a version every registry rejects. Prefixing keeps it traceable.
+    return /^0\d+$/.test(cleaned) ? `v${cleaned}` : cleaned;
+}
+/**
+ * Map a Salesforce package version onto a semver version.
+ *
+ * The build number becomes the first prerelease identifier and the git tag's suffix, if any, the
+ * second — so `1.2.3.4` on a release branch is `1.2.3-4`, and the same version built from `beta`
+ * is `1.2.3-4.beta`. This is the transformation `sfdx-project.json` already uses for a dependency
+ * pin (`"package": "MyPackage@1.2.3-4"`), not a new convention.
+ *
+ * @throws {Error} If the version isn't `major.minor.patch.build`. Publishing a version derived
+ * from something unrecognised is worse than failing the job.
+ */
+export function toNpmVersion(salesforceVersion, tagSuffix) {
+    const match = SALESFORCE_VERSION_PATTERN.exec(salesforceVersion.trim());
+    if (!match?.groups) {
+        throw new Error(`Cannot derive an npm version from Salesforce package version "${salesforceVersion}": expected major.minor.patch.build.`);
+    }
+    const { major, minor, patch, build } = match.groups;
+    const sanitizedSuffix = tagSuffix ? sanitizePrereleaseId(tagSuffix) : '';
+    const prerelease = sanitizedSuffix ? `${build}.${sanitizedSuffix}` : build;
+    return `${major}.${minor}.${patch}-${prerelease}`;
+}
+/**
+ * The npm dist-tag for a build: `latest` for a release-branch build, else the sanitized tag suffix,
+ * so `npm install <pkg>@beta` reaches the newest build off the `beta` package branch.
+ */
+export function toDistTag(tagSuffix) {
+    const sanitized = tagSuffix ? sanitizePrereleaseId(tagSuffix) : '';
+    return sanitized.length > 0 ? sanitized : 'latest';
+}
+/** @returns The last value assigned to `key` in dotenv-shaped `content`, or `undefined`. */
+export function readEnvFileValue(content, key) {
+    let found;
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith('#')) {
+            continue;
+        }
+        const separator = trimmed.indexOf('=');
+        if (separator !== -1 && trimmed.slice(0, separator).trim() === key) {
+            // Last wins: the file is appended to, so a later line is the newer value.
+            found = trimmed.slice(separator + 1).trim();
+        }
+    }
+    return found;
+}
+/**
+ * Find the `04t` this run should publish page objects for.
+ *
+ * Three sources, because the command is useful from two pipeline shapes and they surface the value
+ * differently: an explicit flag; `SUBSCRIBER_PACKAGE_VERSION_ID` in the environment, which is how a
+ * *separate* job receives `create-package-version`'s dotenv report artifact; and the dotenv file
+ * itself, which is how the *same* job sees it, since a dotenv report only ever reaches other jobs.
+ *
+ * An explicit flag that isn't a `04t` throws — the caller asked for something specific and got it
+ * wrong. A malformed value discovered rather than passed only warns, and the search continues.
+ *
+ * @returns The ID, or `undefined` when no source has one.
+ * @throws {Error} If `flagValue` is not a subscriber package version ID.
+ */
+export async function resolveSubscriberPackageVersionId(options) {
+    const { flagValue, env = process.env, envFile } = options;
+    if (flagValue) {
+        if (!isSubscriberPackageVersionId(flagValue)) {
+            throw new Error(`--subscriber-package-version-id must be a subscriber package version ID (04t), got "${flagValue}".`);
+        }
+        return flagValue;
+    }
+    const fromEnv = env[SUBSCRIBER_PACKAGE_VERSION_ID_KEY];
+    if (fromEnv) {
+        if (isSubscriberPackageVersionId(fromEnv)) {
+            logger.info(`Using ${SUBSCRIBER_PACKAGE_VERSION_ID_KEY} from the environment: ${fromEnv}`);
+            return fromEnv;
+        }
+        logger.warn(`Ignoring ${SUBSCRIBER_PACKAGE_VERSION_ID_KEY}="${fromEnv}" from the environment: not a 04t ID.`);
+    }
+    let content;
+    try {
+        content = await fs.readFile(envFile, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const fromFile = readEnvFileValue(content, SUBSCRIBER_PACKAGE_VERSION_ID_KEY);
+    if (!fromFile) {
+        return undefined;
+    }
+    if (!isSubscriberPackageVersionId(fromFile)) {
+        logger.warn(`Ignoring ${SUBSCRIBER_PACKAGE_VERSION_ID_KEY}="${fromFile}" in ${envFile}: not a 04t ID.`);
+        return undefined;
+    }
+    logger.info(`Using ${SUBSCRIBER_PACKAGE_VERSION_ID_KEY} from ${envFile}: ${fromFile}`);
+    return fromFile;
+}
+//# sourceMappingURL=packageVersionArtifact.js.map

package/lib/build/packageVersionArtifact.js.map

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

package/lib/build/publishAerPackage.d.ts

@@ -0,0 +1,49 @@
+export type PublishAerPackageOptions = {
+    /** The packaging Dev Hub's alias. Must already be authenticated. */
+    packagingDevhub: string;
+    /** URL template to upload to. Overrides `plugins.simply.aer.repositoryUrl`. */
+    repositoryUrl?: string;
+    /** One `Name: value` header sent with every repository request. Never logged. */
+    repositoryHeader?: string;
+    subscriberPackageVersionId?: string;
+    /** Directories of `.pkg` files for dependencies this command can't download, e.g. managed packages. */
+    dependencyPackageDirs?: string[];
+    /** The aer binary. Otherwise `AER_BIN`, the aer sf plugin's download, then `PATH`. */
+    aerPath?: string;
+    /** Build the package and copy it to the working directory, but don't upload it. */
+    dryRun?: boolean;
+    /** Dotenv file to append the published URL, file name and version to. */
+    out?: string;
+    /** Dotenv file to read `SUBSCRIBER_PACKAGE_VERSION_ID` from. */
+    envFile?: string;
+    debug?: boolean;
+    disabled?: boolean;
+};
+export type PublishAerPackageResult = {
+    skipped: boolean;
+    published: boolean;
+    /** True when this exact version was already in the repository, so nothing needed uploading. */
+    alreadyPublished?: boolean;
+    packageName?: string;
+    namespace?: string;
+    version?: string;
+    url?: string;
+    /** The package's file name, or its local path on `--dry-run`. */
+    file?: string;
+    aerVersion?: string;
+};
+/**
+ * Build the project's aer package (`.pkg`) for one package version and upload it to an artifact
+ * repository, under a path 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 matching aer package a consumer can test against locally. See
+ * `docs/design/0059-aer-package-publish.md` in `simply-plugins` for the reasoning, particularly why
+ * the file name carries the namespace and the version lives only in the path.
+ *
+ * Skips (without failing) when the package didn't change, when the job is disabled, when no `04t`
+ * can be found, when the package has no Apex, or when this exact version is already uploaded.
+ * Everything past those guards throws on failure: a missing aer package would silently break every
+ * consumer pinned to that version.
+ */
+export declare function publishAerPackage(options: PublishAerPackageOptions): Promise<PublishAerPackageResult>;