devlaunch 0.0.23__tar.gz → 0.0.25__tar.gz

{devlaunch-0.0.23 → devlaunch-0.0.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.23
+Version: 0.0.25
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -34,7 +34,7 @@ A streamlined CLI for [devpod](https://devpod.sh) with intuitive autocomplete an
 [![PyPI](https://img.shields.io/pypi/v/devlaunch)](https://pypi.org/project/devlaunch/)
 [![Conda](https://img.shields.io/badge/conda-v0.0.9-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
 [![License](https://img.shields.io/github/license/blooop/devlaunch)](https://opensource.org/license/mit/)
-[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
 [![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
 
 ## Installation
@@ -235,6 +235,7 @@ than the filesystem has actually done.
 
 | Command | Description |
 |---------|-------------|
+| `dl <user/repo> up` | Start (or create) the workspace without attaching — for prewarming a container before a session wants it |
 | `dl <user/repo> stop` | Stop the workspace |
 | `dl <user/repo> rm, prune` | Delete the workspace |
 | `dl <user/repo> code` | Open in VS Code |
@@ -340,6 +341,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 |---------|-------------|
 | `dl --ls` | List all workspaces |
 | `dl --ls --json` | The same list as JSON, with each workspace's repo, branch, state and [unsaved work](#cleaning-up-workspaces) — for tools that decide what to clean up |
+| `dl --ls --size` | Add [what deleting each workspace would free](#how-much-disk-a-workspace-costs). Opt-in: it walks every file in the clone |
 | `dl --install` | Install shell completions |
 | `dl --purge [-y]` | Remove all devlaunch data — [the workspaces devlaunch created](#what-purge-deletes), and its caches |
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
@@ -453,8 +455,9 @@ from an abandoned one. So `dl` supplies the two halves a tool that *does* know
 needs, and that tool drives the cleanup:
 
 ```bash
-dl --ls --json     # what exists, and what each workspace holds
-dl <workspace> rm  # remove one
+dl --ls --json          # what exists, and what each workspace holds
+dl --ls --json --size   # ...and what removing each one would free
+dl <workspace> rm       # remove one
 ```
 
 The JSON reports, per workspace: `id`, `devlaunch` (did `dl` create it),
@@ -469,24 +472,39 @@ cleanup tool must not ignore — `unsaved`:
   "repo": "blooop/devlaunch",
   "branch": "wayfinder/devlaunch-80",
   "state": "Stopped",
-  "unsaved": "2 uncommitted change(s) (pixi.lock, notes.md) and 1 unpushed commit(s)"
+  "unsaved": {
+    "wouldLose": "2 uncommitted change(s) (pixi.lock, notes.md) and 1 unpushed commit(s)"
+  }
 }
 ```
 
-`unsaved` is a description of what deleting would destroy, or `null` when the
-clone holds nothing that does not also exist on a remote — uncommitted changes
-(untracked files included) and commits no remote has. The changed paths are
-named, not just counted, and that matters more than it looks: a devcontainer
-that runs a package install in its `postCreateCommand` can leave a tracked
-lockfile modified in *every* workspace it builds — this repo's own does — and as
-a bare count that is indistinguishable from an hour of unsaved work. A cleanup
-tool believing the count would then never clean anything. Named, it is
-judgeable. A workspace `dl` did not
-create reports `devlaunch: false` with no repo, branch or `unsaved`: there is no
-clone of `dl`'s to protect, and it has no business inspecting your checkout.
-
-**`dl <workspace> rm` refuses when the clone holds unsaved work**, so a caller
-that forgets to read the field is still caught:
+`unsaved` is an object with exactly one key, and the key says which of three
+answers it is:
+
+| `unsaved` | Meaning |
+| --- | --- |
+| `{"nothingToLose": true}` | Everything in the clone exists on a remote too. Deleting it costs nothing. |
+| `{"wouldLose": "<what>"}` | Uncommitted changes (untracked files included), commits no remote has, or both. |
+| `{"couldNotTell": "<why>"}` | `git` could not read the clone as a repository — a half-removed `.git`, an interrupted delete. The files are still there and nothing has established that they exist anywhere else. |
+
+The changed paths are named, not just counted, and that matters more than it
+looks: a devcontainer that runs a package install in its `postCreateCommand` can
+leave a tracked lockfile modified in *every* workspace it builds — this repo's
+own does — and as a bare count that is indistinguishable from an hour of unsaved
+work. A cleanup tool believing the count would then never clean anything. Named,
+it is judgeable. A workspace `dl` did not create reports `devlaunch: false` and
+no `unsaved` — `unsaved` is `null` exactly where `devlaunch` is `false`, and
+nowhere else: there is no clone of `dl`'s to protect, and it has no business
+inspecting your checkout. (`repo` and `branch` are a weaker test and not the
+same set: they come from `dl`'s metadata record, and a clone `dl` owns can have
+lost its record while the clone and the work in it are still on disk. That clone
+is inspected and reported like any other.)
+
+**`dl <workspace> rm` refuses to delete a clone it would lose work from — when
+the recorded clone holds unsaved work, and when it cannot tell what that clone
+holds**, so a caller that forgets to read the field is still caught. (Recorded,
+because that is the directory the guard reads; the case with no record is
+neither, and is described below.)
 
 ```
 $ dl blooop/repo@feature rm
@@ -494,14 +512,108 @@ error: devlaunch-repo-feature-xyz holds 1 unpushed commit(s).
        Push or commit it, or run: dl blooop/repo@feature rm --force
 ```
 
+```
+$ dl blooop/repo@feature rm
+error: devlaunch-repo-feature-xyz: git could not read /home/…/repo/feature:
+       fatal: not a git repository. devlaunch will not delete a clone it cannot
+       check. Look at it, or run: dl blooop/repo@feature rm --force
+```
+
 That refusal is the only judgement `dl` makes here, and it is not about finished
-work — it is `dl` declining to destroy the only copy of something. Say `--force`
-if you mean it.
+work — it is `dl` declining to destroy the only copy of something, including
+when it cannot prove there is another copy. Say `--force` if you mean it.
+
+The guard reads `dl`'s metadata record, so the recorded directory is the one it
+asks about. (The delete does not always remove that same directory: when the
+recorded path is not on disk it falls back to a derived one. That divergence is
+older than this guard and is tracked as devlaunch#174.) One case is therefore
+neither a refusal nor a delete: a clone under `dl`'s cache that has **no** record — a metadata write
+that failed, a record pruned, a cache restored without one. The listing still
+reports what that clone holds, so `unsaved` is the field to read; but `rm`
+removes the devpod workspace, exits `0` without asking for `--force`, and leaves
+the clone on disk, because there is no recorded directory for it to remove
+either. Nothing is destroyed, and nothing then points at the clone: it is yours
+to keep or to `rm -rf` by hand.
 
 [`wf`](https://github.com/blooop/wayfinder) is the caller this was built for: it
 names its branches after its tickets, so it knows which workspaces belong to
 finished work and removes those.
 
+### How much disk a workspace costs
+
+`dl --ls --size` adds a `SIZE` column, and `dl --ls --json --size` adds a `disk`
+object beside the other per-workspace facts:
+
+```
+$ dl --ls --size
+WORKSPACE                      TYPE   SOURCE                                              SIZE  LAST USED
+kinisi-ros-main-lubadaha       local  /home/…/repos/kinisi-robotics/kinisi_ros/main    64.9 MiB  2026-08-08 11:43:27
+my-own-checkout                local  /home/…/projects/scratch                                -  2026-08-01 09:12:04
+```
+
+**The number is what deleting that workspace would give back, not what `du`
+prints.** Those differ, and the gap is the point of the design. A repo is cloned
+once into a bare cache and every workspace clone hardlinks its git objects out
+of that one copy, so the objects exist once on disk however many workspaces
+share them. A size that walked each workspace on its own — which is what `du`
+does when you point it at one directory, counting the blocks every file in it
+occupies — bills each workspace for the whole shared pool.
+
+The measurement the row above comes from, taken with the shipped code on one
+machine (Ubuntu 24.04, ext4, warm page cache) on a real clone of that repo made
+by `git clone` from the bare in `dl`'s own cache:
+
+| | bytes |
+| --- | --- |
+| `du -s --block-size=1` on the clone alone | 353,230,848 |
+| what `dl --ls --size` reports for it | 68,050,944 |
+| what `dl --ls --size` reports for the bare it clones from | 651,264 |
+| `du -sc --block-size=1` over both together | 353,882,112 |
+
+`du` bills that workspace **5.2x** what deleting it would actually free. The
+difference is a single 270,823,424-byte pack file with one link in the clone and
+one in the bare, so removing either end frees none of it.
+
+So `dl` counts a file only when every one of its hardlinks lies inside the
+workspace being measured. Two consequences, both deliberate:
+
+- **The sizes do not add up to the size of the cache.** Bytes shared between
+  workspaces belong to none of them, because deleting any one frees none of
+  them. They become the last workspace's the moment it is the last one — which
+  is exactly when deleting it *would* free them. In the table above that is the
+  last two rows read against each other: 68,702,208 reported bytes against
+  353,882,112 held.
+- **A workspace's size can change without the workspace changing**, when a
+  sibling that was sharing with it goes away. That is the truth about shared
+  storage.
+
+A workspace `dl` did not create reads `-` (`null` in JSON): there is no clone of
+`dl`'s there to measure, and walking your own project directory is not `dl`'s to
+do. The table and the JSON decide that from the same rule — is the clone one
+`dl` put in its own cache, the same question `--purge` deletes by — so the two
+always name the same set of workspaces as measurable. Where a walk hits a
+directory it cannot read — a container writes into its
+clone as its own user, so this happens — the answer is a floor rather than a
+total: `≥2.0 MiB` in the table, and `{"atLeastBytes": …, "unreadable": 1}` in
+JSON instead of `{"exclusiveBytes": …}`. A partial measurement never comes back
+looking like a complete one.
+
+**It is opt-in because it walks the whole clone.** Plain `dl --ls` is one devpod
+round-trip and no filesystem work at all, and the walk is O(files) with no
+ceiling. Measured with the shipped code on one machine — Ubuntu 24.04, ext4,
+warm page cache, five runs after a warm-up, the machine otherwise busy — a real
+8,309-entry clone walked in 24–28 ms, this repo's own tree with its built
+environment inside it (9,124 entries) in 17–21 ms, and a 114,817-entry tree in
+232–239 ms. No cold-cache figure is quoted because none was taken: dropping the
+page cache needs root on that machine. Those are one machine's numbers on warm
+cache and yours will differ, but the shape is the point — it grows with the file
+count, and a devcontainer that builds its environment *inside* the clone (this
+repo's own does) is most of that count. That is not a bill a listing should
+present unasked.
+
+Docker images and named volumes are not counted: `dl` did not create the layer
+store and does not manage volumes. `docker system df` is the tool that knows.
+
 ## Examples
 
 ```bash

{devlaunch-0.0.23 → devlaunch-0.0.25}/README.md

@@ -12,7 +12,7 @@ A streamlined CLI for [devpod](https://devpod.sh) with intuitive autocomplete an
 [![PyPI](https://img.shields.io/pypi/v/devlaunch)](https://pypi.org/project/devlaunch/)
 [![Conda](https://img.shields.io/badge/conda-v0.0.9-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
 [![License](https://img.shields.io/github/license/blooop/devlaunch)](https://opensource.org/license/mit/)
-[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
 [![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
 
 ## Installation
@@ -213,6 +213,7 @@ than the filesystem has actually done.
 
 | Command | Description |
 |---------|-------------|
+| `dl <user/repo> up` | Start (or create) the workspace without attaching — for prewarming a container before a session wants it |
 | `dl <user/repo> stop` | Stop the workspace |
 | `dl <user/repo> rm, prune` | Delete the workspace |
 | `dl <user/repo> code` | Open in VS Code |
@@ -318,6 +319,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 |---------|-------------|
 | `dl --ls` | List all workspaces |
 | `dl --ls --json` | The same list as JSON, with each workspace's repo, branch, state and [unsaved work](#cleaning-up-workspaces) — for tools that decide what to clean up |
+| `dl --ls --size` | Add [what deleting each workspace would free](#how-much-disk-a-workspace-costs). Opt-in: it walks every file in the clone |
 | `dl --install` | Install shell completions |
 | `dl --purge [-y]` | Remove all devlaunch data — [the workspaces devlaunch created](#what-purge-deletes), and its caches |
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
@@ -431,8 +433,9 @@ from an abandoned one. So `dl` supplies the two halves a tool that *does* know
 needs, and that tool drives the cleanup:
 
 ```bash
-dl --ls --json     # what exists, and what each workspace holds
-dl <workspace> rm  # remove one
+dl --ls --json          # what exists, and what each workspace holds
+dl --ls --json --size   # ...and what removing each one would free
+dl <workspace> rm       # remove one
 ```
 
 The JSON reports, per workspace: `id`, `devlaunch` (did `dl` create it),
@@ -447,24 +450,39 @@ cleanup tool must not ignore — `unsaved`:
   "repo": "blooop/devlaunch",
   "branch": "wayfinder/devlaunch-80",
   "state": "Stopped",
-  "unsaved": "2 uncommitted change(s) (pixi.lock, notes.md) and 1 unpushed commit(s)"
+  "unsaved": {
+    "wouldLose": "2 uncommitted change(s) (pixi.lock, notes.md) and 1 unpushed commit(s)"
+  }
 }
 ```
 
-`unsaved` is a description of what deleting would destroy, or `null` when the
-clone holds nothing that does not also exist on a remote — uncommitted changes
-(untracked files included) and commits no remote has. The changed paths are
-named, not just counted, and that matters more than it looks: a devcontainer
-that runs a package install in its `postCreateCommand` can leave a tracked
-lockfile modified in *every* workspace it builds — this repo's own does — and as
-a bare count that is indistinguishable from an hour of unsaved work. A cleanup
-tool believing the count would then never clean anything. Named, it is
-judgeable. A workspace `dl` did not
-create reports `devlaunch: false` with no repo, branch or `unsaved`: there is no
-clone of `dl`'s to protect, and it has no business inspecting your checkout.
-
-**`dl <workspace> rm` refuses when the clone holds unsaved work**, so a caller
-that forgets to read the field is still caught:
+`unsaved` is an object with exactly one key, and the key says which of three
+answers it is:
+
+| `unsaved` | Meaning |
+| --- | --- |
+| `{"nothingToLose": true}` | Everything in the clone exists on a remote too. Deleting it costs nothing. |
+| `{"wouldLose": "<what>"}` | Uncommitted changes (untracked files included), commits no remote has, or both. |
+| `{"couldNotTell": "<why>"}` | `git` could not read the clone as a repository — a half-removed `.git`, an interrupted delete. The files are still there and nothing has established that they exist anywhere else. |
+
+The changed paths are named, not just counted, and that matters more than it
+looks: a devcontainer that runs a package install in its `postCreateCommand` can
+leave a tracked lockfile modified in *every* workspace it builds — this repo's
+own does — and as a bare count that is indistinguishable from an hour of unsaved
+work. A cleanup tool believing the count would then never clean anything. Named,
+it is judgeable. A workspace `dl` did not create reports `devlaunch: false` and
+no `unsaved` — `unsaved` is `null` exactly where `devlaunch` is `false`, and
+nowhere else: there is no clone of `dl`'s to protect, and it has no business
+inspecting your checkout. (`repo` and `branch` are a weaker test and not the
+same set: they come from `dl`'s metadata record, and a clone `dl` owns can have
+lost its record while the clone and the work in it are still on disk. That clone
+is inspected and reported like any other.)
+
+**`dl <workspace> rm` refuses to delete a clone it would lose work from — when
+the recorded clone holds unsaved work, and when it cannot tell what that clone
+holds**, so a caller that forgets to read the field is still caught. (Recorded,
+because that is the directory the guard reads; the case with no record is
+neither, and is described below.)
 
 ```
 $ dl blooop/repo@feature rm
@@ -472,14 +490,108 @@ error: devlaunch-repo-feature-xyz holds 1 unpushed commit(s).
        Push or commit it, or run: dl blooop/repo@feature rm --force
 ```
 
+```
+$ dl blooop/repo@feature rm
+error: devlaunch-repo-feature-xyz: git could not read /home/…/repo/feature:
+       fatal: not a git repository. devlaunch will not delete a clone it cannot
+       check. Look at it, or run: dl blooop/repo@feature rm --force
+```
+
 That refusal is the only judgement `dl` makes here, and it is not about finished
-work — it is `dl` declining to destroy the only copy of something. Say `--force`
-if you mean it.
+work — it is `dl` declining to destroy the only copy of something, including
+when it cannot prove there is another copy. Say `--force` if you mean it.
+
+The guard reads `dl`'s metadata record, so the recorded directory is the one it
+asks about. (The delete does not always remove that same directory: when the
+recorded path is not on disk it falls back to a derived one. That divergence is
+older than this guard and is tracked as devlaunch#174.) One case is therefore
+neither a refusal nor a delete: a clone under `dl`'s cache that has **no** record — a metadata write
+that failed, a record pruned, a cache restored without one. The listing still
+reports what that clone holds, so `unsaved` is the field to read; but `rm`
+removes the devpod workspace, exits `0` without asking for `--force`, and leaves
+the clone on disk, because there is no recorded directory for it to remove
+either. Nothing is destroyed, and nothing then points at the clone: it is yours
+to keep or to `rm -rf` by hand.
 
 [`wf`](https://github.com/blooop/wayfinder) is the caller this was built for: it
 names its branches after its tickets, so it knows which workspaces belong to
 finished work and removes those.
 
+### How much disk a workspace costs
+
+`dl --ls --size` adds a `SIZE` column, and `dl --ls --json --size` adds a `disk`
+object beside the other per-workspace facts:
+
+```
+$ dl --ls --size
+WORKSPACE                      TYPE   SOURCE                                              SIZE  LAST USED
+kinisi-ros-main-lubadaha       local  /home/…/repos/kinisi-robotics/kinisi_ros/main    64.9 MiB  2026-08-08 11:43:27
+my-own-checkout                local  /home/…/projects/scratch                                -  2026-08-01 09:12:04
+```
+
+**The number is what deleting that workspace would give back, not what `du`
+prints.** Those differ, and the gap is the point of the design. A repo is cloned
+once into a bare cache and every workspace clone hardlinks its git objects out
+of that one copy, so the objects exist once on disk however many workspaces
+share them. A size that walked each workspace on its own — which is what `du`
+does when you point it at one directory, counting the blocks every file in it
+occupies — bills each workspace for the whole shared pool.
+
+The measurement the row above comes from, taken with the shipped code on one
+machine (Ubuntu 24.04, ext4, warm page cache) on a real clone of that repo made
+by `git clone` from the bare in `dl`'s own cache:
+
+| | bytes |
+| --- | --- |
+| `du -s --block-size=1` on the clone alone | 353,230,848 |
+| what `dl --ls --size` reports for it | 68,050,944 |
+| what `dl --ls --size` reports for the bare it clones from | 651,264 |
+| `du -sc --block-size=1` over both together | 353,882,112 |
+
+`du` bills that workspace **5.2x** what deleting it would actually free. The
+difference is a single 270,823,424-byte pack file with one link in the clone and
+one in the bare, so removing either end frees none of it.
+
+So `dl` counts a file only when every one of its hardlinks lies inside the
+workspace being measured. Two consequences, both deliberate:
+
+- **The sizes do not add up to the size of the cache.** Bytes shared between
+  workspaces belong to none of them, because deleting any one frees none of
+  them. They become the last workspace's the moment it is the last one — which
+  is exactly when deleting it *would* free them. In the table above that is the
+  last two rows read against each other: 68,702,208 reported bytes against
+  353,882,112 held.
+- **A workspace's size can change without the workspace changing**, when a
+  sibling that was sharing with it goes away. That is the truth about shared
+  storage.
+
+A workspace `dl` did not create reads `-` (`null` in JSON): there is no clone of
+`dl`'s there to measure, and walking your own project directory is not `dl`'s to
+do. The table and the JSON decide that from the same rule — is the clone one
+`dl` put in its own cache, the same question `--purge` deletes by — so the two
+always name the same set of workspaces as measurable. Where a walk hits a
+directory it cannot read — a container writes into its
+clone as its own user, so this happens — the answer is a floor rather than a
+total: `≥2.0 MiB` in the table, and `{"atLeastBytes": …, "unreadable": 1}` in
+JSON instead of `{"exclusiveBytes": …}`. A partial measurement never comes back
+looking like a complete one.
+
+**It is opt-in because it walks the whole clone.** Plain `dl --ls` is one devpod
+round-trip and no filesystem work at all, and the walk is O(files) with no
+ceiling. Measured with the shipped code on one machine — Ubuntu 24.04, ext4,
+warm page cache, five runs after a warm-up, the machine otherwise busy — a real
+8,309-entry clone walked in 24–28 ms, this repo's own tree with its built
+environment inside it (9,124 entries) in 17–21 ms, and a 114,817-entry tree in
+232–239 ms. No cold-cache figure is quoted because none was taken: dropping the
+page cache needs root on that machine. Those are one machine's numbers on warm
+cache and yours will differ, but the shape is the point — it grows with the file
+count, and a devcontainer that builds its environment *inside* the clone (this
+repo's own does) is most of that count. That is not a bill a listing should
+present unasked.
+
+Docker images and named volumes are not counted: `dl` did not create the layer
+store and does not manage volumes. `docker system df` is the tool that knows.
+
 ## Examples
 
 ```bash

{devlaunch-0.0.23 → devlaunch-0.0.25}/devlaunch/completions/dl.bash

@@ -61,7 +61,7 @@ _dl_completion() {
     fi
 
     # Workspace subcommands
-    local ws_cmds="stop rm code restart recreate reset --"
+    local ws_cmds="up stop rm code restart recreate reset --"
 
     # Options that take a value; a variant name or a path follows them.
     local value_opts="--devcontainer"