@copado/agentia-cli 1.3.0 → 1.4.0

package/dist/commands/cicd/work/environment-sync.js

@@ -1,18 +1,21 @@
 import { Flags } from '@oclif/core';
 import { CicdCommand } from '../../../lib/cicd-command.js';
 import { commandStdioCaptureOptions, withCapturedCommandOutput } from '../../../lib/command-output-buffer.js';
-import { assertEnvironmentSyncDestOrgSelector, formatWorkEnvironmentSyncResult, performWorkEnvironmentSync, WorkEnvironmentSyncConflictError, WorkEnvironmentSyncValidationError, } from '../../../lib/work-environment-sync.js';
+import { isPromotionRunExecutionError, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, promotionRunErrorJson, waitForPromotionDeploymentExecution, } from '../../../lib/promotion-run.js';
+import { assertEnvironmentSyncDestOrgSelector, ENVIRONMENT_SYNC_DEPLOYMENT_WAIT_MESSAGE, ENVIRONMENT_SYNC_DEPLOYMENTS, formatWorkEnvironmentSyncDeploymentMonitor, formatWorkEnvironmentSyncResult, performWorkEnvironmentSync, shouldWaitForEnvironmentSyncDeployment, WorkEnvironmentSyncConflictError, WorkEnvironmentSyncValidationError, } from '../../../lib/work-environment-sync.js';
 export default class WorkEnvironmentSync extends CicdCommand {
     static description = [
         'Sync committed metadata from the next environment onto the destination environment (or current feature branch).',
         'Back-promotes every user story behind the destination environment from the next environment branch.',
-        'GET user stories ahead and behind. If none are behind, log that and stop. Otherwise create a back-promotion and POST those behind stories onto the promotion.',
+        'On a feature branch, requires published commits first: stops when HEAD is ahead of origin/<feature> and suggests `cicd work publish`.',
+        'GET user stories ahead and behind. If none are behind, log that and stop. Otherwise create a back-promotion via POST /agentia/headless/work/promote-action (PromoteAction with execute flags false) including those behind stories.',
         'Resolves the next-environment Git branch from --destination-environment or --dev-org-branch (the dest pipeline connection destinationBranch, or that destination environment\'s outbound branch).',
-        'Merges origin/<next-env> with --no-ff --no-commit, restores every other path from HEAD, commits the guessed pathspecs,',
-        'and pushes the dest org branch (and the feature branch when HEAD starts with feature/).',
-        'If guessed pathspecs still conflict, PATCH the back-promotion status to Merge Conflict, store lastEnvironmentSyncName, resolve the files, and re-run with --continue (optional --promotion). The promotion destination environment supplies the dest org branch and the next-env branch.',
-        'To discard a conflicted merge, re-run with --abort (optional --promotion); runs git merge --abort and sets the back-promotion status to Draft.',
-        'After a successful sync, PATCH the back-promotion status to Completed and clear lastEnvironmentSyncName.',
+        'Creates promotion/<promotionName> from the dest org branch, merges origin/<next-env> pathspecs into that promotion branch (--no-ff --no-commit, restores non-pathspec paths), commits, merges the promotion branch into the dest org branch, and pushes both refs.',
+        'If the run started on a feature branch, checks out that branch\'s changed files (vs lastBaseBranch) from the dest org, commits updates when needed, and tells you to re-check and publish again.',
+        'If guessed pathspecs still conflict, PATCH the back-promotion status to Merge Conflict, store lastEnvironmentSyncName, resolve the files on promotion/<name>, and re-run with --continue (optional --promotion).',
+        'To discard a conflicted merge, re-run with --abort (optional --promotion); runs git merge --abort and POST /agentia/headless/work/promote-action/complete with status Cancelled.',
+        'After a successful sync, when --deployment resolves to local, runs `sf project deploy start --ignore-conflicts` against --sf-alias (Add-only changes), then POST /agentia/headless/work/promote-action/complete with status Completed and the resolved deployment (none|local|cloud; auto chooses local when every change is Add and --sf-alias is set, otherwise cloud).',
+        'By default polls the cloud deployment JobExecution to a terminal status when deployment is cloud (--no-wait to skip).',
         'On git/merge failure (including conflicts) and after a successful --continue, uploads the captured command transcript as a Salesforce File on the back-promotion (`Environment Sync Logs <name-or-id> <datetime>.txt`) via `/agentia/headless/file/upload`. HTTP 404 is ignored until that endpoint is rolled out; other upload failures are warned and do not change the environment-sync outcome.',
     ].join(' ');
     static examples = [
@@ -21,12 +24,16 @@ export default class WorkEnvironmentSync extends CicdCommand {
         '<%= config.bin %> <%= command.id %> --continue',
         '<%= config.bin %> <%= command.id %> --abort',
         '<%= config.bin %> <%= command.id %> --promotion=P29334 --continue',
+        '<%= config.bin %> <%= command.id %> --destination-environment=dev1 --deployment=local --sf-alias=dev1',
+        '<%= config.bin %> <%= command.id %> --destination-environment=dev1 --deployment=cloud',
+        '<%= config.bin %> <%= command.id %> --destination-environment=dev1 --no-wait',
         '<%= config.bin %> <%= command.id %> --destination-environment=dev1 --json',
     ];
+    static experimental = true;
     static flags = {
         abort: Flags.boolean({
             default: false,
-            description: 'Abort an in-progress merge (`git merge --abort`) and set the back-promotion status to Draft. Uses --promotion or lastEnvironmentSyncName. Exclusive with --continue.',
+            description: 'Abort an in-progress merge (`git merge --abort`) and cancel the back-promotion via promote-action/complete. Uses --promotion or lastEnvironmentSyncName. Exclusive with --continue.',
             exclusive: ['continue'],
         }),
         continue: Flags.boolean({
@@ -34,8 +41,13 @@ export default class WorkEnvironmentSync extends CicdCommand {
             description: 'Finish after merge conflicts. If the merge is still in progress (conflicts fixed and staged, but not committed), commits it; if you already committed, continues from there through the remaining git steps. Uses --promotion or lastEnvironmentSyncName.',
             exclusive: ['abort'],
         }),
+        deployment: Flags.string({
+            default: 'auto',
+            description: 'How promote-action/complete handles deployment after a successful sync: none (leave deployment job untouched), local (sf project deploy start --ignore-conflicts then mark deployment JobExecution Successful; Add-only changes; requires --sf-alias), cloud (start PromotionDeployAction), or auto (local when every change is Add and --sf-alias is set, otherwise cloud). Sent to the gateway as none|local|cloud (never auto).',
+            options: [...ENVIRONMENT_SYNC_DEPLOYMENTS],
+        }),
         'destination-credential': Flags.string({
-            description: 'Credential ID posted as destinationCredentialId when creating the back-promotion. Copado requires a credential on the next/source environment (PRO-033 if a dest/dev credential is sent) and then stores the dest/dev credential. Defaults to that source environment defaultCredential, otherwise the first source credential.',
+            description: 'Credential ID recorded on the environment-sync result as destinationCredentialId. Defaults to the next/source environment defaultCredential, otherwise the first source credential. PromoteAction resolves deployment credentials itself.',
         }),
         'destination-environment': Flags.string({
             description: 'Destination org environment name or Id. Resolves to that environment\'s pipeline connection Git branch.',
@@ -51,42 +63,29 @@ export default class WorkEnvironmentSync extends CicdCommand {
         promotion: Flags.string({
             description: 'Back-promotion Id or name to PATCH when this run stops on merge conflicts, finishes successfully, continues, or aborts. Optional for --continue/--abort when lastEnvironmentSyncName was stored from a prior environment-sync run. Defaults to the back-promotion created in this run.',
         }),
+        'sf-alias': Flags.string({
+            description: 'Salesforce CLI org alias or username for local deployment (`sf project deploy start -o`). Required with --deployment=local; with --deployment=auto enables local when changes are Add-only.',
+        }),
+        wait: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Poll promotion and deployment executions to terminal status.',
+        }),
+        'wait-timeout': Flags.integer({
+            default: PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS,
+            description: 'Maximum total seconds to wait for promotion and deployment executions.',
+        }),
     };
     async run() {
         const { flags } = await this.parse(WorkEnvironmentSync);
+        const syncFlags = flags;
+        if (!Number.isInteger(syncFlags['wait-timeout']) || syncFlags['wait-timeout'] <= 0) {
+            this.error('--wait-timeout must be a positive integer.', { exit: 2 });
+        }
         return withCapturedCommandOutput(async () => {
             const startedAt = Date.now();
             try {
-                await assertEnvironmentSyncDestOrgSelector({
-                    abort: flags.abort === true,
-                    continue: flags.continue === true,
-                    destinationEnvironment: flags['destination-environment'],
-                    devOrgBranch: flags['dev-org-branch'],
-                    promotion: flags.promotion,
-                });
-                const result = await performWorkEnvironmentSync({
-                    abort: flags.abort === true,
-                    cliBin: this.config.bin,
-                    continue: flags.continue === true,
-                    hooks: {
-                        log: (message) => {
-                            this.display(() => {
-                                this.log(message);
-                            });
-                        },
-                        withSpinner: (message, action) => this.withSpinner(message, action),
-                    },
-                    json: this.jsonEnabled(),
-                    ...(flags['destination-credential'] === undefined
-                        ? {}
-                        : { destinationCredentialId: flags['destination-credential'] }),
-                    ...(flags['destination-environment'] === undefined
-                        ? {}
-                        : { destinationEnvironment: flags['destination-environment'] }),
-                    ...(flags['dev-org-branch'] === undefined ? {} : { devOrgBranch: flags['dev-org-branch'] }),
-                    ...(flags['pipeline-id'] === undefined ? {} : { pipelineId: flags['pipeline-id'] }),
-                    ...(flags.promotion === undefined ? {} : { promotion: flags.promotion }),
-                });
+                const result = await this.runEnvironmentSync(syncFlags);
                 this.display(() => {
                     const formatted = formatWorkEnvironmentSyncResult(result);
                     if (formatted.length > 0) {
@@ -94,34 +93,111 @@ export default class WorkEnvironmentSync extends CicdCommand {
                     }
                 });
                 this.logElapsed(startedAt);
+                await this.waitForDeploymentIfNeeded(result, syncFlags, startedAt);
                 return result;
             }
             catch (error) {
-                if (error instanceof WorkEnvironmentSyncConflictError) {
-                    const { suggestions } = error;
-                    const suggestionOptions = suggestions === undefined ? {} : { suggestions };
-                    if (this.jsonEnabled()) {
-                        const message = error.gitStatus === undefined || error.gitStatus.length === 0
-                            ? error.message
-                            : `${error.message}\n\n${error.gitStatus}`;
-                        this.error(message, { exit: error.exit, ...suggestionOptions });
-                    }
-                    this.error(error.message, { exit: false, ...suggestionOptions });
-                    if (error.gitStatus !== undefined && error.gitStatus.length > 0) {
-                        this.log('');
-                        this.log(error.gitStatus);
-                    }
-                    this.exit(error.exit);
-                }
-                if (error instanceof WorkEnvironmentSyncValidationError) {
-                    this.error(error.message, {
-                        exit: error.exit,
-                        ...(error.suggestions === undefined ? {} : { suggestions: error.suggestions }),
-                    });
-                }
-                throw error;
+                this.handleEnvironmentSyncError(error);
             }
         }, commandStdioCaptureOptions(this));
     }
+    toErrorJson(err) {
+        const base = super.toErrorJson(err);
+        return promotionRunErrorJson(base, err);
+    }
+    handleEnvironmentSyncError(error) {
+        if (error instanceof WorkEnvironmentSyncConflictError) {
+            const { suggestions } = error;
+            const suggestionOptions = suggestions === undefined ? {} : { suggestions };
+            if (this.jsonEnabled()) {
+                const message = error.gitStatus === undefined || error.gitStatus.length === 0
+                    ? error.message
+                    : `${error.message}\n\n${error.gitStatus}`;
+                this.error(message, { exit: error.exit, ...suggestionOptions });
+            }
+            this.error(error.message, { exit: false, ...suggestionOptions });
+            if (error.gitStatus !== undefined && error.gitStatus.length > 0) {
+                this.log('');
+                this.log(error.gitStatus);
+            }
+            this.exit(error.exit);
+        }
+        if (error instanceof WorkEnvironmentSyncValidationError) {
+            this.error(error.message, {
+                exit: error.exit,
+                ...(error.suggestions === undefined ? {} : { suggestions: error.suggestions }),
+            });
+        }
+        throw error;
+    }
+    async runEnvironmentSync(syncFlags) {
+        await assertEnvironmentSyncDestOrgSelector({
+            abort: syncFlags.abort === true,
+            continue: syncFlags.continue === true,
+            destinationEnvironment: syncFlags['destination-environment'],
+            devOrgBranch: syncFlags['dev-org-branch'],
+            promotion: syncFlags.promotion,
+        });
+        return performWorkEnvironmentSync({
+            abort: syncFlags.abort === true,
+            cliBin: this.config.bin,
+            continue: syncFlags.continue === true,
+            deployment: syncFlags.deployment,
+            hooks: {
+                log: (message) => {
+                    this.display(() => {
+                        this.log(message);
+                    });
+                },
+                withSpinner: (message, action) => this.withSpinner(message, action),
+            },
+            json: this.jsonEnabled(),
+            ...(syncFlags['destination-credential'] === undefined
+                ? {}
+                : { destinationCredentialId: syncFlags['destination-credential'] }),
+            ...(syncFlags['destination-environment'] === undefined
+                ? {}
+                : { destinationEnvironment: syncFlags['destination-environment'] }),
+            ...(syncFlags['dev-org-branch'] === undefined ? {} : { devOrgBranch: syncFlags['dev-org-branch'] }),
+            ...(syncFlags['pipeline-id'] === undefined ? {} : { pipelineId: syncFlags['pipeline-id'] }),
+            ...(syncFlags.promotion === undefined ? {} : { promotion: syncFlags.promotion }),
+            ...(syncFlags['sf-alias'] === undefined ? {} : { sfAlias: syncFlags['sf-alias'] }),
+        });
+    }
+    async waitForDeploymentIfNeeded(result, syncFlags, startedAt) {
+        if (!syncFlags.wait || !shouldWaitForEnvironmentSyncDeployment(result) || result.promotion?.id === undefined) {
+            return;
+        }
+        this.display(() => {
+            this.log(ENVIRONMENT_SYNC_DEPLOYMENT_WAIT_MESSAGE);
+        });
+        try {
+            const deploymentJobMonitor = await this.withSpinner('Waiting for deployment execution', () => waitForPromotionDeploymentExecution({
+                hooks: {
+                    log: (message) => {
+                        this.display(() => {
+                            this.log(message);
+                        });
+                    },
+                    withSpinner: (message, action) => this.withSpinner(message, action),
+                },
+                promotionId: result.promotion.id,
+                timeoutSeconds: syncFlags['wait-timeout'],
+            }));
+            result.deploymentJobMonitor = deploymentJobMonitor;
+            result.wait = true;
+            this.display(() => {
+                this.log(formatWorkEnvironmentSyncDeploymentMonitor(deploymentJobMonitor));
+            });
+        }
+        catch (error) {
+            if (isPromotionRunExecutionError(error)) {
+                ;
+                error.oclif = { exit: 1 };
+            }
+            throw error;
+        }
+        this.logElapsed(startedAt);
+    }
 }
 //# sourceMappingURL=environment-sync.js.map

package/dist/commands/cicd/work/get.js

@@ -8,11 +8,11 @@ import { formatUserStoryDetail, } from '../../../lib/work-types.js';
 export default class WorkGet extends CicdCommand {
     static args = {
         id: Args.string({
-            description: 'User story ID (defaults to the active work item from `work set`)',
+            description: 'User story ID or name (defaults to the active work item from `work set`)',
             required: false,
         }),
     };
-    static description = 'Get a Copado user story by ID';
+    static description = 'Get a Copado user story by ID or name';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
         '<%= config.bin %> <%= command.id %> a0SKC000000CmZ2AU',

package/dist/commands/cicd/work/list.js

@@ -1,5 +1,5 @@
 import { CicdCommand } from '../../../lib/cicd-command.js';
-import { displayListPagination } from '../../../lib/list-pagination.js';
+import { displayListPagination, emitPaginatedListWarnings } from '../../../lib/list-pagination.js';
 import { getUserContext } from '../../../lib/user-context.js';
 import { buildWorkListFilters, workListFilterFlags } from '../../../lib/work-flags.js';
 import { fetchWorkItems } from '../../../lib/work-get.js';
@@ -42,6 +42,7 @@ export default class WorkList extends CicdCommand {
             }
         }
         const page = await this.withSpinner('Fetching user stories', () => fetchWorkItems(filters));
+        emitPaginatedListWarnings(this.warn.bind(this), page);
         this.display(() => {
             if (page.data.length === 0) {
                 this.log('No user stories found.');

package/dist/commands/cicd/work/test/apex.js

@@ -1,11 +1,11 @@
 import { Flags } from '@oclif/core';
 import { CicdCommand } from '../../../../lib/cicd-command.js';
-import { planWorkApexTestRun, recordWorkApexTestOutcome, WorkApexRerunError, } from '../../../../lib/work-apex-test-failures.js';
-import { DEFAULT_APEX_TEST_WAIT_MINUTES, formatWorkApexTestHuman, parseApexTestClassNames, runWorkApexTests, skippedWorkApexTestResult, validateApexTestWaitMinutes, WorkApexTestError, } from '../../../../lib/work-apex-test.js';
+import { executeWorkApexTestRun, WorkApexRerunError } from '../../../../lib/work-apex-test-failures.js';
+import { DEFAULT_APEX_TEST_WAIT_MINUTES, formatWorkApexTestHuman, parseApexTestClassNames, validateApexTestWaitMinutes, } from '../../../../lib/work-apex-test.js';
 export default class WorkTestApex extends CicdCommand {
     static description = [
+        'Legacy alias of `work test --gate apex`; prefer that form (it is what the sample quality-gate scripts call).',
         'Run specified Apex test classes via Salesforce CLI (`sf apex run test`) with code coverage.',
-        'Usually run from project-root local quality gates (`.agentia_quality_gates.sh` / `.agentia_quality_gates.cmd`) when those scripts are configured.',
         'When `--apex-test-classes` is omitted or empty, logs that no Apex tests were specified and exits without running Salesforce CLI.',
         'Failed runs save `.agentia/apex.tests.<user-story>.json`; successful runs delete that file.',
         '`--rerun-failed-apex-tests` runs the previously failed classes (optionally filtered by `--apex-test-classes`).',
@@ -34,6 +34,7 @@ export default class WorkTestApex extends CicdCommand {
             description: 'Minutes to wait for Salesforce CLI Apex test results',
         }),
     };
+    static hidden = true;
     async run() {
         const { flags } = await this.parse(WorkTestApex);
         const startedAt = Date.now();
@@ -46,42 +47,26 @@ export default class WorkTestApex extends CicdCommand {
         catch (error) {
             this.error(error.message, { exit: 2 });
         }
-        let plan;
         try {
-            plan = await planWorkApexTestRun({
-                requestedClassNames: classNames,
-                rerunFailed: flags['rerun-failed-apex-tests'] === true,
-            });
-        }
-        catch (error) {
-            if (error instanceof WorkApexRerunError) {
-                this.error(error.message, { exit: 2 });
-            }
-            throw error;
-        }
-        if (plan.kind === 'skip') {
-            const result = skippedWorkApexTestResult(waitMinutes);
-            this.display(() => {
-                this.log(plan.message);
-            });
-            this.logElapsed(startedAt);
-            return result;
-        }
-        try {
-            const result = await this.withSpinner(`Running Apex tests (${plan.classNames.join(', ')}), waiting up to ${waitMinutes} minute(s)`, () => runWorkApexTests({ classNames: plan.classNames, waitMinutes }));
-            await recordWorkApexTestOutcome({ failed: false, result, userStory: plan.userStory });
-            this.display(() => {
-                this.log(formatWorkApexTestHuman(result));
+            const result = await executeWorkApexTestRun({ requestedClassNames: classNames, rerunFailed: flags['rerun-failed-apex-tests'] === true, waitMinutes }, {
+                onResult: (apexResult) => {
+                    this.display(() => {
+                        this.log(formatWorkApexTestHuman(apexResult));
+                    });
+                },
+                onSkip: (message) => {
+                    this.display(() => {
+                        this.log(message);
+                    });
+                },
+                withSpinner: (message, action) => this.withSpinner(message, action),
             });
             this.logElapsed(startedAt);
             return result;
         }
         catch (error) {
-            if (error instanceof WorkApexTestError) {
-                await recordWorkApexTestOutcome({ failed: true, result: error.result, userStory: plan.userStory });
-                this.display(() => {
-                    this.log(formatWorkApexTestHuman(error.result));
-                });
+            if (error instanceof WorkApexRerunError) {
+                this.error(error.message, { exit: 2 });
             }
             throw error;
         }

package/dist/commands/cicd/work/test.js

@@ -2,27 +2,38 @@ import { Flags } from '@oclif/core';
 import path from 'node:path';
 import { CicdCommand } from '../../../lib/cicd-command.js';
 import { getCurrentBranch } from '../../../lib/git-worktree.js';
-import { LocalQualityGatesError, parseQualityGatesEnvAssignments, resolveLocalQualityGatesScript, } from '../../../lib/local-quality-gates.js';
-import { runWorkTestLocalQualityGates } from '../../../lib/stock-quality-gates.js';
-import { reportLocalQualityGatesFailure, reportLocalQualityGatesOutcome, } from '../../../lib/work-local-run-tests.js';
+import { isInsideQualityGatesScript, LocalQualityGatesError, parseQualityGatesEnvAssignments, resolveLocalQualityGatesScript, } from '../../../lib/local-quality-gates.js';
+import { formatDeclaredQualityGates, isApexOnlySelection, resolveQualityGateSelection, UnknownQualityGateError, } from '../../../lib/quality-gates.js';
+import { listLocalQualityGates, runWorkTestLocalQualityGates } from '../../../lib/stock-quality-gates.js';
+import { executeWorkApexTestRun, WorkApexRerunError } from '../../../lib/work-apex-test-failures.js';
+import { DEFAULT_APEX_TEST_WAIT_MINUTES, formatWorkApexTestHuman, parseApexTestClassNames, validateApexTestWaitMinutes, WorkApexTestError, } from '../../../lib/work-apex-test.js';
+import { reportApexGateRun, reportLocalQualityGatesFailure, reportLocalQualityGatesOutcome, } from '../../../lib/work-local-run-tests.js';
 import { extractUserStoryFromFeatureBranch } from '../../../lib/work-types.js';
 export default class WorkTest extends CicdCommand {
     static description = [
         'Run quality gates for the current work item.',
-        'With --local (the default) it runs project-root .agentia_quality_gates.sh (macOS/Linux) or',
-        '.agentia_quality_gates.cmd (Windows) when present.',
-        'When no project script exists it warns, runs the stock Agentia setup sample from a temporary file, then deletes that file.',
+        'Runs the project-root .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows);',
+        'when none exists it warns and runs the stock Agentia sample from a temporary file.',
+        'Every gate runs by default. Use --gate <id> (repeatable or comma-separated) to select gates; the selection is exported as AGENTIA_GATES.',
+        'Standard ids are apex, lint and lwc; scripts declare gates with `# agentia-gate: <id> - <description>` comments (see --list-gates).',
+        '`--gate apex` alone skips the script, runs the Apex tests directly and uploads the result to the work item (nested inside a script it does not upload; the outer run reports).',
         'With --cloud it runs remote Copado quality gates (not implemented yet).',
     ].join(' ');
     static examples = [
         '<%= config.bin %> <%= command.id %>',
-        '<%= config.bin %> <%= command.id %> --local --apex-test-classes=MyTest,OtherTest',
-        '<%= config.bin %> <%= command.id %> --local --rerun-failed-apex-tests',
+        '<%= config.bin %> <%= command.id %> --gate lint --gate lwc',
+        '<%= config.bin %> <%= command.id %> --gate apex --apex-test-classes=MyTest,OtherTest',
+        '<%= config.bin %> <%= command.id %> --list-gates',
         '<%= config.bin %> <%= command.id %> -e SKIP_LWC_TESTS=1 -e TOOL_API_KEY=secret',
         '<%= config.bin %> <%= command.id %> --json',
         '<%= config.bin %> <%= command.id %> --cloud',
     ];
     static flags = {
+        all: Flags.boolean({
+            default: false,
+            description: 'Run every gate in the quality-gates script (the default when no --gate is given).',
+            exclusive: ['gate', 'list-gates'],
+        }),
         'apex-test-classes': Flags.string({
             description: 'Comma-separated Apex test class names passed to local quality gates as AGENTIA_APEX_TEST_CLASSES',
         }),
@@ -35,13 +46,27 @@ export default class WorkTest extends CicdCommand {
             description: 'Extra environment variable for the quality-gate script as NAME=value. Repeatable. Applied before reserved AGENTIA_APEX_* variables.',
             multiple: true,
         }),
+        gate: Flags.string({
+            description: 'Run only this gate id (for example apex, lint, lwc or a custom id declared in the script). Repeatable or comma-separated. Exported to the script as AGENTIA_GATES.',
+            exclusive: ['all', 'list-gates'],
+            multiple: true,
+        }),
+        'list-gates': Flags.boolean({
+            default: false,
+            description: 'List the gates declared in the quality-gates script (or the stock sample) and exit.',
+        }),
         local: Flags.boolean({
             default: false,
             description: 'Run local project-root quality gates scripts. Used by default when --cloud is omitted.',
         }),
         'rerun-failed-apex-tests': Flags.boolean({
             default: false,
-            description: 'Pass AGENTIA_APEX_RERUN_FAILED=--rerun-failed-apex-tests to local quality gates so sample scripts forward that flag to work test apex.',
+            description: 'Pass AGENTIA_APEX_RERUN_FAILED=--rerun-failed-apex-tests to local quality gates so sample scripts forward that flag to the apex gate.',
+        }),
+        wait: Flags.integer({
+            char: 'w',
+            default: DEFAULT_APEX_TEST_WAIT_MINUTES,
+            description: 'Minutes to wait for Apex test results (only with --gate apex alone).',
         }),
     };
     async run() {
@@ -62,6 +87,19 @@ export default class WorkTest extends CicdCommand {
         catch (error) {
             this.error(error.message, { exit: 2 });
         }
+        let selection;
+        try {
+            selection = resolveQualityGateSelection({ all: flags.all, gates: flags.gate });
+        }
+        catch (error) {
+            this.error(error.message, { exit: 2 });
+        }
+        if (flags['list-gates']) {
+            return this.listGates();
+        }
+        if (isApexOnlySelection(selection)) {
+            return this.runApexGate({ classNames: flags['apex-test-classes'], rerunFailed: flags['rerun-failed-apex-tests'] === true, wait: flags.wait }, startedAt);
+        }
         let qualityGates;
         try {
             const scriptPath = resolveLocalQualityGatesScript();
@@ -78,6 +116,7 @@ export default class WorkTest extends CicdCommand {
             qualityGates = await runWorkTestLocalQualityGates({
                 apexTestClasses: flags['apex-test-classes'],
                 env: flags.env,
+                gates: selection.gates,
                 onWarning: (message) => this.warn(message),
                 rerunFailed: flags['rerun-failed-apex-tests'] === true,
             });
@@ -100,6 +139,9 @@ export default class WorkTest extends CicdCommand {
                     exit: error.exitCode || 1,
                 });
             }
+            if (error instanceof UnknownQualityGateError) {
+                this.error(error.message, { exit: 2 });
+            }
             throw error;
         }
         this.logElapsed(startedAt);
@@ -108,6 +150,35 @@ export default class WorkTest extends CicdCommand {
             qualityGates,
         };
     }
+    async listGates() {
+        const catalog = await listLocalQualityGates();
+        this.display(() => {
+            if (catalog.gates.length === 0) {
+                this.log('No gates declared. Add `# agentia-gate: <id> - <description>` comments to the quality-gates script.');
+                return;
+            }
+            this.log(`Gates declared in ${catalog.stock ? 'the stock sample' : path.basename(catalog.scriptPath)}:`);
+            this.log(formatDeclaredQualityGates(catalog.gates));
+        });
+        return { gates: catalog.gates, local: true, qualityGates: { ran: false, skipped: false } };
+    }
+    async reportApexGate(result, failed) {
+        if (isInsideQualityGatesScript()) {
+            return;
+        }
+        const workItem = await this.resolveWorkItemForReport();
+        if (workItem === undefined) {
+            this.warn('Failed to report local quality gates result: not on a feature/US-XXXX branch.');
+            return;
+        }
+        await reportApexGateRun({
+            failed,
+            onLog: (message) => this.display(() => this.log(message)),
+            onWarning: (message) => this.warn(message),
+            result,
+            workItem,
+        });
+    }
     async reportLocalFailure(error) {
         const workItem = await this.resolveWorkItemForReport();
         if (workItem === undefined) {
@@ -138,5 +209,39 @@ export default class WorkTest extends CicdCommand {
         const branch = await getCurrentBranch();
         return extractUserStoryFromFeatureBranch(branch);
     }
+    async runApexGate(options, startedAt) {
+        let requestedClassNames;
+        let waitMinutes;
+        try {
+            requestedClassNames = parseApexTestClassNames(options.classNames);
+            waitMinutes = validateApexTestWaitMinutes(options.wait);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 2 });
+        }
+        try {
+            const apex = await executeWorkApexTestRun({
+                requestedClassNames,
+                rerunFailed: options.rerunFailed,
+                waitMinutes,
+            }, {
+                onResult: (result) => this.display(() => this.log(formatWorkApexTestHuman(result))),
+                onSkip: (message) => this.display(() => this.log(message)),
+                withSpinner: (message, action) => this.withSpinner(message, action),
+            });
+            await this.reportApexGate(apex, false);
+            this.logElapsed(startedAt);
+            return { apex, local: true, qualityGates: { ran: apex.skipped !== true, skipped: false } };
+        }
+        catch (error) {
+            if (error instanceof WorkApexRerunError) {
+                this.error(error.message, { exit: 2 });
+            }
+            if (error instanceof WorkApexTestError) {
+                await this.reportApexGate(error.result, true);
+            }
+            throw error;
+        }
+    }
 }
 //# sourceMappingURL=test.js.map

package/dist/commands/cicd/work/update.js

@@ -7,11 +7,11 @@ import { workEndpoint } from '../../../lib/work-types.js';
 export default class WorkUpdate extends CicdCommand {
     static args = {
         id: Args.string({
-            description: 'User story ID (defaults to the active work item from `work set`)',
+            description: 'User story ID or name (defaults to the active work item from `work set`)',
             required: false,
         }),
     };
-    static description = 'Update a Copado user story by ID';
+    static description = 'Update a Copado user story by ID or name';
     static examples = [
         '<%= config.bin %> <%= command.id %> --title "Updated story"',
         '<%= config.bin %> <%= command.id %> --custom-field JIRA_Key__c=CICD-1',

package/dist/lib/defaults-store.js

@@ -14,6 +14,7 @@ const readGlobalConfigDocument = modules["defaults-store.js"]["readGlobalConfigD
 const readLastApexTestClassesSelected = modules["defaults-store.js"]["readLastApexTestClassesSelected"]
 const readLastBaseBranch = modules["defaults-store.js"]["readLastBaseBranch"]
 const readLastDevOrgBranch = modules["defaults-store.js"]["readLastDevOrgBranch"]
+const readLastEnvironmentSyncFeatureBranch = modules["defaults-store.js"]["readLastEnvironmentSyncFeatureBranch"]
 const readLastEnvironmentSyncName = modules["defaults-store.js"]["readLastEnvironmentSyncName"]
 const readLastFullMetadataSelected = modules["defaults-store.js"]["readLastFullMetadataSelected"]
 const readLastPermissionSelected = modules["defaults-store.js"]["readLastPermissionSelected"]
@@ -35,8 +36,9 @@ const updateGlobalConfigDocument = modules["defaults-store.js"]["updateGlobalCon
 const writeCredentialSyncReceipt = modules["defaults-store.js"]["writeCredentialSyncReceipt"]
 const writeDefaults = modules["defaults-store.js"]["writeDefaults"]
 const writeLastCommitSelections = modules["defaults-store.js"]["writeLastCommitSelections"]
+const writeLastEnvironmentSyncFeatureBranch = modules["defaults-store.js"]["writeLastEnvironmentSyncFeatureBranch"]
 const writeLastEnvironmentSyncName = modules["defaults-store.js"]["writeLastEnvironmentSyncName"]
 const writeLastWorkSelection = modules["defaults-store.js"]["writeLastWorkSelection"]
 const writeUpdateChannel = modules["defaults-store.js"]["writeUpdateChannel"]
 const writeUserContext = modules["defaults-store.js"]["writeUserContext"]
-export {DEFAULT_WORK_PUSH_RETRY_TIMEOUT_SECONDS, clearCredentialSyncReceipt, clearLastEnvironmentSyncName, clearLastKeysFromUserConfig, clearUserContext, getDefaultsStorePaths, isValidUserContext, migrateUserSettingsFromProjectConfig, readCredentialSyncReceipt, readDefaults, readEnableLocalPromote, readGlobalConfigDocument, readLastApexTestClassesSelected, readLastBaseBranch, readLastDevOrgBranch, readLastEnvironmentSyncName, readLastFullMetadataSelected, readLastPermissionSelected, readLastPullRequestBaseUrl, readLastWorkItem, readLastWorkItemId, readLastWorkItemTitle, readSkipNestedMetadataDetection, readSkipPullRequest, readUpdateChannel, readUserContext, readWorkPushRetryTimeoutSeconds, resetDefaultsStorePathsForTests, resolveDefaults, setDefaultsStorePathsForTests, setDefaultsStoreProjectRoot, unsetDefaults, updateGlobalConfigDocument, writeCredentialSyncReceipt, writeDefaults, writeLastCommitSelections, writeLastEnvironmentSyncName, writeLastWorkSelection, writeUpdateChannel, writeUserContext};
+export {DEFAULT_WORK_PUSH_RETRY_TIMEOUT_SECONDS, clearCredentialSyncReceipt, clearLastEnvironmentSyncName, clearLastKeysFromUserConfig, clearUserContext, getDefaultsStorePaths, isValidUserContext, migrateUserSettingsFromProjectConfig, readCredentialSyncReceipt, readDefaults, readEnableLocalPromote, readGlobalConfigDocument, readLastApexTestClassesSelected, readLastBaseBranch, readLastDevOrgBranch, readLastEnvironmentSyncFeatureBranch, readLastEnvironmentSyncName, readLastFullMetadataSelected, readLastPermissionSelected, readLastPullRequestBaseUrl, readLastWorkItem, readLastWorkItemId, readLastWorkItemTitle, readSkipNestedMetadataDetection, readSkipPullRequest, readUpdateChannel, readUserContext, readWorkPushRetryTimeoutSeconds, resetDefaultsStorePathsForTests, resolveDefaults, setDefaultsStorePathsForTests, setDefaultsStoreProjectRoot, unsetDefaults, updateGlobalConfigDocument, writeCredentialSyncReceipt, writeDefaults, writeLastCommitSelections, writeLastEnvironmentSyncFeatureBranch, writeLastEnvironmentSyncName, writeLastWorkSelection, writeUpdateChannel, writeUserContext};

package/dist/lib/function-list.js

@@ -0,0 +1,3 @@
+import {modules} from './runtime.js';
+const fetchFunctions = modules["function-list.js"]["fetchFunctions"]
+export {fetchFunctions};

package/dist/lib/git-worktree.js

@@ -3,6 +3,7 @@ const NAME_STATUS_PRETTY_FORMAT = modules["git-worktree.js"]["NAME_STATUS_PRETTY
 const abortMerge = modules["git-worktree.js"]["abortMerge"]
 const checkoutBranch = modules["git-worktree.js"]["checkoutBranch"]
 const checkoutFeatureBranch = modules["git-worktree.js"]["checkoutFeatureBranch"]
+const checkoutPathsFromRef = modules["git-worktree.js"]["checkoutPathsFromRef"]
 const checkoutPreferredBranch = modules["git-worktree.js"]["checkoutPreferredBranch"]
 const commitAllTrackedChanges = modules["git-worktree.js"]["commitAllTrackedChanges"]
 const commitAllowEmpty = modules["git-worktree.js"]["commitAllowEmpty"]
@@ -27,9 +28,11 @@ const isAncestor = modules["git-worktree.js"]["isAncestor"]
 const isInsideGitWorkTree = modules["git-worktree.js"]["isInsideGitWorkTree"]
 const isMergeInProgress = modules["git-worktree.js"]["isMergeInProgress"]
 const isSafeGitBranchName = modules["git-worktree.js"]["isSafeGitBranchName"]
+const listDiffNamesBetween = modules["git-worktree.js"]["listDiffNamesBetween"]
 const listDiffNamesVsHead = modules["git-worktree.js"]["listDiffNamesVsHead"]
 const listPendingChanges = modules["git-worktree.js"]["listPendingChanges"]
 const listStagedChanges = modules["git-worktree.js"]["listStagedChanges"]
+const listTreeFileNames = modules["git-worktree.js"]["listTreeFileNames"]
 const listUnmergedFiles = modules["git-worktree.js"]["listUnmergedFiles"]
 const localBranchExists = modules["git-worktree.js"]["localBranchExists"]
 const mergeFfOnly = modules["git-worktree.js"]["mergeFfOnly"]
@@ -49,4 +52,4 @@ const restoreFeatureBranch = modules["git-worktree.js"]["restoreFeatureBranch"]
 const restoreHeadPaths = modules["git-worktree.js"]["restoreHeadPaths"]
 const setGitExecForTests = modules["git-worktree.js"]["setGitExecForTests"]
 const stageAndCommit = modules["git-worktree.js"]["stageAndCommit"]
-export {NAME_STATUS_PRETTY_FORMAT, abortMerge, checkoutBranch, checkoutFeatureBranch, checkoutPreferredBranch, commitAllTrackedChanges, commitAllowEmpty, commitCurrentMerge, commitStagedChanges, countCommitsSince, createAndCheckoutBranch, fetchAndCheckoutBranch, fetchOriginBranch, fetchOriginBranchIfExists, formatGitExecError, getCommitsNameStatus, getCurrentBranch, getFileAtRef, getGitRepoRoot, getHeadCommitId, getHumanGitStatus, getMergeBase, getRemoteUrl, hasUnpushedCommits, isAncestor, isInsideGitWorkTree, isMergeInProgress, isSafeGitBranchName, listDiffNamesVsHead, listPendingChanges, listStagedChanges, listUnmergedFiles, localBranchExists, mergeFfOnly, mergeNoFf, mergeNoFfNoCommit, mergeTheirsIgnoreSpaceChange, originBranchRef, originFetchRefspec, parseNameOnly, parsePorcelainPaths, pullOriginBranch, pushOriginBranch, pushOriginBranches, resetGitExecForTests, resetHardHead, restoreFeatureBranch, restoreHeadPaths, setGitExecForTests, stageAndCommit};
+export {NAME_STATUS_PRETTY_FORMAT, abortMerge, checkoutBranch, checkoutFeatureBranch, checkoutPathsFromRef, checkoutPreferredBranch, commitAllTrackedChanges, commitAllowEmpty, commitCurrentMerge, commitStagedChanges, countCommitsSince, createAndCheckoutBranch, fetchAndCheckoutBranch, fetchOriginBranch, fetchOriginBranchIfExists, formatGitExecError, getCommitsNameStatus, getCurrentBranch, getFileAtRef, getGitRepoRoot, getHeadCommitId, getHumanGitStatus, getMergeBase, getRemoteUrl, hasUnpushedCommits, isAncestor, isInsideGitWorkTree, isMergeInProgress, isSafeGitBranchName, listDiffNamesBetween, listDiffNamesVsHead, listPendingChanges, listStagedChanges, listTreeFileNames, listUnmergedFiles, localBranchExists, mergeFfOnly, mergeNoFf, mergeNoFfNoCommit, mergeTheirsIgnoreSpaceChange, originBranchRef, originFetchRefspec, parseNameOnly, parsePorcelainPaths, pullOriginBranch, pushOriginBranch, pushOriginBranches, resetGitExecForTests, resetHardHead, restoreFeatureBranch, restoreHeadPaths, setGitExecForTests, stageAndCommit};