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

package/package.json

@@ -235,7 +235,7 @@
     }
   },
   "type": "module",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "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, Slack notification configure, and data.
+- `agentia-cicd/SKILL.md`: Copado stories, commits, publish, submit, done, promotions, jobs, Functions, Job Templates, 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

@@ -1,4 +1,10 @@
+---
+name: agentia-adv
+description: Use this skill when working with Copado Pipelines Advanced through the Agentia CLI or MCP, including PAT auth via auth set --adv, organizations, deployments, components, and deployment jobs. Use it for experimental ADV workflows separate from standard CICD pipeline commands.
+---
+
 <!-- Agentia managed skill file: agentia setup skills -->
+
 # Agentia Pipelines Advanced Skill
 
 Use this skill when working with Copado Pipelines Advanced through the Agentia CLI.
@@ -19,4 +25,4 @@ Use this skill when working with Copado Pipelines Advanced through the Agentia C
 - 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.
+See [references/pipelines-advanced.md](references/pipelines-advanced.md) for command flows and examples.

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

@@ -29,22 +29,22 @@ agentia adv job get <deployment-id> --json
 
 - `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`.
+- `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. Unknown option names can be silently dropped; verify saved options with `deployment get --json`. Rejected values can return HTTP 400 with no provider detail. The server owns the complete option catalog.
 - `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`.
+- `validate`, `deploy`, `quick-deploy`, and `cancel` are asynchronous; use `--wait` or `agentia adv job wait`. A timeout stops only the CLI wait; the run continues and the JSON error includes the last observed job.
 - `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.
