@aurodesignsystem-dev/auro-cli 0.0.0-pr289.2 → 0.0.0-pr294.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +104 -0
  2. package/dist/auro-cli.js +125 -50
  3. package/dist/auro-cli.js.map +4 -4
  4. package/dist/migrations/package-update-node/migration.js +2 -2
  5. package/dist/migrations/wca-script-update/migration.js +2 -2
  6. package/package.json +13 -4
package/README.md CHANGED
@@ -12,6 +12,7 @@ Auro CLI is a command-line interface designed to help consumers of the Auro Desi
12
12
  ## Table of Contents
13
13
 
14
14
  - [Installation](#installation)
15
+ - [First time setup](#first-time-setup)
15
16
  - [Usage](#usage)
16
17
  - [Commands](#commands)
17
18
  - [Options](#options)
@@ -25,6 +26,42 @@ To install Auro CLI, clone the repository and install the dependencies:
25
26
  npm install @aurodesignsystem/auro-cli
26
27
  ```
27
28
 
29
+ ## First time setup
30
+
31
+ Some commands talk to GitHub or Azure DevOps and need Personal Access Tokens.
32
+ The CLI auto-loads variables from a `.env` file in your **current working
33
+ directory**, so each user manages their own tokens locally.
34
+
35
+ 1. Copy the template into a real `.env`:
36
+
37
+ ```bash
38
+ cp .env.example .env
39
+ ```
40
+
41
+ `.env` is gitignored — never commit it.
42
+
43
+ 2. Generate a **GitHub PAT** at <https://github.com/settings/tokens> →
44
+ *Personal access tokens (classic)* → *Generate new token (classic)*.
45
+ - Scope: `repo` (read access to private repos and CHANGELOG content).
46
+ - You also need read access to the `Alaska-ECommerce` and
47
+ `AlaskaAirlines` orgs.
48
+ - Paste the token into `GH_TOKEN=` in your `.env`.
49
+
50
+ 3. Generate an **Azure DevOps PAT** at
51
+ <https://dev.azure.com/itsals/_usersSettings/tokens> → *+ New Token*.
52
+ - Organization: `itsals`.
53
+ - Scope: *Custom defined* → **Work Items: Read, write, & manage**.
54
+ - Paste the token into `ADO_TOKEN=` in your `.env`.
55
+
56
+ 4. (Optional) Override `ECOM_ORG` in `.env` if you want `auro version-scan`
57
+ to default to a different GitHub org than `Alaska-ECommerce`.
58
+
59
+ For CI / scheduled automation, skip the `.env` file entirely — export the
60
+ same variables from your CI's secret store (GitHub Actions secrets, Azure
61
+ Pipelines variables marked secret, etc.) and the CLI will read them
62
+ directly. Use a dedicated bot/service-account PAT for automation, not a
63
+ personal one.
64
+
28
65
  ## Usage
29
66
 
30
67
  To use Auro CLI, run the following command in your terminal:
@@ -58,3 +95,70 @@ Open the server to a specific directory:
58
95
  ```
59
96
  auro dev --open src/
60
97
  ```
98
+
99
+ `auro version-scan`
100
+ Scans a GitHub organization for repos using outdated `@aurodesignsystem/*` and `@alaskaairux/*` packages, and writes two JSON files under `./.cache/version-bot/`:
101
+
102
+ - `auro-deps-by-ecommerce-repo.json` — full per-repo Auro dependency snapshot (incremental, keyed by `pushed_at`).
103
+ - `auro-upgrade-candidates.json` — flat list of `(repo, package, pinned, latest, majorsBehind)` rows for every pair at least one major version behind. This is the input to `auro version-tickets`.
104
+
105
+ Re-runs are incremental — repos whose `pushed_at` matches the cache are skipped.
106
+
107
+ #### Required environment variables
108
+
109
+ - `GH_TOKEN` — GitHub token with read access to the target org and to `AlaskaAirlines` (used to fetch each `package.json` and to detect archived Auro source repos).
110
+
111
+ #### Options
112
+
113
+ - `--org <name>` GitHub org to scan (default: value of `ECOM_ORG` env var, or `Alaska-ECommerce`).
114
+ - `--force` Re-scan every repo, ignoring the `pushed_at` incremental short-circuit (default: false).
115
+ - `--output-dir <dir>` Directory to write the cache + candidates JSON (default: `./.cache/version-bot/`). Override for CI artifact paths or one-off runs.
116
+
117
+ #### Examples
118
+
119
+ Initial scan of the default org:
120
+
121
+ ```
122
+ auro version-scan
123
+ ```
124
+
125
+ Scan a different org and force a full refresh:
126
+
127
+ ```
128
+ auro version-scan --org SomeOtherOrg --force
129
+ ```
130
+
131
+ `auro version-tickets`
132
+ Reads `./.cache/version-bot/auro-upgrade-candidates.json` (produced by `auro version-scan`) and creates an Azure DevOps User Story per `(repo, package)` upgrade candidate under `E_Retain_Content\Auro Design System`. Defaults to dry-run; pass `--apply` to actually write to ADO. Every ticket is tagged `auro`, `version-upgrade`, and `majors-behind-<n>`.
133
+
134
+ #### Required environment variables
135
+
136
+ - `GH_TOKEN` — GitHub token used to fetch CHANGELOG.md from `AlaskaAirlines/<package-name>` for the migration-guide section. If unset, tickets fall back to a plain CHANGELOG link.
137
+ - `ADO_TOKEN` — Azure DevOps Personal Access Token with **Work Items: Read, write, & manage** scope on the `itsals` org. Required only with `--apply`.
138
+
139
+ #### Options
140
+
141
+ - `--min-majors <n>` Only ticket candidates at or above this majors-behind threshold (default: 2).
142
+ - `--apply` Actually create tickets in ADO. Without this flag, the command runs in dry-run mode (default: false).
143
+ - `--limit <n>` Cap on how many tickets to process this run.
144
+ - `--repo <name>` Only process candidates from this consumer repo.
145
+
146
+ #### Examples
147
+
148
+ Dry-run preview of all candidates 2+ majors behind:
149
+
150
+ ```
151
+ auro version-tickets
152
+ ```
153
+
154
+ Bounded first live run — one ticket from one repo:
155
+
156
+ ```
157
+ auro version-tickets --apply --limit 1 --repo my-safe-repo
158
+ ```
159
+
160
+ Lower the threshold and dry-run everything 1+ major behind:
161
+
162
+ ```
163
+ auro version-tickets --min-majors 1
164
+ ```