@koderlabs/tasks-cli 0.1.0 → 0.1.1

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 (2) hide show
  1. package/README.md +188 -5
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,9 +1,192 @@
1
- # Proprietary Software
1
+ # @koderlabs/tasks-cli
2
2
 
3
- KoderLabs proprietary. All rights reserved.
3
+ InstantTasks operator CLI: validate your install, upload source maps and native
4
+ symbols, scaffold SDK init, and tail incoming events from any terminal.
4
5
 
5
- See the bundled `LICENSE` for terms. No grant of any rights, express or
6
- implied, is conferred by access to or possession of this package. A
7
- separate signed written licence from KoderLabs is required for any use.
6
+ Install + run on demand:
7
+
8
+ ```sh
9
+ npx @koderlabs/tasks-cli doctor
10
+ ```
11
+
12
+ Or pin globally:
13
+
14
+ ```sh
15
+ npm i -g @koderlabs/tasks-cli
16
+ tasks --help
17
+ ```
18
+
19
+ ## Configuration
20
+
21
+ Every command resolves config in this order (highest precedence first):
22
+
23
+ 1. CLI flag (e.g. `--api-url`, `--key`)
24
+ 2. Environment variable
25
+ 3. `.tasksrc.json` in the current directory or any ancestor
26
+ 4. Built-in defaults
27
+
28
+ | Env var | Purpose | Alias accepted |
29
+ |----------------------------|----------------------------------|---------------------------------|
30
+ | `INSTANTTASKS_ENDPOINT` | API base URL incl. `/api/v1` | `INSTANTTASKS_API_URL` |
31
+ | `INSTANTTASKS_INGEST_KEY` | `pk_` (read) or `sk_` (write) | `INSTANTTASKS_MANAGEMENT_KEY` |
32
+ | `INSTANTTASKS_PROJECT_ID` | Project UUID | |
33
+
34
+ A `.tasksrc.json` looks like:
35
+
36
+ ```json
37
+ {
38
+ "endpoint": "https://tasks.koderlabs.net/api/v1",
39
+ "ingestKey": "sk_live_xxx",
40
+ "projectId": "00000000-0000-0000-0000-000000000000"
41
+ }
42
+ ```
43
+
44
+ ## Commands
45
+
46
+ ### `tasks doctor`
47
+
48
+ Validates config + connectivity. Exits non-zero on any failure (CI-friendly).
49
+
50
+ ```sh
51
+ tasks doctor
52
+ ```
53
+
54
+ Checks:
55
+
56
+ - `.tasksrc.json` / env vars resolve
57
+ - `GET /sdk/v1/config` is reachable with the provided key
58
+ - Key role allows source-map uploads (`sk_` only — `pk_` keys are warned)
59
+ - `INSTANTTASKS_PROJECT_ID` is set
60
+
61
+ ### `tasks sourcemap upload <dist>`
62
+
63
+ Recursively walks `<dist>` for `*.map` files, defends against path
64
+ traversal/symlink escapes, then POSTs each map to `/sdk/source-maps` with
65
+ exponential backoff on transient 5xx.
66
+
67
+ ```sh
68
+ tasks sourcemap upload ./dist --release "$GIT_SHA" --environment production
69
+ ```
70
+
71
+ Flags:
72
+
73
+ | Flag | Default | Meaning |
74
+ |-------------------|------------------------|--------------------------------------------------------|
75
+ | `--release <sha>` | none | Associate maps with a release version |
76
+ | `--environment` | `production` | Environment label |
77
+ | `--max-size` | `52428800` (50 MB) | Per-file size cap; oversized files are skipped |
78
+ | `--no-strict` | strict on | Don't fail the run on individual file errors |
79
+
80
+ ### `tasks symbols upload-ios <dsym>`
81
+
82
+ Walks a `.dSYM` bundle's DWARF directory and posts each symbol file to
83
+ `/sdk/native-symbols`.
84
+
85
+ ```sh
86
+ tasks symbols upload-ios ./build/MyApp.dSYM --release "$BUILD_NUMBER"
87
+ ```
88
+
89
+ **Requires backend endpoint `/sdk/native-symbols`** — when the endpoint is
90
+ absent the CLI surfaces a warning and exits gracefully (does not fail the
91
+ build) so you can wire the CLI into CI before the backend ships.
92
+
93
+ ### `tasks symbols upload-android <mapping>`
94
+
95
+ Posts a single ProGuard `mapping.txt` to the same `/sdk/native-symbols`
96
+ endpoint.
97
+
98
+ ```sh
99
+ tasks symbols upload-android ./android/app/build/outputs/mapping/release/mapping.txt \
100
+ --release "$BUILD_NUMBER"
101
+ ```
102
+
103
+ Same backend caveat as `upload-ios`.
104
+
105
+ ### `tasks init <platform>`
106
+
107
+ Scaffolds a `.tasksrc.json` template plus an `init({...})` snippet appropriate
108
+ to the platform. Refuses to overwrite existing files unless `--force`.
109
+
110
+ ```sh
111
+ tasks init web # vanilla browser
112
+ tasks init react # CSR React app
113
+ tasks init nextjs # writes instrumentation.ts
114
+ tasks init vue
115
+ tasks init rn # React Native + Expo
116
+ tasks init nestjs # backend Node
117
+ ```
118
+
119
+ Flags:
120
+
121
+ - `--dry-run` — print the files that would be written but write nothing
122
+ - `--force` — overwrite existing files
123
+
124
+ ### `tasks events tail`
125
+
126
+ Tails recent SDK events one-per-line. Currently long-polls
127
+ `/sdk/v1/events?since=<ms>` every 5s; intended to be swapped for a WebSocket
128
+ stream once the backend ships one. Ctrl-C exits cleanly.
129
+
130
+ ```sh
131
+ tasks events tail --filter project=$INSTANTTASKS_PROJECT_ID --since 10m
132
+ ```
133
+
134
+ Flags:
135
+
136
+ - `--filter k=v ...` — repeatable filter pairs
137
+ - `--since <duration>` — lookback window (e.g. `30s`, `10m`, `1h`, `2d`)
138
+ - `--interval <ms>` — poll interval (default `5000`)
139
+
140
+ **Requires backend endpoint `/sdk/v1/events`** — when missing the CLI prints a
141
+ clear warning and exits.
142
+
143
+ ## Example workflows
144
+
145
+ ### Verify your install
146
+
147
+ ```sh
148
+ export INSTANTTASKS_ENDPOINT=https://tasks.koderlabs.net/api/v1
149
+ export INSTANTTASKS_INGEST_KEY=sk_live_xxx
150
+ export INSTANTTASKS_PROJECT_ID=00000000-0000-0000-0000-000000000000
151
+ tasks doctor
152
+ ```
153
+
154
+ ### Upload source maps from CI
155
+
156
+ ```sh
157
+ # .github/workflows/deploy.yml
158
+ - name: Upload source maps
159
+ env:
160
+ INSTANTTASKS_ENDPOINT: ${{ secrets.INSTANTTASKS_ENDPOINT }}
161
+ INSTANTTASKS_INGEST_KEY: ${{ secrets.INSTANTTASKS_SOURCEMAPS_KEY }}
162
+ run: npx @koderlabs/tasks-cli sourcemap upload ./dist --release "${{ github.sha }}"
163
+ ```
164
+
165
+ ### Tail events during dev
166
+
167
+ ```sh
168
+ tasks events tail --since 30m --filter project=$INSTANTTASKS_PROJECT_ID
169
+ ```
170
+
171
+ ## Legacy commands
172
+
173
+ `upload-sourcemaps` and `create-release` (the original scaffold commands) are
174
+ still wired and behave exactly as before. Prefer `tasks sourcemap upload …`
175
+ for new work.
176
+
177
+ ## Runtime
178
+
179
+ - Node 22+ (uses native `fetch`)
180
+ - Zero native modules
181
+
182
+ ---
183
+
184
+ ## Suite overview
185
+
186
+ Full SDK suite map + platform availability matrix: [docs/sdk/overview.md](https://github.com/jawaidgadiwala/instant-tasks/blob/main/docs/sdk/overview.md).
187
+
188
+ ## License
189
+
190
+ KoderLabs proprietary. See [`LICENSE`](./LICENSE) for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.
8
191
 
9
192
  Licensing inquiries: jawaidgadiwala@gmail.com
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@koderlabs/tasks-cli",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "InstantTasks CLI — source-map uploads and release management for CI",
5
5
  "keywords": [
6
6
  "instanttasks",
@@ -49,7 +49,7 @@
49
49
  "node": ">=20"
50
50
  },
51
51
  "publishConfig": {
52
- "access": "restricted"
52
+ "access": "public"
53
53
  },
54
54
  "scripts": {
55
55
  "build": "tsup",