@automatify-au/cli 0.1.11 → 0.1.13

package/README.md

@@ -141,6 +141,11 @@ All TestOps commands are invoked as `automatify testops <command>`:
 
 ### Setup, ingestion, and CI commands
 
+- `setup`
+  - `automatify testops setup plan ... > testops-setup-plan.json`
+  - `automatify testops setup apply --plan testops-setup-plan.json --dry-run`
+  - `automatify testops setup apply --plan testops-setup-plan.json --approve all --confirm ...`
+  - `automatify testops setup doctor --plan testops-setup-plan.json ...`
 - `ingest`
   - `automatify testops ingest feature --file <path>` or `--stdin`
 - `run`
@@ -154,6 +159,110 @@ All TestOps commands are invoked as `automatify testops <command>`:
   - `automatify testops auto --dry-run`
   - `automatify testops auto`
 
+## Agent-friendly provider setup
+
+`automatify testops setup` provides a GitHub-first, provider-bounded onboarding flow. The CLI remains a thin Forge client: Jira profile reads/writes/default selection use the existing `listScenarioAutomationProfiles`, `upsertScenarioAutomationProfile`, and `setScenarioAutomationDefaultProfile` contracts. Forge continues to own profile validation, tier limits, provider-secret storage, and default-profile rules.
+
+### 1. Generate a deterministic plan
+
+Run this from the repository that contains the approved workflow source:
+
+```bash
+automatify testops setup plan \
+  --provider github-actions \
+  --project-key DEV \
+  --owner Automatify-Pty-Ltd \
+  --repo customer-tests \
+  --ref main \
+  --workflow-id scenario-dispatch.yml \
+  --workflow-source .github/workflows/scenario-dispatch.yml \
+  --workflow-path .github/workflows/scenario-dispatch.yml \
+  --profile-label "Customer GitHub Actions" \
+  --set-default \
+  > testops-setup-plan.json
+```
+
+The command itself writes nothing: it emits one versioned JSON plan to stdout, and the shell redirection above saves it. The plan contains the workflow source path and SHA-256 digest, not workflow contents or secret values. The source must declare `workflow_dispatch` and reference the selected callback secret names. Given the same explicit inputs and unchanged workflow source, the plan and `planId` are deterministic.
+
+The GitHub plan covers:
+
+- local workflow destination and approved source hash;
+- repository, ref, workflow id, and Jira profile fields;
+- required `TESTOPS_FORGE_ENDPOINT` and `TESTOPS_FORGE_AUTH_TOKEN` repository secret names;
+- profile create/update, optional project-default selection, read-only smoke checks, and rollback guidance;
+- explicit exclusion of account creation, credentials, commits, pull requests, and workflow runs.
+
+### 2. Validate with a mutation-free dry-run
+
+```bash
+automatify testops setup apply \
+  --plan testops-setup-plan.json \
+  --repo-root /path/to/customer-tests \
+  --dry-run
+```
+
+Dry-run previews all plan actions when no `--approve` is supplied. It may call read contracts to describe current state, but it does not write files, Jira profiles/defaults, GitHub secrets, commits, PRs, or workflow runs. Output is stable JSON.
+
+### 3. Apply only explicitly approved scopes
+
+Secrets must come from stdin or safe environment references. Secret values are rejected as ordinary command options and are not printed in JSON, logs, diagnostics, snapshots, or child-process arguments.
+
+```bash
+export TESTOPS_GITHUB_PROVIDER_TOKEN="<github-app-installation-or-fine-grained-token>"
+export TESTOPS_GITHUB_ADMIN_TOKEN="<least-privilege-token-allowed-to-manage-actions-secrets>"
+export TESTOPS_FORGE_ENDPOINT="<forge-webtrigger-url>"
+export TESTOPS_FORGE_AUTH_TOKEN="<one-time-project-cli-key>"
+
+automatify testops setup apply \
+  --plan testops-setup-plan.json \
+  --repo-root /path/to/customer-tests \
+  --approve all \
+  --confirm \
+  --secret-ref githubProviderToken=env:TESTOPS_GITHUB_PROVIDER_TOKEN \
+  --secret-ref githubAdminToken=env:TESTOPS_GITHUB_ADMIN_TOKEN \
+  --secret-ref callbackEndpoint=env:TESTOPS_FORGE_ENDPOINT \
+  --secret-ref callbackAuthToken=env:TESTOPS_FORGE_AUTH_TOKEN
+```
+
+Available scopes are `workflow-file`, `github-secrets`, `jira-profile`, and `project-default` when the plan includes the default action. Real mutations require both `--confirm` and one or more `--approve` flags; use repeated flags for a partial apply. `--approve all` approves every action in the content-addressed plan.
+
+The `github-secrets` scope uses the installed `gh` CLI, sends each repository secret through stdin, and passes the GitHub admin credential through `GH_TOKEN` in the child environment. Existing secret names are skipped because GitHub does not expose their values. Use `--rotate-secrets` to explicitly overwrite them. An existing matching Jira profile is also skipped; use `--rotate-provider-token` to explicitly replace its stored provider credential.
+
+For JSON secret input instead of references, pipe one object with supported keys to `--secrets-stdin`:
+
+```bash
+node -e 'process.stdout.write(JSON.stringify({githubProviderToken:process.env.TESTOPS_GITHUB_PROVIDER_TOKEN,githubAdminToken:process.env.TESTOPS_GITHUB_ADMIN_TOKEN,callbackEndpoint:process.env.TESTOPS_FORGE_ENDPOINT,callbackAuthToken:process.env.TESTOPS_FORGE_AUTH_TOKEN}))' \
+  | automatify testops setup apply \
+      --plan testops-setup-plan.json \
+      --repo-root /path/to/customer-tests \
+      --approve all \
+      --confirm \
+      --secrets-stdin
+```
+
+Prefer a GitHub App installation token. When using fine-grained tokens, grant only the selected repository access plus the minimum Actions/Contents/Secrets permissions needed for the approved scopes. The command never creates or commits the workflow remotely; review and commit the local workflow through the repository's normal change-control process.
+
+### 4. Run read-only provider doctor/smoke validation
+
+```bash
+automatify testops setup doctor \
+  --plan testops-setup-plan.json \
+  --repo-root /path/to/customer-tests \
+  --secret-ref githubProviderToken=env:TESTOPS_GITHUB_PROVIDER_TOKEN \
+  --secret-ref githubAdminToken=env:TESTOPS_GITHUB_ADMIN_TOKEN
+```
+
+Doctor verifies the local workflow hash, GitHub workflow metadata/content at the configured ref, required repository secret names, Jira profile fields/provider-secret metadata, and optional project default. It never dispatches a workflow. GitHub secret values cannot be read, so doctor verifies names only and reports that limitation. If the workflow has not been committed to the repository default branch, doctor reports what remains unverifiable without creating a commit or run.
+
+Current authentication boundary:
+
+- `TESTOPS_FORGE_AUTH_TOKEN` is still a project-scoped, project-admin-created CLI key from Jira `Operations -> CLI access`.
+- The key authorizes the current Forge webtrigger transport for that project; command groups are not separate security scopes.
+- Setup does not turn this into an all-user auth model. Customer-admin packaging and any future user-level authentication remain separate work.
+- The same callback key may be stored as a GitHub Actions repository secret only under the explicit `github-secrets` apply scope.
+
+Azure DevOps setup uses the same plan/apply/doctor safety boundary. Generate a plan with `--provider azure-devops`, mapping `--organization`, `--azure-project`, `--pipeline-id`, and `--ref` into the existing `azureDevops` Forge profile. Callback pipeline variables are accepted only through stdin or `--secret-ref key=env:NAME`; dry-run, explicit approval, idempotency, and redaction are identical to GitHub setup. Doctor inspects pipeline metadata and variable names only; it never queues a pipeline run.
+
 ## Allure Evidence for Jira
 
 Purpose:
@@ -551,7 +660,7 @@ Recommended CI sequence:
 - `0` success
 - `1` internal/runtime error
 - `2` usage/argument errors
-- `3` local validation errors
+- `3` local/plan validation errors, doctor failures, or post-apply smoke validation failures
 - `4` Forge service errors (`ok: false` payload)
 - `5` Forge transport/connectivity errors