@copado/agentia-cli 1.0.0-beta.0 → 1.0.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +40 -0
- package/README.md +505 -329
- package/dist/commands/auth/get.js +45 -136
- package/dist/commands/auth/set.js +3 -3
- package/dist/commands/cicd/cloud/commit.js +252 -0
- package/dist/commands/cicd/cloud/promote.js +139 -0
- package/dist/commands/cicd/health-check.js +77 -0
- package/dist/commands/cicd/work/commit.js +10 -324
- package/dist/commands/cicd/work/environment-sync.js +120 -0
- package/dist/commands/cicd/work/get.js +25 -4
- package/dist/commands/cicd/work/promote.js +93 -97
- package/dist/commands/cicd/work/set.js +4 -2
- package/dist/commands/cicd/work/submit.js +7 -0
- package/dist/lib/ai-config.js +2 -1
- package/dist/lib/auth-status-format.js +6 -0
- package/dist/lib/defaults-store.js +2 -1
- package/dist/lib/git-sizer.js +5 -0
- package/dist/lib/git-worktree.js +16 -1
- package/dist/lib/health-check.js +3 -0
- package/dist/lib/mcp/command-id.js +1 -0
- package/dist/lib/mcp/health-check-tools.js +16 -0
- package/dist/lib/mcp/server.js +2 -1
- package/dist/lib/mcp/tool-annotations.js +265 -0
- package/dist/lib/mcp/tools.js +3 -0
- package/dist/lib/mcp/work-tools.js +96 -78
- package/dist/lib/metadata-pathspecs.js +4 -0
- package/dist/lib/metadataRegistry.json +5427 -0
- package/dist/lib/promotion-types.js +4 -1
- package/dist/lib/runtime.js +1 -1
- package/dist/lib/work-environment-sync-errors.js +4 -0
- package/dist/lib/work-environment-sync-ready.js +18 -0
- package/dist/lib/work-environment-sync.js +42 -0
- package/dist/lib/work-promote-deploy.js +13 -0
- package/dist/lib/work-promote-errors.js +5 -0
- package/dist/lib/work-promote.js +12 -0
- package/dist/lib/work-set-selection.js +2 -1
- package/dist/lib/work-submit-ahead-behind.js +8 -0
- package/dist/lib/work-types.js +2 -1
- package/oclif.manifest.json +2725 -2282
- package/package.json +5 -2
- package/templates/skills/agentia-cicd/SKILL.md +2 -2
- package/templates/skills/agentia-cicd/references/promotions.md +8 -8
- package/templates/skills/agentia-cicd/references/work.md +16 -14
package/package.json
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"@xmldom/xmldom": "^0.9.12",
|
|
14
14
|
"exceljs": "^4.4.0",
|
|
15
15
|
"semver": "^7.8.5",
|
|
16
|
-
"tty-table": "^
|
|
16
|
+
"tty-table": "^7.0.1",
|
|
17
17
|
"uuid": "^14.0.1",
|
|
18
18
|
"ws": "^8.21.3",
|
|
19
19
|
"zod": "^4.4.3"
|
|
@@ -159,6 +159,9 @@
|
|
|
159
159
|
"cicd:user": {
|
|
160
160
|
"description": "Manage Copado users"
|
|
161
161
|
},
|
|
162
|
+
"cicd:cloud": {
|
|
163
|
+
"description": "Run Copado cloud commit and promotion operations"
|
|
164
|
+
},
|
|
162
165
|
"cicd:work": {
|
|
163
166
|
"description": "Manage Copado user stories"
|
|
164
167
|
},
|
|
@@ -198,7 +201,7 @@
|
|
|
198
201
|
}
|
|
199
202
|
},
|
|
200
203
|
"type": "module",
|
|
201
|
-
"version": "1.0.0-beta.
|
|
204
|
+
"version": "1.0.0-beta.2",
|
|
202
205
|
"x-agentia-protected-build": true,
|
|
203
206
|
"x-agentia-protected-files": [
|
|
204
207
|
"dist/lib/runtime.js"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentia-cicd
|
|
3
|
-
description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools: user stories,
|
|
3
|
+
description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools: user stories, cloud commit/promote, work publish/submit/done, promotion runs and conflicts, job executions, environments, credentials, pipelines, stages, and release data templates. Use it whenever the user asks an agent to operate Copado CICD from a terminal, IDE, or headless workflow.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
<!-- Agentia managed skill file: agentia setup skills -->
|
|
@@ -31,7 +31,7 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
|
|
|
31
31
|
|
|
32
32
|
- Use Salesforce record IDs or generated names read from Copado. Do not invent story names, promotion IDs, job IDs, credential IDs, or pipeline IDs.
|
|
33
33
|
- Keep human output off stdout in JSON workflows. Prefer `--json`, then parse the result object.
|
|
34
|
-
- For local project work, keep the tracked working tree clean before commands that require it: `work set`, `work publish`, and `work submit`. If `work set` returns `status: "warning"`, show the message and do not assume a feature branch
|
|
34
|
+
- For local project work, keep the tracked working tree clean before commands that require it: `work set`, `work publish`, and `work submit`. If `work set` returns `status: "warning"`, show the message and do not assume a feature branch was created; branch keys are cleared and the work item id/name/title are still recorded in config.user.json.
|
|
35
35
|
- Treat `cicd job` as Copado CICD JobExecution. It is different from CRT `testing job`.
|
|
36
36
|
- Treat `cicd work test` as local quality gates (`--local` is the default). It is different from CRT `testing test run`.
|
|
37
37
|
- Treat `cicd work test apex` as the Apex test runner that local quality gates (`.agentia_quality_gates.*`) usually call when those scripts are configured. It can also be invoked directly. It is different from CRT.
|
|
@@ -2,17 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
# CICD Promotions Reference
|
|
4
4
|
|
|
5
|
-
Use this reference for `agentia cicd promotion ...`, `agentia cicd promotion conflict ...`, and `agentia cicd
|
|
5
|
+
Use this reference for `agentia cicd promotion ...`, `agentia cicd promotion conflict ...`, and `agentia cicd cloud promote`.
|
|
6
6
|
|
|
7
7
|
## Entry Points
|
|
8
8
|
|
|
9
9
|
| Command | Starts From | Use When |
|
|
10
10
|
| --- | --- | --- |
|
|
11
11
|
| `agentia cicd promotion run <promotion-id>` | Promotion ID | You already know the Promotion record and want explicit merge or merge-and-deploy control. |
|
|
12
|
-
| `agentia cicd
|
|
12
|
+
| `agentia cicd cloud promote [story-id]` | User Story | You want Agentia to resolve the story's Promotion before running it. |
|
|
13
13
|
| `agentia cicd work submit --done` | Active User Story branch | The story is approved and should move to the next stage (Copado UI Submit promote). |
|
|
14
14
|
|
|
15
|
-
Prefer `
|
|
15
|
+
Prefer `cloud promote` when the user talks about a story. Prefer `promotion run` when the user provides a Promotion ID.
|
|
16
16
|
|
|
17
17
|
## Promotion Commands
|
|
18
18
|
|
|
@@ -22,19 +22,19 @@ Prefer `work promote` when the user talks about a story. Prefer `promotion run`
|
|
|
22
22
|
| `promotion get ID` | Inspect one promotion | Read this before running, resuming, or resolving conflicts. |
|
|
23
23
|
| `promotion run ID` | Preflight and submit a run | Requires `--operation merge` or `--operation merge_and_deploy` unless `--resume` is used. |
|
|
24
24
|
| `promotion open ID` | Open in browser | CLI-only navigation helper. |
|
|
25
|
-
| `
|
|
25
|
+
| `cloud promote [ID]` | Story-centric run | Use `--deploy` for merge and deploy; use `--promotion-id` if the story has multiple promotions. |
|
|
26
26
|
|
|
27
27
|
Example:
|
|
28
28
|
|
|
29
29
|
```sh
|
|
30
30
|
agentia cicd promotion list --work-id <story-id> --json
|
|
31
31
|
agentia cicd promotion run <promotion-id> --operation merge_and_deploy --json
|
|
32
|
-
agentia cicd
|
|
32
|
+
agentia cicd cloud promote <story-id> --deploy --json
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
## Resume And Wait
|
|
36
36
|
|
|
37
|
-
`promotion run` and `
|
|
37
|
+
`promotion run` and `cloud promote` can poll job execution status. Use the default wait for normal agent workflows and lower it only when the user wants a fire-and-follow-up flow.
|
|
38
38
|
|
|
39
39
|
Use `--resume <job-execution-id>` to resume the original execution after conflict resolution instead of starting a new `/run` request.
|
|
40
40
|
|
|
@@ -52,7 +52,7 @@ Read conflict content before manual resolution. Do not invent resolved content;
|
|
|
52
52
|
|
|
53
53
|
## Gotchas
|
|
54
54
|
|
|
55
|
-
- Promotion IDs are not User Story IDs. Use `
|
|
56
|
-
- `--deploy` on `
|
|
55
|
+
- Promotion IDs are not User Story IDs. Use `cloud promote` if you only have the story.
|
|
56
|
+
- `--deploy` on `cloud promote` maps to promotion operation `merge_and_deploy`; without it, the default is merge only.
|
|
57
57
|
- `--recreate-promotion-branch` is a sensitive run option and should be paired with explicit user intent and `--yes` when required.
|
|
58
58
|
- If conflicts exist, resolve them first and then resume the same execution.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# CICD Work Reference
|
|
4
4
|
|
|
5
|
-
Use this reference for `agentia cicd work
|
|
5
|
+
Use this reference for `agentia cicd work ...`, `agentia cicd cloud ...`, and matching MCP tools such as `agentia_work_get`, `agentia_cloud_commit`, `agentia_work_publish`, and `agentia_work_submit`.
|
|
6
6
|
|
|
7
7
|
## Choose One Workflow
|
|
8
8
|
|
|
@@ -13,8 +13,8 @@ Local and cloud work are separate delivery paths. Do not continue a cloud commit
|
|
|
13
13
|
Use this path when the change exists in the local repository:
|
|
14
14
|
|
|
15
15
|
1. Discover and inspect: `agentia cicd work list --assigned-to-me --json`, then `agentia cicd work get <id-or-name> --json`.
|
|
16
|
-
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 stop until the Story setup is fixed
|
|
17
|
-
3. Implement with Salesforce CLI, VS Code, or an IDE. Stage and commit with `git add` / `git commit`. Do not use `agentia cicd
|
|
16
|
+
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.
|
|
17
|
+
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.
|
|
18
18
|
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.
|
|
19
19
|
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.
|
|
20
20
|
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.
|
|
@@ -28,9 +28,9 @@ Use this path when the change exists in the local repository:
|
|
|
28
28
|
Use this path when Copado should retrieve metadata from a configured source environment instead of using local Git changes:
|
|
29
29
|
|
|
30
30
|
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.
|
|
31
|
-
2. Start a cloud commit with `agentia cicd
|
|
31
|
+
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. Salesforce metadata requires `--metadata-category SFDX`.
|
|
32
32
|
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.
|
|
33
|
-
4. When explicitly approved to promote an existing Promotion, use `agentia cicd
|
|
33
|
+
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`.
|
|
34
34
|
|
|
35
35
|
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.
|
|
36
36
|
|
|
@@ -43,14 +43,16 @@ Cloud commit checks Story readiness and source credentials before submission. Av
|
|
|
43
43
|
| `work get [ID]` | Read story details | ID is optional after `work set`. Human output redacts OAuth signatures; JSON preserves structured fields. |
|
|
44
44
|
| `work create` | Create a story | Use `--title`, project/team/assignee/theme fields, specs, and short acceptance criteria. `--source-credential` sends `sourceEnvironment` as null so Salesforce assigns the environment. |
|
|
45
45
|
| `work update [ID]` | Mutate story fields or status | ID is optional after `work set`. Acceptance criteria must be fewer than 255 chars. `--source-credential` sends `sourceEnvironment` as null. |
|
|
46
|
-
| `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 and
|
|
47
|
-
| `
|
|
46
|
+
| `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`. |
|
|
47
|
+
| `cloud commit` | Copado cloud metadata commit | For local Git work, use `git commit` then `work publish`. `work commit` is a hidden compatibility alias. |
|
|
48
48
|
| `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. |
|
|
49
49
|
| `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. |
|
|
50
50
|
| `work test apex` | Run named Apex test classes | Required `--apex-test-classes`. Optional `--wait` minutes (default 60). Usually invoked from `.agentia_quality_gates.*` when local quality gates are configured. |
|
|
51
51
|
| `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. |
|
|
52
52
|
| `work done` | Compatibility alias | Prefer `work submit --done`; both promote and deploy rather than validate-only. |
|
|
53
|
-
| `work promote` |
|
|
53
|
+
| `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. |
|
|
54
|
+
| `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`; `--continue --promotion` after pathspec conflicts. |
|
|
55
|
+
| `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. |
|
|
54
56
|
| `work status [ID]` | Check story and related executions | Useful after submit, promote, or commit jobs. |
|
|
55
57
|
| `work open [ID]` | Open story in browser | CLI-only browser helper. |
|
|
56
58
|
|
|
@@ -80,8 +82,8 @@ agentia cicd work submit --json
|
|
|
80
82
|
Use cloud commits when Copado should retrieve metadata itself:
|
|
81
83
|
|
|
82
84
|
```sh
|
|
83
|
-
agentia cicd
|
|
84
|
-
agentia cicd
|
|
85
|
+
agentia cicd cloud commit <story-id> --message "Commit AccountService" --metadata-name AccountService --metadata-type ApexClass --metadata-category SFDX --json
|
|
86
|
+
agentia cicd cloud commit <story-id> --file commit-request.json --json
|
|
85
87
|
```
|
|
86
88
|
|
|
87
89
|
For Salesforce metadata, include `--metadata-category SFDX`. Without the SFDX category, Copado deploy logs can report "Salesforce changes not found."
|
|
@@ -89,8 +91,8 @@ For Salesforce metadata, include `--metadata-category SFDX`. Without the SFDX ca
|
|
|
89
91
|
For a cloud promotion, the Story must already belong to a Promotion:
|
|
90
92
|
|
|
91
93
|
```sh
|
|
92
|
-
agentia cicd
|
|
93
|
-
agentia cicd
|
|
94
|
+
agentia cicd cloud promote <story-id> --json
|
|
95
|
+
agentia cicd cloud promote <story-id> --deploy --json
|
|
94
96
|
```
|
|
95
97
|
|
|
96
98
|
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.
|
|
@@ -117,9 +119,9 @@ Prefer explicit flags for standard step types. Use `--config-json`, `--file`, or
|
|
|
117
119
|
|
|
118
120
|
- `work test` is not CRT. For Robot Framework execution, use the `agentia-testing` skill.
|
|
119
121
|
- `work test apex` runs named Apex classes. Local quality gates (`.agentia_quality_gates.*`) usually call it when `AGENTIA_APEX_TEST_CLASSES` is set. Direct use is for a targeted rerun without the rest of the gates.
|
|
120
|
-
- Local Git work uses `git commit` then `work publish`. Cloud `
|
|
122
|
+
- Local Git work uses `git commit` then `work publish`. Cloud `cloud commit` is a separate path.
|
|
121
123
|
- `work submit` may push ahead commits, but the local flow still needs story and branch context from `work set`.
|
|
122
124
|
- `work submit --done` (or `--deploy`) promotes/deploys. Do not run it unless the user explicitly asked to promote or finish the story.
|
|
123
|
-
- `
|
|
125
|
+
- `cloud promote` is not the next step after a local git commit; local delivery uses `work publish` and `work submit`.
|
|
124
126
|
- `work delete` is destructive; read the story and confirm intent first.
|
|
125
127
|
|