@copado/agentia-cli 1.3.0 → 1.5.0-rc.0

package/templates/skills/agentia-cicd/references/work.md

@@ -36,7 +36,7 @@ Use this path when the change exists in the local repository:
 1. Discover and inspect: `agentia cicd work list --assigned-to-me --json`, then `agentia cicd work get <id-or-name> --json`.
 2. Activate: `agentia cicd work set <id-or-name> --json`. This fetches the configured base branch, fetches the Story feature branch when it exists on origin, then checks out `feature/<story-name>` from that remote branch when present (otherwise from the base), and records the story, base branch, dev org branch, and pull-request context in `.agentia/config.user.json`. Use `--base-branch <branch>` only when intentionally overriding the Pipeline default. If the JSON result has `status: "warning"` (missing pipeline or credential), show that `message`, do not assume a feature branch was created, and note that branch keys (`lastBaseBranch`, `lastDevOrgBranch`, `lastPullRequestBaseUrl`) were cleared while `lastWorkItemId`/`lastWorkItem`/`lastWorkItemTitle` were recorded — stop until the Story setup is fixed; publish and submit will not work. If the Story source credential differs from the project default, work set warns with the current credential and environment and does not PATCH; use `agentia cicd work update <id> --source-credential <credential-id>` to change it.
 3. Implement with Salesforce CLI, VS Code, or an IDE. Stage and commit with `git add` / `git commit`. Do not use `agentia cicd cloud commit` for local Git work.
-4. Run project-owned gates: `agentia cicd work test --json`. This runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from the repository root when present. If those files are missing, it warns and runs `agentia cicd work test apex` via the stock sample from a temporary file. Local tests can be slow; pass `--apex-test-classes=MyTest,OtherTest` for faster, earlier Apex checks.
+4. Run project-owned gates: `agentia cicd work test --json`. This runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from the repository root when present. If those files are missing, it warns and runs the stock sample from a temporary file. Local tests can be slow; pass `--apex-test-classes=MyTest,OtherTest` for faster, earlier Apex checks.
 5. Register and synchronize: `agentia cicd work publish --json`. A plain `git push` does not register a Copado Commit or merge the feature branch into the recorded dev org branch. Pass `--permissions` and `--full-metadata` when nested detection is not enough.
 6. Validate and open the merge-request flow: `agentia cicd work submit --json`. Submit runs the local gates unless `--skip-local-tests` is explicit, pushes ahead commits, waits if the last pending related job is a Commit template, and submits with validate-only behavior. `--skip-pull-request` skips opening the compare URL.
 7. Only with explicit approval to promote and deploy, run `agentia cicd work submit --deploy --json` (or `--done`). `work done` is a compatibility alias.
@@ -51,7 +51,7 @@ Use this path when Copado should retrieve metadata from a configured source envi
 1. Inspect the Story and pass its Salesforce ID explicitly when possible. An active Story from `work set` is optional, not a prerequisite for the cloud operation.
 2. Start a cloud commit with `agentia cicd cloud commit <story-id> ... --json`. Use the simple metadata flags for one change, or `--file`/`--stdin` for a multi-change request. Always pass `--metadata-category` (use `SFDX` for Salesforce metadata). With `--file`/`--stdin`, each change requires `c` (or `category`).
 3. Let the command wait for its Job Execution by default. After a timeout, use the returned execution ID with `agentia cicd job get` and `agentia cicd job log get`; do not immediately submit a duplicate commit.
-4. When explicitly approved to promote an existing Promotion, use `agentia cicd cloud promote <story-id> --json`; add `--deploy` only for promote-and-deploy. This is independent of local `work submit`.
+4. When explicitly approved to promote, use `agentia cicd cloud promote <story-id> --json`; add `--deploy` only for promote-and-deploy. Creates a forward Draft promotion when none contains the story (`createdPromotion` in JSON/MCP). This is independent of local `work submit`.
 
 Cloud commit checks Story readiness and source credentials before submission. Avoid concurrent cloud commits to one Story. Treat `--recreate-feature-branch` as destructive because it can overwrite Story-branch work.
 
