@abruncloud/cli 0.1.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 +261 -0
- package/abrun.js +2 -0
- package/dist/abrun.js +200 -0
- package/dist/index.js +26 -0
- package/package.json +53 -0
package/README.md
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# abrun cli
|
|
2
|
+
|
|
3
|
+
CLI for the abrun platform.
|
|
4
|
+
|
|
5
|
+
## Model
|
|
6
|
+
|
|
7
|
+
The CLI is flow-first.
|
|
8
|
+
|
|
9
|
+
There is no separate command action layer. A command is an ordered onion stack:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
input -> resolve auth -> resolve user -> resolve project -> resolve resource -> perform operation -> render output
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Examples:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
abrun login
|
|
19
|
+
=> [withState, login]
|
|
20
|
+
|
|
21
|
+
abrun app create <name>
|
|
22
|
+
=> [withState, withSelectedAuth, withProject, createApp, printCreatedApp]
|
|
23
|
+
|
|
24
|
+
abrun app domain add <app> <hostname>
|
|
25
|
+
=> [withState, withSelectedAuth, withProject, withApp, addDomain, printDomain]
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Resolver onions usually start with `with*`.
|
|
29
|
+
Terminal onions use verbs like `createApp`, `restartApp`, `verifyDomain`, or `printCreatedApp`.
|
|
30
|
+
The runtime API client is also an onion now, so flows explicitly add `withClient` where they need an authenticated or project-scoped client instance.
|
|
31
|
+
|
|
32
|
+
## SDK
|
|
33
|
+
|
|
34
|
+
The /api SDK is generated from `docs/openapi.yaml` into `apps/sdk/src/api-client`.
|
|
35
|
+
|
|
36
|
+
Regenerate it with:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
cd ../.. && bun run generate:sdk
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
CLI code should import the public SDK from `@abruncloud/sdk`:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { HttpClient, V1, type Project } from '@abruncloud/sdk'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The CLI runtime injects auth/project context through `src/lib/runtime.ts`.
|
|
49
|
+
|
|
50
|
+
## Current Commands
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
abrun login
|
|
54
|
+
abrun logout
|
|
55
|
+
abrun whoami
|
|
56
|
+
|
|
57
|
+
abrun auth list
|
|
58
|
+
abrun auth use <auth>
|
|
59
|
+
abrun auth remove <auth>
|
|
60
|
+
|
|
61
|
+
abrun project list
|
|
62
|
+
abrun project use <project>
|
|
63
|
+
abrun project current
|
|
64
|
+
|
|
65
|
+
abrun app list
|
|
66
|
+
abrun app inspect <app>
|
|
67
|
+
abrun app create <name>
|
|
68
|
+
abrun app update <app>
|
|
69
|
+
abrun app delete <app>
|
|
70
|
+
abrun app start <app>
|
|
71
|
+
abrun app stop <app>
|
|
72
|
+
abrun app restart <app>
|
|
73
|
+
abrun app status <app>
|
|
74
|
+
abrun app logs <app> [--follow]
|
|
75
|
+
abrun app shell <app>
|
|
76
|
+
abrun app deploy <app> [path]
|
|
77
|
+
abrun deploy <app> [path]
|
|
78
|
+
|
|
79
|
+
abrun app disk list <app>
|
|
80
|
+
abrun app disk inspect <app> <disk>
|
|
81
|
+
abrun app disk create <app> <name> --size <gb>
|
|
82
|
+
abrun app disk mount <app> <disk> <mountPath>
|
|
83
|
+
abrun app disk unmount <app> <disk>
|
|
84
|
+
abrun app disk expand <app> <disk> --size <gb>
|
|
85
|
+
abrun app disk delete <app> <disk>
|
|
86
|
+
|
|
87
|
+
abrun app env list <app>
|
|
88
|
+
abrun app env set <app> KEY=VALUE
|
|
89
|
+
abrun app env unset <app> KEY
|
|
90
|
+
|
|
91
|
+
abrun app domain list <app>
|
|
92
|
+
abrun app domain add <app> <hostname>
|
|
93
|
+
abrun app domain delete <app> <hostname>
|
|
94
|
+
abrun app domain verify <app> <hostname>
|
|
95
|
+
abrun app domain check <app> <hostname>
|
|
96
|
+
|
|
97
|
+
abrun app deployment list <app>
|
|
98
|
+
abrun app deployment inspect <app> <deployment>
|
|
99
|
+
abrun app deployment logs <app> <deployment>
|
|
100
|
+
abrun app deployment watch <app> <deployment>
|
|
101
|
+
abrun app deployment cancel <app> <deployment>
|
|
102
|
+
abrun app deployment redo <app> <deployment>
|
|
103
|
+
|
|
104
|
+
abrun db list
|
|
105
|
+
abrun db inspect <database>
|
|
106
|
+
abrun db create <name>
|
|
107
|
+
abrun db update <database>
|
|
108
|
+
abrun db delete <database>
|
|
109
|
+
abrun db start <database>
|
|
110
|
+
abrun db stop <database>
|
|
111
|
+
abrun db logs <database> [--follow]
|
|
112
|
+
abrun db tunnel <database> --port <port> [--host <host>]
|
|
113
|
+
abrun db credentials <database> --show-password
|
|
114
|
+
abrun db backup list <database>
|
|
115
|
+
abrun db backup create <database>
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Global flags:
|
|
119
|
+
|
|
120
|
+
```text
|
|
121
|
+
--endpoint <url>
|
|
122
|
+
--auth <auth>
|
|
123
|
+
--project <project>
|
|
124
|
+
--json
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Auth resolution order:
|
|
128
|
+
|
|
129
|
+
```text
|
|
130
|
+
explicit flags -> ABRUN_TOKEN -> saved local state
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`ABRUN_TOKEN` is a normal API token and always wins over saved local auth. It is sent as:
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
Authorization: Bearer <token>
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`abrun login` uses browser approval by default. The CLI calls `POST /api/auth/cli-login`, opens the returned browser URL, polls with the private `pollToken`, and stores only the returned API token after approval. Browser codes and poll tokens are not stored.
|
|
140
|
+
|
|
141
|
+
Email/password login is still available when `--email` or `--password` is provided, and uses `POST /api/auth/login`.
|
|
142
|
+
|
|
143
|
+
Project selection is local CLI state. `abrun project use <project>` accepts a project ID or immutable slug, resolves it through `GET /api/projects`, and stores the resolved `projectID`. Project-scoped collection requests send:
|
|
144
|
+
|
|
145
|
+
```text
|
|
146
|
+
X-Project-ID: <projectID>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`abrun app deploy` and `abrun deploy` are CLI-first deploy actions. Source deploys default to the current working directory, or use `[path]` when provided. Image deploys use the same `/deploy` endpoint with `--image`.
|
|
150
|
+
|
|
151
|
+
## Deploy Flow
|
|
152
|
+
|
|
153
|
+
`abrun app deploy <app> [path]` performs a local source sync before creating the deployment:
|
|
154
|
+
|
|
155
|
+
1. scans the selected source directory recursively
|
|
156
|
+
2. respects nested `.gitignore` and `.abrunignore` files
|
|
157
|
+
3. always excludes a hard denylist such as `.git`, `.abrun`, `node_modules`, common cache folders, and `.env*`
|
|
158
|
+
4. sends the current file manifest to `POST /api/apps/{appID}/deploy`
|
|
159
|
+
5. if the server returns `sync_required`, prints the requested file count
|
|
160
|
+
6. creates a tar archive with only the required changed files
|
|
161
|
+
7. uploads that archive through `POST /api/apps/{appID}/upload`
|
|
162
|
+
8. retries `POST /api/apps/{appID}/deploy` with the same file manifest
|
|
163
|
+
9. polls rollout status, prints build/deployment logs, then exits when the rollout reaches a terminal state
|
|
164
|
+
|
|
165
|
+
Deploy flags:
|
|
166
|
+
|
|
167
|
+
```text
|
|
168
|
+
--image <image> Deploy an image instead of source
|
|
169
|
+
--port <port> Update runtime port for this deploy
|
|
170
|
+
--message <text> Deployment message
|
|
171
|
+
--logs Follow app logs after a successful deploy
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Image deploys call `POST /api/apps/{appID}/deploy` directly and do not scan or upload local files.
|
|
175
|
+
|
|
176
|
+
## Runtime Streams
|
|
177
|
+
|
|
178
|
+
Runtime log commands use the new API:
|
|
179
|
+
|
|
180
|
+
```text
|
|
181
|
+
GET /api/apps/{appID}/logs
|
|
182
|
+
GET /api/databases/{databaseID}/logs
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`abrun db tunnel` keeps the process attached, listens on the requested local host and port, and opens one authorized websocket tunnel per local TCP client connection. It prints the database name, engine, and local address only; credentials are available through the explicit credentials command.
|
|
186
|
+
|
|
187
|
+
`--follow` adds `stream=true` and reads Server-Sent Events. `--tail`, `--since`, `--filter`, and `--previous` map to the API log query parameters.
|
|
188
|
+
|
|
189
|
+
`abrun app shell <app>` uses `GET /api/apps/{appID}/console` as a WebSocket console and sends normal bearer auth. The current API requires session authentication for console access, so raw `ABRUN_TOKEN` API tokens are rejected for shell sessions.
|
|
190
|
+
|
|
191
|
+
Operationally the platform now has only two deploy pipelines:
|
|
192
|
+
|
|
193
|
+
- `image`: release an existing image directly
|
|
194
|
+
- `source`: build from managed source, then release the produced image
|
|
195
|
+
|
|
196
|
+
CLI and Git deployments are both source-ingest paths into the same managed-source pipeline. The internal deployment `method` still records whether a source deployment came from `cli` or `git`, but builder and release behavior no longer diverge on that distinction.
|
|
197
|
+
|
|
198
|
+
### Source Metadata
|
|
199
|
+
|
|
200
|
+
For CLI deploys:
|
|
201
|
+
|
|
202
|
+
- commit author and default commit message are derived from the local git repository when available
|
|
203
|
+
- commit SHA, commit subject, author name, and author email are attached to source metadata when available
|
|
204
|
+
- `--message` overrides the git-derived deployment message without dropping commit/author metadata
|
|
205
|
+
|
|
206
|
+
### Cancel Behavior
|
|
207
|
+
|
|
208
|
+
- `Ctrl+C` before deployment creation aborts the local diff/upload flow
|
|
209
|
+
- `Ctrl+C` after deployment creation requests deployment cancellation
|
|
210
|
+
- uploaded source changes remain in the managed repo even if the later build/deploy is cancelled
|
|
211
|
+
|
|
212
|
+
## Local Context
|
|
213
|
+
|
|
214
|
+
Saved auth and project context are stored in:
|
|
215
|
+
|
|
216
|
+
```text
|
|
217
|
+
~/.abrun/config.yaml
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
The CLI keeps project selection locally and forwards the resolved project ID through the runtime client. Slugs are accepted only as selectors; API requests use `projectID`.
|
|
221
|
+
|
|
222
|
+
## Binary Plan
|
|
223
|
+
|
|
224
|
+
Recommended release shape:
|
|
225
|
+
|
|
226
|
+
```text
|
|
227
|
+
abrun-darwin-arm64
|
|
228
|
+
abrun-darwin-amd64
|
|
229
|
+
abrun-linux-amd64
|
|
230
|
+
abrun-linux-arm64
|
|
231
|
+
checksums.txt
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Recommended commands:
|
|
235
|
+
|
|
236
|
+
```text
|
|
237
|
+
abrun version
|
|
238
|
+
abrun upgrade --check
|
|
239
|
+
abrun upgrade
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Recommended self-upgrade flow:
|
|
243
|
+
|
|
244
|
+
1. detect current version and platform
|
|
245
|
+
2. fetch release manifest
|
|
246
|
+
3. compare versions
|
|
247
|
+
4. download the matching artifact to a temp file
|
|
248
|
+
5. verify checksum
|
|
249
|
+
6. atomically replace the current binary
|
|
250
|
+
7. keep one backup for rollback on failure
|
|
251
|
+
|
|
252
|
+
The CLI should never silently auto-upgrade. It should only suggest or perform upgrades when the user explicitly asks.
|
|
253
|
+
|
|
254
|
+
## Development
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
bun install
|
|
258
|
+
cd ../.. && bun run generate:sdk
|
|
259
|
+
bun run check
|
|
260
|
+
bun run build
|
|
261
|
+
```
|
package/abrun.js
ADDED