@automatify-au/cli 0.1.10 → 0.1.12

package/README.md

@@ -120,6 +120,12 @@ All TestOps commands are invoked as `automatify testops <command>`:
 - `doctor`
   - `automatify testops doctor check`
   - `automatify testops doctor check --json`
+- `allure`
+  - `automatify allure doctor`
+  - `automatify allure doctor --json`
+  - `automatify allure doctor --issue-key ABC-123`
+  - `automatify allure open ./allure-report.zip`
+  - `automatify allure open ./allure-report.zip --no-open --port 8080`
 
 ### Advanced browse commands
 
@@ -135,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`
@@ -143,10 +154,115 @@ All TestOps commands are invoked as `automatify testops <command>`:
   - `automatify testops allure upload ABC-123 ./allure-report.zip --dry-run`
   - `automatify testops allure upload ABC-123 ./allure-report.zip`
   - `automatify testops allure download ABC-123 --output-dir ./downloads`
+  - `automatify testops allure open ./allure-report.zip`
 - `auto`
   - `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 follow-up is deliberately outside this stage. The next adapter should reuse the same plan/apply/doctor orchestration and mutation scopes, map Azure organization/project/pipeline/ref fields into the existing `azureDevops` Forge profile config, manage callback pipeline variables through stdin/safe references, inspect pipeline metadata without queueing a run, and preserve the same confirmation/idempotency/redaction rules.
+
 ## Allure Evidence for Jira
 
 Purpose:
@@ -234,6 +350,43 @@ Download dry run / JSON:
 automatify testops allure download ABC-123 --dry-run --json
 ```
 
+Allure preflight:
+```bash
+automatify allure doctor
+```
+
+`automatify allure doctor` checks:
+- Jira site/email/API token resolution for direct Allure upload/download.
+- optional Jira issue access only when `--issue-key` is passed.
+- `unzip` availability for manual local ZIP inspection.
+- Java availability as a warning-only optional check for future raw `allure-results` workflows.
+- Allure CLI availability as a warning-only optional check.
+
+Generated Allure HTML ZIP upload/download/open does not require Java or the Allure CLI.
+
+Optional live Jira issue check:
+```bash
+automatify allure doctor --issue-key ABC-123
+```
+
+### Open a generated Allure HTML report locally
+
+```bash
+automatify allure open ./allure-report.zip
+```
+
+`automatify allure open <zipPath>` and `automatify testops allure open <zipPath>` extract the report into a temporary directory, start a Java-free Node static HTTP server on an ephemeral port, and open the URL in your default browser. This is useful after downloading an Allure ZIP from Jira.
+
+Options:
+- `--port <n>` fixed port (default `0` for an OS-assigned free port).
+- `--host <h>` bind host (default `127.0.0.1`).
+- `--extract-to <dir>` extract into a chosen directory; the directory is preserved on shutdown.
+- `--keep` preserves the auto-created temp extract directory on shutdown.
+- `--no-open` skips browser launch for CI/headless checks.
+- `--json`, `--dry-run`, `--verbose`.
+
+The server stays alive until Ctrl+C / `SIGTERM`. URL path traversal and malformed paths are rejected.
+
 ### Optional gated maintenance commands
 
 - `sync`
@@ -387,6 +540,7 @@ automatify testops bdd features export --project-key DEV --output-dir ./artifact
 automatify testops runs show --project-key DEV --id <RUN_ID> --json
 automatify testops config validate
 automatify testops doctor check --json
+automatify allure doctor --json
 ```
 
 Advanced browse examples:
@@ -506,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