+- `quick-deploy --backup` invokes the server's `backupThenDeploy` action instead of a quick deploy. The CLI refuses a quick deploy only when the latest job explicitly reports `canQuickDeploy: false`; validate with tests first.
 - 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`.
+- API JSON errors expose sanitized code/status/method/URL/name/message plus `transactionId`; validation errors expose only safe fields plus `transactionId`, never parser state or command configuration.
 
 ## 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).
+- Organizations use `id`. All deployment-scoped tools use canonical `deploymentId`; legacy `id` and `flow` aliases remain accepted but cannot disagree.
+- Deployment validate: `deploymentId`, 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`.
+- Cancel: `deploymentId`, `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 (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.
+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, Copado Functions, Job Templates, 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 -->
@@ -23,6 +23,8 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - User stories, git commits, cloud commits, publish, submit, done, quality gates, and deployment steps: [references/work.md](references/work.md)
 - Promotion lookup, run, resume, merge conflicts, and story-centric promotion: [references/promotions.md](references/promotions.md)
 - Copado JobExecution lookup, actions, logs, and monitoring: [references/jobs.md](references/jobs.md)
+- Copado Functions lifecycle, remote run/results, and local Docker run: [references/functions.md](references/functions.md)
+- Copado Job Templates (`cicd template`, not data templates): [references/templates.md](references/templates.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)
@@ -35,6 +37,8 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - 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.
 - Treat `cicd job` as Copado CICD JobExecution. It is different from CRT `testing job`.
+- Treat `cicd function` as Copado Function definitions and runs. It is different from JobExecution (`cicd job`) and Job Templates (`cicd template`).
+- Treat `cicd template` as Copado Job Templates via `/release/jobs/templates`. It is different from Release Data Templates (`cicd data template`).
 - Treat `cicd work test` as local quality gates (`--local` is the default). It is different from CRT `testing test run`.
 - Treat `cicd work test apex` as the Apex test runner that local quality gates (`.agentia_quality_gates.*`) usually call. An empty `--apex-test-classes` list skips Salesforce CLI. It can also be invoked directly. It is different from CRT.
 - Treat `auth` credentials as keychain/API credentials and `cicd credential` records as Copado environment credentials.

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

@@ -0,0 +1,148 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Functions Reference
+
+Use this reference for Copado Function commands under `agentia cicd function ...`.
+
+Prefer `agentia_function_*` MCP tools when available. Otherwise use the CLI and add `--json` when an agent will parse or reuse the result.
+
+`cicd function` manages Copado Function definitions and remote runs through the CICD gateway. It is not the same as `cicd job` (JobExecution), CRT `testing job`, or Job Templates (`cicd template`).
+
+## Operating Rules
+
+- Confirm CICD auth before gateway-backed commands (`defaults`, `list`, `get`, `upsert`, `delete`, `run`, `result …`).
+- Use Function API names returned by Copado. Do not invent API names for delete or run.
+- Prefer reading `function get <api-name> --json` before upsert or delete.
+- `function run` starts a remote run and returns a result Id; it does not wait for completion.
+- `function run-local` runs a script in Docker on the local machine. It does not call the CICD gateway and does not persist a Copado Function.
+- Never pass secrets as `--parameter` values for `run` or `run-local`. Parameter values can appear in command results and Docker argv.
+
+## Choose A Workflow
+
+| Intent | Workflow |
+| --- | --- |
+| Scaffold metadata/script without persisting | Defaults |
+| Find or inspect a Function | List And Get |
+| Create or update a Function | Upsert |
+| Execute a persisted Function remotely | Remote Run And Results |
+| Validate a script in Docker without Copado | Local Docker Run |
+| Remove a Function | Delete |
+
+## Defaults
+
+1. Run `function defaults --name <display-name> --json`.
+2. Optional: set `--runtime` (`bash` default) and `--image-name` (`copado-function-core:v1` default).
+3. Use the returned scaffold as a starting point for upsert. Nothing is written to Salesforce.
+
+```sh
+agentia cicd function defaults --name MyFunction --runtime python --json
+```
+
+## List And Get
+
+1. Discover candidates with `function list --json` (Custom only by default).
+2. Use `--type all` when Standard Functions must be included.
+3. Filter with `--name`, `--image-name`, and `--size` when needed.
+4. Inspect one Function with `function get <api-name> --json`.
+5. Use `function open <function-id>` only for browser navigation (CLI-only; not an MCP tool).
+
+```sh
+agentia cicd function list --json
+agentia cicd function list --type all --name MyFunction --json
+agentia cicd function get myFunction --json
+```
+
+## Upsert
+
+1. Read the current Function when updating an existing API name.
+2. Choose one payload source:
+   - `--file <function.json>` for a full JSON payload (cannot combine with individual payload flags), or
+   - individual flags with script from `--script` or `--script-file`.
+3. Optional: `--parameters-file` for a parameters array; also description, Apex class, callback, flow handler, timeout, image, size, type, and version.
+4. Run `function upsert <api-name> ... --json`.
+5. Read the Function back with `function get <api-name> --json`.
+
+Defaults when using individual flags: display name = API name, runtime `bash`, image `copado-function-core:v1`, size `S`, type `Custom`, version `1`.
+
+```sh
+agentia cicd function upsert myFunction --name "My Function" --script-file ./functions/my-function.sh --runtime bash --json
+agentia cicd function upsert myFunction --file ./function.json --json
+```
+
+## Remote Run And Results
+
+1. Confirm the Function exists with `function get <api-name> --json`.
+2. Start a run with `function run <api-name> --json`.
+3. Pass repeatable `--parameter key=value` values when needed.
+4. Optional: `--context-id` and `--deploy-first` when the user requests pre-run deployment or an execution context.
+5. Capture `result.resultId` from JSON output.
+6. Poll `function result get <result-id> --json` until status is terminal.
+7. Fetch logs with `function result log get <result-id> [--type <log-type>] --json` when diagnosis is needed.
+
+```sh
+agentia cicd function run myFunction --parameter env=qa --json
+agentia cicd function result get <result-id> --json
+agentia cicd function result log get <result-id> --type stdout --json
+```
+
+## Local Docker Run
+
+1. Ensure Docker is installed, running, and on `PATH`.
+2. Provide a readable `.sh`, `.js`, or `.py` script.
+3. Run `function run-local <script-path> --json`.
+4. Override `--image` when the default Copado image cannot be pulled.
+5. Optional: `--cwd`, `--runtime`, `--platform`, and repeatable `--parameter key=value`.
+6. In JSON mode, inspect `.result.exitCode` (do not assume CLI process exit reflects the container).
+
+```sh
+agentia cicd function run-local ./functions/my-function.sh --cwd . --parameter ENV=dev --json
+agentia cicd function run-local ./functions/my-function.py --runtime python --platform linux/amd64 --image my-registry/function-core:v1 --json
+```
+
+Local execution validates the script in a container only. It does not upsert, deploy, or invoke a persisted remote Function.
+
+## Delete
+
+1. Confirm the exact API name with `function get` or `function list`.
+2. Confirm destructive intent with the user.
+3. Run `function delete <api-name> --json`.
+
+Deletion is immediate and has no confirmation prompt.
+
+## Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `function defaults` | Scaffold defaults | Gateway call; not persisted. |
+| `function list` | Find Functions | Default `--type custom`; filters for name, image, size. |
+| `function get API_NAME` | Inspect one Function | Read before upsert/delete/run. |
+| `function upsert API_NAME` | Create or update | `--file` or script flags; script required without `--file`. |
+| `function delete API_NAME` | Delete a Function | Destructive; confirm API name. |
+| `function run API_NAME` | Start remote run | Returns result Id; does not wait. |
+| `function result get RESULT_ID` | Poll run status | Caller-controlled polling. |
+| `function result log get RESULT_ID` | Read run logs | Optional `--type` filter. |
+| `function run-local SCRIPT` | Docker local run | No gateway; no Salesforce write. |
+| `function open ID` | Open in browser | CLI-only. |
+
+## MCP Tools
+
+| Tool | Maps To |
+| --- | --- |
+| `agentia_function_defaults` | `function defaults` |
+| `agentia_function_list` | `function list` |
+| `agentia_function_get` | `function get` |
+| `agentia_function_upsert` | `function upsert` |
+| `agentia_function_delete` | `function delete` |
+| `agentia_function_run` | `function run` |
+| `agentia_function_result_get` | `function result get` |
+| `agentia_function_result_log_get` | `function result log get` |
+| `agentia_function_run_local` | `function run-local` |
+
+MCP uses structured fields (for example `apiName`, `parameters` object) instead of CLI flag names.
+
+## Gotchas
+
+- Function API name, Function Salesforce Id, and Function result Id are different values. Use the Id type each command documents.
+- `AGENTIA_USE_LOCAL_GATEWAY=true` redirects gateway-backed Function commands to a contributor local gateway. That is not the same as `run-local`.
+- `function open` is CLI-only; MCP covers Function operations but not browser navigation.
+- Do not use Function commands for Job Templates (`cicd template`), Release Data Templates (`cicd data template`), or CRT jobs (`agentia testing …`).

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

@@ -0,0 +1,132 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Job Templates Reference
+
+Use this reference for Copado Job Template commands under `agentia cicd template ...`.
+
+Prefer `agentia_template_*` MCP tools when available. Otherwise use the CLI and add `--json` when an agent will parse or reuse the result.
+
+`cicd template` manages Job Template definitions through the CICD Gateway `/release/jobs/templates` APIs. It is not the same as:
+
+- Release Data Templates (`agentia cicd data template …` — see [data.md](data.md))
+- Copado JobExecution records (`agentia cicd job …` — see [jobs.md](jobs.md))
+- Copado Functions (`agentia cicd function …` — see [functions.md](functions.md))
+
+There is no Job Template `run` command on the gateway. To execute jobs, use JobExecution commands after a template is already attached to a job flow elsewhere in Copado.
+
+## Operating Rules
+
+- Confirm CICD auth before any command.
+- Use Job Template API names returned by Copado (`[A-Za-z0-9_-]` only). Do not invent API names for get, upsert, or delete.
+- Prefer reading `template get <api-name> --json` before upsert or delete.
+- Upsert requires an explicit `steps` array (use `[]` to clear all steps). Partial flag-only upsert without `--file`, `--steps-file`, or the default disk file is rejected.
+- Optional CLI disk I/O uses `copado/templates/{apiName}.metadata.json` with lowercase keys for legacy migration. MCP tools do not write disk files; pass structured JSON payloads.
+- After every mutation, read the template back or list it by name.
+
+## Choose A Workflow
+
+| Intent | Workflow |
+| --- | --- |
+| Scaffold metadata without persisting | Defaults |
+| Find or inspect a Job Template | List And Get |
+| Create or update a Job Template | Upsert |
+| Persist retrieved JSON to disk | Get Or Defaults With Write |
+| Remove a Job Template | Delete |
+
+## Defaults
+
+1. Run `template defaults --name <display-name> --json`.
+2. Optional: `--api-name` to control the scaffolded API name.
+3. Optional CLI disk write: `--write` (default path) or `--output <path>`.
+4. Nothing is written to Salesforce until upsert.
+
+```sh
+agentia cicd template defaults --name MyTemplate --json
+agentia cicd template defaults --name MyTemplate --api-name MyTemplate_1 --write
+```
+
+## List And Get
+
+1. Discover candidates with `template list --json` (Custom only by default).
+2. Use `--type all` when Standard templates must be included.
+3. Filter with `--name`, pagination (`--cursor`, `--page-size`), or `--fetch-all` when needed (`--fetch-all` is incompatible with `--cursor` on the gateway).
+4. Inspect one template with `template get <api-name> --json`.
+5. Optional CLI disk write on get: `--write` or `--output <path>`.
+
+```sh
+agentia cicd template list --json
+agentia cicd template list --type all --name Demo --fetch-all --json
+agentia cicd template get MyTemplate_1 --json
+agentia cicd template get MyTemplate_1 --write
+```
+
+## Upsert
+
+1. Prepare steps and metadata:
+   - default disk path `copado/templates/{apiName}.metadata.json`, or
+   - `--file <path>`, or
+   - `--steps-file` plus optional name/description flags.
+2. Ensure the payload includes a `steps` array.
+3. Run `template upsert <api-name> ... --json`.
+4. Read back with `template get <api-name> --json`.
+
+Wire format is camelCase (`apiName`, `customType`, `volumeOptions`). Disk files use lowercase keys (`apiname`, `customtype`, `volumeoptions`); reads accept either casing.
+
+```sh
+agentia cicd template upsert MyTemplate_1 --json
+agentia cicd template upsert MyTemplate_1 --file ./copado/templates/MyTemplate_1.metadata.json --json
+agentia cicd template upsert MyTemplate_1 --name "My Template" --steps-file ./steps.json --json
+```
+
+## Delete
+
+1. Confirm the exact API name with `template get` or `template list`.
+2. Confirm destructive intent with the user.
+3. Run `template delete <api-name> --json`.
+
+```sh
+agentia cicd template delete MyTemplate_1 --json
+```
+
+## Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `template defaults` | Scaffold defaults | Gateway GET; not persisted. Optional `--write` / `--output`. |
+| `template list` | Find Job Templates | Default `--type custom`; name filter and pagination. |
+| `template get API_NAME` | Inspect one template | Optional `--write` / `--output` for disk. |
+| `template upsert API_NAME` | Create or update | Requires explicit `steps`; disk/`--file`/`--steps-file`. |
+| `template delete API_NAME` | Delete a template | Destructive; confirm API name. |
+
+## MCP Tools
+
+| Tool | Maps To |
+| --- | --- |
+| `agentia_template_defaults` | `template defaults` |
+| `agentia_template_list` | `template list` |
+| `agentia_template_get` | `template get` |
+| `agentia_template_upsert` | `template upsert` |
+| `agentia_template_delete` | `template delete` |
+
+MCP tools accept structured fields (for example `apiName`, `steps`) and do not perform legacy disk writes.
+
+## Disk Format
+
+Path: `copado/templates/{apiName}.metadata.json`
+
+| Disk key | Gateway field |
+| --- | --- |
+| `apiname` | `apiName` |
+| `customtype` (on steps) | `customType` |
+| `volumeoptions` | `volumeOptions` |
+| `name`, `type`, `version`, `description`, `steps` | same camelCase names |
+
+Use disk files only when migrating from legacy `copado:beta:template:*` or when the user asks to keep local metadata in the repo.
+
+## Gotchas
+
+- Job Template API name and Job Template Salesforce Id are different. CLI/MCP identify templates by API name for get/upsert/delete.
+- Do not confuse `cicd template` with `cicd data template`. Data templates use Salesforce template Ids and live under `/release/data-templates`.
+- Upsert without `steps` fails validation before the gateway runs. Provide `[]` only when clearing all steps is intentional.
+- `--fetch-all` cannot be combined with `--cursor`.
+- Gateway dependency: `/release/jobs/templates` (nested under release jobs). Older `/templates` paths are obsolete.