@copado/agentia-cli 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,807 @@
+# Copado Agentia CLI
+
+## Goal
+
+The **Copado Agentia CLI** is the command-line entry point for interacting with Copado Agentia products: **CI/CD**, **robotic testing**, and **AI** capabilities exposed through **APIs**. The CLI wraps those services so teams can script pipelines, trigger tests, query or drive AI-assisted workflows, and integrate Agentia into local development and automation without building custom HTTP clients for every task.
+
+This repository is the Node.js + TypeScript implementation of that CLI. It includes a **Front API CICD proxy** client (`POST /json/v1/cicd-api`), **profile-based login** (token2 or CRT PAT), and commands for **connectivity checks** and **generic gateway invocation**.
+
+## Prerequisites
+
+- **Node.js** `>= 18.18` (see `package.json` → `engines`)
+- **npm** (or another client compatible with `package-lock.json`)
+- **JDK 11+** on your `PATH` — only required when regenerating TypeScript clients from the OpenAPI specs with **`npm run codegen`** (or **`npm run build:openapi`**). Everyday **`npm run build`** does not run the generator; a fresh clone uses the committed output under [`src/generated/`](src/generated/).
+
+## How to execute
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+`prepare` runs `npm run build` after install, so `dist/` is produced automatically when dependencies are installed.
+
+### Build
+
+```bash
+npm run build
+```
+
+Compiles TypeScript from `src/` to `dist/` and copies [`cicd_openapi.json`](cicd_openapi.json) and [`cicd_openapi.v2.json`](cicd_openapi.v2.json) into `dist/` so the CLI can resolve OpenAPI paths at runtime. Typed clients under [`src/generated/`](src/generated/) are **committed**; see [`src/generated/README.md`](src/generated/README.md).
+
+```bash
+npm run build          # tsc + copy specs to dist/ (default; no codegen)
+npm run codegen        # regenerate src/generated/ — run when OpenAPI specs change
+npm run build:openapi  # codegen then build (spec change shortcut)
+npm run codegen:check  # fail if committed generated code is stale (CI / pre-push)
+```
+
+**Requirements for codegen:** Java (JDK 11+) on your `PATH` when you run `npm run codegen`; the `@openapitools/openapi-generator-cli` npm wrapper downloads the generator JAR on first use.
+
+### OpenAPI spec changes (developer workflow)
+
+Do **not** edit [`src/generated/`](src/generated/) by hand. When you change [`cicd_openapi.json`](cicd_openapi.json) or [`cicd_openapi.v2.json`](cicd_openapi.v2.json):
+
+```bash
+npm run build:openapi   # or: npm run codegen && npm run build
+npm test
+# commit spec files + src/generated/
+```
+
+| Step | What it does |
+|------|----------------|
+| `npm run codegen` | Regenerates `src/generated/cicd-v1` and `src/generated/cicd-v2` from the specs |
+| `npm run build` | Compiles the CLI and copies specs into `dist/` for discovery and schema-driven flags |
+
+Codegen alone does **not** update `dist/`; build alone does **not** refresh `src/generated/` after a spec edit. Use both when the OpenAPI files change.
+
+For everyday CLI work (no spec changes), **`npm run build`** is enough.
+
+**Fresh clone:** `npm install` runs `prepare` → `npm run build` (compile + bundle specs). Generated clients come from git, not from install-time codegen.
+
+For toolchain details, scripts, and CI drift checks, see [docs/architecture/cicd-openapi-codegen.md](docs/architecture/cicd-openapi-codegen.md).
+
+
+### Run the CLI
+
+After a successful build, the binary is `dist/cli.js` and the published command name is **`agentia`**.
+
+```bash
+node dist/cli.js --help
+node dist/cli.js hello
+```
+
+**Global `agentia` on your PATH (development):**
+
+```bash
+npm link
+agentia --help
+```
+
+## Front API CICD proxy
+
+The Salesforce deployer calls the same contract: **`POST {frontApiBaseUrl}/json/v1/cicd-api`** with JSON body:
+
+```json
+{
+  "endpoint": "<inner CICD Gateway path>",
+  "method": "<inner HTTP verb, e.g. GET or POST>",
+  "body": {}
+}
+```
+
+**Headers** depend on profile auth method (stored after `login`):
+
+**token2 profile:**
+
+- `Content-Type: application/json`
+- `token2` — value you provide at login (same header name as the deployer’s Front API calls)
+- `userId` — Salesforce user Id
+- `orgId` — Salesforce org Id
+
+**PAT profile:**
+
+- `Content-Type: application/json`
+- `X-Agentia-Authorization: PAT <token>` — CRT personal access token
+- `X-Agentia-Region: <crtRegion>` — CRT region saved on the profile at login (`QA`, `US`, `AU`, `EU`, or `SG`)
+- `X-Agentia-OrgId: <orgId>` — CRT organization id (required; resolved at `login pat` from Platform `/users/me`)
+
+The outer request is always **POST** to `/json/v1/cicd-api`; the **inner** `method` may be **GET** (for example `GET /health`) or **POST** (for example `POST /navigation/enabled` with a JSON body).
+
+**Migration:** PAT profiles saved before this header was mandatory may lack `orgId`. Re-run `agentia login pat` to resolve and store the organization id.
+
+## Regions and base URL
+
+Preset **regions:** `NA`, `NA2`, `EU` (default **NA**). Unless you pass **`--url`**, the Front API base URL is:
+
+`https://{na|na2|eu}.api.copado.com`
+
+Use **`--region CUSTOM` together with `--url https://…`** for hosts that are not covered by those presets, for example internal Front API hosts (`dev.api.copado.com`, `test.api.copado.com`, `test-cn.api.copado.com`) or customer-specific hosts (`tmobile.api.copado.com`, `emea-cn.api.copado.com`, and similar). The profile stores **`CUSTOM`** so it is clear the base URL was set explicitly.
+
+You can also pass **`--url`** alone with a preset region when your org uses a custom **Server_URL__c** (same idea as `DeployAPI.copadoURL` in the deployer).
+
+## Configuration and login
+
+Profiles are stored under:
+
+- **macOS / Linux:** `$XDG_CONFIG_HOME/agentia/config.json` or `~/.config/agentia/config.json`
+- **Windows:** `%APPDATA%\agentia\config.json`
+
+The file is written with restrictive permissions where the OS allows.
+
+### `agentia login`
+
+Authenticate using a **subcommand** per auth method: **token2** (Front API legacy headers) or **pat** (CRT personal access token).
+
+#### `agentia login token2`
+
+```bash
+agentia login token2 \
+  --alias myorg \
+  --token2 '<your-token2>' \
+  --org-id '<Salesforce org Id>' \
+  --user-id '<Salesforce user Id>' \
+  --region NA
+```
+
+Optional **`--url https://...`** overrides the regional default host. For internal or customer-specific API hosts, use **`--region CUSTOM --url https://<host>`** ( **`--url` is required** for `CUSTOM`).
+
+#### `agentia login pat`
+
+Validates the PAT against the CRT Platform API (`GET /users/me`) before saving. The response is used to resolve and store a **CRT organization id** (`orgId`) on the profile; every PAT Front API call sends it as `X-Agentia-OrgId`.
+
+**Org resolution** (when `--org-id` is omitted):
+
+| Situation | Selected org |
+|-----------|----------------|
+| One role in `/users/me` | That role's `organizationId` |
+| Multiple roles, `defaultOrg` in `private.settings` matches a role | `defaultOrg` |
+| Multiple roles, no matching `defaultOrg` | First role's `organizationId` |
+
+When `--org-id` is provided, it must match one of the user's role `organizationId` values (string compare); otherwise login fails.
+
+PAT profiles use two independent region settings:
+
+| Flag | Purpose |
+|------|---------|
+| **`--crt-region`** | CRT region for Platform validation and for `X-Agentia-Region` on Front API calls (default **QA**). Saved on the profile as `crtRegion`. |
+| **`--region` / `--url`** | Front API host (same rules as token2: `NA`, `NA2`, `EU`, or `CUSTOM` + `--url`). |
+
+```bash
+# Dev Front API host, QA CRT region
+agentia login pat \
+  --alias crt-dev \
+  --token "$CRT_PAT" \
+  --crt-region QA \
+  --region CUSTOM \
+  --url https://dev.api.copado.com
+
+# Production Front API (NA), US CRT region, explicit org
+agentia login pat \
+  --alias crt-prod \
+  --token "$CRT_PAT" \
+  --crt-region US \
+  --region NA \
+  --org-id "12345"
+```
+
+On success, the CLI prints the resolved `orgId` (for example `orgId: 1` when auto-selected from `/users/me`).
+
+Downstream commands (`cicd ping`, `cicd invoke`, etc.) use the **stored** `crtRegion` from the selected profile — there is no per-command `--crt-region` override.
+
+The first profile saved becomes the **default profile** until you add more and change defaults (future enhancement: `config set-default`).
+
+### Choosing a profile
+
+- Global option on any command: **`--profile <alias>`**
+- Environment variable: **`AGENTIA_PROFILE`**
+
+Example:
+
+```bash
+agentia --profile staging cicd ping          # token2 profile
+agentia --profile crt-dev cicd ping          # PAT profile
+```
+
+## Commands (summary)
+
+| Command | Purpose |
+|---------|---------|
+| `login token2` | Save profile using token2 + orgId + userId + region + frontApiBaseUrl |
+| `login pat` | Save profile using CRT PAT; validates token; resolves orgId from `/users/me`; stores crtRegion + frontApiBaseUrl |
+| `cicd ping` | Inner **GET /health** through the proxy (connectivity) |
+| `cicd invoke` | Call any inner endpoint/method/body through the proxy |
+| `cicd environment list` | Inner **GET** list environments (path from `cicd_openapi.v2.json` discovery) |
+| `cicd environment get <environment-id>` | Inner **GET** one environment (path from `cicd_openapi.v2.json` discovery) |
+| `cicd environment create` | Inner **POST** create environment (path from `cicd_openapi.v2.json` discovery) |
+| `cicd repository list` | Inner **GET** list git repositories (path from `cicd_openapi.v2.json` discovery) |
+| `cicd repository get <repository-id>` | Inner **GET** one git repository (path from `cicd_openapi.v2.json` discovery) |
+| `cicd repository create` | Inner **POST** create git repository (path from `cicd_openapi.v2.json` discovery) |
+| `cicd repository ssh-key --repository-id <id>` | Inner **POST** generate SSH public key for a git repository (path from `cicd_openapi.v2.json` discovery) |
+| `cicd repository http-credentials --repository-id <id>` | Inner **PUT** update HTTP credentials for a git repository (path from `cicd_openapi.v2.json` discovery) |
+| `cicd repository validate --repository-id <id>` | Inner **POST** validate repository authentication (path from `cicd_openapi.v2.json` discovery) |
+| `cicd repository authenticate --repository-id <id>` | Browser GitLab OAuth login: local loopback + direct Front API `POST /agentia/v1/gitoauth/authorize`; human-oriented stdout (not JSON) |
+| `cicd pipeline list` | Inner **GET** list pipelines (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline get <pipeline-id>` | Inner **GET** one pipeline (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline create` | Inner **POST** create pipeline (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline update <pipeline-id>` | Inner **PATCH** update pipeline (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline delete <pipeline-id>` | Inner **DELETE** delete pipeline (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline visualize <pipeline-id> [--format ascii\|mermaid\|dot\|html] [--open]` | Render pipeline environment graph from live connections (ASCII default; `--open` writes HTML and opens browser) |
+| `cicd pipeline connection list [--pipeline-id <id>]` | Inner **GET** list pipeline connections (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline connection get <connection-id>` | Inner **GET** one pipeline connection (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline connection create` | Inner **POST** create pipeline connection (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline connection update <connection-id>` | Inner **PATCH** update pipeline connection (path from `cicd_openapi.v2.json` discovery) |
+| `cicd pipeline connection delete <connection-id>` | Inner **DELETE** delete pipeline connection (path from `cicd_openapi.v2.json` discovery) |
+| `plan work-item list [--pipeline-id <id>] [--release-id <id>]` | Inner **GET** list work items (path from `cicd_openapi.v2.json` discovery) |
+| `plan work-item get <work-item-id>` | Inner **GET** one work item (path from `cicd_openapi.v2.json` discovery) |
+| `plan work-item create` | Inner **POST** create work item (path from `cicd_openapi.v2.json` discovery) |
+| `plan work-item update <work-item-id>` | Inner **PATCH** update work item (path from `cicd_openapi.v2.json` discovery) |
+| `plan work-item delete <work-item-id>` | Inner **DELETE** delete work item (path from `cicd_openapi.v2.json` discovery) |
+| `cicd credential get <environment-id> <credential-id>` | Inner **GET** one environment credential (path from `cicd_openapi.v2.json` discovery) |
+| `cicd credential create <environment-id>` | Inner **POST** create environment credential (path from `cicd_openapi.v2.json` discovery) |
+| `cicd credential authenticate --env-id <id> --cred-id <id>` | Browser OAuth login: local loopback + **GET** auth-url; human-oriented stdout (not JSON) |
+| `cicd metadata index refresh --credential <id>` | Inner **POST** refresh Salesforce metadata index (full or partial by `--types`); optional `--module-type vlocity` adds `moduletype` to request body |
+| `cicd metadata index status <event-id>` | Inner **GET** metadata index refresh job status |
+| `cicd metadata index search --credential <id>` | Inner **POST** search Salesforce metadata index; optional `--module-type vlocity` adds `moduletype` to request body |
+| `cicd metadata types --environment <id> --credential <id>` | Inner **GET** metadata types in system (`/v2/release/metadata/types/{system_id}`); optional `--module-type vlocity` adds `moduleTypes=vlocity` |
+| `cicd metadata users --environment <id> --credential <id>` | Inner **GET** users on system (`/v2/release/metadata/users/{system_id}`); optional `--module-type vlocity` adds `moduleTypes=vlocity` |
+| `cicd deploy-selection` | Inner **POST** submit a Salesforce deploy selection job (`/v2/release/metadata/deploy-selection`) |
+| `cicd commit` | Inner **POST** submit a commit job (`/v2/release/actions/commit`) |
+| `user-story create` | If a matching create operation exists in `cicd_openapi.json`, call it; otherwise prints guidance and suggests `cicd invoke` |
+
+### Examples
+
+**Ping (after login):**
+
+```bash
+agentia cicd ping
+```
+
+**Generic invoke — inner GET /health:**
+
+```bash
+agentia cicd invoke --endpoint /health --method GET --body '{}'
+```
+
+**Generic invoke — inner POST /navigation/enabled** (same shape as deployer `CICDEnabledCallout`):
+
+```bash
+agentia cicd invoke --endpoint /navigation/enabled --method POST \
+  --body '{"objectName":"Copado_User_Story__c","action":"merge"}'
+```
+
+**List environments (v2 corpus API):**
+
+```bash
+agentia cicd environment list
+```
+
+**Get one environment:**
+
+```bash
+agentia cicd environment get env-abc123
+```
+
+**Create an environment:**
+
+```bash
+agentia cicd environment create --name "Dev Sandbox" --type Sandbox
+```
+
+**List git repositories:**
+
+```bash
+agentia cicd repository list
+```
+
+**Get one git repository:**
+
+```bash
+agentia cicd repository get repo-abc123
+```
+
+**Create a git repository** (`--name` and `--provider` required; valid `--provider` values: `Github`, `Bitbucket`, `Gitlab`, `Microsoft Team Service`, `Copado Version Control`, `Others`; optional `--auth-type` (`HTTPS`, `SSH`, `OAuth`), `--uri`, `--tag-base-url`, `--pull-request-base-url`, `--commit-base-url`, `--branch-base-url`, or `--data`):
+
+```bash
+agentia cicd repository create --name "My Repo" --provider Github
+```
+
+**Generate an SSH public key for a git repository** (`--repository-id` required; response `data` includes `publicKey` and `algorithm`):
+
+```bash
+agentia cicd repository ssh-key --repository-id repo-abc123
+```
+
+**Update HTTP credentials for a git repository** (`--repository-id` required; `--username` and `--password` required unless supplied via `--data`; optional `--data <json>` merged with flags; flags win on conflict; returns `204` with no body on success):
+
+```bash
+agentia cicd repository http-credentials \
+  --repository-id repo-abc123 \
+  --username git-user \
+  --password git-pass
+```
+
+**Validate repository authentication** (`--repository-id` required; response `data` includes `validated` and optional `message`):
+
+```bash
+agentia cicd repository validate --repository-id repo-abc123
+```
+
+**Authenticate a git repository** (GitLab OAuth via direct Front API; repository must exist with `authType=OAuth` and provider GitLab; optional `--port`, `--timeout` in seconds, default 300):
+
+```bash
+agentia cicd repository authenticate --repository-id 8f14e45f-ceea-467a-9575-2f7f5e6f1b0e
+```
+
+On success, copado-front-api redirects the browser to the CLI loopback URL with `?status=success`. On failure, the redirect includes `?status=error&reason=...`. The CLI prints progress lines to stdout and exits `0` on success, `1` on auth failure, `130` on timeout. This command does **not** use the CICD gateway proxy or OpenAPI discovery.
+
+**List pipelines:**
+
+```bash
+agentia cicd pipeline list
+```
+
+**Get one pipeline:**
+
+```bash
+agentia cicd pipeline get pipe-abc123
+```
+
+**Create a pipeline** (`--name`, `--status`, and `--repository-id` required; valid `--status` values: `active`, `paused`, `archived`; optional `--data <json>` merged with flags; flags win on conflict):
+
+```bash
+agentia cicd pipeline create \
+  --name "Release Pipeline" \
+  --status active \
+  --repository-id repo-abc123
+```
+
+**Update a pipeline** (at least one of `--name`, `--status`, `--repository-id`, or `--data` required):
+
+```bash
+agentia cicd pipeline update pipe-abc123 --status paused
+```
+
+**Delete a pipeline:**
+
+```bash
+agentia cicd pipeline delete pipe-abc123
+```
+
+**Visualize a pipeline** (fetches pipeline metadata and connections, renders environment graph; default ASCII in terminal):
+
+```bash
+agentia cicd pipeline visualize pipe-abc123
+agentia cicd pipeline visualize pipe-abc123 --format mermaid
+agentia cicd pipeline visualize pipe-abc123 --format dot
+agentia cicd pipeline visualize pipe-abc123 --format html > pipeline.html
+agentia cicd pipeline visualize pipe-abc123 --open
+```
+
+`--format` accepts `ascii` (default), `mermaid`, `dot`, or `html`. `--open` writes a temporary HTML file and opens it in the default browser (falls back to ASCII with a stderr warning in headless environments).
+
+**List pipeline connections** (optional `--pipeline-id` filter):
+
+```bash
+agentia cicd pipeline connection list --pipeline-id pipe-abc123
+```
+
+**Get one pipeline connection:**
+
+```bash
+agentia cicd pipeline connection get conn-abc123
+```
+
+**Create a pipeline connection** (`--pipeline-id`, `--from-environment-id`, and `--to-environment-id` required; optional `--source-branch-name`, `--destination-branch-name`, or `--data`):
+
+```bash
+agentia cicd pipeline connection create \
+  --pipeline-id pipe-abc123 \
+  --from-environment-id env-dev \
+  --to-environment-id env-staging \
+  --source-branch-name main \
+  --destination-branch-name release
+```
+
+**Update a pipeline connection** (at least one update field required):
+
+```bash
+agentia cicd pipeline connection update conn-abc123 --destination-branch-name hotfix
+```
+
+**Delete a pipeline connection:**
+
+```bash
+agentia cicd pipeline connection delete conn-abc123
+```
+
+**List work items** (optional `--pipeline-id` and/or `--release-id` filters):
+
+```bash
+agentia plan work-item list --pipeline-id pipe-abc123 --release-id rel-abc123
+```
+
+**Get one work item:**
+
+```bash
+agentia plan work-item get wi-abc123
+```
+
+**Create a work item** (`--title` required; optional `--pipeline-id`, `--release-id`, `--current-environment-id`, `--branch-name`, or `--data`):
+
+```bash
+agentia plan work-item create \
+  --title "Implement deployment checks" \
+  --pipeline-id pipe-abc123 \
+  --release-id rel-abc123 \
+  --current-environment-id env-dev123 \
+  --branch-name feature/US-12345-add-checks
+```
+
+**Update a work item** (at least one update field required: `--title`, `--pipeline-id`, `--release-id`, `--current-environment-id`, `--branch-name`, or `--data`):
+
+```bash
+agentia plan work-item update wi-abc123 \
+  --current-environment-id env-qa456 \
+  --branch-name release/1.0
+```
+
+**Delete a work item:**
+
+```bash
+agentia plan work-item delete wi-abc123
+```
+
+**Get one credential** (both ids required):
+
+```bash
+agentia cicd credential get env-abc123 cred-xyz789
+```
+
+**Create a credential** (`--name` required; optional `--default-credential`, `--username`, `--unique-id`, or `--data`):
+
+```bash
+agentia cicd credential create env-1 --name "Default Org User" --default-credential
+```
+
+**Authenticate a credential** (Step 3 — opens a browser for Salesforce OAuth; optional `--port`, `--timeout` in seconds, default 300):
+
+```bash
+agentia cicd credential authenticate --env-id env-1 --cred-id cred-456
+```
+
+On success, copado-front-api redirects the browser to the CLI loopback URL with **no** query parameters. On failure, the redirect includes `errorCode` and `errorDescription` (see `AgentiaOAuthErrorCodes` in copado-front-api). The CLI prints progress lines to stdout and exits `0` on success, `1` on auth failure, `130` on timeout.
+
+On Linux without `$DISPLAY` (SSH/headless), the CLI prints the auth URL instead of opening a browser and waits for Enter after you complete login elsewhere.
+
+There is no credential list API. To discover credential ids for an environment, use **`cicd environment get <environment-id>`** and read the `credentials` array in the response.
+
+**Refresh Salesforce metadata index (full):**
+
+```bash
+agentia cicd metadata index refresh --credential cred-xyz789 --wait
+```
+
+**Partial refresh by metadata types:**
+
+```bash
+agentia cicd metadata index refresh --credential cred-xyz789 --types ApexClass,Flow --wait --timeout 600
+```
+
+**Vlocity metadata index refresh** (optional `--module-type vlocity` adds `moduletype: "vlocity"` to the request body):
+
+```bash
+agentia cicd metadata index refresh --credential cred-xyz789 --module-type vlocity --wait
+```
+
+**Poll refresh status** (event id from the refresh response `data.eventId`):
+
+```bash
+agentia cicd metadata index status job-abc123
+```
+
+**Search metadata index** (credential id from `cicd environment get` or `cicd credential get`; uses `credentialId`, not `sourceCredentialId`):
+
+```bash
+agentia cicd metadata index search \
+  --credential 669745f0-1477-4e70-ada0-4272b78c5617 \
+  --types ApexClass,ApexTrigger \
+  --source NewAndChanged \
+  --limit 100
+```
+
+**Search deleted metadata** (`--source` accepts `Deleted`, `deleted`, or `delete`; all map to `"source": "Deleted"` in the request body):
+
+```bash
+agentia cicd metadata index search \
+  --credential 669745f0-1477-4e70-ada0-4272b78c5617 \
+  --types ApexClass \
+  --source deleted
+```
+
+**Search Vlocity metadata index** (optional `--module-type vlocity` adds `moduletype: "vlocity"` to the request body):
+
+```bash
+agentia cicd metadata index search \
+  --credential 0409d7c4-ea05-4ca7-bb70-8e9d8022b8b8 \
+  --types ApexClass \
+  --module-type vlocity
+```
+
+On V2, `NewAndChanged` is the default index search source. Use `--source Deleted` (or aliases `deleted` / `delete`) to search deleted metadata. `PreviouslyCommitted` may return `422` (`V2-MDT-005`) depending on backend support. If the index is empty or missing, run `metadata index refresh` first (a `404` with `V2-MDT-002` means no index exists yet).
+
+Omit `--wait` on refresh to return immediately after the job is submitted. With `--wait`, the CLI prints JSON status to stdout after each poll until the job reaches `COMPLETED` or `ERROR`. V2 refresh uses the credential’s Salesforce session and supports full index refresh (no `--types`) or partial refresh by metadata type names only.
+
+**List metadata types in a system** (`--environment` is the system id; `--credential` is passed as the `credentialId` query param; optional `--module-type vlocity` adds `moduleTypes=vlocity`):
+
+```bash
+agentia cicd metadata types \
+  --environment env-abc123 \
+  --credential cred-xyz789
+```
+
+**List Vlocity metadata types in a system:**
+
+```bash
+agentia cicd metadata types \
+  --environment env-abc123 \
+  --credential cred-xyz789 \
+  --module-type vlocity
+```
+
+**List users on a system** (`--environment` is the system id; `--credential` is passed as the `credentialId` query param; optional `--module-type vlocity` adds `moduleTypes=vlocity`):
+
+```bash
+agentia cicd metadata users \
+  --environment env-abc123 \
+  --credential cred-xyz789
+```
+
+**List Vlocity users on a system:**
+
+```bash
+agentia cicd metadata users \
+  --environment env-abc123 \
+  --credential cred-xyz789 \
+  --module-type vlocity
+```
+
+**Submit a deploy selection job** (`--source-credential` maps to `sourceId`, `--target-environment` to `destinationId`; metadata uses `Type:Member` syntax, repeatable):
+
+```bash
+agentia cicd deploy-selection \
+  --source-credential cred-src \
+  --target-environment env-dest \
+  --metadata ApexClass:MyClass \
+  --metadata Flow:My_Flow \
+  --dry-run \
+  --test-level NoTestRun
+```
+
+Optional flags: `--tests <class>` (repeatable; with `RunSpecifiedTests`), `--ignore-warnings`, `--rollback-on-error`, `--name <label>`, and `--data <json>` (merged with flags; flags win on conflict). `--dry-run` sets validation-only deployment (`isValidation: true`). Valid `--test-level` values: `NoTestRun`, `RunSpecifiedTests`, `RunLocalTests`, `RunAllTestsInOrg`.
+
+On success, the response `data` includes fields such as `jobExecutionId`, `status`, and `resultId` (see `DeploySelectionResult` in `cicd_openapi.v2.json`).
+
+**Submit a commit job** (metadata uses `Type:Name[:operation]` syntax, repeatable; default operation is `add`):
+
+```bash
+agentia cicd commit \
+  --pipeline-id pipe-abc \
+  --work-item-id wi-123 \
+  --pipeline-connection-id conn-456 \
+  --message "US-12345: add MyClass" \
+  --metadata ApexClass:MyClass \
+  --metadata Flow:My_Flow:full
+```
+
+Optional flags: `--do-not-push-changes` (skip pushing the feature branch; default is to push), `--recreate-if-exists`, `--clean-pull-request`, and `--data <json>` (merged with flags; flags win on conflict). Valid operation values: `add`, `retrieve_only`, `full`, `delete`, `selective_commit` (aliases such as `del`, `ret-only`, and `selectivecommit` are accepted).
+
+On success, the response `data` includes fields such as `actionId`, `commitId`, `jobExecutionId`, and `status` (see `CommitResult` in `cicd_openapi.v2.json`).
+
+Successful list/get/create/credential-get/credential-create/repository-ssh-key/repository-http-credentials/repository-validate/metadata-types/metadata-users/deploy-selection/commit commands print JSON to stdout: `{ "status": <httpStatus>, "data": <inner payload> }`. Validation errors (`422`) print a message to stderr and exit with code 1. **`credential authenticate`** and **`repository authenticate`** use human-oriented messages, not JSON.
+
+**User story create** (only when the OpenAPI spec contains a discoverable “create user story” operation, for example tagged with `x-agentia-cli-command: user-story-create`):
+
+```bash
+agentia user-story create --data '{"your":"payload"}'
+```
+
+If the spec does not define that operation yet, the command exits with an error and lists related paths; use **`cicd invoke`** with the inner route your team provides.
+
+## OpenAPI specs and CICD Gateway commands
+
+The CLI talks to the CICD Gateway **indirectly** through the Front API proxy (see [Front API CICD proxy](#front-api-cicd-proxy)). OpenAPI JSON files describe the **inner** gateway routes (`endpoint` + `method` + `body`). Named commands **discover** those routes from a bundled spec at runtime instead of hardcoding paths in TypeScript.
+
+### Two spec files (v1 and v2)
+
+| Repo file | Bundled to | Typical API surface | Commands using it today |
+|-----------|------------|---------------------|-------------------------|
+| [`cicd_openapi.v2.json`](cicd_openapi.v2.json) | `dist/cicd_openapi.v2.json` | CICD Gateway v2 (environments, repositories, pipelines, …) | `cicd environment list`, `cicd environment get`, `cicd environment create`, `cicd credential get`, `cicd credential create`, `cicd credential authenticate`, `cicd metadata index refresh`, `cicd metadata index status`, `cicd metadata index search`, `cicd metadata types`, `cicd metadata users`, `cicd deploy-selection`, `cicd commit`, `cicd repository list`, `cicd repository get`, `cicd repository create`, `cicd repository ssh-key`, `cicd repository http-credentials`, `cicd repository validate`, `cicd pipeline list`, `cicd pipeline get`, `cicd pipeline create`, `cicd pipeline update`, `cicd pipeline delete`, `cicd pipeline connection list`, `cicd pipeline connection get`, `cicd pipeline connection create`, `cicd pipeline connection update`, `cicd pipeline connection delete`, `plan work-item list`, `plan work-item get`, `plan work-item create`, `plan work-item update`, `plan work-item delete` |
+
+On **`npm run build`**, `scripts/copy-openapi.mjs` copies both files into **`dist/`** next to the compiled JS. At runtime the CLI resolves paths via `resolveBundledOpenApiPath()` and `resolveBundledOpenApiV2Path()` in [`src/openapi.ts`](src/openapi.ts) — it does **not** read the repo-root copies unless you rebuild.
+
+**Refresh workflow:** update the root JSON from the gateway team → **`npm run build:openapi`** (or `codegen` + `build`) → commit specs and `src/generated/` → discovery and validation match on the next CLI run. See [Build → OpenAPI spec changes](#openapi-spec-changes-developer-workflow).
+
+### What uses OpenAPI vs what does not
+
+| Pattern | Examples | OpenAPI? |
+|---------|----------|----------|
+| **Discovery command** | `user-story create`, `cicd environment list/get/create`, `cicd credential get/create`, `cicd metadata index refresh/status/search`, `cicd metadata types/users`, `cicd deploy-selection`, `cicd commit`, `cicd repository list/get/create/ssh-key/http-credentials/validate`, `cicd pipeline list/get/create/update/delete`, `cicd pipeline connection list/get/create/update/delete`, `plan work-item list/get/create/update/delete` | Yes — load spec, find operation, call proxy |
+| **Orchestration command** | `cicd credential authenticate` | Uses auth-url from spec + local loopback (not JSON stdout) |
+| **Orchestration command (direct Front API)** | `cicd repository authenticate` | Direct `POST /agentia/v1/gitoauth/authorize` + local loopback (not JSON stdout; not OpenAPI/proxy) |
+| **Hardcoded shortcut** | `cicd ping` → `GET /health` | No |
+| **Manual escape hatch** | `cicd invoke --endpoint … --method … --body …` | No — caller supplies inner route |
+| **Non-gateway** | `login`, `hello` | No |
+
+Prefer **discovery commands** for stable, user-facing product verbs. Keep **`cicd invoke`** for one-offs, previews, or operations not yet wired as named commands.
+
+### Discovery flow (runtime)
+
+Every OpenAPI-bound command follows the same shape:
+
+```
+1. Resolve bundled spec path (v1 or v2 under dist/)
+2. loadOpenApiFromPath() — parse JSON paths/methods/components
+3. find*Operation(doc) — locate the inner route (tag or heuristics)
+4. Build inner request via schema bridge (flags + --data) for POST bodies
+5. Generated typescript-fetch client → proxy fetch adapter → callCicdGateway
+6. writeCicdSuccess / handleCicdFailure — stdout { status, data } or stderr on errors
+```
+
+**Codegen:** [`@openapitools/openapi-generator-cli`](https://openapi-generator.tech/) generates typed models and API clients under [`src/generated/`](src/generated/) (committed; see [`src/generated/README.md`](src/generated/README.md)). Regenerate with **`npm run codegen`** after spec changes. Generated clients never call the gateway directly; [`src/transport/proxy-fetch-adapter.ts`](src/transport/proxy-fetch-adapter.ts) routes every request through the Front API proxy. See [docs/architecture/cicd-openapi-codegen.md](docs/architecture/cicd-openapi-codegen.md) for the full architecture.
+
+**Schema-driven CLI inputs:** For commands like `cicd environment create`, request validation and Commander flags are derived from OpenAPI `requestBody` schemas (`required`, property types, enums) via [`src/cli/schema-reader.ts`](src/cli/schema-reader.ts), [`src/cli/body-builder.ts`](src/cli/body-builder.ts), and [`src/cli/flag-mapper.ts`](src/cli/flag-mapper.ts) — not hand-maintained body builders.
+
+Reference implementations:
+
+- **v1 POST + body:** [`src/cmd/user-story.ts`](src/cmd/user-story.ts) + schema bridge + [`runOpenApiCreateWithBridge`](src/cli/openapi-command.ts)
+- **v2 environment commands:** [`src/cmd/cicd-environment.ts`](src/cmd/cicd-environment.ts) + generated [`CorpusEnvironmentsCredentialsV2Api`](src/generated/cicd-v2/apis/CorpusEnvironmentsCredentialsV2Api.ts)
+- **v2 repository commands:** [`src/cmd/cicd-repository.ts`](src/cmd/cicd-repository.ts) + generated [`CorpusRepositoriesApi`](src/generated/cicd-v2/apis/CorpusRepositoriesApi.ts)
+- **v2 pipeline commands:** [`src/cmd/cicd-pipeline.ts`](src/cmd/cicd-pipeline.ts) + generated [`CorpusPipelinesApi`](src/generated/cicd-v2/apis/CorpusPipelinesApi.ts)
+- **v2 pipeline connection commands:** [`src/cmd/cicd-pipeline-connection.ts`](src/cmd/cicd-pipeline-connection.ts) + generated [`CorpusPipelineConnectionsApi`](src/generated/cicd-v2/apis/CorpusPipelineConnectionsApi.ts)
+- **v2 plan work item commands:** [`src/cmd/plan-work-item.ts`](src/cmd/plan-work-item.ts) + generated [`PlanWorkItemsApi`](src/generated/cicd-v2/apis/PlanWorkItemsApi.ts)
+- **v2 deploy selection:** [`src/cmd/cicd-deploy-selection.ts`](src/cmd/cicd-deploy-selection.ts) + [`src/cicd/deploy-selection.ts`](src/cicd/deploy-selection.ts) + [`runGeneratedDeploySelection`](src/cli/openapi-command.ts)
+- **v2 commit:** [`src/cmd/cicd-commit.ts`](src/cmd/cicd-commit.ts) + [`src/cicd/commit-request.ts`](src/cicd/commit-request.ts) + [`runGeneratedCommit`](src/cli/openapi-command.ts)
+
+Shared transport and response handling live in [`src/cicd-client.ts`](src/cicd-client.ts) and [`src/transport/invoke-generated.ts`](src/transport/invoke-generated.ts).
+
+### How an operation is found
+
+Discovery scans `paths` in the spec. For each candidate operation it checks, in order:
+
+1. **Extension tag (preferred)** — `x-agentia-cli-command` on the operation object:
+   - `user-story-create` → `user-story create`
+   - `environment-list` / `environment-get` / `environment-create` → `cicd environment list` / `get` / `create`
+   - `repository-list` / `repository-get` / `repository-create` → `cicd repository list` / `get` / `create`
+   - `repository-ssh-key` / `repository-http-credentials` / `repository-validate` → `cicd repository ssh-key` / `http-credentials` / `validate`
+   - `pipeline-list` / `pipeline-get` / `pipeline-create` / `pipeline-update` / `pipeline-delete` → `cicd pipeline list` / `get` / `create` / `update` / `delete`
+   - `pipeline-connection-list` / `pipeline-connection-get` / `pipeline-connection-create` / `pipeline-connection-update` / `pipeline-connection-delete` → `cicd pipeline connection list` / `get` / `create` / `update` / `delete`
+   - `work-item-list` / `work-item-get` / `work-item-create` / `work-item-update` / `work-item-delete` → `plan work-item list` / `get` / `create` / `update` / `delete`
+   - `deploy-selection` → `cicd deploy-selection`
+   - `commit` → `cicd commit`
+2. **Heuristics** — `operationId` / `summary` keywords (e.g. “list” + “environment”)
+3. **Path pattern** — e.g. `/v2/corpus/environments/` for list, `/v2/corpus/environments/{environment_id}` for get, `/v2/release/metadata/deploy-selection` for deploy selection, `/v2/release/actions/commit` for commit
+
+If multiple operations match, the tagged one wins. If none match, the command prints related paths from the spec and suggests **`cicd invoke`**.
+
+**Gateway/API owners:** when adding a new CLI-bound operation, add the tag to the OpenAPI export:
+
+```json
+"get": {
+  "operationId": "list_environments_corpus_environments__get",
+  "summary": "List Environments",
+  "x-agentia-cli-command": "environment-list"
+}
+```
+
+### Adding a new CICD Gateway command (checklist)
+
+1. **Choose the spec** — v1 (`cicd_openapi.json`) or v2 (`cicd_openapi.v2.json`) depending on which gateway surface the route lives on.
+2. **Ensure the operation exists** in the spec (or land the spec update first). Tag it with `x-agentia-cli-command: <your-command-id>`.
+3. **Add discovery** in [`src/openapi.ts`](src/openapi.ts):
+   - `findYourOperation(doc)` returning `{ path, method, operation } | null`
+   - optional `listYourRelatedPaths(doc)` for error hints
+4. **Add a command module** under [`src/cmd/`](src/cmd/):
+   - load bundled spec (`resolveBundledOpenApiPath()` or `resolveBundledOpenApiV2Path()`)
+   - call your `find*Operation`
+   - substitute path params with [`substitutePathParams`](src/openapi.ts) / [`primaryPathParamName`](src/openapi.ts) when needed
+   - use `callCicdGateway` or `executeCicdGet` / `executeCicdPost` / shared success-failure helpers
+5. **Register** the command in [`src/cli.ts`](src/cli.ts) or from [`src/cmd/cicd.ts`](src/cmd/cicd.ts) (nested under `cicd` when appropriate).
+6. **Tests** in `test/`:
+   - discovery unit tests against bundled spec or minimal mock docs ([`test/openapi.test.js`](test/openapi.test.js))
+   - command tests with mock `fetchImpl` ([`test/cicd-environment.test.js`](test/cicd-environment.test.js))
+7. **Document** the command in the [Commands (summary)](#commands-summary) table and examples above.
+
+### Output and error conventions
+
+Discovery commands should align with existing CICD helpers:
+
+- **Success:** stdout JSON `{ "status": <httpStatus>, "data": <inner payload> }` (via `writeCicdSuccess`)
+- **Gateway validation (`422`):** stderr with `message` and optional `(code: …)` (via `handleCicdFailure`)
+- **Other HTTP errors:** stderr with message or response text; `process.exitCode = 1`
+- **Missing spec file:** stderr pointing at `dist/cicd_openapi*.json` and `npm run build`
+- **Missing operation:** stderr listing related paths + suggest `cicd invoke`
+
+Do not log secrets beyond existing profile/header behavior.
+
+### What OpenAPI is not used for (today)
+
+The bundled specs are **routing catalogs**, not full client generators. The CLI does **not**:
+
+- validate request/response bodies against JSON Schema at runtime
+- auto-generate Commander flags from parameters
+- register every operation as its own subcommand
+
+For ad-hoc access to any inner route, use **`cicd invoke`**. For new product commands, extend discovery as above.
+
+## How to develop
+
+### Watch mode
+
+```bash
+npm run dev
+```
+
+Keep this running in one terminal; run `node dist/cli.js …` in another after each compile. After pulling OpenAPI spec changes, run **`npm run build:openapi`** (or `codegen` then `build`). Watch mode alone does not copy specs to `dist/` or run codegen.
+
+### Tests
+
+```bash
+npm test
+```
+
+Runs `node --test` against `test/` (after a fresh build).
+
+### Project layout
+
+```
+agentia-cli/
+├── cicd_openapi.json     # CICD Gateway OpenAPI v1 (copied to dist on build)
+├── cicd_openapi.v2.json  # CICD Gateway OpenAPI v2 corpus (copied to dist on build)
+├── package.json
+├── tsconfig.json
+├── scripts/
+│   ├── codegen.mjs       # OpenAPI → src/generated/ (runs on build)
+│   └── copy-openapi.mjs  # repo-root specs → dist/
+├── src/
+│   ├── generated/        # OpenAPI Generator output (committed; do not edit)
+│   ├── cli.ts            # Entry and Commander wiring
+│   ├── config.ts         # Profiles and config file I/O
+│   ├── region.ts         # NA/NA2/EU/CUSTOM → Front API base URL
+│   ├── auth/
+│   │   └── frontApiHeaders.ts  # token2 vs PAT Front API headers
+│   ├── crt/
+│   │   ├── region.ts     # QA/US/AU/EU/SG → Platform base URL
+│   │   └── auth/         # PAT validation (Platform GET /users/me)
+│   ├── cicd-client.ts    # POST /json/v1/cicd-api; shared success/error helpers
+│   ├── cicd/
+│   │   ├── credential-authenticate.ts
+│   │   ├── repository-authenticate.ts  # GitLab OAuth via direct Front API
+│   │   ├── deploy-selection.ts  # Deploy selection request builder
+│   │   └── commit-request.ts  # Commit request builder
+│   ├── openapi.ts        # Load bundled specs; find*Operation discovery
+│   ├── cmd/
+│   │   ├── login.ts      # login token2, login pat
+│   │   ├── cicd.ts
+│   │   ├── cicd-environment.ts
+│   │   ├── cicd-repository.ts
+│   │   ├── cicd-deploy-selection.ts
+│   │   ├── cicd-commit.ts
+│   │   └── user-story.ts
+│   └── util/
+│       └── commander.ts
+├── test/
+│   ├── cicd-client.test.js
+│   ├── cicd-environment.test.js
+│   ├── cicd-repository.test.js
+│   ├── repository-authenticate.test.js
+│   ├── login-pat.test.js
+│   ├── openapi.test.js
+│   └── proxy-contract.test.js
+└── dist/                 # build output
+```
+
+## License / distribution
+
+The package is marked `"private": true` in `package.json`; publishing and licensing are defined by your Copado release process, not by this README.