@automatify-au/cli 0.1.2 → 0.1.4

package/README.md

@@ -9,6 +9,11 @@ Current product stance:
 - 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.
 
+Command-group note:
+- The groupings below describe intended usage and complexity only.
+- They are not a security boundary in the current transport model.
+- A valid project CLI token is not yet scoped per command group.
+
 ## Architecture boundary (must hold)
 - Thin client only.
 - No separate backend.
@@ -37,12 +42,12 @@ 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.
+This produces a single self-contained bundle at `dist/automatify.cjs` (≈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
+automatify testops --help            # if linked globally (npm link)
+node apps/cli/dist/automatify.cjs --help  # direct node run
 ```
 
 Dev run (for local iteration):
@@ -77,34 +82,56 @@ Optional:
 - `TESTOPS_FORGE_RETRY_DELAY_MS`
 - `TESTOPS_AUTH_MODE`, `JIRA_EMAIL`, `JIRA_API_TOKEN` (when auth mode requires)
 
-## Command reference (MVP)
+## Command groups (MVP)
 
 All TestOps commands are invoked as `automatify testops <command>`:
 
+### Core browse commands
+
 - `bdd`
   - `automatify testops bdd scenarios show --id <SCENARIO_ID>`
+  - `automatify testops bdd scenarios show --id <SCENARIO_ID> --format feature`
+  - `automatify testops bdd scenarios export --id <SCENARIO_ID|SC-4> --output-dir ./scenario-export`
+  - `automatify testops bdd scenarios export --all --output-dir ./scenario-export`
+  - `automatify testops bdd scenarios import --file ./scenario-export/SC-4.feature`
+  - `automatify testops bdd scenarios import --input-dir ./scenario-export`
+  - `automatify testops bdd features export --output-dir ./features-export`
+  - `automatify testops bdd features export --output-dir ./features-export --zip`
+  - `automatify testops bdd features export --output-dir ./features-export --feature-id <FEATURE_ID>`
+- `runs`
+  - `automatify testops runs show --id <RUN_ID>`
+- `config`
+  - `automatify testops config show`
+  - `automatify testops config validate`
+- `doctor`
+  - `automatify testops doctor check`
+  - `automatify testops doctor check --json`
+
+### Advanced browse commands
+
 - `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)
+
+### Setup, ingestion, and CI commands
+
+- `ingest`
+  - `automatify testops ingest feature --file <path>` or `--stdin`
+- `run`
+  - `automatify testops run upload --file <path>` or `--stdin`
+- `auto`
+  - `automatify testops auto --dry-run`
+  - `automatify testops auto`
+
+### Optional gated maintenance commands
+
+- `sync`
   - enable with `TESTOPS_ENABLE_SYNC=1`
   - `automatify testops sync status`
   - `automatify testops sync reconcile --confirm RECONCILE`
@@ -226,37 +253,76 @@ Azure DevOps callback example:
   displayName: Report scenario automation status to Forge
 ```
 
-Hierarchy browse examples:
+Azure DevOps setup note:
+- prefer pipeline variables for `TESTOPS_FORGE_ENDPOINT`
+- prefer secret pipeline variables for `TESTOPS_FORGE_AUTH_TOKEN`
+- do not keep those values in the Jira automation profile `bodyTemplate`
+
+Core browse examples:
+```bash
+automatify testops bdd scenarios show --project-key DEV --id <SCENARIO_ID> --json
+automatify testops bdd scenarios export --project-key DEV --id SC-4 --output-dir ./artifacts/scenario-export --json
+automatify testops bdd scenarios import --project-key DEV --file ./artifacts/scenario-export/SC-4.feature --json
+automatify testops bdd scenarios export --project-key DEV --all --output-dir ./artifacts/scenario-bulk --json
+automatify testops bdd scenarios import --project-key DEV --input-dir ./artifacts/scenario-bulk --json
+automatify testops bdd features export --project-key DEV --output-dir ./artifacts/features-export --zip --json
+automatify testops runs show --project-key DEV --id <RUN_ID> --json
+automatify testops config validate
+automatify testops doctor check --json
+```
+
+Advanced 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:
+Recommended browse flow:
 ```bash
-# 1. Find a case worth inspecting.
-automatify testops cases list --project-key DEV
+# Path A: scenario-first browse
+automatify testops bdd scenarios show --project-key DEV --id <SCENARIO_ID> --json
+automatify testops runs show --project-key DEV --id <RUN_ID> --json
 
-# 2. Inspect one case in detail.
+# Path B: testcase-assisted browse
+automatify testops cases list --project-key DEV
 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
 ```
 
+Feature-file round-trip:
+```bash
+# Export all Jira-managed BDD features as .feature files
+automatify testops bdd features export --project-key DEV --output-dir ./artifacts/features-export --zip --json
+
+# Export one scenario as SC-4.feature and import it back after editing
+automatify testops bdd scenarios export --project-key DEV --id SC-4 --output-dir ./artifacts/scenario-export
+automatify testops bdd scenarios import --project-key DEV --file ./artifacts/scenario-export/SC-4.feature
+
+# Export every visible SC-* file and import the whole folder back later
+automatify testops bdd scenarios export --project-key DEV --all --output-dir ./artifacts/scenario-bulk
+automatify testops bdd scenarios import --project-key DEV --input-dir ./artifacts/scenario-bulk
+
+# Re-import one exported file later
+automatify testops ingest feature --project-key DEV --file ./artifacts/features-export/001-checkout.feature
+```
+
+Feature export notes:
+- `bdd scenarios show --format feature` renders one scenario in feature-style text.
+- `bdd scenarios export` writes a single-scenario `SC-*.feature` file with a reserved `@testops-scenario-SC-*` tag.
+- Jira issue links are exported as normal Gherkin tags like `@DEV-2`; on import they are written back to `linkedIssueKeys`.
+- current model has `linked issues`, not a separate persisted `primary issue`, so all exported issue-key tags are treated as equal links.
+- `bdd features export` writes one `.feature` file per stored BDD feature plus `manifest.json`.
+- with `--zip`, the CLI also writes `./artifacts/features-export.zip` next to the export directory.
+- pass `--issue-key DEV-2` to export only features visible in that Jira issue context.
+- `getSummaryExport` remains the reporting/export path for JSON/CSV summary snapshots and is separate from feature-file round-trip export.
+
 Coverage and readiness report via the Forge transport:
 ```bash
 curl -sS "$TESTOPS_FORGE_ENDPOINT" \
@@ -348,6 +414,16 @@ automatify testops ingest feature \
   --project-key DEV
 ```
 
+Bulk feature export to local `.feature` files:
+```bash
+pnpm --filter @automatify-au/cli build
+automatify testops bdd features export \
+  --project-key DEV \
+  --output-dir ./artifacts/features-export \
+  --zip \
+  --json
+```
+
 Run upload from file with CI-friendly branching:
 ```bash
 set +e