@copado/agentia-cli 1.0.0-beta.5 → 1.0.0-beta.7

package/package.json

@@ -35,7 +35,22 @@
   ],
   "homepage": "https://developer.copado.com/docs",
   "keywords": [
-    "oclif"
+    "agentia",
+    "copado",
+    "salesforce",
+    "sfdc",
+    "devops",
+    "cicd",
+    "cli",
+    "oclif",
+    "mcp",
+    "ai",
+    "robotic",
+    "testting",
+    "metadata",
+    "pipeline",
+    "promotion",
+    "deployment"
   ],
   "license": "SEE LICENSE IN LICENSE.md",
   "main": "dist/index.js",
@@ -79,6 +94,24 @@
       "auth": {
         "description": "Manage authentication credentials"
       },
+      "adv": {
+        "description": "Manage Copado Pipelines Advanced deployments"
+      },
+      "adv:auth": {
+        "description": "Inspect Pipelines Advanced authentication"
+      },
+      "adv:component": {
+        "description": "Manage Pipelines Advanced deployment components"
+      },
+      "adv:deployment": {
+        "description": "Manage Pipelines Advanced deployments and runs"
+      },
+      "adv:job": {
+        "description": "Inspect Pipelines Advanced deployment jobs"
+      },
+      "adv:organization": {
+        "description": "Inspect Pipelines Advanced organizations"
+      },
       "cicd": {
         "description": "Manage Copado CICD workflows"
       },
