@freecodecamp/universe-cli 0.3.2 → 0.4.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.
- package/README.md +88 -19
- package/dist/index.cjs +16060 -47360
- package/dist/index.js +1422 -792
- package/package.json +7 -10
package/README.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
Static site deployment for the freeCodeCamp Universe platform.
|
|
4
4
|
|
|
5
|
+
> v0.4 routes every deploy through the **artemis** proxy at
|
|
6
|
+
> `uploads.freecode.camp`. Staff hold only a `platform.yaml` and a
|
|
7
|
+
> GitHub identity — the proxy holds the R2 credentials. See
|
|
8
|
+
> [Universe ADR-016](https://github.com/freeCodeCamp-Universe/Universe/blob/main/decisions/016-deploy-proxy.md)
|
|
9
|
+
> for the full design.
|
|
10
|
+
|
|
5
11
|
## Install
|
|
6
12
|
|
|
7
13
|
### npm
|
|
@@ -47,43 +53,106 @@ Verify:
|
|
|
47
53
|
universe --version
|
|
48
54
|
```
|
|
49
55
|
|
|
50
|
-
##
|
|
56
|
+
## CLI surface
|
|
57
|
+
|
|
58
|
+
Top-level (cross-cutting):
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
universe login # GitHub OAuth device flow → ~/.config/universe-cli/token
|
|
62
|
+
universe logout # delete stored token
|
|
63
|
+
universe whoami # echo current login + authorized sites
|
|
64
|
+
universe --version # CLI version
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Static-site verbs (namespaced under `static`):
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
universe static deploy [--promote] [--dir <path>]
|
|
71
|
+
universe static promote [--from <deployId>]
|
|
72
|
+
universe static rollback --to <deployId>
|
|
73
|
+
universe static ls [--site <site>]
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
All commands support `--json` for CI integration.
|
|
77
|
+
|
|
78
|
+
## Identity (priority chain)
|
|
79
|
+
|
|
80
|
+
The CLI resolves a GitHub identity in this order — first match wins:
|
|
81
|
+
|
|
82
|
+
1. `$GITHUB_TOKEN` / `$GH_TOKEN` env (CI explicit)
|
|
83
|
+
2. GHA OIDC (`$ACTIONS_ID_TOKEN_REQUEST_URL` + `$ACTIONS_ID_TOKEN_REQUEST_TOKEN`)
|
|
84
|
+
3. Woodpecker OIDC env (deferred — placeholder slot)
|
|
85
|
+
4. `gh auth token` shell-out (laptop with `gh` installed)
|
|
86
|
+
5. Device-flow stored token at `~/.config/universe-cli/token`
|
|
87
|
+
|
|
88
|
+
The proxy validates whatever it receives via GitHub `GET /user`, then
|
|
89
|
+
authorizes against the `sites.yaml` map server-side. Run
|
|
90
|
+
`universe whoami` to see which slot resolved.
|
|
91
|
+
|
|
92
|
+
## Configuration (`platform.yaml`)
|
|
93
|
+
|
|
94
|
+
Every site has a `platform.yaml` at its repo root. Minimal valid file:
|
|
95
|
+
|
|
96
|
+
```yaml
|
|
97
|
+
site: my-site
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Full reference (every field, defaults, validation rules, v0.3 → v0.4
|
|
101
|
+
migration): [`docs/platform-yaml.md`](docs/platform-yaml.md).
|
|
102
|
+
|
|
103
|
+
No credential fields. The proxy holds the R2 admin key; the CLI never
|
|
104
|
+
reads or writes one.
|
|
105
|
+
|
|
106
|
+
## Common flows
|
|
51
107
|
|
|
52
108
|
```sh
|
|
53
|
-
#
|
|
109
|
+
# 1. Authenticate (laptop, first time)
|
|
110
|
+
universe login
|
|
111
|
+
|
|
112
|
+
# 2. Deploy to preview
|
|
54
113
|
universe static deploy
|
|
55
114
|
|
|
56
|
-
#
|
|
57
|
-
universe
|
|
115
|
+
# 3. Inspect identity + authorized sites
|
|
116
|
+
universe whoami
|
|
58
117
|
|
|
59
|
-
#
|
|
60
|
-
universe static
|
|
118
|
+
# 4. List recent deploys for the current site
|
|
119
|
+
universe static ls
|
|
61
120
|
|
|
62
|
-
# Promote preview to production
|
|
121
|
+
# 5. Promote current preview to production
|
|
63
122
|
universe static promote
|
|
64
123
|
|
|
65
|
-
#
|
|
66
|
-
universe static
|
|
67
|
-
|
|
68
|
-
# Rollback production to previous deploy
|
|
69
|
-
universe static rollback --confirm
|
|
124
|
+
# 6. Roll production back to a past deploy
|
|
125
|
+
universe static rollback --to 20260427-141522-abc1234
|
|
70
126
|
```
|
|
71
127
|
|
|
72
|
-
|
|
128
|
+
CI (GitHub Actions) — set `permissions: id-token: write` and rely on
|
|
129
|
+
slot 2 (GHA OIDC) of the identity chain, or pass `$GITHUB_TOKEN`
|
|
130
|
+
explicitly.
|
|
131
|
+
|
|
132
|
+
## Environment overrides
|
|
73
133
|
|
|
74
|
-
|
|
134
|
+
| Env | Default | Purpose |
|
|
135
|
+
| --------------------------- | -------------------------------- | --------------------------------------------------------- |
|
|
136
|
+
| `UNIVERSE_PROXY_URL` | `https://uploads.freecode.camp` | Override proxy host (staging etc.) |
|
|
137
|
+
| `UNIVERSE_GH_CLIENT_ID` | _baked-in freeCodeCamp OAuth id_ | Override GitHub OAuth App id (fork tenants, `login` only) |
|
|
138
|
+
| `GITHUB_TOKEN` / `GH_TOKEN` | — | Slot 1 of identity chain |
|
|
75
139
|
|
|
76
|
-
The
|
|
140
|
+
The shipped binary embeds the `freeCodeCamp` GitHub OAuth App client id
|
|
141
|
+
(public; device flow uses no `client_secret`), so `universe login` works
|
|
142
|
+
out of the box for staff. Fork operators and self-hosted mirror tenants
|
|
143
|
+
set `UNIVERSE_GH_CLIENT_ID` to their own OAuth App's id — env value
|
|
144
|
+
wins when set.
|
|
77
145
|
|
|
78
146
|
## Development
|
|
79
147
|
|
|
80
148
|
```sh
|
|
81
149
|
pnpm install
|
|
82
|
-
pnpm
|
|
83
|
-
pnpm
|
|
84
|
-
pnpm
|
|
150
|
+
pnpm test # vitest
|
|
151
|
+
pnpm typecheck # tsc --noEmit
|
|
152
|
+
pnpm lint # oxlint
|
|
153
|
+
pnpm build # tsup → dist/
|
|
85
154
|
```
|
|
86
155
|
|
|
87
156
|
## Releasing
|
|
88
157
|
|
|
89
|
-
See [RELEASING.md](docs/RELEASING.md).
|
|
158
|
+
See [docs/RELEASING.md](docs/RELEASING.md).
|