kdev-cli 0.1.3__py3-none-any.whl

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.
@@ -0,0 +1,598 @@
1
+ Metadata-Version: 2.5
2
+ Name: kdev-cli
3
+ Version: 0.1.3
4
+ Summary: A Kaggle notebook as your remote dev box: SSH and VS Code in, files that persist across sessions, accounts and machines.
5
+ Project-URL: Homepage, https://github.com/tushar-mahalya/kdev
6
+ Project-URL: Repository, https://github.com/tushar-mahalya/kdev
7
+ Project-URL: Issues, https://github.com/tushar-mahalya/kdev/issues
8
+ Project-URL: Changelog, https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: cloudflare-tunnel,gpu,kaggle,remote-development,ssh,vscode
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: MacOS
18
+ Classifier: Operating System :: POSIX :: Linux
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Software Development
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: httpx<1,>=0.27
26
+ Requires-Dist: kaggle<3,>=2.2
27
+ Requires-Dist: questionary<3,>=2.0
28
+ Requires-Dist: rich<16,>=13
29
+ Requires-Dist: typer<1,>=0.27
30
+ Description-Content-Type: text/markdown
31
+
32
+ <p align="center">
33
+ <img src="https://raw.githubusercontent.com/tushar-mahalya/kdev/main/docs/assets/kdev-logo.png" alt="kdev" width="520">
34
+ </p>
35
+
36
+ <p align="center">
37
+ <b>A Kaggle notebook as your remote dev box.</b><br>
38
+ Start it with one command, work in it from VS Code or a shell, and leave whenever you like.<br>
39
+ Your files are there next time — on any account in your Kaggle group, from any machine.
40
+ </p>
41
+
42
+ <p align="center">
43
+ <a href="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml/badge.svg"></a>
44
+ <a href="https://pypi.org/project/kdev-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kdev-cli?color=00b8d4"></a>
45
+ <img alt="Python 3.11 | 3.12 | 3.13" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-3776AB?logo=python&logoColor=white">
46
+ <a href="https://github.com/tushar-mahalya/kdev/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-2ea44f"></a>
47
+ <a href="#contributing"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-00b8d4"></a>
48
+ </p>
49
+
50
+ <p align="center">
51
+ <a href="#install-and-set-up">Install</a> ·
52
+ <a href="#everyday-use">Everyday use</a> ·
53
+ <a href="#your-files">Your files</a> ·
54
+ <a href="#commands">Commands</a> ·
55
+ <a href="#troubleshooting">Troubleshooting</a> ·
56
+ <a href="#contributing">Contributing</a>
57
+ </p>
58
+
59
+ <br>
60
+
61
+ ```bash
62
+ kdev setup # once per machine
63
+ kdev up # start the box (or connect to the one that is running)
64
+ ssh kaggle # or VS Code → Remote-SSH → kaggle
65
+ kdev down # optional: stop early and hand the quota back
66
+ ```
67
+
68
+ - **One box, pooled quota.** Every account in your group runs the same shared
69
+ notebook on its own 30 GPU-hours a week. When one runs short, `kdev up` asks
70
+ which account takes over.
71
+ - **Files that persist.** Whatever is in `/kaggle/working` when a session ends
72
+ comes back at the next start, however it ended: `kdev down`, the Kaggle UI,
73
+ a timeout, a crash, your wifi dropping.
74
+ - **A real server.** A stable hostname over Cloudflare Tunnel, public-key SSH,
75
+ your notebook's full environment (CUDA, Python, Kaggle variables) in every
76
+ session, interactive or not.
77
+
78
+ ---
79
+
80
+ ## Contents
81
+
82
+ - [How it works](#how-it-works)
83
+ - [Install and set up](#install-and-set-up)
84
+ - [Everyday use](#everyday-use)
85
+ - [Your files](#your-files)
86
+ - [Several accounts, several machines](#several-accounts-several-machines)
87
+ - [Commands](#commands)
88
+ - [Settings](#settings)
89
+ - [Troubleshooting](#troubleshooting)
90
+ - [Security and limits](#security-and-limits)
91
+ - [Contributing](#contributing)
92
+
93
+ ---
94
+
95
+ ## How it works
96
+
97
+ Kaggle's API can save a notebook and run it, but it has no "give me a shell"
98
+ call. kdev writes a small cell at the top of your notebook. When Kaggle runs
99
+ that cell, it turns the container into an SSH server and connects it to your
100
+ Cloudflare tunnel. Your laptop then reaches it by name.
101
+
102
+ ```mermaid
103
+ flowchart LR
104
+ subgraph laptop["Your machine"]
105
+ cli["kdev"]
106
+ code["VS Code / ssh"]
107
+ end
108
+ subgraph kaggle["Kaggle"]
109
+ api["Kaggle API"]
110
+ store[("Notebook versions<br/>= saved /kaggle/working")]
111
+ subgraph box["The box (a notebook session)"]
112
+ cell["kdev's cell:<br/>sshd · cloudflared · restore"]
113
+ work["/kaggle/working"]
114
+ end
115
+ end
116
+ edge(("Cloudflare<br/>edge"))
117
+
118
+ cli -- "save + run notebook,<br/>quota, logs" --> api
119
+ api --> box
120
+ cell -- "outbound tunnel" --> edge
121
+ code -- "ssh kaggle" --> edge
122
+ edge --> cell
123
+ work -. "saved when the<br/>session ends" .-> store
124
+ store -. "restored at<br/>the next start" .-> work
125
+ ```
126
+
127
+ Nothing listens on a public port: the box dials *out* to Cloudflare, and your
128
+ `ssh` reaches it through Cloudflare by hostname.
129
+
130
+ ### What `kdev up` does
131
+
132
+ ```mermaid
133
+ sequenceDiagram
134
+ autonumber
135
+ actor You
136
+ participant K as kdev
137
+ participant API as Kaggle API
138
+ participant B as The box
139
+ participant CF as Cloudflare
140
+
141
+ You->>K: kdev up
142
+ K->>API: session status (already running?)
143
+ alt a box is running
144
+ K-->>You: connect to it — no second session
145
+ else nothing running
146
+ K->>API: which saved version to build on (walk back from latest)
147
+ K->>API: SaveKernel: your notebook + kdev's cell, "Save & Run All"
148
+ API->>B: start the container
149
+ B->>B: record the plan in .kdev/state.json (before anything slow)
150
+ B->>B: sshd, environment, git clone
151
+ B->>CF: open the tunnel
152
+ B-->>K: KDEV_READY (via the session log)
153
+ K->>API: fresh file list + signed URLs for the saved version
154
+ K->>B: "restore this" (over ssh)
155
+ B->>API: download every file straight from Kaggle
156
+ B->>B: put back symlinks, empty dirs, exec bits
157
+ K->>B: ssh check
158
+ K-->>You: ready — open VS Code or a shell
159
+ end
160
+ ```
161
+
162
+ The board you watch while this happens shows each step's own clock, so a slow
163
+ queue looks like a queue and not a hang:
164
+
165
+ ```
166
+ alice · T4 ×2 · 9h 1m52s
167
+ ✓ Submitting 1s
168
+ ✓ Waiting for a machine 1m21s
169
+ ✓ Installing SSH server 14s
170
+ ✓ Exporting notebook environment 0s
171
+ ✓ Syncing workspace 0s
172
+ ✓ Starting Cloudflare tunnel 4s
173
+ ⠹ Restoring your files 9s
174
+ 812/1505 files
175
+ ○ Ready
176
+ ```
177
+
178
+ ---
179
+
180
+ ## Install and set up
181
+
182
+ Needs Python 3.11+, `ssh`, and a Kaggle account in a Kaggle group.
183
+
184
+ ```bash
185
+ uv tool install kdev-cli # or: pipx install kdev-cli
186
+ kdev setup
187
+ ```
188
+
189
+ The package is `kdev-cli` (PyPI does not allow `kdev`); the command it installs
190
+ is `kdev`. Upgrade with `uv tool upgrade kdev-cli`. For what is on `main` but not released
191
+ yet: `uv tool install git+https://github.com/tushar-mahalya/kdev`.
192
+
193
+ `kdev setup` does only what is missing, so it is safe to run again at any
194
+ time. It will:
195
+
196
+ 1. find (or create) your SSH key;
197
+ 2. fetch Cloudflare's `cloudflared` if you don't have it — a system install
198
+ (`brew install cloudflared`) always wins;
199
+ 3. sign a Kaggle account in, through your browser (OAuth);
200
+ 4. join your group's workspace notebook, or create one;
201
+ 5. set up the tunnel — **skipped on a second machine**, which takes the tunnel
202
+ from the notebook itself.
203
+
204
+ ### The tunnel
205
+
206
+ With a domain on Cloudflare (free plan, domain showing *Active*):
207
+
208
+ ```bash
209
+ kdev tunnel setup # opens a browser once to authorise your Cloudflare account
210
+ ```
211
+
212
+ It creates the tunnel and its DNS record, and stores the credentials. There's
213
+ nothing to configure in the Zero Trust dashboard. Re-running it is a no-op; it
214
+ never repoints a hostname that belongs to something else without asking.
215
+
216
+ | | Named tunnel (your domain) | Quick tunnel (no domain) |
217
+ |---|---|---|
218
+ | Setup | once, ~2 minutes | none |
219
+ | Hostname | the same forever | new every session |
220
+ | After a network drop | same name, `ssh` just reconnects | new name; `kdev up` finds it |
221
+ | Speed | identical | identical |
222
+
223
+ ### The workspace
224
+
225
+ A Kaggle group can't own anything, so one account owns the notebook and shares
226
+ it with the group as **Can Edit**:
227
+
228
+ ```bash
229
+ kdev workspace create --group <your-group-slug> # the owner, once
230
+ kdev workspace join # everyone else
231
+ ```
232
+
233
+ ---
234
+
235
+ ## Everyday use
236
+
237
+ ```bash
238
+ kdev # overview: the box, every account's quota, what to do next
239
+ kdev up # start the box, or connect to the one already running
240
+ kdev status # running? who started it? when does it end? files back?
241
+ kdev down # stop it now
242
+ ```
243
+
244
+ Bare `kdev` in a terminal ends with a menu of the actions that make sense
245
+ right now: connect or stop when the box is up; start it, or switch account,
246
+ when it isn't.
247
+
248
+ The box you start is a setting — pick once, and `kdev up` stops asking:
249
+
250
+ ```bash
251
+ kdev config set gpu t4
252
+ kdev config set hours 9
253
+ ```
254
+
255
+ **Leaving needs no ceremony.** Close the laptop, lose the wifi, walk away.
256
+ The box runs to the end of its session and saves as it stops. `kdev down` is
257
+ for stopping *early*, to hand the quota back.
258
+
259
+ ---
260
+
261
+ ## Your files
262
+
263
+ `/kaggle/working` behaves like a disk that is always there.
264
+
265
+ **Kaggle saves it.** When a "Save & Run All" session ends, Kaggle keeps
266
+ `/kaggle/working` as that version's output — and it does so however the
267
+ session ends. A clean exit, a crash and a cancel were all measured to save
268
+ every file up to the moment the container stopped. Older versions stay
269
+ readable (`v1`, `v2`, …), and they belong to the **notebook**, not to an account.
270
+
271
+ **kdev puts it back.** Kaggle starts every batch session with an empty
272
+ `/kaggle/working`; its "Persistence" setting only covers the web editor. So
273
+ each `kdev up` works out which saved version you left off at, and the new box
274
+ downloads it before you connect.
275
+
276
+ ```mermaid
277
+ stateDiagram-v2
278
+ direction LR
279
+ [*] --> Running: kdev up
280
+ Running --> Saved: the session ends, however it ends
281
+ Saved --> Running: kdev up, any account or machine
282
+ ```
283
+
284
+ | how the last session ended | what the next `kdev up` gives you |
285
+ |---|---|
286
+ | `kdev down` | everything |
287
+ | `kdev down`, then `kdev up` straight away | everything: `up` waits for the save first (about 2 min per GB) |
288
+ | **Stop session** in the Kaggle UI | everything (a cancel still saves) |
289
+ | the session's time ran out | everything (the box stops itself 2 min early) |
290
+ | the tunnel process died | everything |
291
+ | the box crashed | everything, up to the crash |
292
+ | your laptop or network dropped | the box is still running: `kdev up` connects to it |
293
+ | Kaggle's machine itself failed | not testable; a git remote covers it |
294
+
295
+ ### What kdev adds on top of Kaggle
296
+
297
+ Kaggle's saved output keeps every regular file — thousands of them, dotfiles,
298
+ `.git`, large binaries. It **drops symlinks and empty directories, and loses
299
+ executable bits**, which would break a Python virtualenv. The box records
300
+ those in `.kdev/meta.json` every 30 seconds, and the restore puts them back.
301
+
302
+ ### Picking the version to restore
303
+
304
+ ```mermaid
305
+ flowchart TD
306
+ start["latest saved version vN"] --> empty{"has files?"}
307
+ empty -- no --> back["try v(N-1)"] --> empty
308
+ empty -- yes --> state{"its .kdev/state.json says"}
309
+ state -- "restored: true<br/>(or kdev never touched it)" --> one["restore vN alone"]
310
+ state -- "restored: false, or files missing<br/>(cut short, or worked in<br/>before the restore)" --> stack["what vN never got from<br/>its base layers, then vN on top"]
311
+ ```
312
+
313
+ A version with no files is a source-only save (group setup, a Quick Save), so
314
+ kdev walks past it. A session that was stopped before its restore finished —
315
+ or that you worked in before restoring — is not skipped: it gets stacked on
316
+ the versions it was meant to be built on, so nothing done in it is lost. The
317
+ layers underneath fill in only what that session's restore never delivered
318
+ (the box logs each file as it lands, in `.kdev/fetched`), so a file you deleted
319
+ there stays deleted.
320
+
321
+ A restore never overwrites a file written in the current session, so it is
322
+ safe to run again at any time:
323
+
324
+ ```bash
325
+ kdev restore # finish or repeat the restore on the running box
326
+ kdev restore --from v12 # add files v12 has that the box doesn't (not a rollback)
327
+ kdev workspace files # what `kdev up` would restore (--version v12 for another)
328
+ kdev backup # optional: an exact copy of the box on this machine
329
+ ```
330
+
331
+ ### Your own cells in the notebook
332
+
333
+ kdev's cell sits on top, and **nothing below it runs**. When a session ends,
334
+ later cells are blanked for that run, so a training cell can't start after
335
+ `kdev down` and use quota. Your cells stay in the notebook, untouched.
336
+
337
+ ### Files made in the Kaggle web editor
338
+
339
+ The editor's interactive session is the one place kdev can't reach: its files
340
+ only reach the API when a version is saved. Kaggle describes Quick Save as
341
+ saving the notebook "as displayed", which isn't a clear promise to save the
342
+ working directory, so check with `kdev workspace files`. Everything made
343
+ through kdev is covered.
344
+
345
+ ---
346
+
347
+ ## Several accounts, several machines
348
+
349
+ ```mermaid
350
+ flowchart TB
351
+ subgraph group["Kaggle group (Can Edit on one notebook)"]
352
+ a["account A · 30h GPU/week"]
353
+ b["account B · 30h GPU/week"]
354
+ c["account C · 30h GPU/week"]
355
+ end
356
+ nb[("the shared notebook<br/>+ its saved versions")]
357
+ a & b & c -- "each runs it on<br/>its own quota" --> nb
358
+ l1["laptop 1"] & l2["laptop 2"] -- "kdev up / ssh" --> nb
359
+ ```
360
+
361
+ - **Quota is per account.** A session is charged to the account that starts
362
+ it, not to the notebook's owner (measured).
363
+ - **Switching is a question, not a wall.** If the active account can't finish
364
+ the session you asked for, `kdev up` shows every account's remaining hours
365
+ and lets you pick. `kdev account use <name>` switches by hand.
366
+ - **The box is still running?** `kdev up` from any account or machine
367
+ connects to it instead of starting a second one.
368
+ - **A new laptop.** `kdev setup` signs you in and joins the workspace. The
369
+ tunnel and git settings come from the notebook, and the new laptop's SSH
370
+ key is saved in the workspace (`.kdev/authorized_keys`). So every machine
371
+ that has used it can reach every later box.
372
+ - **Stopping a box someone else started.** Kaggle only lets the account that
373
+ started a session cancel it. When the box doesn't answer, `kdev down` finds
374
+ out which account that was and cancels as it — or tells you which account
375
+ has to.
376
+
377
+ ```bash
378
+ kdev account add alice # sign an account in (browser); re-run to refresh it
379
+ kdev account # every account and its GPU/TPU hours left
380
+ kdev account use alice # it runs the next box
381
+ ```
382
+
383
+ ---
384
+
385
+ ## Commands
386
+
387
+ | command | what it does |
388
+ |---|---|
389
+ | `kdev` | overview of the box, accounts and workspace; in a terminal, the next actions |
390
+ | `kdev setup` | get this machine ready; only does what is missing |
391
+ | `kdev up` | start the box, or connect to the running one |
392
+ | `kdev down` | stop the box; files are saved however it stops |
393
+ | `kdev ssh [-- ARGS]` | shell on the box; ssh's exit code is kdev's |
394
+ | `kdev status [--json]` | running?, started by, ends at, reachable, restore state |
395
+ | `kdev logs [-n N] [--all]` | the session log |
396
+ | `kdev restore [--from vN \| --from-backup]` | put saved files back |
397
+ | `kdev backup` | copy the running box to this machine |
398
+ | `kdev account [--json]` | accounts and quota |
399
+ | `kdev account add \| use \| remove` | manage accounts |
400
+ | `kdev workspace` | the notebook: owner, sharing, members, saved versions |
401
+ | `kdev workspace files [--version vN] [--json]` | what a saved version holds |
402
+ | `kdev workspace join \| use \| create \| share` | choose, make, or re-share the notebook |
403
+ | `kdev config` / `set KEY VALUE` / `unset KEY` | settings |
404
+ | `kdev tunnel` / `tunnel setup` | the Cloudflare tunnel |
405
+ | `kdev doctor [--fix]` | check everything; exits 1 if something is broken |
406
+
407
+ Useful flags on `kdev up`: `--gpu none|t4|p100|tpu`, `--hours N`,
408
+ `--account NAME`, `--open code|shell|none`, `--no-restore`, `--replace`, `-y`.
409
+
410
+ Global: `-v` logs every Kaggle API call with its status and timing;
411
+ `--version`; `--install-completion` for shell completion.
412
+
413
+ **Exit codes:** `0` success · `1` failed (the message says why and what to
414
+ run) · `2` usage mistake · `130` cancelled.
415
+
416
+ **Scripting:** every prompt has a flag, and a prompt never appears without a
417
+ terminal. `status`, `account` and `workspace files` take `--json` (data on
418
+ stdout, errors on stderr). `NO_COLOR` is honoured.
419
+
420
+ ---
421
+
422
+ ## Settings
423
+
424
+ `kdev config` lists them; secrets are never shown.
425
+
426
+ | setting | meaning |
427
+ |---|---|
428
+ | `gpu` | accelerator for `kdev up`: `none`, `t4`, `p100`, `tpu` (and `l4`, `a100`, `h100` where your account has them) |
429
+ | `hours` | session length for `kdev up` (Kaggle's limit: 12h, 9h on TPU) |
430
+ | `git-remote` | a repo cloned at boot, pushed every 15 minutes and at teardown |
431
+ | `git-deploy-key` | path to that repo's deploy key |
432
+ | `ssh-key` | path to this machine's public key |
433
+ | `ssh-alias` | the name in `~/.ssh/config` (default `kaggle`) |
434
+ | `tunnel-hostname` | the box's hostname |
435
+ | `tunnel-token` | a Cloudflare-dashboard tunnel token, instead of `kdev tunnel setup` |
436
+
437
+ Stored in `~/.config/kdev/config.json` (mode 0600). Move it with
438
+ `KDEV_CONFIG_DIR`.
439
+
440
+ ---
441
+
442
+ ## Troubleshooting
443
+
444
+ ```bash
445
+ kdev doctor # every dependency, account token, the workspace and the tunnel's DNS
446
+ kdev -v status # the same command, with each Kaggle API call logged
447
+ kdev logs # what the box itself is saying
448
+ ```
449
+
450
+ | you see | what to do |
451
+ |---|---|
452
+ | `… is not signed in` | `kdev account add <name>` refreshes that account |
453
+ | `ssh does not answer` right after starting | give Cloudflare a minute; `kdev ssh` |
454
+ | `The session never reported a tunnel` | `kdev logs`; the message names the command to stop it |
455
+ | `Only X can cancel session …` | sign X in (`kdev account add`) or stop it in the Kaggle UI |
456
+ | `Not all your files are back yet` | `kdev restore` finishes it |
457
+ | `your last box is still saving your files` | nothing: `kdev up` waits, then starts |
458
+ | `… has a session kdev cannot reach` | someone is using the notebook in the Kaggle editor |
459
+
460
+ ---
461
+
462
+ ## Security and limits
463
+
464
+ - **Access** is public-key SSH only; password login is disabled. The box
465
+ accepts every key saved in the workspace's `.kdev/authorized_keys`: remove a
466
+ line there to revoke a machine.
467
+ - **Secrets in the notebook.** Kaggle has no API for notebook Secrets, so the
468
+ tunnel credentials (and a git deploy key, if you set one) sit in the private
469
+ notebook's source. Anyone with Can Edit can read them. Scope a deploy key to
470
+ one repository.
471
+ - **Host keys.** Every session is a new container with a new host key, so the
472
+ `kaggle` block in `~/.ssh/config` doesn't pin one; a pinned key would break
473
+ VS Code on every other machine. Only a box holding the workspace's tunnel
474
+ credentials can answer on that hostname, and anyone holding those can
475
+ already edit the notebook that builds the box.
476
+ - **One box at a time.** kdev is built for one person on one machine at a
477
+ time; switching machines is fine. Two machines running `kdev up` at the same
478
+ moment start two boxes behind one hostname, and only the one that stops last
479
+ carries forward. Start from one machine, then connect from the other.
480
+ - **Metadata in the last 30 s.** After a hard kill, symlinks, empty folders and
481
+ executable bits created in the final 30 seconds are gone. File contents never
482
+ are.
483
+ - **Nothing sensitive in crash reports.** kdev never prints tracebacks with
484
+ local variables; `-v` shows a traceback when you ask for one.
485
+ - **Kaggle's limits:** 12h per CPU/GPU session and 9h on TPU; weekly GPU/TPU
486
+ quota per account; 20 GB of `/kaggle/working` saved per version.
487
+ - **Kaggle's terms.** Kaggle allows one account per person, and restricts
488
+ tunnelling out of notebooks; accounts have been banned for both. kdev does
489
+ nothing to hide what it does. Know the rules you are working under.
490
+
491
+ ---
492
+
493
+ ## Contributing
494
+
495
+ Contributions are welcome — bug reports, fixes, docs and features alike. kdev
496
+ is small and opinionated, so for anything bigger than a fix, open an issue
497
+ first and say what you want to change and why. It saves you writing code that
498
+ goes a different way than the project.
499
+
500
+ ### Ways to help
501
+
502
+ - **Report a bug.** Open an issue with what you ran, what you expected and
503
+ what happened. The output of the same command with `-v` (`kdev -v up …`)
504
+ helps most. It logs every Kaggle API call; check it for anything you would
505
+ rather not share before you paste it.
506
+ - **Fix something.** Pick an open issue and say in it that you are on it, so
507
+ two people don't fix the same thing.
508
+ - **Improve the docs.** If something here was unclear when you set up, it will
509
+ be unclear to the next person too.
510
+ - **Report a vulnerability** privately, as [SECURITY.md](https://github.com/tushar-mahalya/kdev/blob/main/SECURITY.md)
511
+ describes, never in a public issue.
512
+
513
+ ### Set up
514
+
515
+ You need Python 3.11+ and [uv](https://docs.astral.sh/uv/).
516
+
517
+ ```bash
518
+ git clone https://github.com/tushar-mahalya/kdev && cd kdev
519
+ uv sync
520
+ uv run pre-commit install # hooks on commit, tests on push
521
+ uv run pytest # 199 tests, no network needed
522
+ uv run kdev -v … # the working tree, with API logging
523
+ ```
524
+
525
+ Every commit runs formatting, lint, a secrets scan (`detect-secrets`,
526
+ private-key detection), config validation and a lockfile check; every push
527
+ runs the tests. CI runs the same hooks, the tests on Python 3.11–3.13, a
528
+ build-and-install check, and `gitleaks` over the full history.
529
+
530
+ ### Trying a change against real Kaggle
531
+
532
+ The test suite needs no Kaggle account, and most changes need nothing more.
533
+ When yours touches the box, the tunnel or the restore, try it for real:
534
+
535
+ - Use **your own** workspace (`kdev workspace create --group <slug>`), not a
536
+ shared one someone else works in.
537
+ - Start **CPU boxes**: `uv run kdev up --gpu none --hours 1`. They cost no GPU
538
+ quota. A GPU run spends the quota of whichever account starts it.
539
+ - `kdev down` when you are done, and `kdev workspace files` to see exactly
540
+ what was saved.
541
+
542
+ ### How the code is laid out
543
+
544
+ ```mermaid
545
+ flowchart LR
546
+ cli["cli.py<br/>entry point,<br/>one error boundary"]
547
+ cmds["commands/<br/>box · account · workspace<br/>config · tunnel · doctor · home"]
548
+ logic["session · persistence<br/>quota · notebook · bootstrap"]
549
+ edges["api · auth · config<br/>tunnel · cloudflared · sshcfg"]
550
+ ui["ui.py<br/>the design system"]
551
+ kbox["kdev_box.py<br/>runs on the box"]
552
+
553
+ cli --> cmds --> logic --> edges
554
+ cmds --> ui
555
+ logic -. "bootstrap ships it<br/>inside kdev's cell" .-> kbox
556
+ ```
557
+
558
+ | layer | rule |
559
+ |---|---|
560
+ | `commands/` | parse arguments, call logic, render with `ui`; no API calls of their own beyond reads |
561
+ | `session`, `persistence`, `quota`, `notebook` | the behaviour; testable without a terminal |
562
+ | `kdev_box.py` | standard library only; it's shipped into the container and runs there |
563
+ | `ui.py` | every visual element, with its tokens and rules written down at the top |
564
+ | `errors.KdevError` | every failure a user can act on: a message and the command that fixes it |
565
+
566
+ Tests are split by module. `tests/test_cli.py` runs every command through
567
+ the real entry point against a fake Kaggle. `tests/test_kdev_box.py` runs the
568
+ on-box restore against a temporary directory.
569
+
570
+ ### Pull requests
571
+
572
+ - **One change per pull request**, with a description of the problem it
573
+ solves and how you checked it.
574
+ - **A bug fix comes with a test** that fails without the fix. New behaviour
575
+ comes with the smallest test that would catch it breaking. Tests stay
576
+ offline: use the fake Kaggle in `tests/test_cli.py`.
577
+ - **Match the code around you.** `kdev_box.py` stays standard-library only.
578
+ Everything the user sees goes through `ui.py`. A failure the user can act on
579
+ is a `KdevError` with the command that fixes it.
580
+ - **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/)
581
+ (`fix:`, `feat:`, `docs:`, `test:`, `ci:`, `refactor:`), with the *why* in
582
+ the body.
583
+ - **Record what users will notice** under `## [Unreleased]` in
584
+ [CHANGELOG.md](https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md), and update this README if a command or its
585
+ behaviour changes.
586
+
587
+ ### Releasing
588
+
589
+ For maintainers: bump `version` in `pyproject.toml`, move the `Unreleased`
590
+ notes in `CHANGELOG.md` under the new version, then
591
+ `git tag vX.Y.Z && git push origin vX.Y.Z`. The release workflow checks that
592
+ the tag matches the version, runs the tests, and publishes a GitHub release
593
+ with the wheel and sdist attached.
594
+
595
+ ### License
596
+
597
+ kdev is [MIT licensed](https://github.com/tushar-mahalya/kdev/blob/main/LICENSE). By contributing, you agree that your
598
+ contributions are licensed under the same terms.
@@ -0,0 +1,33 @@
1
+ kdev/__init__.py,sha256=ecSXKn1GxiCoAcPrSh9UkwnV8a9Y3NZWnjNBmEKrJe0,290
2
+ kdev/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
3
+ kdev/api.py,sha256=yyxkmm-SrqejGp7QoKm_OFcWiWWa4Poh53ecqCGU7LA,13786
4
+ kdev/auth.py,sha256=w0SdxlvY9Gr50IknWUaaMq1Wng2PusqkukFzcG2lLUc,4078
5
+ kdev/bootstrap.py,sha256=VhyNjTAmNGoSbHo_QfuLZBDi-NCO0Jnqg1ezSXOF98g,19582
6
+ kdev/cli.py,sha256=d9cxq01SLEdfLmXqI24be-Sx-6R0ehfA9JZAwGSDvBU,5686
7
+ kdev/cloudflared.py,sha256=j36shLAeEnxhR1j_nyimNs_5ojxHswIwVdghX9esOm8,6649
8
+ kdev/config.py,sha256=Zuz3uEM8iXOcsM0lyD2RMfNmUf9zUOzsU9tMFnQ8XiU,6652
9
+ kdev/errors.py,sha256=PFnW-6xIqlf15XYFaRD4BeRG4tGLZEcUrY8NE1wpk8Q,778
10
+ kdev/kdev_box.py,sha256=DXfe8R_I2u6rJAA56KNa2d8LhyF4rB23Tgem39PjL78,19730
11
+ kdev/notebook.py,sha256=JSYiy_TX1wsyfeHyt6FXpT4unZXHCcB0F88h9XkbLFM,9658
12
+ kdev/persistence.py,sha256=ILhZgTXq2cf6_ojS5ivodYf6Fxqa4QHoyZJ0MEbOqlU,11383
13
+ kdev/quota.py,sha256=5PwTINkYIhH3Y2lxnJ6X9Ak-Zq5sM6R5ggCmNz4TcII,3781
14
+ kdev/safety.py,sha256=5B2hx4AzwLMVqdsGsy9g8U4o_lS3rPH-Pj23XbXHNys,2404
15
+ kdev/session.py,sha256=3_WEnd_cFil8eN7a0MwUgYScKOL2JqCQp0MWSHF3_b8,10301
16
+ kdev/sshcfg.py,sha256=bM8_rLqJlnb7dDq7xsk9PhuxFGnkLq1FN8X0ONK69Os,2532
17
+ kdev/tunnel.py,sha256=ncjqHmsfl1cxsOXjVspaNFYo1nyWXQBfNsX7d9qmg2o,9355
18
+ kdev/ui.py,sha256=y8reaS_U0jFzhS9BmAWwWbKWWTw1DuljymQ-QJ9-UxE,22246
19
+ kdev/wizard.py,sha256=7fq95teZVf6begCjXZMW0LL7I2eMAZMsYHFGAeNmtr8,9749
20
+ kdev/commands/__init__.py,sha256=-58qAN72GcwNmlWDHIZcU3HoGOcBAqCk-kop1MG_rbQ,214
21
+ kdev/commands/_common.py,sha256=uaFLH5u1z9dznLdHl5zwwgGQt5R_SteInJIFM2s54ww,1617
22
+ kdev/commands/account.py,sha256=beGutLPp_oAvHUtWKe0BoDvxigutU7EwiWPUJoj_W-Q,5019
23
+ kdev/commands/box.py,sha256=HRTE4ztnY73Zg11gHgRz1UaVwZL2Xs-peedmpluqHgI,28151
24
+ kdev/commands/doctor.py,sha256=J5SY6y5HEs4TTxhm_SC-oIo-en1wbdNaUMA-87fTMXI,4432
25
+ kdev/commands/home.py,sha256=R5R6zUIAkw9AFgonMtjHkopyNacWNCBEy0c3gT9ep9o,3060
26
+ kdev/commands/settings.py,sha256=TBtCE1H-y_fWZ-h3qU9iXFjfwOzTZxywP0C-J11r9LU,5213
27
+ kdev/commands/tunnel.py,sha256=MhRqS1yelwfKxfv4WTDb6ciW9izcmzchR8E5npgPnzM,2737
28
+ kdev/commands/workspace.py,sha256=2Si_oPgmGQXSvD0hLkIFqZgaUXTYDns0Oau0no8-ioc,7910
29
+ kdev_cli-0.1.3.dist-info/METADATA,sha256=PhszbY4Qnt3XNLegcxsl_QjneYE66gMALW6u-n1m_5A,25217
30
+ kdev_cli-0.1.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
31
+ kdev_cli-0.1.3.dist-info/entry_points.txt,sha256=5AJwKppkj9XR71Z0VBHy7n6JS8XRveXpr-EDd4e1On0,39
32
+ kdev_cli-0.1.3.dist-info/licenses/LICENSE,sha256=Tpqla7xv4dG8AaNC99OGTltC5F0WB4yr7CJbOkZ0IuQ,1073
33
+ kdev_cli-0.1.3.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.32.4
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ kdev = kdev.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The kdev authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.