@simplysf/simply-cicd-core 0.2.2 → 0.4.0

package/lib/build/versionTagFormat.js

@@ -0,0 +1,194 @@
+/*
+ * 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 { getPluginConfig } from '@simplysf/simply-core';
+/** The tag shape every `simply cicd build` command used before the format was configurable. */
+export const DEFAULT_VERSION_TAG_FORMAT = 'v{MAJOR}.{MINOR}.{PATCH}.{BUILD}';
+/** Where in `sfdx-project.json` a project declares its own format. */
+export const VERSION_TAG_FORMAT_CONFIG_PATH = 'plugins.simply.versionTagFormat';
+/** Overrides the project's format, in every command that reads it, when set to a non-empty value. */
+export const VERSION_TAG_FORMAT_ENV_VAR = 'SIMPLY_CICD_VERSION_TAG_FORMAT';
+const PLACEHOLDERS = ['MAJOR', 'MINOR', 'PATCH', 'BUILD'];
+/** `sf package version report` returns `Version` as `major.minor.patch.build`. */
+const SALESFORCE_VERSION_PATTERN = /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)\.(?<build>\d+)$/;
+/** Thrown for a format that can't be used, so callers that otherwise swallow errors can let it through. */
+export class VersionTagFormatError extends Error {
+    constructor(format, problem, source = VERSION_TAG_FORMAT_CONFIG_PATH) {
+        super(`Invalid version tag format "${format}" (${source}): ${problem}`);
+        this.name = 'VersionTagFormatError';
+    }
+}
+/**
+ * Why `tag` isn't a legal git tag name, or `undefined` when it is. Mirrors `git check-ref-format`'s
+ * rules for `refs/tags/<tag>`, plus git's refusal of tag names starting with `-`.
+ */
+function findRefNameProblem(tag) {
+    if (tag.startsWith('-'))
+        return 'a tag cannot start with "-"';
+    // eslint-disable-next-line no-control-regex -- control characters are exactly what git refuses
+    if (/[\x00-\x20\x7f~^:?*[\\]/.test(tag))
+        return 'contains a space, a control character, or one of ~^:?*[\\';
+    if (tag.includes('..'))
+        return 'contains ".."';
+    if (tag.includes('@{'))
+        return 'contains "@{"';
+    if (tag === '@')
+        return 'cannot be "@"';
+    if (tag.endsWith('.'))
+        return 'cannot end with "."';
+    if (tag.startsWith('/') || tag.endsWith('/') || tag.includes('//'))
+        return 'has an empty "/"-separated component';
+    if (tag.split('/').some((component) => component.startsWith('.') || component.endsWith('.lock'))) {
+        return 'has a "/"-separated component starting with "." or ending with ".lock"';
+    }
+    return undefined;
+}
+function tokenize(format, source) {
+    const segments = [];
+    const placeholderPattern = /\{(?<name>[^{}]*)\}/g;
+    let lastIndex = 0;
+    for (const match of format.matchAll(placeholderPattern)) {
+        const name = match.groups?.name ?? '';
+        if (!PLACEHOLDERS.includes(name)) {
+            throw new VersionTagFormatError(format, `unknown placeholder "{${name}}"; use {MAJOR}, {MINOR}, {PATCH}, and {BUILD}`, source);
+        }
+        if (match.index > lastIndex) {
+            segments.push({ kind: 'literal', text: format.slice(lastIndex, match.index) });
+        }
+        segments.push({ kind: 'placeholder', name: name });
+        lastIndex = match.index + match[0].length;
+    }
+    if (lastIndex < format.length) {
+        segments.push({ kind: 'literal', text: format.slice(lastIndex) });
+    }
+    return segments;
+}
+function validate(format, segments, source) {
+    if (segments.some((segment) => segment.kind === 'literal' && /[{}]/.test(segment.text))) {
+        throw new VersionTagFormatError(format, 'contains an unmatched "{" or "}"', source);
+    }
+    for (const name of PLACEHOLDERS) {
+        const count = segments.filter((segment) => segment.kind === 'placeholder' && segment.name === name).length;
+        if (count !== 1) {
+            throw new VersionTagFormatError(format, `{${name}} must appear exactly once, found ${count}`, source);
+        }
+    }
+    segments.forEach((segment, index) => {
+        const next = segments[index + 1];
+        if (segment.kind === 'placeholder' && next?.kind === 'placeholder') {
+            throw new VersionTagFormatError(format, `{${segment.name}}{${next.name}} must be separated by a non-digit`, source);
+        }
+        const following = segments[index + 2];
+        if (segment.kind === 'placeholder' &&
+            next?.kind === 'literal' &&
+            following?.kind === 'placeholder' &&
+            /^\d+$/.test(next.text)) {
+            throw new VersionTagFormatError(format, `{${segment.name}} and {${following.name}} must be separated by a non-digit`, source);
+        }
+    });
+    const problem = findRefNameProblem(renderSegments(segments, { major: '1', minor: '2', patch: '3', build: '4' }));
+    if (problem) {
+        throw new VersionTagFormatError(format, `the tags it produces aren't valid git tag names: ${problem}`, source);
+    }
+}
+function renderSegments(segments, values, missing = '') {
+    return segments
+        .map((segment) => segment.kind === 'literal' ? segment.text : (values[segment.name.toLowerCase()] ?? missing))
+        .join('');
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * A validated version tag format. Every command that writes or reads a package version's git tag
+ * goes through one of these, so they agree on the tag's shape.
+ */
+export class VersionTagFormat {
+    format;
+    segments;
+    tagPattern;
+    constructor(format, source) {
+        this.format = format;
+        this.segments = tokenize(format, source);
+        validate(format, this.segments, source);
+        const versionPattern = this.segments
+            .map((segment) => segment.kind === 'literal' ? escapeRegExp(segment.text) : `(?<${segment.name.toLowerCase()}>\\d+)`)
+            .join('');
+        this.tagPattern = new RegExp(`^(?<versionTag>${versionPattern})(?:-(?<rest>.*))?$`);
+    }
+    /** @throws {VersionTagFormatError} If the format can't produce distinct, parseable, legal tags. */
+    static parse(format) {
+        return new VersionTagFormat(format);
+    }
+    /**
+     * The format in `SIMPLY_CICD_VERSION_TAG_FORMAT` when it's set, otherwise the one declared under
+     * `plugins.simply.versionTagFormat`, otherwise the default.
+     *
+     * @throws {VersionTagFormatError} If the chosen format is invalid.
+     */
+    static fromProject(project) {
+        const override = process.env[VERSION_TAG_FORMAT_ENV_VAR];
+        if (override) {
+            return new VersionTagFormat(override, VERSION_TAG_FORMAT_ENV_VAR);
+        }
+        const declared = project ? getPluginConfig(project, VERSION_TAG_FORMAT_CONFIG_PATH) : undefined;
+        if (declared === undefined || declared === null || declared === '') {
+            return new VersionTagFormat(DEFAULT_VERSION_TAG_FORMAT);
+        }
+        if (typeof declared !== 'string') {
+            throw new VersionTagFormatError(JSON.stringify(declared), 'must be a string');
+        }
+        return new VersionTagFormat(declared);
+    }
+    /**
+     * The tag for `salesforceVersion` (`major.minor.patch.build`), with `-<suffix>` appended when given.
+     *
+     * @throws {Error} If the version isn't four numeric parts.
+     */
+    render(salesforceVersion, suffix) {
+        const match = SALESFORCE_VERSION_PATTERN.exec(salesforceVersion.trim());
+        if (!match?.groups) {
+            throw new Error(`Cannot render a version tag for Salesforce package version "${salesforceVersion}": expected major.minor.patch.build.`);
+        }
+        const versionTag = renderSegments(this.segments, match.groups);
+        return suffix ? `${versionTag}-${suffix}` : versionTag;
+    }
+    /**
+     * A `git describe --match` / `git tag --list` glob for tags of the `major.minor.patch` that
+     * `versionNumber` (e.g. `6.40.0.NEXT`) declares, with any build and suffix. Without a usable
+     * `versionNumber`, any tag starting the way the format starts.
+     */
+    matchPattern(versionNumber) {
+        const parts = versionNumber?.split('.') ?? [];
+        if (parts.length >= 3) {
+            const glob = renderSegments(this.segments, { major: parts[0], minor: parts[1], patch: parts[2] }, '*');
+            return glob.endsWith('*') ? glob : `${glob}*`;
+        }
+        const first = this.segments[0];
+        return `${first.kind === 'literal' ? first.text : ''}*`;
+    }
+    /** Splits a tag this format rendered back into its version and suffix; `undefined` if it doesn't match. */
+    parseTag(tag) {
+        const groups = this.tagPattern.exec(tag)?.groups;
+        if (!groups)
+            return undefined;
+        return {
+            versionTag: groups.versionTag,
+            version: { major: groups.major, minor: groups.minor, patch: groups.patch, build: groups.build },
+            rest: groups.rest ?? '',
+        };
+    }
+}
+//# sourceMappingURL=versionTagFormat.js.map

package/lib/build/versionTagFormat.js.map

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

package/lib/config/defaultDeploymentPlugins.d.ts

@@ -0,0 +1,2 @@
+/** Plugins installed by default before running a deployment. */
+export declare const DEFAULT_DEPLOYMENT_PLUGINS: string[];

package/lib/config/defaultDeploymentPlugins.js

@@ -0,0 +1,18 @@
+/*
+ * 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.
+ */
+/** Plugins installed by default before running a deployment. */
+export const DEFAULT_DEPLOYMENT_PLUGINS = ['@simplysf/simply'];
+//# sourceMappingURL=defaultDeploymentPlugins.js.map

package/lib/config/defaultDeploymentPlugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultDeploymentPlugins.js","sourceRoot":"","sources":["../../src/config/defaultDeploymentPlugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,0BAA0B,GAAa,CAAC,kBAAkB,CAAC,CAAC"}

package/lib/config/trustedPlugins.d.ts

@@ -0,0 +1,2 @@
+/** Plugins pre-approved as trusted unsigned publishers, to avoid interactive install prompts. */
+export declare const TRUSTED_PLUGINS: string[];

package/lib/config/trustedPlugins.js

@@ -0,0 +1,18 @@
+/*
+ * 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.
+ */
+/** Plugins pre-approved as trusted unsigned publishers, to avoid interactive install prompts. */
+export const TRUSTED_PLUGINS = ['sfdmu', '@simplysf/simply'];
+//# sourceMappingURL=trustedPlugins.js.map

package/lib/config/trustedPlugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trustedPlugins.js","sourceRoot":"","sources":["../../src/config/trustedPlugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,iGAAiG;AACjG,MAAM,CAAC,MAAM,eAAe,GAAa,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC"}

package/lib/deploy/deployCommon.d.ts

@@ -0,0 +1,105 @@
+import type { z } from 'zod';
+import { type VcsProviderKind } from '../vcs/index.js';
+import { type DeployConfig } from '../schemas/deployConfig.js';
+import { type DeployProgress } from '../schemas/deployProgress.js';
+/**
+ * A Salesforce org this command operates on, referenced by an alias the calling pipeline has
+ * already authenticated — `simply-cicd` never authenticates orgs itself. Optional here because not
+ * every stage needs one (e.g. `deployment-close-out`); commands that do require it declare
+ * `alias` as `required: true` on the flag itself.
+ */
+export type OrgAuthConfig = {
+    alias?: string;
+};
+/** A deployment entry from `deploy.json`, plus the synthetic `{ name: 'local' }` project deployment. */
+export type StageDeployment = {
+    [key: string]: unknown;
+    name: string;
+    slug?: string;
+    ref?: string;
+    postDeploy?: boolean;
+    postDestructive?: boolean;
+    preDestructive?: boolean;
+    unpackagedDeploy?: boolean;
+    testLevel?: string;
+    tests?: string;
+};
+export type StageProperty = 'postDeploy' | 'postDestructive' | 'preDestructive' | 'unpackagedDeploy';
+/** Validates `data` against a zod schema, throwing a formatted error (one bullet per issue) if it fails. */
+export declare function validateWithSchema<T>(schema: z.ZodType<T>, data: unknown, fileName: string): T;
+/**
+ * Read a JSON file and validate it against a zod schema.
+ *
+ * @param filePath - The file to read. Its name appears in the error on a schema violation.
+ * @param schema - The schema to validate against.
+ * @returns The validated contents.
+ * @throws {Error} With one bullet per schema issue, via {@link validateWithSchema}.
+ * @throws {NodeJS.ErrnoException} If the file can't be read — callers check for `ENOENT` to
+ * treat a missing file as non-fatal.
+ * @throws {SyntaxError} If the file isn't valid JSON.
+ */
+export declare function loadValidatedJsonFile<T>(filePath: string, schema: z.ZodType<T>): Promise<T>;
+/** Validates a deployment configuration against a set of deployment rules (e.g. "prod must run postDeploy"). */
+export declare function validateDeploymentRules(deploymentConfig: DeployConfig, rulesFile: string): Promise<void>;
+export declare const STAGE_TO_SCRIPT_NAME_MAP: Record<string, string>;
+export declare const STAGE_TO_PROPERTY_MAP: Record<string, string>;
+export declare const STAGE_CONFIG: Record<string, {
+    property: StageProperty;
+}>;
+/** Atomically updates a progress file: writes to a temp file first, then renames it into place. */
+export declare function updateProgress(deployProgressFile: string, newProgress: DeployProgress): Promise<void>;
+export type ExecuteStageScriptConfig = {
+    alias?: string;
+    testLevel?: string;
+    tests?: string;
+};
+/**
+ * Executes a stage-specific script (e.g. `bin/preDestructive.sh`) for a deployment: installs npm
+ * production dependencies if a `package.json` exists, sets executable/writable permissions on the
+ * repo's working directories, and runs the script with `--target-org`/`--test-level`/`--tests`.
+ */
+export declare function executeStageScript(deployment: StageDeployment, stage: string, repoDir: string, config: ExecuteStageScriptConfig): Promise<void>;
+export type DeployInstallPackageDependenciesConfig = OrgAuthConfig & {
+    wait?: string;
+    installType?: 'All' | 'Delta' | 'Upgrade';
+    upgradeType?: 'DeprecateOnly' | 'Mixed' | 'Delete';
+};
+/** Installs the target org's packaged dependencies. The org must already be authenticated. */
+export declare function installDeployPackageDependencies(config: DeployInstallPackageDependenciesConfig): Promise<void>;
+/** Logs a per-job duration summary for the given stage, from the recorded progress file durations. */
+export declare function printDeploymentSummary(deployProgress: DeployProgress, stage: string): void;
+export type RunApexTestsConfig = OrgAuthConfig & {
+    testLevel?: string;
+    testSuite?: string;
+    wait?: string;
+    debugMode?: boolean;
+};
+/** Runs Apex tests on the target org. The org must already be authenticated. */
+export declare function runDeployApexTests(config: RunApexTestsConfig): Promise<void>;
+export declare function loadProgress(deployProgressFile: string): Promise<DeployProgress>;
+export type RunDeploymentStepsConfig = OrgAuthConfig & {
+    deployConfigFile: string;
+    deployRulesFile: string;
+    deployProgressFile: string;
+    stage: string;
+    startFrom?: string;
+    isProjectDeployment?: boolean;
+    debug?: boolean;
+    testLevel?: string;
+    tests?: string;
+    ciJobToken: string;
+    vcsHost?: string;
+    vcsProvider: VcsProviderKind;
+};
+export type RunDeploymentStepsResult = {
+    deployProgress: DeployProgress;
+};
+/**
+ * Runs a complete set of deployment jobs for a stage: loads (and validates) the progress and
+ * config files, determines where to resume from, then clones/prepares/executes each job in order
+ * — persisting progress after every job so a mid-run crash can resume cleanly. The target org
+ * (`config.alias`) must already be authenticated.
+ */
+export declare function runDeploymentSteps(config: RunDeploymentStepsConfig): Promise<RunDeploymentStepsResult>;
+/** Determines the deploy config file path: explicit path wins, else derived from the branch name. */
+export declare function determineDeployConfigFile(sourceBranchName?: string, deployConfigFile?: string): string | undefined;