nbdevAuto 0.3.66__tar.gz → 0.3.68__tar.gz

{nbdevauto-0.3.66/nbdevAuto.egg-info → nbdevauto-0.3.68}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdevAuto
-Version: 0.3.66
+Version: 0.3.68
 Summary: automating nbdev
 Author-email: Benedict Thekkel <bthekkel1@gmail.com>
 License-Expression: Apache-2.0
@@ -73,23 +73,25 @@ from nbdevAuto.pdf import PDFreader
 | [Automate](01_Automate.ipynb) | The command line surface: the prep/commit/push pipeline, the GitHub and PyPI release halves, and the help output that lists them all |
 | [PDF Reader](02_PDF_reader.ipynb) | [`PDFreader`](https://bthek1.github.io/nbdevAuto/pdf_reader.html#pdfreader), a class that converts a PDF through `pdf2image` and renders page ranges inline when you slice it (`pdf[0:5]`) |
 | [GitHub](03_GitHub.ipynb) | [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus): reading `.gitmodules`, resolving a token, and asking the GitHub API about every submodule at once - CI runs, Pages deploys, Pages builds, remote `main` shas - plus the `--report` and `--audit` views and the exit codes that keep “absent” apart from “cannot ask” |
+| [Fleet](04_Fleet.ipynb) | [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet): running one command across every submodule of a superproject. A walker that reports only what did work and counts the rest, plus the verbs built on it - upload, push, copy, status, update and sync |
 
 ------------------------------------------------------------------------
 
 ## The Command Line Surface
 
-Installing the package puts these on your `PATH`. Most are ordinary functions in [Automate](01_Automate.ipynb), exposed as scripts through `[project.scripts]`; [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) comes from [GitHub](03_GitHub.ipynb).
+Installing the package puts these on your `PATH`. Most are ordinary functions in [Automate](01_Automate.ipynb), exposed as scripts through `[project.scripts]`; [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) comes from [GitHub](03_GitHub.ipynb) and [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet) from [Fleet](04_Fleet.ipynb).
 
 | Command | Does |
 |----|----|
 | [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) | Bump the version, then export, test and clean the notebooks, refreshing `_quarto.yml` and the README |
-| [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp) | git add, commit, and push. Without `-m` the commit message is the status output |
+| [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp) | git add, commit, and push. Without `-m` the message is built from the staged paths |
 | [`status`](https://bthek1.github.io/nbdevAuto/automate.html#status) | Show the working tree state |
 | [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) | [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) then [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp), the one you actually type |
 | `gitrelease` | Bump the **minor** version, then tag and create a GitHub release |
 | `piprelease` | Build the sdist and wheel, then upload to PyPI with twine |
 | [`release`](https://bthek1.github.io/nbdevAuto/automate.html#release) | `gitrelease` then `piprelease` |
 | [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) | Remote status for every submodule of an nbdev superproject, from the GitHub API. `--report` for the sync view, `--audit` to check `.gitmodules` against the repos the account owns, `--json` for machine output |
+| [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet) | Run one command across every submodule: `fleet upload|push|copy|status|update|sync`. Every verb takes `--help`, and the destructive ones take `--dry-run` |
 | `h` | Print the list of available commands |
 
 Both [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) and [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) take `-p` to choose which version part to increment; it defaults to 2, the patch, so every [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) ships a new version.

{nbdevauto-0.3.66 → nbdevauto-0.3.68}/README.md

@@ -43,23 +43,25 @@ from nbdevAuto.pdf import PDFreader
 | [Automate](01_Automate.ipynb) | The command line surface: the prep/commit/push pipeline, the GitHub and PyPI release halves, and the help output that lists them all |
 | [PDF Reader](02_PDF_reader.ipynb) | [`PDFreader`](https://bthek1.github.io/nbdevAuto/pdf_reader.html#pdfreader), a class that converts a PDF through `pdf2image` and renders page ranges inline when you slice it (`pdf[0:5]`) |
 | [GitHub](03_GitHub.ipynb) | [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus): reading `.gitmodules`, resolving a token, and asking the GitHub API about every submodule at once - CI runs, Pages deploys, Pages builds, remote `main` shas - plus the `--report` and `--audit` views and the exit codes that keep “absent” apart from “cannot ask” |
+| [Fleet](04_Fleet.ipynb) | [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet): running one command across every submodule of a superproject. A walker that reports only what did work and counts the rest, plus the verbs built on it - upload, push, copy, status, update and sync |
 
 ------------------------------------------------------------------------
 
 ## The Command Line Surface
 
-Installing the package puts these on your `PATH`. Most are ordinary functions in [Automate](01_Automate.ipynb), exposed as scripts through `[project.scripts]`; [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) comes from [GitHub](03_GitHub.ipynb).
+Installing the package puts these on your `PATH`. Most are ordinary functions in [Automate](01_Automate.ipynb), exposed as scripts through `[project.scripts]`; [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) comes from [GitHub](03_GitHub.ipynb) and [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet) from [Fleet](04_Fleet.ipynb).
 
 | Command | Does |
 |----|----|
 | [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) | Bump the version, then export, test and clean the notebooks, refreshing `_quarto.yml` and the README |
-| [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp) | git add, commit, and push. Without `-m` the commit message is the status output |
+| [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp) | git add, commit, and push. Without `-m` the message is built from the staged paths |
 | [`status`](https://bthek1.github.io/nbdevAuto/automate.html#status) | Show the working tree state |
 | [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) | [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) then [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp), the one you actually type |
 | `gitrelease` | Bump the **minor** version, then tag and create a GitHub release |
 | `piprelease` | Build the sdist and wheel, then upload to PyPI with twine |
 | [`release`](https://bthek1.github.io/nbdevAuto/automate.html#release) | `gitrelease` then `piprelease` |
 | [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) | Remote status for every submodule of an nbdev superproject, from the GitHub API. `--report` for the sync view, `--audit` to check `.gitmodules` against the repos the account owns, `--json` for machine output |
+| [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet) | Run one command across every submodule: `fleet upload|push|copy|status|update|sync`. Every verb takes `--help`, and the destructive ones take `--dry-run` |
 | `h` | Print the list of available commands |
 
 Both [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) and [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) take `-p` to choose which version part to increment; it defaults to 2, the patch, so every [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) ships a new version.

nbdevauto-0.3.68/nbdevAuto/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.68"

{nbdevauto-0.3.66 → nbdevauto-0.3.68}/nbdevAuto/_modidx.py

@@ -36,16 +36,34 @@ d = { 'settings': { 'branch': 'main',
                                  'nbdevAuto.fleet.Report.failed': ('fleet.html#report.failed', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.Report.ran': ('fleet.html#report.ran', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.Report.skip_counts': ('fleet.html#report.skip_counts', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.Skip': ('fleet.html#skip', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet._classify': ('fleet.html#_classify', 'nbdevAuto/fleet.py'),
-                                 'nbdevAuto.fleet._fail_reason': ('fleet.html#_fail_reason', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet._count': ('fleet.html#_count', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet._fail_parts': ('fleet.html#_fail_parts', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet._git_ok': ('fleet.html#_git_ok', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet._porcelain': ('fleet.html#_porcelain', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet._render': ('fleet.html#_render', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.ahead_of_remote': ('fleet.html#ahead_of_remote', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.copy_one': ('fleet.html#copy_one', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.dirty_submodules': ('fleet.html#dirty_submodules', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.fetch_all': ('fleet.html#fetch_all', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.finish': ('fleet.html#finish', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.fleet': ('fleet.html#fleet', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.fleet_copy': ('fleet.html#fleet_copy', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.fleet_push': ('fleet.html#fleet_push', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.fleet_status': ('fleet.html#fleet_status', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.fleet_sync': ('fleet.html#fleet_sync', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.fleet_update': ('fleet.html#fleet_update', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.fleet_upload': ('fleet.html#fleet_upload', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.format_summary': ('fleet.html#format_summary', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.init_new': ('fleet.html#init_new', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.parse_verb': ('fleet.html#parse_verb', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.pull_root': ('fleet.html#pull_root', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.push_one': ('fleet.html#push_one', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.run_verb': ('fleet.html#run_verb', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.script_path': ('fleet.html#script_path', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.status_one': ('fleet.html#status_one', 'nbdevAuto/fleet.py'),
+                                 'nbdevAuto.fleet.update_one': ('fleet.html#update_one', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.upload_one': ('fleet.html#upload_one', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.usage': ('fleet.html#usage', 'nbdevAuto/fleet.py'),
                                  'nbdevAuto.fleet.walk': ('fleet.html#walk', 'nbdevAuto/fleet.py')},

nbdevauto-0.3.68/nbdevAuto/fleet.py

@@ -0,0 +1,442 @@
+"""Run one command across every submodule of a superproject
+
+Docs: https://bthek1.github.io/nbdevAuto/fleet.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/04_Fleet.ipynb.
+
+# %% auto #0
+__all__ = ['VERBS', 'Skip', 'Outcome', 'Report', 'format_summary', 'walk', 'finish', 'script_path', 'upload_one', 'fleet_upload',
+           'ahead_of_remote', 'push_one', 'copy_one', 'fleet_push', 'fleet_copy', 'status_one', 'fleet_status',
+           'fetch_all', 'update_one', 'dirty_submodules', 'init_new', 'pull_root', 'fleet_update', 'fleet_sync',
+           'parse_verb', 'usage', 'run_verb', 'fleet']
+
+# %% ../nbs/04_Fleet.ipynb #d361ee5f-9f09-464f-aec6-0e27cec90fe9
+import re
+import shutil
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from fastcore.script import *
+
+# The rendering layer lives in `automate`, the git/discovery layer in `github`. This
+# module is the only one that knows about MANY repos; those two stay single-repo.
+from .automate import StepFailed, _push_summary, _run, _step, console, escape
+from .github import find_root, git, local_state, parse_gitmodules
+
+# %% ../nbs/04_Fleet.ipynb #4e6b24c5-cd71-434c-84e6-e6994d5959c7
+class Skip(Exception):
+    "Raised by a walked callable that has decided this submodule has nothing to do"
+
+@dataclass
+class Outcome:
+    "What happened in one submodule"
+    path:   str
+    state:  str                                  # ran | skipped | failed
+    reason: str  = ""                            # why it was skipped, or how it failed
+    detail: list = field(default_factory=list)   # short lines to show under the path
+
+@dataclass
+class Report:
+    "Everything a `walk` did, and the exit code it implies"
+    outcomes: list = field(default_factory=list)
+
+    @property
+    def ran(self):    return [o for o in self.outcomes if o.state == "ran"]
+    @property
+    def failed(self): return [o for o in self.outcomes if o.state == "failed"]
+    @property
+    def code(self):   return 1 if self.failed else 0
+
+    def skip_counts(self):
+        "Skip reason -> count, in the order the reasons were first seen"
+        counts = {}
+        for o in self.outcomes:
+            if o.state == "skipped": counts[o.reason] = counts.get(o.reason, 0) + 1
+        return counts
+
+def format_summary(rep, verb="ran"):
+    "The one line that replaces a message per submodule. Quiet submodules are counted, not narrated"
+    n = len(rep.outcomes)
+    parts = [f"{len(rep.ran)} {verb}"]
+    parts += [f"{c} {reason}" for reason, c in rep.skip_counts().items()]
+    if rep.failed: parts.append(f"{len(rep.failed)} FAILED")
+    return f"{n} submodule{'' if n == 1 else 's'}: " + ", ".join(parts)
+
+# %% ../nbs/04_Fleet.ipynb #099242e8-c9ad-4b48-8ebc-7a818e5f8f81
+def _classify(base, sub, need_nbs, only_dirty):
+    "The reason to skip this submodule before running anything, or None to run it"
+    p = base/sub.path
+    # An uninitialised submodule is an empty directory: present, but with no .git
+    if not (p/".git").exists():             return "not initialised"
+    if need_nbs and not (p/"nbs").is_dir(): return "without nbs"
+    if only_dirty and not git(p, "status", "--porcelain"): return "clean"
+    return None
+
+def _fail_parts(e):
+    """(headline, remaining lines) for a callable that did not finish.
+
+    A `StepFailed` carries the command's own output, and its first line is the message
+    worth putting on the summary line - "uncommitted changes" says far more than
+    "update exited 1". The rest is kept for the block renderer."""
+    if isinstance(e, StepFailed):
+        out = (e.output or "").strip().splitlines()
+        if out: return out[0], out[1:]
+        return f"{e.cmd} exited {e.code}", []
+    return f"{type(e).__name__}: {e}", []
+
+def _render(o, style="block", width=0, header=True):
+    "One submodule's result. A skip prints nothing at all; it is counted instead"
+    if o.state == "skipped": return
+    if style == "line":
+        pad = f"{o.path:<{width}}"
+        if o.state == "failed":
+            console.print(f"[bold red]{escape(pad)}[/bold red] [red]{escape(o.reason)}[/red]")
+            return
+        console.print(f"[cyan]{escape(pad)}[/cyan] [dim]{escape(o.detail[0] if o.detail else '')}[/dim]")
+        for line in o.detail[1:]: console.print(f"{' ' * width} [dim]{escape(line)}[/dim]")
+        return
+    if header: console.print(f"\n[bold cyan]==> {escape(o.path)}[/bold cyan]")
+    if o.state == "failed":
+        console.print(f"    [bold red]FAIL[/bold red] [red]{escape(o.reason)}[/red]")
+    for line in o.detail: console.print(f"    [dim]{escape(line)}[/dim]")
+
+def walk(fn, *, root=None, only_dirty=False, need_nbs=False, workers=1, style="block"):
+    """Run `fn(path, sub)` in each submodule, returning a `Report`.
+
+    `fn` returns a list of short strings to show under the submodule's name, or raises
+    `Skip` once it knows there is nothing to do. Only submodules that do something print;
+    the rest are counted by `format_summary`.
+
+    `style="block"` gives each submodule a `==> path` heading with its own output beneath,
+    which is what a long command like `upload` needs. `style="line"` gives one padded line
+    per submodule, which suits verbs that report a single fact.
+
+    Sequential block runs print the heading BEFORE calling `fn`, so its output streams
+    underneath. Everything else prints after, in submodule order, so parallel work cannot
+    interleave and two runs of the same fleet read the same way."""
+    base = Path(root) if root else find_root()
+    rep, todo = Report(), []
+    for s in parse_gitmodules(base):
+        why = _classify(base, s, need_nbs, only_dirty)
+        if why: rep.outcomes.append(Outcome(s.path, "skipped", why))
+        else:   todo.append(s)
+    width = max((len(s.path) for s in todo), default=0) + 2
+
+    def _one(s):
+        try:                       return Outcome(s.path, "ran", detail=list(fn(base/s.path, s) or []))
+        except Skip as e:          return Outcome(s.path, "skipped", str(e))
+        except BaseException as e:
+            head, rest = _fail_parts(e)
+            return Outcome(s.path, "failed", head, rest)
+
+    if workers > 1 and len(todo) > 1:
+        with ThreadPoolExecutor(max_workers=workers) as ex: done = list(ex.map(_one, todo))
+        for o in done: _render(o, style, width)
+    else:
+        done = []
+        live = style == "block"
+        for s in todo:
+            if live: console.print(f"\n[bold cyan]==> {escape(s.path)}[/bold cyan]")
+            o = _one(s)
+            done.append(o)
+            _render(o, style, width, header=not live)
+    rep.outcomes += done
+    rep.outcomes.sort(key=lambda o: o.path)
+    return rep
+
+def finish(rep, verb):
+    "Print the counted summary, name any failures, and return the exit code"
+    console.print(f"\n[bold]{escape(format_summary(rep, verb))}[/bold]")
+    for o in rep.failed:
+        console.print(f"[bold red]FAILED[/bold red] {escape(o.path)}: [dim]{escape(o.reason)}[/dim]")
+    return rep.code
+
+# %% ../nbs/04_Fleet.ipynb #99e2c4fe-c885-4880-b9df-31da51e61f3a
+def script_path(name):
+    """The console script `name` from the environment this is running in.
+
+    Taking it from `sys.executable`'s directory is what makes this work under a
+    non-interactive shell that never put the venv on PATH."""
+    cand = Path(sys.executable).parent/name
+    if cand.is_file(): return str(cand)
+    found = shutil.which(name)
+    if found: return found
+    raise RuntimeError(f"Cannot find the '{name}' console script. Run `uv sync` first")
+
+def upload_one(path, sub=None, args=()):
+    """Run the single-repo `upload` in `path`, letting its own rich output through.
+
+    A subprocess rather than an in-process call: `prep` reads nbdev's config from the cwd
+    and caches it, and `nbdev_test` spawns its own process pool, so nineteen repos in one
+    interpreter is a trap. The subprocess keeps this tty, so colour survives."""
+    r = subprocess.run([script_path("upload"), *args], cwd=str(path), check=False)
+    if r.returncode: raise StepFailed("upload", r.returncode)
+    return []
+
+# %% ../nbs/04_Fleet.ipynb #2ef9f1e5-239a-4790-8cec-43fffb8bc422
+def fleet_upload(
+    all:bool = False,    # Upload every submodule with an nbs/ folder, not just the changed ones
+    root:str = None,     # Superproject root (default: nearest ancestor with .gitmodules)
+):
+    "Run `upload` in each submodule that has local changes"
+    # Sequential on purpose: `upload` runs nbdev_test with 8 workers, and knowledge-lab
+    # has 4 vCPU. Parallel uploads would oversubscribe the box and interleave the output.
+    rep = walk(upload_one, root=root, need_nbs=True, only_dirty=not all, workers=1)
+    sys.exit(finish(rep, "uploaded"))
+
+# %% ../nbs/04_Fleet.ipynb #cee8b478-470e-46fb-9d4a-e77bf6718c23
+def ahead_of_remote(path):
+    "(commits origin has not seen, branch name). Branch is None when HEAD is detached"
+    br = git(path, "rev-parse", "--abbrev-ref", "HEAD")
+    if not br or br == "HEAD": return 0, None
+    n = git(path, "rev-list", "--count", f"origin/{br}..HEAD")
+    return (int(n) if n.isdigit() else 0), br
+
+def push_one(path, sub=None, dry_run=False):
+    "Push `path` when it has local commits origin has not seen"
+    n, br = ahead_of_remote(path)
+    if br is None:              raise Skip("detached HEAD")
+    if not git(path, "remote"): raise Skip("no remote")
+    if not n:                   raise Skip("nothing to push")
+    if dry_run: return [f"would push {n} commit{'' if n == 1 else 's'} on {br}"]
+    return _push_summary(_run("git", "-C", str(path), "push"))
+
+def copy_one(path, sub=None, files=(), dest="nbs", dry_run=False):
+    """Copy `files` into `path`/`dest`.
+
+    The file list belongs to the caller, so this stays a general-purpose copy rather than
+    learning about any particular superproject's shared chrome."""
+    out = Path(path)/dest
+    if not out.is_dir(): raise Skip(f"no {dest}/")
+    names = []
+    for f in files:
+        src = Path(f)
+        if not src.is_file(): raise StepFailed(f"copy {src.name}", 1, f"no such file: {src}")
+        if not dry_run: shutil.copy2(src, out/src.name)
+        names.append(src.name)
+    return [("would copy " if dry_run else "copied ") + ", ".join(names) + f" -> {dest}/"]
+
+# %% ../nbs/04_Fleet.ipynb #93610aa9-b47c-47f0-af54-f6293984e066
+def fleet_push(
+    dry_run:bool = False,   # Report what would be pushed without pushing it
+    root:str     = None,    # Superproject root (default: nearest ancestor with .gitmodules)
+):
+    "Push every submodule that has local commits not yet on its remote"
+    # Network-bound and independent per remote, so this one does parallelise.
+    rep = walk(lambda p, s: push_one(p, s, dry_run=dry_run),
+               root=root, workers=8, style="line")
+    sys.exit(finish(rep, "would push" if dry_run else "pushed"))
+
+def fleet_copy(
+    files:str,              # Files to copy into each submodule, comma or space separated
+    dest:str     = "nbs",   # Directory inside each submodule to copy into
+    dry_run:bool = False,   # Report what would be copied without copying it
+    root:str     = None,    # Superproject root (default: nearest ancestor with .gitmodules)
+):
+    "Copy shared files into every submodule that has the destination directory"
+    fs = [f for f in re.split(r"[,\s]+", files) if f]
+    if not fs: sys.exit("fleet copy: no files given")
+    rep = walk(lambda p, s: copy_one(p, s, files=fs, dest=dest, dry_run=dry_run),
+               root=root, workers=8, style="line")
+    sys.exit(finish(rep, "would update" if dry_run else "updated"))
+
+# %% ../nbs/04_Fleet.ipynb #5e870c46-a03b-4be9-a7a5-0a30e9af8830
+def _porcelain(path):
+    """`git status -s` for `path`, NOT stripped.
+
+    `github.git` strips its output, and `git status -s` pads the code to two columns, so
+    stripping eats the leading space of the FIRST line and shifts that one path by a
+    character. `automate.status` documents the same trap."""
+    return subprocess.run(["git", "-C", str(path), "status", "-s"],
+                          capture_output=True, text=True, check=False).stdout
+
+def status_one(path, sub=None, short=False):
+    """Branch, dirty flag and short HEAD for `path`.
+
+    With `short`, clean submodules are skipped and the dirty ones list their changed
+    paths - the fleet-wide "what have I got outstanding" view."""
+    st = local_state(path)
+    br = st["branch"] or "?"
+    if br == "HEAD": br = "DETACHED"
+    line = f"{br:<10} {'dirty' if st['dirty'] else 'clean':<6} {st['head'] or '-'}"
+    if not short: return [line]
+    if not st["dirty"]: raise Skip("clean")
+    return [line] + [f"  {l}" for l in _porcelain(path).splitlines()]
+
+def fleet_status(
+    short:bool = False,   # Only the submodules with changes, listing the changed paths
+    root:str   = None,    # Superproject root (default: nearest ancestor with .gitmodules)
+):
+    "Branch, dirty flag and HEAD for every submodule"
+    rep = walk(lambda p, s: status_one(p, s, short=short), root=root, workers=8, style="line")
+    sys.exit(finish(rep, "changed" if short else "reported"))
+
+# %% ../nbs/04_Fleet.ipynb #68d6b97c-8e6c-4bd5-86bd-a0e0ca83469c
+def _git_ok(path, *args):
+    "True when git succeeded in `path`. `git()` hides the exit code, and here it matters"
+    return subprocess.run(["git", "-C", str(path), *args],
+                          capture_output=True, check=False).returncode == 0
+
+def _count(path, rng):
+    "Commit count for an `a..b` range, 0 when the range does not resolve"
+    n = git(path, "rev-list", "--count", rng)
+    return int(n) if n.isdigit() else 0
+
+def fetch_all(root=None, workers=8):
+    "Fetch every initialised submodule concurrently. This is the slow half of an update"
+    base = Path(root) if root else find_root()
+    subs = [s for s in parse_gitmodules(base) if (base/s.path/".git").exists()]
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        list(ex.map(lambda s: git(base/s.path, "fetch", "-q", "origin"), subs))
+    return len(subs)
+
+def update_one(path, sub=None, dry_run=False, branch="main"):
+    """Reattach `path` to `branch` and fast-forward it to origin/<branch>.
+
+    Assumes `fetch_all` already ran: fetching is the half that parallelises, and this is
+    the half that must not, because a checkout rewrites the worktree."""
+    if git(path, "status", "--porcelain"):
+        raise StepFailed("update", 1, "uncommitted changes; commit or stash first")
+    if not git(path, "remote"): raise Skip("no remote")
+    target = f"origin/{branch}"
+    if not git(path, "rev-parse", "--verify", "--quiet", target): raise Skip(f"no {target}")
+
+    br   = git(path, "rev-parse", "--abbrev-ref", "HEAD")
+    move = br != branch
+    # Compare the branch we are ABOUT to be on, not the one we happen to be on now
+    ref    = branch if _git_ok(path, "rev-parse", "--verify", "--quiet", branch) else "HEAD"
+    behind = _count(path, f"{ref}..{target}")
+    ahead  = _count(path, f"{target}..{ref}")
+    # Diverged needs a human. The bash version echoed a line and moved on, which is easy
+    # to scroll past; this fails the run so the exit code carries it.
+    if ahead and behind:
+        raise StepFailed("merge --ff-only", 1,
+                         f"diverged from {target}: {ahead} ahead, {behind} behind - resolve by hand")
+    was = "DETACHED" if br == "HEAD" else br
+    if not move and not behind: raise Skip("up to date")
+    if dry_run:
+        bits = ([f"checkout {branch} (from {was})"] if move else []) + \
+               ([f"fast-forward {behind}"] if behind else [])
+        return ["would " + ", ".join(bits)]
+
+    done = []
+    if move:
+        if not _git_ok(path, "checkout", "-q", branch):
+            _run("git", "-C", str(path), "checkout", "-q", "-b", branch, target)
+        done.append(f"checked out {branch} (was {was})")
+    behind = _count(path, f"HEAD..{target}")   # the checkout may already have moved us
+    if behind:
+        _run("git", "-C", str(path), "merge", "--ff-only", target)
+        done.append(f"fast-forwarded {behind} commit{'' if behind == 1 else 's'}")
+    return done
+
+def dirty_submodules(root=None):
+    "Submodule paths holding uncommitted changes"
+    base = Path(root) if root else find_root()
+    return [s.path for s in parse_gitmodules(base)
+            if (base/s.path/".git").exists() and git(base/s.path, "status", "--porcelain")]
+
+def init_new(root=None, dry_run=False):
+    """Initialise only the submodules git reports as uninitialised.
+
+    A blanket `submodule update --init` would reset every initialised submodule back to
+    its recorded gitlink and detach its HEAD, which is the one thing this setup avoids."""
+    base = Path(root) if root else find_root()
+    new = [l.split()[1] for l in git(base, "submodule", "status").splitlines() if l.startswith("-")]
+    if new and not dry_run:
+        _run("git", "-C", str(base), "submodule", "update", "--init", "--", *new)
+    return new
+
+def pull_root(base):
+    "Fast-forward the superproject itself, with the advice its usual failure needs"
+    try: return _run("git", "-C", str(base), "pull", "--ff-only").strip().splitlines()[-1:]
+    except StepFailed as e:
+        raise StepFailed(e.cmd, e.code, f"{e.output}\n"
+            "If it complains about submodule paths, the recorded gitlinks drifted.\n"
+            "Discard them (the update step re-advances them anyway):\n"
+            "  git checkout -- $(git diff --name-only)") from None
+
+# %% ../nbs/04_Fleet.ipynb #8fb7bc91-d79a-4c1a-bb81-e28b3a77b118
+def fleet_update(
+    dry_run:bool = False,   # Report what would move without moving it
+    root:str     = None,    # Superproject root (default: nearest ancestor with .gitmodules)
+):
+    "Fetch every submodule, then fast-forward each one's main to origin/main"
+    base = Path(root) if root else find_root()
+    with _step(1, 2, "fetch every submodule") as d:
+        d += [f"{fetch_all(base)} fetched"]
+    console.print("[dim]2/2[/dim] [bold]fast-forward each main[/bold]")
+    rep = walk(lambda p, s: update_one(p, s, dry_run=dry_run), root=base, workers=1, style="line")
+    sys.exit(finish(rep, "would update" if dry_run else "updated"))
+
+def fleet_sync(
+    dry_run:bool = False,   # Report what would move without moving it
+    root:str     = None,    # Superproject root (default: nearest ancestor with .gitmodules)
+):
+    "Bring this checkout level with every remote: pull, init new submodules, fast-forward each"
+    base = Path(root) if root else find_root()
+    # Pre-flight FIRST: a dirty submodule turns the checkout/merge below into a conflicted
+    # tree, so nothing at all should happen until this passes.
+    dirty = dirty_submodules(base)
+    if dirty:
+        console.print("[bold red]Uncommitted changes in:[/bold red]")
+        for d in dirty: console.print(f"  {escape(d)}")
+        console.print("Commit or stash them first ([bold]just upload[/bold]), then re-run.")
+        sys.exit(1)
+
+    with _step(1, 3, "pull the superproject") as d:
+        d += ["skipped (dry run)"] if dry_run else pull_root(base)
+    with _step(2, 3, "initialise new submodules") as d:
+        new = init_new(base, dry_run=dry_run)
+        d += [f"{'would init ' if dry_run else 'initialised '}{', '.join(new)}"] if new else ["none"]
+    with _step(3, 3, "fetch every submodule") as d:
+        d += [f"{fetch_all(base)} fetched"]
+    rep = walk(lambda p, s: update_one(p, s, dry_run=dry_run), root=base, workers=1, style="line")
+    sys.exit(finish(rep, "would update" if dry_run else "updated"))
+
+# %% ../nbs/04_Fleet.ipynb #0281bd2b-91ba-4e49-90dc-d1a95d54d5a6
+VERBS = {"upload": fleet_upload, "push": fleet_push, "copy": fleet_copy,
+         "status": fleet_status, "update": fleet_update, "sync": fleet_sync}
+
+def parse_verb(argv):
+    "(verb, remaining args) for `fleet ...`, or None when `argv` does not name a verb"
+    if not argv or argv[0].startswith("-"): return None
+    return (argv[0], argv[1:]) if argv[0] in VERBS else None
+
+def usage():
+    "The verb list, for --help and for an unknown verb"
+    lines = ["Usage: fleet <verb> [options]", "", "Verbs:"]
+    lines += [f"  {name:<8} {(fn.__doc__ or '').strip()}" for name, fn in sorted(VERBS.items())]
+    lines += ["", "Any verb takes --help for its own options."]
+    return "\n".join(lines)
+
+def run_verb(name, argv):
+    """Parse `argv` against the verb's own annotations, then call it.
+
+    Deliberately NOT `@call_parse`: fastcore runs the first decorated function in a module
+    the moment that module is `__main__`, which is exactly what makes `python -m
+    nbdevAuto.github` work with its single verb. With several verbs it would run whichever
+    happened to be defined first, so the verbs stay plain functions and the parser is built
+    here. `anno_parser` is the same one `call_parse` uses, so `--help` is unchanged."""
+    fn = VERBS[name]
+    args = vars(anno_parser(fn, prog=f"fleet {name}").parse_args(argv))
+    for k in ("pdb", "xtra"): args.pop(k, None)
+    return fn(**args)
+
+def fleet():
+    """Dispatch `fleet <verb>` to the matching command.
+
+    `upload` and `status` are already console scripts bound to the single-repo versions in
+    `automate`, so the fleet-wide ones cannot claim those names. One script with verbs
+    sidesteps the collision and keeps `--help` working per verb."""
+    picked = parse_verb(sys.argv[1:])
+    if not picked:
+        print(usage())
+        sys.exit(0 if sys.argv[1:2] in ([], ["-h"], ["--help"]) else 2)
+    return run_verb(*picked)
+
+# %% ../nbs/04_Fleet.ipynb #7adb89c6-6788-4241-acff-53cb4566b5ce
+if __name__ == "__main__": fleet()

{nbdevauto-0.3.66 → nbdevauto-0.3.68/nbdevAuto.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdevAuto
-Version: 0.3.66
+Version: 0.3.68
 Summary: automating nbdev
 Author-email: Benedict Thekkel <bthekkel1@gmail.com>
 License-Expression: Apache-2.0
@@ -73,23 +73,25 @@ from nbdevAuto.pdf import PDFreader
 | [Automate](01_Automate.ipynb) | The command line surface: the prep/commit/push pipeline, the GitHub and PyPI release halves, and the help output that lists them all |
 | [PDF Reader](02_PDF_reader.ipynb) | [`PDFreader`](https://bthek1.github.io/nbdevAuto/pdf_reader.html#pdfreader), a class that converts a PDF through `pdf2image` and renders page ranges inline when you slice it (`pdf[0:5]`) |
 | [GitHub](03_GitHub.ipynb) | [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus): reading `.gitmodules`, resolving a token, and asking the GitHub API about every submodule at once - CI runs, Pages deploys, Pages builds, remote `main` shas - plus the `--report` and `--audit` views and the exit codes that keep “absent” apart from “cannot ask” |
+| [Fleet](04_Fleet.ipynb) | [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet): running one command across every submodule of a superproject. A walker that reports only what did work and counts the rest, plus the verbs built on it - upload, push, copy, status, update and sync |
 
 ------------------------------------------------------------------------
 
 ## The Command Line Surface
 
-Installing the package puts these on your `PATH`. Most are ordinary functions in [Automate](01_Automate.ipynb), exposed as scripts through `[project.scripts]`; [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) comes from [GitHub](03_GitHub.ipynb).
+Installing the package puts these on your `PATH`. Most are ordinary functions in [Automate](01_Automate.ipynb), exposed as scripts through `[project.scripts]`; [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) comes from [GitHub](03_GitHub.ipynb) and [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet) from [Fleet](04_Fleet.ipynb).
 
 | Command | Does |
 |----|----|
 | [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) | Bump the version, then export, test and clean the notebooks, refreshing `_quarto.yml` and the README |
-| [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp) | git add, commit, and push. Without `-m` the commit message is the status output |
+| [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp) | git add, commit, and push. Without `-m` the message is built from the staged paths |
 | [`status`](https://bthek1.github.io/nbdevAuto/automate.html#status) | Show the working tree state |
 | [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) | [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) then [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp), the one you actually type |
 | `gitrelease` | Bump the **minor** version, then tag and create a GitHub release |
 | `piprelease` | Build the sdist and wheel, then upload to PyPI with twine |
 | [`release`](https://bthek1.github.io/nbdevAuto/automate.html#release) | `gitrelease` then `piprelease` |
 | [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) | Remote status for every submodule of an nbdev superproject, from the GitHub API. `--report` for the sync view, `--audit` to check `.gitmodules` against the repos the account owns, `--json` for machine output |
+| [`fleet`](https://bthek1.github.io/nbdevAuto/fleet.html#fleet) | Run one command across every submodule: `fleet upload|push|copy|status|update|sync`. Every verb takes `--help`, and the destructive ones take `--dry-run` |
 | `h` | Print the list of available commands |
 
 Both [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) and [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) take `-p` to choose which version part to increment; it defaults to 2, the patch, so every [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) ships a new version.

nbdevauto-0.3.66/nbdevAuto/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.66"

nbdevauto-0.3.66/nbdevAuto/fleet.py

@@ -1,201 +0,0 @@
-"""Run one command across every submodule of a superproject
-
-Docs: https://bthek1.github.io/nbdevAuto/fleet.html.md"""
-
-# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/04_Fleet.ipynb.
-
-# %% auto #0
-__all__ = ['VERBS', 'Outcome', 'Report', 'format_summary', 'walk', 'finish', 'script_path', 'upload_one', 'fleet_upload',
-           'parse_verb', 'usage', 'run_verb', 'fleet']
-
-# %% ../nbs/04_Fleet.ipynb #d361ee5f-9f09-464f-aec6-0e27cec90fe9
-import shutil
-import subprocess
-import sys
-from concurrent.futures import ThreadPoolExecutor
-from dataclasses import dataclass, field
-from pathlib import Path
-
-from fastcore.script import *
-
-# The rendering layer lives in `automate`, the git/discovery layer in `github`. This
-# module is the only one that knows about MANY repos; those two stay single-repo.
-from .automate import StepFailed, console, escape
-from .github import find_root, git, parse_gitmodules
-
-# %% ../nbs/04_Fleet.ipynb #4e6b24c5-cd71-434c-84e6-e6994d5959c7
-@dataclass
-class Outcome:
-    "What happened in one submodule"
-    path:   str
-    state:  str                                  # ran | skipped | failed
-    reason: str  = ""                            # why it was skipped, or how it failed
-    detail: list = field(default_factory=list)   # short lines to show under the path
-
-@dataclass
-class Report:
-    "Everything a `walk` did, and the exit code it implies"
-    outcomes: list = field(default_factory=list)
-
-    @property
-    def ran(self):    return [o for o in self.outcomes if o.state == "ran"]
-    @property
-    def failed(self): return [o for o in self.outcomes if o.state == "failed"]
-    @property
-    def code(self):   return 1 if self.failed else 0
-
-    def skip_counts(self):
-        "Skip reason -> count, in the order the reasons were first seen"
-        counts = {}
-        for o in self.outcomes:
-            if o.state == "skipped": counts[o.reason] = counts.get(o.reason, 0) + 1
-        return counts
-
-def format_summary(rep, verb="ran"):
-    "The one line that replaces a message per submodule. Quiet submodules are counted, not narrated"
-    n = len(rep.outcomes)
-    parts = [f"{len(rep.ran)} {verb}"]
-    parts += [f"{c} {reason}" for reason, c in rep.skip_counts().items()]
-    if rep.failed: parts.append(f"{len(rep.failed)} FAILED")
-    return f"{n} submodule{'' if n == 1 else 's'}: " + ", ".join(parts)
-
-# %% ../nbs/04_Fleet.ipynb #099242e8-c9ad-4b48-8ebc-7a818e5f8f81
-def _classify(base, sub, need_nbs, only_dirty):
-    "The reason to skip this submodule, or None to run it"
-    p = base/sub.path
-    # An uninitialised submodule is an empty directory: present, but with no .git
-    if not (p/".git").exists():          return "not initialised"
-    if need_nbs and not (p/"nbs").is_dir(): return "without nbs"
-    if only_dirty and not git(p, "status", "--porcelain"): return "clean"
-    return None
-
-def _fail_reason(e):
-    "One line describing why a submodule's callable did not finish"
-    if isinstance(e, StepFailed): return f"{e.cmd} exited {e.code}"
-    return f"{type(e).__name__}: {e}"
-
-def walk(fn, *, root=None, only_dirty=False, need_nbs=False, workers=1, header=True):
-    """Run `fn(path, sub)` in each submodule, returning a `Report`.
-
-    `fn` may return a list of short strings to show under the submodule's name. Only
-    submodules that actually do something get printed; the rest are counted by the caller
-    through `format_summary`. Sequential runs print the header BEFORE the callable so its
-    own output streams under it; parallel runs print after, so lines cannot interleave."""
-    base = Path(root) if root else find_root()
-    rep, todo = Report(), []
-    for s in parse_gitmodules(base):
-        why = _classify(base, s, need_nbs, only_dirty)
-        if why: rep.outcomes.append(Outcome(s.path, "skipped", why))
-        else:   todo.append(s)
-
-    def _one(s):
-        try: return Outcome(s.path, "ran", detail=list(fn(base/s.path, s) or []))
-        except BaseException as e: return Outcome(s.path, "failed", _fail_reason(e))
-
-    def _head(path): console.print(f"\n[bold cyan]==> {escape(path)}[/bold cyan]")
-
-    if workers > 1 and len(todo) > 1:
-        # Results are rendered in submodule order, not completion order, so two runs of
-        # the same fleet read the same way.
-        with ThreadPoolExecutor(max_workers=workers) as ex: done = list(ex.map(_one, todo))
-        for o in done:
-            if header: _head(o.path)
-            _render(o)
-            rep.outcomes.append(o)
-    else:
-        for s in todo:
-            if header: _head(s.path)
-            o = _one(s)
-            _render(o)
-            rep.outcomes.append(o)
-    rep.outcomes.sort(key=lambda o: o.path)
-    return rep
-
-def _render(o):
-    "A submodule's own lines, or why it failed"
-    if o.state == "failed":
-        console.print(f"    [bold red]FAIL[/bold red] [dim]{escape(o.reason)}[/dim]")
-    for line in o.detail: console.print(f"    [dim]{escape(line)}[/dim]")
-
-def finish(rep, verb):
-    "Print the counted summary, name any failures, and return the exit code"
-    console.print(f"\n[bold]{escape(format_summary(rep, verb))}[/bold]")
-    for o in rep.failed:
-        console.print(f"[bold red]FAILED[/bold red] {escape(o.path)}: [dim]{escape(o.reason)}[/dim]")
-    return rep.code
-
-# %% ../nbs/04_Fleet.ipynb #99e2c4fe-c885-4880-b9df-31da51e61f3a
-def script_path(name):
-    """The console script `name` from the environment this is running in.
-
-    Taking it from `sys.executable`'s directory is what makes this work under a
-    non-interactive shell that never put the venv on PATH."""
-    cand = Path(sys.executable).parent/name
-    if cand.is_file(): return str(cand)
-    found = shutil.which(name)
-    if found: return found
-    raise RuntimeError(f"Cannot find the '{name}' console script. Run `uv sync` first")
-
-def upload_one(path, sub=None, args=()):
-    """Run the single-repo `upload` in `path`, letting its own rich output through.
-
-    A subprocess rather than an in-process call: `prep` reads nbdev's config from the cwd
-    and caches it, and `nbdev_test` spawns its own process pool, so nineteen repos in one
-    interpreter is a trap. The subprocess keeps this tty, so colour survives."""
-    r = subprocess.run([script_path("upload"), *args], cwd=str(path))
-    if r.returncode: raise StepFailed("upload", r.returncode)
-    return []
-
-# %% ../nbs/04_Fleet.ipynb #2ef9f1e5-239a-4790-8cec-43fffb8bc422
-def fleet_upload(
-    all:bool = False,    # Upload every submodule with an nbs/ folder, not just the changed ones
-    root:str = None,     # Superproject root (default: nearest ancestor with .gitmodules)
-):
-    "Run `upload` in each submodule that has local changes"
-    # Sequential on purpose: `upload` runs nbdev_test with 8 workers, and knowledge-lab
-    # has 4 vCPU. Parallel uploads would oversubscribe the box and interleave the output.
-    rep = walk(upload_one, root=root, need_nbs=True, only_dirty=not all, workers=1)
-    sys.exit(finish(rep, "uploaded"))
-
-# %% ../nbs/04_Fleet.ipynb #0281bd2b-91ba-4e49-90dc-d1a95d54d5a6
-VERBS = {"upload": fleet_upload}
-
-def parse_verb(argv):
-    "(verb, remaining args) for `fleet ...`, or None when `argv` does not name a verb"
-    if not argv or argv[0].startswith("-"): return None
-    return (argv[0], argv[1:]) if argv[0] in VERBS else None
-
-def usage():
-    "The verb list, for --help and for an unknown verb"
-    lines = ["Usage: fleet <verb> [options]", "", "Verbs:"]
-    lines += [f"  {name:<10} {(fn.__doc__ or '').strip()}" for name, fn in sorted(VERBS.items())]
-    lines += ["", "Any verb takes --help for its own options."]
-    return "\n".join(lines)
-
-def run_verb(name, argv):
-    """Parse `argv` against the verb's own annotations, then call it.
-
-    Deliberately NOT `@call_parse`: fastcore runs the first decorated function in a module
-    the moment that module is `__main__`, which is exactly what makes `python -m
-    nbdevAuto.github` work with its single verb. With several verbs it would run whichever
-    happened to be defined first, so the verbs stay plain functions and the parser is built
-    here. `anno_parser` is the same one `call_parse` uses, so `--help` is unchanged."""
-    fn = VERBS[name]
-    args = vars(anno_parser(fn, prog=f"fleet {name}").parse_args(argv))
-    for k in ("pdb", "xtra"): args.pop(k, None)
-    return fn(**args)
-
-def fleet():
-    """Dispatch `fleet <verb>` to the matching command.
-
-    `upload` and `status` are already console scripts bound to the single-repo versions in
-    `automate`, so the fleet-wide ones cannot claim those names. One script with verbs
-    sidesteps the collision and keeps `--help` working per verb."""
-    picked = parse_verb(sys.argv[1:])
-    if not picked:
-        print(usage())
-        sys.exit(0 if sys.argv[1:2] in ([], ["-h"], ["--help"]) else 2)
-    return run_verb(*picked)
-
-# %% ../nbs/04_Fleet.ipynb #7adb89c6-6788-4241-acff-53cb4566b5ce
-if __name__ == "__main__": fleet()