@@ -60,20 +60,20 @@ Cloud commit checks Story readiness and source credentials before submission. Av
 
 | Command            | Use For                                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `work list`        | Find candidate stories                         | Use `--assigned-to-me`, `--status`, `--project-name`, `--name`, pagination flags.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `work list`        | Find candidate stories                         | Use `--assigned-to-me`, `--status`, `--project-name`, `--name`, pagination flags. An expired or invalid `--cursor` (`SF-014`) self-heals to page 1 with a `warnings` entry in human/`--json`/MCP.                                                                                                                                                                                                                                                                                                    |
 | `work get [ID]`    | Read story details                             | ID is optional after `work set`. Human output redacts OAuth signatures; JSON preserves structured fields including subscriber `customFields` (`apiName`, `label`, `type`, `value`, `displayValue`, `updateable`, optional `options`). `--committed-metadata` also includes the Story committed metadata list as `committedMetadata` in the result.                                                                                                                                                |
 | `work create`      | Create a story                                 | Use `--title`, project/team/assignee/theme fields, specs, and short acceptance criteria. Write subscriber fields with repeatable `--custom-field ApiName=value` (MCP: `customFields: [{ apiName, value }]`). `--source-credential` sends `sourceEnvironment` as null so Salesforce assigns the environment.                                                                                                                                                                                          |
 | `work update [ID]` | Mutate story fields or status                  | ID is optional after `work set`. Acceptance criteria must be fewer than 255 chars. Same `--custom-field` / MCP `customFields` write shape as create; update-only custom fields is allowed. `--source-credential` sends `sourceEnvironment` as null.                                                                                                                                                                                                                                                  |
 | `work set ID`      | Mark active and prepare branch                 | Fetches the base branch and, when present, the remote feature branch; creates/checks out `feature/<story-name>` from `origin/feature` when that ref exists, otherwise from the base; stores local context. A gateway warning prints the message, skips git, clears branch keys, and records work-item id/name/title. Warns without PATCHing when the Story credential differs from the project default; use `work update --source-credential` to change it. `--none` clears every `last*` key and checks out `lastBaseBranch`, else `main`, else `master`. |
 | `cloud commit`     | Copado cloud metadata commit                   | Prefer `agentia cicd cloud commit`. Requires `--metadata-category` (or `c`/`category` per `--file` change); use `SFDX` for Salesforce metadata. For local Git work, use `git commit` then `work publish`. `cicd work commit` remains a hidden compatibility alias.                                                                                                                                                                                                                                  |
 | `work publish`     | Publish local commits and register with Copado | Requires active story context and clean tree. Accepts `--permissions` and `--full-metadata` when nested detection is not enough. `work push` is a compatibility alias.                                                                                                                                                                                                                                                                                                                               |
-| `work test`        | Run local quality gate scripts                 | `--local` is default. Runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from repo root. If missing, warns and runs the stock setup sample from a temp file. `--cloud` is not implemented yet.                                                                                                                                                                                                                                                                                         |
-| `work test apex`   | Run named Apex test classes                    | Optional `--apex-test-classes`. Omit or pass empty to log a skip and exit 0 without calling Salesforce CLI. `--rerun-failed-apex-tests` reruns classes from `.agentia/apex.tests.<user-story>.json`. Optional `--wait` minutes (default 60). Usually invoked from `.agentia_quality_gates.*`. |
+| `work test`        | Run local quality gate scripts                 | `--local` is default. Runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from repo root. If missing, warns and runs the stock setup sample from a temp file. `--gate <id>` (repeatable) runs only selected gates, `--all` runs everything (default), `--list-gates` lists gates declared via `# agentia-gate: <id> - <description>` in the script. Standard ids: `apex`, `lint`, `lwc`; custom ids allowed. The selection is exported as `AGENTIA_GATES`. `--gate apex` alone skips the script and runs the Apex tests directly (`--apex-test-classes`, `--rerun-failed-apex-tests`, `--wait`). `--cloud` is not implemented yet.                                                                                                                                                                                                                                                                                         |
+| `work test apex`   | Legacy alias of `work test --gate apex`        | Optional `--apex-test-classes`. Omit or pass empty to log a skip and exit 0 without calling Salesforce CLI. `--rerun-failed-apex-tests` reruns classes from `.agentia/apex.tests.<user-story>.json`. Optional `--wait` minutes (default 60). Prefer `work test --gate apex`. |
 | `work submit`      | Submit for review/validation or promote        | Runs local gates unless `--skip-local-tests`; can push ahead commits. Waits up to 5 minutes when the last pending related job template contains `Commit`. `--skip-pull-request` skips opening the MR URL. `--done` and `--deploy` match Copado UI Submit when promoting.                                                                                                                                                                                                                             |
 | `work done`        | Compatibility alias                            | Prefer `work submit --done`; both promote and deploy rather than validate-only.                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `work promote`     | Experimental local promotion                   | Skips Quality Gates. Requires `enableLocalPromote: true` in `.agentia/config.json`. Merges `feature/<name>` into `promotion/<promotionName>`. Use `--backpromote --destination-branch` for back promotions; `--continue` after conflict resolution.                                                                                                                                                                                                                                                  |
