@koderlabs/tasks-cli 0.1.0 → 0.1.2

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