@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 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
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ import './dist/abrun.js'