-| `work environment-sync` | Sync next-env commits onto dest/dev       | Back-promotes every story behind the destination environment. Use `--destination-environment` or `--dev-org-branch`. On conflict, stores `lastEnvironmentSyncName` so `--continue` / `--abort` can omit `--promotion` (cleared on success, abort, and `work set`).                                                                                                                                                                                                                                  |
-| `cloud promote`    | Story-centric cloud promotion run              | Use `--deploy` for merge and deploy. Prefer this over local `work promote` unless you explicitly enabled local promote.                                                                                                                                                                                                                                                                                                                                                                              |
+| `work environment-sync` | Sync next-env commits onto dest/dev (experimental) | Experimental. Back-promotes every story behind the destination environment onto `promotion/<name>` (from dest org), then merges that branch into dest and pushes both. On a feature branch, unpublished commits stop the command (`work publish` first); after a successful sync, feature files changed vs base are refreshed from dest and you are told to re-check and publish again. On conflict, resolve on `promotion/<name>` (or dest) and `--continue` / `--abort` (`lastEnvironmentSyncName` can omit `--promotion`; cleared on success, abort, and `work set`). Success/abort call `promote-action/complete` with `--deployment` resolved to `none`\|`local`\|`cloud` (`auto` → `local` when every change is Add and `--sf-alias` is set, else `cloud`). Local deploy runs on the dest org branch (before feature refresh) via `sf project deploy start --ignore-conflicts` (Add-only); failures include full `package.xml` and raw `sf` stdout/stderr (human and `--json`). After success with cloud deployment, waits for the JobExecution by default (`--no-wait` / `--wait-timeout`). |
+| `cloud promote`    | Story-centric cloud promotion run              | Auto-creates a forward Draft promotion when none contains the story. Use `--deploy` for merge and deploy. Prefer this over local `work promote` unless you explicitly enabled local promote. |
 | `work status [ID]` | Check story and related executions             | Useful after submit, promote, or commit jobs.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `work open [ID]`   | Open story in browser                          | CLI-only browser helper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
@@ -94,7 +94,7 @@ agentia cicd work submit --json
 
 `--permissions` on publish names metadata that Copado should treat as Retrieve Only. List the components whose access changed, not the permission set or profile files; naming those parent types is rejected. Use `--full-metadata` only for `Profile`, `PermissionSet`, `MutingPermissionSet`, `CustomObject`, or `CustomObjectTranslation` when that complete file should travel; other types are rejected. Both flags apply to that publish only.
 
-`work test` and `work submit` take `--apex-test-classes` when you want the local gate script to receive them as `AGENTIA_APEX_TEST_CLASSES`. Sample quality-gate scripts pass that value to `work test apex`.
+`work test` and `work submit` take `--apex-test-classes` when you want the local gate script to receive them as `AGENTIA_APEX_TEST_CLASSES`. Sample quality-gate scripts pass that value to the apex gate (`work test --gate apex`). Run one gate with `work test --gate lint` (MCP `gates: ["lint"]`); `work submit` always runs every gate. The sample lint gate scans only branch-changed files (diff vs `AGENTIA_BASE_BRANCH` merge-base, plus uncommitted/untracked); set `LINT_SCOPE=all` for a full scan, which is also the fallback outside git.
 
 `work publish` detects nested metadata across the full branch diff from the merge base to `HEAD`, applies Copado environment-variable and YAML replacements, registers every commit in the range, and merges into the recorded dev org branch. Review unexpected Retrieve Only, Full Metadata, or nested-deletion output before continuing.
 