@@ -202,7 +235,7 @@
     }
   },
   "type": "module",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "x-agentia-protected-build": true,
   "x-agentia-protected-files": [
     "dist/lib/runtime.js"

package/templates/AGENTS.md

@@ -16,7 +16,7 @@ Read records before changing them and use IDs returned by Copado. Do not skip `w
 
 Load exactly one copy of each applicable Agentia skill. Prefer the client-specific root when available (`.cursor/skills` in Cursor or `.claude/skills` in Claude); otherwise use `.agents/skills`.
 
-- `agentia-cicd/SKILL.md`: Copado stories, commits, publish, submit, done, promotions, jobs, environments, pipelines, and data.
+- `agentia-cicd/SKILL.md`: Copado stories, commits, publish, submit, done, promotions, jobs, environments, pipelines, Slack notification configure, and data.
 - `agentia-testing/SKILL.md`: Copado Robotic Testing operations.
 - `agentia-ai/SKILL.md`: Copado AI operations.
 

package/templates/skills/agentia-adv/SKILL.md

@@ -0,0 +1,22 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+# Agentia Pipelines Advanced Skill
+
+Use this skill when working with Copado Pipelines Advanced through the Agentia CLI.
+
+## Commands
+
+- Configure global authentication with `agentia auth set --adv <PAT>`, or add `--local` for current-project/current-user scope. Both store the PAT in the keychain and auto-discover the Pipelines Advanced endpoint unless `--adv-base-url` is supplied.
+- Use `agentia adv organization list|get|validate` to inspect accessible organizations and verify connectivity.
+- Use `agentia adv deployment list|get|create|options|validate|deploy|quick-deploy|cancel` to define deployments, update options, and run or stop deployments.
+- Use `agentia adv component types|list|refresh|selected|add|remove` to discover metadata types and manage selected deployment components.
+- Use `agentia adv job get|list|wait` to inspect and poll deployment runs.
+
+## Safety
+
+- Never pass PATs to `agentia adv ...` commands. Use `agentia auth set --adv` or project-scoped auth.
+- Prefer `--json` for automation and agents.
+- For component JSON files, use `--json-file`; `--json` remains the standard Agentia output flag.
+- In JSON or non-interactive CLI runs, deploy, quick deploy, cancel, and auth removal require `--yes`. The matching MCP deployment mutations require `confirm: true`; validation does not.
+- Treat a nonzero exit from a waited run as failure. JSON errors retain the command transaction ID and failed waited runs include `error.result.job`.
+
+See `references/pipelines-advanced.md` for command flows and examples.

package/templates/skills/agentia-adv/references/pipelines-advanced.md

@@ -0,0 +1,50 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+# Pipelines Advanced Reference
+
+## Setup
+
+```sh
+agentia auth set --adv <PAT>
+agentia adv auth status --json
+```
+
+Authentication is global by default. Add `--local` to `auth set` for current-project/current-user scope; the PAT still stays in the keychain. Remove global auth with `auth unset --adv [--global]` or local auth with `auth unset --adv --local`; JSON/non-interactive removal requires `--yes`. Use `--adv-base-url` only for approved non-standard endpoints.
+
+## Deployment Journey
+
+```sh
+agentia adv organization list --json
+agentia adv organization validate <org-id>
+agentia adv deployment create --name release-1 --source-org <source-org-id> --target-org <target-org-id>
+agentia adv deployment options <deployment-id> --set deployOptionsIgnoreWarnings=false
+agentia adv component types --json
+agentia adv component list --flow <deployment-id> --type ApexClass --json
+agentia adv component add <deployment-id> --component ApexClass/Foo
+agentia adv deployment validate <deployment-id> --wait --json
+agentia adv deployment deploy <deployment-id> --yes --wait --json
+agentia adv job get <deployment-id> --json
+```
+
+## Notes
+
+- `deployment list` exposes the API `flowId` as `id`; do not use the raw list row link id.
+- `deployment list` returns at most 500 rows and has no filter.
+- `deployment options` reads current options, merges `--set` or `--file`, and sends the complete options object because the API replaces the entire object. `--set` converts exact booleans/null and finite JavaScript Number forms, including hex and exponent notation. Supported test levels include `NO_TEST_RUN`, `RUN_SPECIFIED_TESTS`, `RUN_LOCAL_TESTS`, and `RUN_ALL_TESTS_IN_ORG`.
+- `component types` can report the same type name in several views.
+- `component add` and `component remove` accept `--component Type/Name`. Add supports a text `--file`; remove does not. `--json-file` must be a bare array and accepts `{type, fullName}`, rows extracted from `result.components`, or `{nodeType: {name}, fullName}`. Remove returns the submitted array in `requested`, not a count.
+- `validate`, `deploy`, `quick-deploy`, and `cancel` are asynchronous; use `--wait` or `agentia adv job wait`.
+- `deploy`, `quick-deploy`, and `cancel` prompt interactively. JSON and non-interactive runs require `--yes`; matching MCP tools require `confirm: true`.
+- `quick-deploy --backup` invokes the server's `backupThenDeploy` action instead of a quick deploy.
+- Polling defaults to 3 seconds with a 3600-second timeout. Failed or cancelled waited runs exit nonzero; JSON errors include the normalized job.
+- `job list` excludes validation runs. Page numbering starts at 0, page size defaults to 50, and the server caps it at 100.
+- API JSON errors expose sanitized code/status/method/URL/name/message plus `transactionId`; validation errors expose name/message plus `transactionId`.
+
+## MCP Argument Names
+
+- Organizations and deployments use `id`; selected/components/jobs use `deploymentId`; component list/refresh use `flow`.
+- Deployment validate: `id`, optional `wait`, `interval`, `timeout` (no confirmation).
+- Deploy: the validation inputs plus `confirm: true`.
+- Quick deploy: deploy inputs plus optional `backup`.
+- Cancel: `id`, `confirm: true`, optional `wait`, `interval`, `timeout`.
+- Component add/remove: `deploymentId`, `components` (`Type/Name` strings or `{type, fullName, excluded?}` objects).
+- Job list: `deploymentId`, optional `page`, `pageSize`.

package/templates/skills/agentia-cicd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentia-cicd
-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.
+description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools: user stories (including current/active story context), cloud commit/promote, work publish/submit/done, promotion runs and conflicts, job executions, environments, credentials, pipelines, stages, Slack pipeline notification subscriptions, and release data templates. Use it whenever the user asks an agent to operate Copado CICD from a terminal, IDE, or headless workflow.
 ---
 
 <!-- Agentia managed skill file: agentia setup skills -->
@@ -25,10 +25,12 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - Copado JobExecution lookup, actions, logs, and monitoring: [references/jobs.md](references/jobs.md)
 - Copado environments, environment credentials, and browser authentication: [references/environments-and-credentials.md](references/environments-and-credentials.md)
 - Pipelines, environment connections, stages, and stage connections: [references/pipelines.md](references/pipelines.md)
+- Slack notification subscriptions on a pipeline (`agentia_notification_configure` / CLI): [references/notifications.md](references/notifications.md)
 - Release data templates, records, matching, sync, dataset files, and data commits: [references/data.md](references/data.md)
 
 ## General Rules
 
+- When the user means the **current story**, **current user story**, **active story**, **story context**, or similar without giving an ID, resolve context first with `agentia cicd work get --json` (no positional story ID). Use the returned user story (`result`) for follow-up work—any fields the task needs (for example `id`, `name`, `title`, `status`, specs, pipeline or environment IDs), not only identifiers. If the command fails (for example no active work item from `work set`), report the CLI error to the user and stop; do not guess, list stories, or pick a substitute unless the user asks you to.
 - Use Salesforce record IDs or generated names read from Copado. Do not invent story names, promotion IDs, job IDs, credential IDs, or pipeline IDs.
 - Keep human output off stdout in JSON workflows. Prefer `--json`, then parse the result object.
 - 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.

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

@@ -0,0 +1,79 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Notifications Reference
+
+Use this reference for `agentia cicd notification configure` and `agentia cicd notification get`.
+
+Prefer `agentia_notification_configure` and `agentia_notification_get` when Agentia MCP is available. Otherwise use the CLI commands and add `--json` when an agent will parse or reuse the result.
+
+Notifications are Slack-only (`providers: ["slack"]`). **Configure** creates or updates one subscription for the **current Copado user** on a **pipeline** for a chosen **event**. **Get** reads the authenticated user's stored subscriptions for that pipeline (sanitized; no raw system-property metadata).
+
+## Workflow
+
+1. Confirm CICD auth with `agentia auth get --cicd --json` (or process overrides). Never log API keys.
+2. Resolve the pipeline Salesforce Id with `agentia cicd pipeline list` and/or `agentia cicd pipeline get <pipeline-id> --json`. See [pipelines.md](pipelines.md).
+3. **Read** existing subscriptions with `agentia_notification_get` (MCP) or `notification get -p <pipeline-id>` (CLI), optionally with `--json`.
+4. **Write** one subscription with `agentia_notification_configure` (MCP) or `notification configure` (CLI) with all required fields/flags.
+5. Report `result.pipelineId`, subscription fields, and `result.subscription` / table rows (no secrets in output).
+
+## Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `notification get` | List the current user's Slack subscriptions on a pipeline | Requires `--pipeline-id` / `-p` only. |
+| `notification configure` | Subscribe the current user to a Slack destination for one pipeline event | All configure flags below are required. |
+
+## `notification get` flags
+
+| Flag | Values | Notes |
+| --- | --- | --- |
+| `--pipeline-id` / `-p` | 15- or 18-character Salesforce Id | Same validation as configure. |
+
+JSON `result`: `{ pipelineId, subscriptions[] }` where each subscription has `event`, `providers`, `destinationType`, `destinationId`, and `subscription`. Empty subscriptions print a clear human message and exit 0.
+
+## `notification configure` required flags
+
+| Flag | Values | Notes |
+| --- | --- | --- |
+| `--pipeline-id` / `-p` | 15- or 18-character Salesforce Id | Letters, digits, underscores only. Read from `pipeline list` / `pipeline get`. |
+| `--event` | See event list below | Quote values that contain spaces (e.g. `"Test_Not Started"`). |
+| `--destination-type` | `user` \| `channel` | Slack destination kind. |
+| `--destination-id` | Slack user or channel id or name | Examples: `U0123ABCD`, `C0123ABCD`, `@jane`, `#alerts`. Cannot be empty or whitespace-only. |
+| `--subscription` | `user` \| `all` | Who receives this notification for the event on the pipeline. |
+
+## Notification Events
+
+`Promotion_Success`, `Promotion_Failed`, `Promotion_Conflict`, `Failed_Promotion_Creation`, `Deploy_Success`, `Deploy_Failed`, `Commit_Failed`, `Successful_Snapshot`, `Failed_Snapshot`, `ManualTask_Assigned`, `Test_Success`, `Test_Failed`, `Test_Cancelled`, `Test_Not Started`, `Quality_Gate_Success`, `Quality_Gate_Failed`, `Quality_Gate_Cancelled`, `Quality_Gate_Not Started`, `Create_Package_Success`, `Create_Package_Failure`, `Generate_Package_Version_Success`, `Generate_Package_Version_Failure`, `Import_Package_Success`, `Import_Package_Failure`, `Publish_Package_Success`, `Publish_Package_Failure`.
+
+## Examples
+
+```sh
+agentia cicd pipeline get <pipeline-id> --json
+agentia cicd notification get -p <pipeline-id> --json
+# MCP: agentia_notification_get with pipelineId
+agentia cicd notification configure --pipeline-id <pipeline-id> --event Promotion_Failed --destination-type user --destination-id U0123ABCD --subscription user --json
+agentia cicd notification configure -p <pipeline-id> --event Commit_Failed --destination-type channel --destination-id C0123ABCD --subscription all --json
+agentia cicd notification configure --pipeline-id <pipeline-id> --event "Test_Not Started" --destination-type user --destination-id @jane --subscription user --json
+```
+
+## JSON Result
+
+With `--json`, stdout is structured data only (no spinner or human summary). Configure echoes the configured subscription in `result`, including `providers: ["slack"]`. Get returns `result.pipelineId` and `result.subscriptions`.
+
+## Errors And Validation
+
+| Situation | What to do |
+| --- | --- |
+| Invalid or empty `--pipeline-id` | Fix before the gateway runs; use a valid 15- or 18-character pipeline Id from Copado. |
+| Current user ID unavailable (get) | Ensure CICD auth is configured; the command exits before querying system properties. |
+| Empty `--destination-id` (configure) | Provide a non-empty Slack user or channel identifier. |
+| `NTF-003` | Slack destination does not match `--destination-type`; recheck `destination-id` and `destination-type`. |
+| `NTF-004` | Pipeline id rejected upstream; re-read `pipeline get` and retry with the correct Id. |
+| Other gateway errors | Surface the message without inventing alternate APIs or leaking credentials. |
+
+## Gotchas
+
+- Pipeline notification setup is separate from `agentia auth set --cicd` (CLI API key) and from `cicd credential` (Salesforce org credentials on environments).
+- `destination-type user` with `subscription user` is the usual personal alert pattern; `subscription all` widens audience for the event on that pipeline.
+- Event names with spaces must be quoted in the shell.
+- Get reads pipeline-scoped system properties for the authenticated user only; there is no cross-user list command.

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

@@ -4,6 +4,25 @@
 
 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`.
 
+## Current Story Context
+
+Treat these as requests for the locally active Copado user story (from a prior `work set`), not a specific ID the user supplied:
+
+- current story, current user story, active story, this story
+- story context, work item context, what story am I on
+
+**Resolve before continuing** (status updates, publish/submit, deployment steps, promotions tied to “this” story, and similar):
+
+```sh
+agentia cicd work get --json
+```
+
+Omit the positional story ID only; keep `--json` so agents parse the `result` object. With MCP, call `agentia_work_get` without an `id` when available.
+
+**On success:** treat the JSON `result` user story as the story context for the rest of the task. Reuse any returned fields later commands or flags need (identifiers, names, status, acceptance criteria, functional or technical specs, pipeline or environment references, and similar)—not only `id` and `name`.
+
+**On failure:** the CLI exits when no active work item is recorded (typical message: no active work item; suggestion to run `agentia cicd work set <id>`). Tell the user that no current story is set, include the sanitized error text, and stop. Do not invent an ID, run `work list` to pick one, or continue the original request until the user sets context or provides an explicit story ID.
+
 ## Choose One Workflow
 
 Local and cloud work are separate delivery paths. Do not continue a cloud commit with local `work publish` or `work submit`: those commands inspect and push the local Git feature branch.