devlaunch 0.0.20__tar.gz → 0.0.22__tar.gz

{devlaunch-0.0.20 → devlaunch-0.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.20
+Version: 0.0.22
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -339,6 +339,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 | Command | Description |
 |---------|-------------|
 | `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 --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) |
@@ -396,6 +397,69 @@ Erring this way is deliberate — a purge that skips one of your own workspaces
 costs you a command, and the other kind of mistake costs you work you cannot get
 back.
 
+### Cleaning up workspaces
+
+One workspace per branch means workspaces accumulate, and `--purge` is the wrong
+tool for tidying: it is all-or-nothing and takes the caches with it.
+
+**devlaunch does not decide which workspaces are finished.** Whether a piece of
+work is over is a fact about a ticket, a review, or somebody's intent, and `dl`
+knows about clones and containers. Inferring it from the branch — merged into
+the default, or deleted from the remote — was tried and dropped: it reads like a
+git fact but is a guess at intent, and it cannot tell a squash-merged branch
+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
+```
+
+The JSON reports, per workspace: `id`, `devlaunch` (did `dl` create it),
+`repo`, `branch` (what the workspace was made for), `checkedOut` (what its clone
+is on now, which can differ), `path`, `state`, `lastUsed`, and — the field a
+cleanup tool must not ignore — `unsaved`:
+
+```json
+{
+  "id": "devlaunch-wayfinder-devlaunch-80-ladepomi",
+  "devlaunch": true,
+  "repo": "blooop/devlaunch",
+  "branch": "wayfinder/devlaunch-80",
+  "state": "Stopped",
+  "unsaved": "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:
+
+```
+$ dl blooop/repo@feature rm
+error: devlaunch-repo-feature-xyz holds 1 unpushed commit(s).
+       Push or commit 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.
+
+[`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.
+
 ## Examples
 
 ```bash

{devlaunch-0.0.20 → devlaunch-0.0.22}/README.md

@@ -317,6 +317,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 | Command | Description |
 |---------|-------------|
 | `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 --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) |
@@ -374,6 +375,69 @@ Erring this way is deliberate — a purge that skips one of your own workspaces
 costs you a command, and the other kind of mistake costs you work you cannot get
 back.
 
+### Cleaning up workspaces
+
+One workspace per branch means workspaces accumulate, and `--purge` is the wrong
+tool for tidying: it is all-or-nothing and takes the caches with it.
+
+**devlaunch does not decide which workspaces are finished.** Whether a piece of
+work is over is a fact about a ticket, a review, or somebody's intent, and `dl`
+knows about clones and containers. Inferring it from the branch — merged into
+the default, or deleted from the remote — was tried and dropped: it reads like a
+git fact but is a guess at intent, and it cannot tell a squash-merged branch
+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
+```
+
+The JSON reports, per workspace: `id`, `devlaunch` (did `dl` create it),
+`repo`, `branch` (what the workspace was made for), `checkedOut` (what its clone
+is on now, which can differ), `path`, `state`, `lastUsed`, and — the field a
+cleanup tool must not ignore — `unsaved`:
+
+```json
+{
+  "id": "devlaunch-wayfinder-devlaunch-80-ladepomi",
+  "devlaunch": true,
+  "repo": "blooop/devlaunch",
+  "branch": "wayfinder/devlaunch-80",
+  "state": "Stopped",
+  "unsaved": "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:
+
+```
+$ dl blooop/repo@feature rm
+error: devlaunch-repo-feature-xyz holds 1 unpushed commit(s).
+       Push or commit 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.
+
+[`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.
+
 ## Examples
 
 ```bash

{devlaunch-0.0.20 → devlaunch-0.0.22}/devlaunch/dl.py

@@ -27,12 +27,13 @@ import re
 import shlex
 import time
 from importlib.metadata import version as pkg_version, PackageNotFoundError, distribution
+from pathlib import Path
 from typing import Any, Dict, List, Mapping, NoReturn, Optional, Sequence, Tuple
 from dataclasses import dataclass
 from urllib.parse import urlparse
 from urllib.request import url2pathname
 
-from . import devpod_ssh, gh_auth, tools, tty_session
+from . import devpod_ssh, gh_auth, tools, tty_session, workspace_state
 from .completion import install_completions
 from .workspace_id import TARGET_LENGTH, WorkspaceId, slug, source_workspace_id, validate_ref_name
 from .worktree.config import get_worktree_config
@@ -431,6 +432,76 @@ def update_cache_background(force: bool = False) -> None:
         pass
 
 
+def _unsaved_work_in(workspace_id: str) -> Optional[str]:
+    """What deleting *workspace_id* would destroy, or None if nothing would be.
+
+    Answers None for a workspace devlaunch has no record of, which is the honest
+    answer rather than a permissive one: those are workspaces opened from a path
+    or a URL that dl never cloned and does not manage, so it has no clone of its
+    own to protect and no business inspecting someone's checkout to find one.
+    """
+    try:
+        record = _get_clone_manager().storage.get_worktree_by_workspace_id(workspace_id)
+    except (OSError, RuntimeError) as e:
+        logging.debug(f"could not read the workspace record for {workspace_id}: {e}")
+        return None
+    if record is None:
+        return None
+    return workspace_state.holds_unsaved_work(Path(record.local_path))
+
+
+def workspaces_as_json() -> int:
+    """Print the workspace list as JSON: what exists, and what each one holds.
+
+    The machine-readable half of cleanup. devlaunch does not decide which
+    workspaces are finished -- that is a fact about tickets, reviews and intent,
+    none of which it knows -- so it reports what it does know and lets the
+    caller that knows the rest decide. `wf` is one such caller: it named the
+    branches after its tickets, so matching a workspace to a ticket is its
+    business, not dl's.
+
+    Every field is something dl can answer for certain:
+
+    - `repo` and `branch` come from the record dl wrote when it made the clone;
+      a workspace dl did not make has neither, and says so with `devlaunch:
+      false` rather than a guess.
+    - `unsaved` is the field a caller must not ignore: a description of what
+      deleting would destroy, or null. `dl <ws> rm` refuses on it too, so a
+      caller that forgets is still caught -- but a caller that reads it can
+      leave the workspace alone instead of arguing with a refusal.
+    - `state` is devpod's, one `devpod status` per workspace, which is why this
+      is a command someone runs rather than something on the fast path.
+    """
+    cache_dir = _get_cache_dir()
+    workspaces = list_workspaces()
+    clone_mgr = _get_clone_manager()
+    report: List[Dict[str, Any]] = []
+    for ws in workspaces:
+        mine = is_devlaunch_clone(ws, cache_dir)
+        record = clone_mgr.storage.get_worktree_by_workspace_id(ws.id) if mine else None
+        clone_path = Path(record.local_path) if record else None
+        state = workspace_state.read_clone(clone_path) if clone_path else None
+        report.append(
+            {
+                "id": ws.id,
+                "devlaunch": mine,
+                "repo": f"{record.owner}/{record.repo}" if record else None,
+                # The recorded branch is what the workspace was made for; the
+                # clone's current HEAD can differ (an agent checked something
+                # else out), so both are reported rather than one being made to
+                # stand for the other.
+                "branch": record.branch if record else None,
+                "checkedOut": state.branch if state else None,
+                "path": str(clone_path) if clone_path else None,
+                "state": get_workspace_state(ws.id),
+                "lastUsed": ws.last_used,
+                "unsaved": state.unsaved if state else None,
+            }
+        )
+    print(json.dumps(report, indent=2))
+    return 0
+
+
 def purge_all_data() -> int:
     """Purge devlaunch's data: the workspaces it created, and its caches.
 
@@ -1609,7 +1680,9 @@ Workspace sources:
 
 Workspace commands:
     dl <user/repo> stop              Stop the workspace
-    dl <user/repo> rm, prune         Delete the workspace
+    dl <user/repo> rm, prune         Delete the workspace. Refuses if its clone
+                                     holds uncommitted or unpushed work; add
+                                     --force to delete it anyway.
     dl <user/repo> code              Open in VS Code
     dl <user/repo> restart           Stop and start (no rebuild)
     dl <user/repo> recreate          Recreate container
@@ -1618,6 +1691,10 @@ Workspace commands:
 
 Global commands:
     dl --ls                          List all workspaces
+    dl --ls --json                   List them as JSON, with each one's repo,
+                                     branch, state, and what it holds that is
+                                     not pushed anywhere ("unsaved"). For tools
+                                     that decide which workspaces to clean up.
     dl --install                     Install shell completions
     dl --refresh                     Refresh completion cache
     dl --purge [-y]                  Remove devlaunch's workspaces and caches
@@ -1760,6 +1837,8 @@ def _run_cli(argv: Optional[List[str]] = None) -> int:
         return 0
 
     if args[0] == "--ls":
+        if "--json" in args[1:]:
+            return workspaces_as_json()
         print_workspaces()
         return 0
 
@@ -1946,6 +2025,20 @@ def _run_cli(argv: Optional[List[str]] = None) -> int:
         return workspace_stop(workspace_id)
 
     if subcommand in ("rm", "prune"):
+        # The one thing dl refuses on its own account. It is not a judgement
+        # about whether the work is finished -- dl has no way to know that --
+        # but about whether this clone is the only place the work exists.
+        # Cleanup is expected to be driven by something that knows more than dl
+        # does (a ticket tool, a script, a person), and this is what keeps a
+        # confident caller from destroying an hour of somebody's afternoon.
+        if "--force" not in args[2:]:
+            unsaved = _unsaved_work_in(workspace_id)
+            if unsaved:
+                logging.error(
+                    f"{workspace_id} holds {unsaved}. Push or commit it, or run: "
+                    f"dl {raw_spec} rm --force"
+                )
+                return 1
         return workspace_delete(workspace_id)
 
     if subcommand == "code":

devlaunch-0.0.22/devlaunch/workspace_state.py

@@ -0,0 +1,150 @@
+"""What a workspace holds — the facts a cleanup decision is made from elsewhere.
+
+A workspace per branch means workspaces accumulate, and something has to remove
+the finished ones. That something is **not devlaunch**: whether a piece of work
+is finished is a fact about a ticket, a review or a person's intent, and dl
+knows about none of those. It knows about clones and containers.
+
+So the split is mechanism here, policy in the caller:
+
+- ``dl --ls --json`` reports what exists and what each workspace holds, which is
+  what a caller needs to decide anything at all.
+- ``dl <ws> rm`` deletes one, and refuses when the clone holds work that exists
+  nowhere else.
+
+The refusal is the one judgement dl does make, and it is not a policy about
+finished work: it is dl declining to destroy the only copy of something. A
+caller that means it says ``--force``.
+
+The alternative — dl inferring "finished" from the branch (merged into the
+default, or deleted from the remote) — was built first and thrown away. It reads
+as a git fact but it is a guess at intent: a squash-merged branch and an
+abandoned one are indistinguishable, a branch merged upstream may still have
+work to do, and a repo whose flow does not delete branches gets nothing. The
+caller that knows the answer should say the answer.
+"""
+
+import logging
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class CloneState:
+    """What one workspace clone holds, as far as git can tell.
+
+    ``unsaved`` is the load-bearing field and is deliberately a description
+    rather than a flag: it is printed to a person who is deciding whether to
+    force a delete, and "3 uncommitted change(s) and 2 unpushed commit(s)" is
+    the thing that answers them. ``None`` means the clone holds nothing that
+    does not also exist on a remote.
+    """
+
+    branch: Optional[str]
+    unsaved: Optional[str]
+
+
+def _git(repo: Path, *args: str) -> Optional[str]:
+    """Run git in *repo*, returning stdout, or ``None`` if it refused.
+
+    A refusal is "cannot tell", never an answer: a clone that is broken, gone or
+    not a repository must not stop the other workspaces being reported, and must
+    never be reported as *safe to delete* on the strength of a failed command —
+    every caller here treats ``None`` as "no information", and the one place
+    that matters (:func:`holds_unsaved_work`) fails safe explicitly.
+
+    Only trailing newlines are trimmed, never leading whitespace. A full
+    ``strip()`` here was wrong in a way that took real use to notice: the first
+    line of ``git status --porcelain`` for a *modified tracked* file begins with
+    a space (`` M pixi.lock``), so stripping ate the status column and
+    :func:`_name_a_few` then reported ``ixi.lock``. Untracked entries start
+    ``??`` and were unharmed, which is exactly why the tests missed it.
+    """
+    try:
+        result = subprocess.run(
+            ["git", *args], cwd=repo, capture_output=True, text=True, check=False, timeout=30
+        )
+    except (OSError, subprocess.SubprocessError) as e:
+        logger.debug(f"git {' '.join(args)} in {repo}: {e}")
+        return None
+    if result.returncode != 0:
+        logger.debug(f"git {' '.join(args)} in {repo}: {result.stderr.strip()}")
+        return None
+    return result.stdout.rstrip("\n")
+
+
+def read_clone(clone: Path) -> CloneState:
+    """Report what *clone* holds. The only function here that talks to git.
+
+    A directory that is not there, or is not a repository, holds nothing: there
+    is no work in it to lose. That is the truth about it rather than a special
+    case, and it is what lets a caller clear away a workspace whose clone was
+    already removed by hand.
+    """
+    if not clone.is_dir():
+        return CloneState(branch=None, unsaved=None)
+    branch = _git(clone, "rev-parse", "--abbrev-ref", "HEAD")
+    return CloneState(branch=branch or None, unsaved=_unsaved(clone, branch))
+
+
+def _name_a_few(changed: List[str], limit: int = 3) -> str:
+    """Name the first few changed paths from `git status --porcelain` lines.
+
+    A count alone is not enough to decide anything with. A devcontainer that
+    runs `pixi install` in its `postCreateCommand` leaves the tracked lockfile
+    modified in *every* workspace it builds, so "1 uncommitted change(s)" is the
+    permanent state of an otherwise untouched clone — and a person told only the
+    count has no way to tell that from an hour of unsaved work. Told the name,
+    they can.
+
+    The porcelain format is two status characters, a space, then the path, so
+    the path starts at offset 3; a rename reads `old -> new`, and the whole
+    field is kept rather than split, because both halves are the news.
+    """
+    names = [line[3:].strip() for line in changed[:limit] if len(line) > 3]
+    if len(changed) > limit:
+        names.append("…")
+    return ", ".join(names)
+
+
+def _unsaved(clone: Path, branch: Optional[str]) -> Optional[str]:
+    """What deleting *clone* would destroy, in words, or ``None`` if nothing.
+
+    Two kinds of loss, reported together because someone deciding whether to
+    force a delete wants both:
+
+    - a dirty tree, **untracked files included** — an agent's scratch notes are
+      not less lost for never having been added — with the first few paths
+      named, because a count alone cannot be judged (see :func:`_name_a_few`);
+    - commits no remote-tracking ref contains. ``--not --remotes`` asks about
+      *any* remote ref rather than this branch's upstream, so work that was
+      pushed under another name, or merged and fetched back, is correctly not
+      counted as lost.
+    """
+    losses: List[str] = []
+    status = _git(clone, "status", "--porcelain")
+    if status:
+        changed = status.splitlines()
+        losses.append(f"{len(changed)} uncommitted change(s) ({_name_a_few(changed)})")
+    if branch:
+        # Argument order is load-bearing: `--not` flips the sense of every ref
+        # *after* it, so the branch has to be named before it. `log --not
+        # --remotes <branch>` excludes the branch as well and is silently always
+        # empty — which would report every clone as safe to delete.
+        unpushed = _git(clone, "log", "--oneline", branch, "--not", "--remotes")
+        if unpushed:
+            losses.append(f"{len(unpushed.splitlines())} unpushed commit(s)")
+    return " and ".join(losses) if losses else None
+
+
+def holds_unsaved_work(clone: Path) -> Optional[str]:
+    """What would be lost by deleting *clone*, or ``None`` if nothing would be.
+
+    The guard `dl <ws> rm` consults. Thin on purpose: the interesting behaviour
+    is in :func:`read_clone`, and this is the name the guard reads by.
+    """
+    return read_clone(clone).unsaved

{devlaunch-0.0.20 → devlaunch-0.0.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.20"
+version = "0.0.22"
 authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }]
 description = "DevLaunch - A streamlined CLI for devpod workspaces"
 readme = "README.md"