@@ -107,15 +107,29 @@ agentia cicd cloud commit <story-id> --message "Commit AccountService" --metadat
 agentia cicd cloud commit <story-id> --file commit-request.json --json
 ```
 
-`--metadata-category` is required on simple flag input. Each `--file`/`--stdin` change requires `c` (or `category`). For Salesforce metadata, use `SFDX`. Without `c:SFDX`, Copado deploy logs can report "Salesforce changes not found."
+Example `commit-request.json` for multiple components:
 
-For a cloud promotion, the Story must already belong to a Promotion:
+```json
+{
+  "message": "Account service and trigger",
+  "changes": [
+    {"a": "Add", "c": "SFDX", "n": "AccountService", "t": "ApexClass"},
+    {"a": "Add", "c": "SFDX", "n": "AccountTrigger", "t": "ApexTrigger"}
+  ]
+}
+```
+
+`--metadata-category` is required on simple flag input (one component only). Each `--file`/`--stdin` change requires `c` (or `category`). For Salesforce metadata, use `SFDX`. Without `c:SFDX`, Copado deploy logs can report "Salesforce changes not found."
+
+For cloud promotion from a User Story:
 
 ```sh
 agentia cicd cloud promote <story-id> --json
 agentia cicd cloud promote <story-id> --deploy --json
 ```
 
+When no Promotion contains the story, `cloud promote` and MCP `agentia_cloud_promote` create one automatically before running.
+
 Cloud commit and promotion wait for Job Executions by default and return nonzero on failed or timed-out jobs while preserving diagnostic IDs. If a Promotion reaches Merge Conflict, resolve it and resume the original execution; do not start a replacement run.
 
 ## Subscriber Custom Fields
@@ -154,7 +168,7 @@ Prefer explicit flags for standard step types. Use `--config-json`, `--file`, or
 ## Gotchas
 
 - `work test` is not CRT. For Robot Framework execution, use the `agentia-testing` skill.
-- `work test apex` runs named Apex classes. Local quality gates (`.agentia_quality_gates.*`) usually call it with `-t "${AGENTIA_APEX_TEST_CLASSES}"` and `${AGENTIA_APEX_RERUN_FAILED}` (empty or `--rerun-failed-apex-tests`); an empty class list skips Apex without failing the script. `--rerun-failed-apex-tests` reruns classes saved in `.agentia/apex.tests.<user-story>.json` after a failure. Direct use is for a targeted rerun without the rest of the gates.
+- `work test --gate apex` runs named Apex classes directly (the legacy `work test apex` is an alias). Sample local quality gates (`.agentia_quality_gates.*`) call it with `--apex-test-classes="${AGENTIA_APEX_TEST_CLASSES}"` and `${AGENTIA_APEX_RERUN_FAILED}` (empty or `--rerun-failed-apex-tests`); an empty class list skips Apex without failing the script. `--rerun-failed-apex-tests` reruns classes saved in `.agentia/apex.tests.<user-story>.json` after a failure. Run it directly for a targeted rerun without the rest of the gates.
 - Local Git work uses `git commit` then `work publish`. Cloud `cloud commit` is a separate path.
 - `work submit` may push ahead commits, but the local flow still needs story and branch context from `work set`.
 - `work submit --done` (or `--deploy`) promotes/deploys. Do not run it unless the user explicitly asked to promote or finish the story.

package/templates/skills/agentia-testing/references/browser-testing.md

@@ -49,7 +49,6 @@ agentia testing browser stop --project <project-id> --yes --json
 | `testing browser execute [job-id]` | Run keywords using `--line "..."` (repeatable), `--keyword <name> --arg <val>`, `--file <path>`, or `--stdin`. Pass `--raw` to skip `.robot` section parsing. |
 | `testing browser inspect [job-id]` | Fetch `GET /api/system-state` (`url`, `timestamp`, `changeOrigin`, `systemState` interactive element annotations). Add `--dom` with `--output <file>` or `--json` to stream and reassemble `document.documentElement.outerHTML` over the terminal WebSocket. |
 | `testing browser screenshot [job-id]` | Save the current viewport PNG (including teal detection bounding boxes) to `--output <path>`. |
-| `testing browser reports [job-id]` | Fetch Robot Framework `log.html`, `report.html`, and `output.xml` metadata, or write them to `--output-dir <dir>`. |
 | `testing browser set-options [job-id]` | Set the full recorder option block (`--[no-]enable`, `--[no-]scroll-text`, `--[no-]healing-context`, `--[no-]hover-text`, `--[no-]system-state`, `--[no-]verify-text`, `--[no-]table-keywords`). Unspecified options default to `false`. |
 | `testing browser view` | Print (`--no-open`, default for agents) or open the CRT browser session URL. Always use `--no-open` unless the user explicitly asks to open the browser. |
 | `testing browser recorder [job-id]` | Connect to the session WebSocket, enable backend recording, and stream captured interactions and executed keywords as Robot Framework lines (or JSON lines with `--json`). Flags: `--output <file.robot>`, `--no-enable`, `--force` (reclaim stale lock), `--debug`. |

package/templates/skills/agentia-testing/references/tests.md

@@ -46,7 +46,7 @@ agentia testing job runs logs <build-id> --project <project-id> --job <job-id> -
 | Variables | `testing variable list|get|create|update|delete` |
 | User parameters | `testing user-parameter list|get|create|update|delete` |
 | Data tables | `testing data-table list|get|create|update|delete|export` |
-| Browser testing | `testing browser start|stop|status|execute|inspect|screenshot|reports|set-options|history|view|recorder` |
+| Browser testing | `testing browser start|stop|status|execute|inspect|screenshot|set-options|history|view|recorder` |
 
 `testing job` is the single namespace for test definitions and their runs. Commands directly under `job` take a job ID; `job runs get|logs|abort` take a build/run ID plus `--job`. On `testing job create` and `testing job update`, `--[no-]show-video-params` (`showVideoParams` in the API/MCP) enables or disables Video Streaming and Recording capabilities when running the test job. The older `testing create|update|status|logs|run`, `testing test ...`, `testing build ...`, and `testing job files|upload|download` forms are deprecated aliases that still execute but warn when used: `create` maps to `job create`, `update` to `job files upload` (file operations, not `job update`), `status`, `build list`, and `build latest` to `job runs list`, `build get` to `job runs get`, and `build search|logs|abort` to `job runs search|logs|abort`.
 

package/dist/commands/testing/browser/reports.js

@@ -1,33 +0,0 @@
-import { Flags } from '@oclif/core';
-import { AgentiaCommand } from '../../../lib/agentia-command.js';
-import { testingBrowserCommonFlags, testingBrowserOptionalJobArg } from '../../../lib/testing-browser-command.js';
-import { getTestingLiveReports } from '../../../lib/testing-browser-operations.js';
-export default class TestingBrowserReports extends AgentiaCommand {
-    static args = testingBrowserOptionalJobArg;
-    static deprecateAliases = true;
-    static description = 'List or save report artifacts from an active CRT browser session';
-    static examples = [
-        '<%= config.bin %> <%= command.id %> --project <project-id>',
-        '<%= config.bin %> <%= command.id %> --project <project-id> --output-dir ./reports',
-    ];
-    static flags = {
-        ...testingBrowserCommonFlags,
-        'output-dir': Flags.string({ description: 'Directory for log.html, report.html, and output.xml.' }),
-    };
-    static hiddenAliases = ['testing:live:reports'];
-    async run() {
-        const { args, flags } = await this.parse(TestingBrowserReports);
-        const result = await this.withSpinner('Reading CRT browser reports', () => getTestingLiveReports({
-            jobId: args['job-id'],
-            outputDir: flags['output-dir'],
-            projectId: flags.project,
-            sessionId: flags['session-id'],
-        }));
-        this.display(() => {
-            for (const file of result.files)
-                this.log(`${file.name}: ${file.bytes} bytes${file.path === undefined ? '' : ` -> ${file.path}`}`);
-        });
-        return result;
-    }
-}
-//# sourceMappingURL=reports.js.map