@automatify-au/cli 0.1.0

package/README.md

@@ -0,0 +1,389 @@
+# @automatify-au/cli
+
+Minimal Forge-first CLI for Automatify Jira TestOps.
+
+Current product stance:
+- Jira UI is the primary day-to-day surface for most users.
+- The CLI is the primary admin and automation surface for setup, ingestion, diagnostics, reporting, and CI.
+- POC audience: operators, CI, internal support, and customer admins running controlled setup/import flows.
+- Future customer-admin packaging is expected before any broader distribution.
+- Any future all-user CLI requires a different auth/onboarding model than the current project-scoped admin key transport.
+
+## Architecture boundary (must hold)
+- Thin client only.
+- No separate backend.
+- No duplicate domain/business logic in CLI.
+- CLI commands must call shared Forge contracts (resolver/webtrigger paths) as they are introduced.
+
+## MVP non-goals
+- No separate backend.
+- No duplicate domain/business logic in CLI.
+- No replacement of Jira UI as a primary product surface.
+- No backend-assisted/hybrid logic in this phase.
+
+## Install and run
+
+### From npm (published package)
+```bash
+npm install -g @automatify-au/cli
+automatify --help
+automatify testops --help
+```
+
+### From repository (development)
+```bash
+pnpm install
+pnpm --filter @automatify-au/cli build
+pnpm --filter @automatify-au/cli bundle
+```
+
+This produces a single self-contained bundle at `dist/automatify.js` (≈125 KB) with `@automatify/shared-types` inlined. No runtime dependencies.
+
+Run built CLI:
+```bash
+automatify testops --help           # if linked globally (npm link)
+node apps/cli/dist/automatify.js --help  # direct node run
+```
+
+Dev run (for local iteration):
+```bash
+pnpm --filter @automatify-au/cli run cli:dev -- --help
+```
+
+### Bundle and publish
+```bash
+cd apps/cli
+npm test                      # optional but recommended local preflight
+npm pack --dry-run            # inspect final tarball contents
+npm publish --dry-run --access public  # simulate publish against npm
+npm publish --access public   # publish to npm
+```
+
+Publish notes:
+- `prepack` now rebuilds `dist/automatify.js` automatically, so `npm pack` and `npm publish` do not rely on a stale bundle.
+- `prepublishOnly` runs the CLI test suite and then rebuilds the bundle before a real publish.
+- Current package target is `@automatify-au/cli`; verify npm auth with `npm whoami` if needed before publishing.
+
+## Required configuration
+Minimum:
+- `JIRA_BASE_URL`
+- At least one of `JIRA_PROJECT_KEY` or `JIRA_ISSUE_KEY`
+- `TESTOPS_FORGE_ENDPOINT` for commands that call Forge contracts (`doctor`, `ingest`, `run`, `sync`)
+- `TESTOPS_FORGE_AUTH_TOKEN` from the one-time token shown in Forge `Operations -> CLI access`
+
+Optional:
+- `TESTOPS_FORGE_TIMEOUT_MS`
+- `TESTOPS_FORGE_MAX_RETRIES`
+- `TESTOPS_FORGE_RETRY_DELAY_MS`
+- `TESTOPS_AUTH_MODE`, `JIRA_EMAIL`, `JIRA_API_TOKEN` (when auth mode requires)
+
+## Command reference (MVP)
+
+All TestOps commands are invoked as `automatify testops <command>`:
+
+- `bdd`
+  - `automatify testops bdd scenarios show --id <SCENARIO_ID>`
+- `cases`
+  - `automatify testops cases list`
+  - `automatify testops cases show --key <TEST_CASE_KEY>`
+  - `automatify testops cases bdd list --key <TEST_CASE_KEY>`
+  - `automatify testops cases runs list --key <TEST_CASE_KEY>`
+- `config`
+  - `automatify testops config show`
+  - `automatify testops config validate`
+- `ingest`
+  - `automatify testops ingest feature --file <path>` or `--stdin`
+- `run`
+  - `automatify testops run upload --file <path>` or `--stdin`
+- `runs`
+  - `automatify testops runs show --id <RUN_ID>`
+- `suites`
+  - `automatify testops suites list`
+  - `automatify testops suites show --key <SUITE_KEY>`
+  - `automatify testops suites cases list --key <SUITE_KEY>`
+- `doctor`
+  - `automatify testops doctor check`
+  - `automatify testops doctor check --json`
+- `sync` (gated)
+  - enable with `TESTOPS_ENABLE_SYNC=1`
+  - `automatify testops sync status`
+  - `automatify testops sync reconcile --confirm RECONCILE`
+
+## `automatify testops auto` (MVP)
+Purpose:
+- deterministic onboarding/import helper for local and CI workflows.
+- thin orchestration only; domain logic stays in Forge contracts/services.
+
+Supported commands:
+- `automatify testops auto --dry-run`
+- `automatify testops auto`
+
+Required env/config for real upload mode:
+- `JIRA_BASE_URL`
+- `JIRA_PROJECT_KEY` (or `--project-key`)
+- `TESTOPS_FORGE_ENDPOINT`
+- `TESTOPS_FORGE_AUTH_TOKEN` for the repo-owned authenticated webtrigger transport
+
+One-time Forge transport setup:
+```bash
+cd apps/forge
+forge deploy
+forge install --upgrade --site automatify-com-au.atlassian.net --product Jira -e development --confirm-scopes --non-interactive
+forge webtrigger create --functionKey cli-transport-webtrigger --site automatify-com-au.atlassian.net --product Jira -e development
+```
+
+Then open the Jira project page, go to `Operations -> CLI access`, create a CLI key, and copy the token immediately. It is shown once only.
+
+Export the webtrigger URL and the one-time token for CLI use:
+```bash
+export TESTOPS_FORGE_ENDPOINT="<webtrigger-url>"
+export TESTOPS_FORGE_AUTH_TOKEN="<one-time-token-from-forge-ui>"
+export JIRA_BASE_URL="https://automatify-com-au.atlassian.net"
+export JIRA_PROJECT_KEY="DEV"
+```
+
+Transport notes:
+- Bearer auth is required for operator/CI use. Forge stores only the token hash plus metadata.
+- Tokens are project-scoped, shown once at creation time, and can be revoked from the Forge UI.
+- Expired or revoked tokens are rejected by the transport.
+
+Scenario automation callback example:
+```bash
+curl -sS "$TESTOPS_FORGE_ENDPOINT" \
+  -H "authorization: Bearer $TESTOPS_FORGE_AUTH_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{
+    "contract":"updateScenarioAutomationStatus",
+    "payload":{
+      "context":{"projectKey":"DEV"},
+      "scenarioId":"manual:checkout:guest-payment",
+      "status":"running",
+      "externalRunId":"gha-1024",
+      "externalRunUrl":"https://github.com/Automatify-Pty-Ltd/automatify-jira-testops/actions/runs/1024",
+      "responseStatus":202,
+      "responseSnippet":"workflow is running"
+    }
+  }' | jq
+```
+
+You can also resolve the target by `automationId` or `scenarioRef` instead of `scenarioId`.
+
+GitHub Actions callback example:
+```yaml
+- name: Report scenario automation status to Forge
+  if: ${{ always() }}
+  env:
+    TESTOPS_FORGE_ENDPOINT: ${{ secrets.TESTOPS_FORGE_ENDPOINT }}
+    TESTOPS_FORGE_AUTH_TOKEN: ${{ secrets.TESTOPS_FORGE_AUTH_TOKEN }}
+    TESTOPS_PROJECT_KEY: DEV
+    TESTOPS_SCENARIO_REF: checkout.feature#3
+    TESTOPS_STATUS: ${{ job.status == 'success' && 'passed' || job.status == 'cancelled' && 'cancelled' || 'failed' }}
+  run: |
+    curl -sS "$TESTOPS_FORGE_ENDPOINT" \
+      -H "authorization: Bearer $TESTOPS_FORGE_AUTH_TOKEN" \
+      -H "content-type: application/json" \
+      -d "{
+        \"contract\":\"updateScenarioAutomationStatus\",
+        \"payload\":{
+          \"context\":{\"projectKey\":\"$TESTOPS_PROJECT_KEY\"},
+          \"scenarioRef\":\"$TESTOPS_SCENARIO_REF\",
+          \"status\":\"$TESTOPS_STATUS\",
+          \"externalRunId\":\"${GITHUB_RUN_ID}\",
+          \"externalRunUrl\":\"https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}\",
+          \"responseStatus\":200,
+          \"responseSnippet\":\"GitHub Actions callback from ${GITHUB_WORKFLOW}\"
+        }
+      }"
+```
+
+Azure DevOps callback example:
+```yaml
+- bash: |
+    set -euo pipefail
+    if [ "$(Agent.JobStatus)" = "Succeeded" ]; then
+      TESTOPS_STATUS="passed"
+    elif [ "$(Agent.JobStatus)" = "Canceled" ]; then
+      TESTOPS_STATUS="cancelled"
+    else
+      TESTOPS_STATUS="failed"
+    fi
+
+    curl -sS "$(TESTOPS_FORGE_ENDPOINT)" \
+      -H "authorization: Bearer $(TESTOPS_FORGE_AUTH_TOKEN)" \
+      -H "content-type: application/json" \
+      -d "{
+        \"contract\":\"updateScenarioAutomationStatus\",
+        \"payload\":{
+          \"context\":{\"projectKey\":\"DEV\"},
+          \"scenarioRef\":\"checkout.feature#3\",
+          \"status\":\"${TESTOPS_STATUS}\",
+          \"externalRunId\":\"$(Build.BuildId)\",
+          \"externalRunUrl\":\"$(System.CollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)\",
+          \"responseStatus\":200,
+          \"responseSnippet\":\"Azure DevOps callback from $(Build.DefinitionName)\"
+        }
+      }"
+  displayName: Report scenario automation status to Forge
+```
+
+Hierarchy browse examples:
+```bash
+automatify testops cases list --project-key DEV
+automatify testops cases show --project-key DEV --key TC-1 --json
+automatify testops cases bdd list --project-key DEV --key TC-1 --json
+automatify testops cases runs list --project-key DEV --key TC-1 --json
+automatify testops bdd scenarios show --project-key DEV --id <SCENARIO_ID> --json
+automatify testops runs show --project-key DEV --id <RUN_ID> --json
+automatify testops suites list --project-key DEV --json
+automatify testops suites cases list --project-key DEV --key TS-1
+```
+
+Recommended hierarchy browse flow:
+```bash
+# 1. Find a case worth inspecting.
+automatify testops cases list --project-key DEV
+
+# 2. Inspect one case in detail.
+automatify testops cases show --project-key DEV --key TC-145 --json
+
+# 3. Inspect the BDD scenarios linked to that case.
+automatify testops cases bdd list --project-key DEV --key TC-145 --json
+
+# 4. Inspect the execution history linked to that case.
+automatify testops cases runs list --project-key DEV --key TC-145 --json
+
+# 5. Drill into one scenario or one run as needed.
+automatify testops bdd scenarios show --project-key DEV --id <SCENARIO_ID> --json
+automatify testops runs show --project-key DEV --id <RUN_ID> --json
+```
+
+Coverage and readiness report via the Forge transport:
+```bash
+curl -sS "$TESTOPS_FORGE_ENDPOINT" \
+  -H "authorization: Bearer $TESTOPS_FORGE_AUTH_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"contract":"getCoverageReport","payload":{"context":{"projectKey":"DEV"}}}' | jq
+```
+
+Deterministic dry-run preview (human):
+```bash
+pnpm --filter @automatify-au/cli build
+automatify testops auto \
+  --dry-run \
+  --root apps/cli/test-fixtures/auto/execution-layout
+```
+
+Deterministic dry-run preview (JSON for CI):
+```bash
+preview_json="$(automatify testops auto \
+  --dry-run \
+  --root apps/cli/test-fixtures/auto/execution-layout \
+  --output json)"
+echo "$preview_json"
+node -e 'const p=JSON.parse(process.argv[1]); if(!p.preview || !p.preview.mapping){process.exit(2)}' "$preview_json"
+```
+
+Real execution mode (Forge upload path):
+```bash
+automatify testops auto \
+  --root apps/cli/test-fixtures/auto/execution-layout \
+  --project-key DEV \
+  --force \
+  --output json
+```
+
+Recommended CI sequence:
+1. `automatify testops config validate`
+2. `automatify testops doctor check --json`
+3. `automatify testops auto --dry-run --output json ...`
+4. `automatify testops auto --force --output json ...`
+
+`automatify testops auto` MVP limits (explicit):
+- detection scope is Playwright, pytest, cucumber/behave hints only.
+- artifact scope is JUnit XML + Cucumber JSON + `.feature` files.
+- mapping is deterministic MVP only (issue-key and supported exact-name matching).
+- no AI-based matching, no backend-assisted matching, no storage surgery actions.
+
+### `automatify testops auto` pilot adoption checklist
+1. Run deterministic preview:
+   - `automatify testops auto --dry-run --output json --root <repo-root>`
+2. Confirm preview is actionable:
+   - framework mode is not `unknown` unless expected,
+   - discovered artifacts count is non-zero for upload scenarios,
+   - unmatched diagnostics are reviewed.
+3. Verify readiness gate:
+   - `automatify testops doctor check --json`
+4. Run first real upload in controlled branch/commit:
+   - `automatify testops auto --force --output json --project-key <KEY> --root <repo-root>`
+5. Record command result and warnings in pilot notes.
+
+## Deterministic exit-code mapping
+- `0` success
+- `1` internal/runtime error
+- `2` usage/argument errors
+- `3` local validation errors
+- `4` Forge service errors (`ok: false` payload)
+- `5` Forge transport/connectivity errors
+
+## CI usage examples
+
+Doctor preflight with JSON parsing:
+```bash
+set -euo pipefail
+pnpm --filter @automatify-au/cli build
+export TESTOPS_FORGE_ENDPOINT="${TESTOPS_FORGE_ENDPOINT:?missing}"
+export JIRA_BASE_URL="${JIRA_BASE_URL:?missing}"
+export JIRA_PROJECT_KEY="${JIRA_PROJECT_KEY:?missing}"
+
+doctor_json="$(automatify testops doctor check --json)"
+echo "$doctor_json"
+node -e 'const d=JSON.parse(process.argv[1]); if(!d.status){process.exit(2)}' "$doctor_json"
+```
+
+Feature ingest from file:
+```bash
+pnpm --filter @automatify-au/cli build
+automatify testops ingest feature \
+  --file ./artifacts/checkout.feature \
+  --project-key DEV
+```
+
+Run upload from file with CI-friendly branching:
+```bash
+set +e
+pnpm --filter @automatify-au/cli build
+automatify testops run upload \
+  --file ./artifacts/run.json \
+  --project-key DEV \
+  --json
+code=$?
+set -e
+
+case "$code" in
+  0) echo "run upload succeeded" ;;
+  2|3) echo "usage/validation issue, fail fast" ; exit "$code" ;;
+  4) echo "Forge service rejected payload" ; exit "$code" ;;
+  5) echo "Forge connectivity issue, consider retry" ; exit "$code" ;;
+  *) echo "unexpected failure" ; exit "$code" ;;
+esac
+```
+
+## Adoption checklist (MVP)
+1. Build CLI:
+   - `pnpm --filter @automatify-au/cli build && pnpm --filter @automatify-au/cli bundle`
+2. Validate config:
+   - `automatify testops config validate`
+3. Run doctor preflight:
+   - `automatify testops doctor check --json`
+4. Ingest one sample feature:
+   - `automatify testops ingest feature --file ./artifacts/checkout.feature --project-key DEV`
+5. Upload one sample run:
+   - `automatify testops run upload --file ./artifacts/run.json --project-key DEV --json`
+6. (Optional) Verify sync:
+   - `TESTOPS_ENABLE_SYNC=1 automatify testops sync status`
+
+## Runbook integration
+- Pilot onboarding/operator triage snippets:
+  - `PILOT_ONBOARDING.md`
+- Release and rollback flow:
+  - `RELEASE_RUNBOOK.md`