ppkit 0.2.0__tar.gz → 0.2.2__tar.gz

{ppkit-0.2.0 → ppkit-0.2.2}/CHANGELOG.md

@@ -1,5 +1,141 @@
 # Changelog
 
+## v0.2.2
+
+`pp queue` records a kill as a kill when the worker sending it dies before
+it records the send. Such a job no longer ends as its own failure, and its
+`on_fail` hook does not run. A stop's new `going` field says when pp began
+sending it.
+
+`pp queue`: a kill whose worker dies while sending it is still a kill.
+
+- A worker that died between sending a kill's stop and recording it left the
+  next worker to read the job's end as the job's own. That job was recorded
+  as its own failure, with exit code 137 or reason `lost`, and its `on_fail`
+  hook ran. It is now recorded `killed`, and no hook runs. A timeout's stop
+  in the same window now ends as a timeout.
+- A stop gains `going` in `show --json` and `status --json`: when pp began
+  sending it, recorded before anything goes out. An exit code the attempt
+  wrote after that time is the stop's outcome, with the code kept, unless pp
+  was refused the stop. A job that ends on its own just as its worker dies
+  before sending is recorded the same way.
+- `show` says "sending began" for a stop pp began sending and has nothing
+  marked sent for. A stop pp was refused still says "nothing signalled".
+- `kill` reports a job that ended in that window as killed, "ended as its
+  stop was being sent", instead of saying the job had already ended.
+
+## v0.2.1
+
+pp finds the session that runs it with nothing set, so `--mine` works for
+any agent and in a terminal. `pp queue` reads the cards with a command of
+yours, and any command answers to an alias of your own. A `pp-NAME` program
+is a command only in pp's own folders, and no longer on your `PATH`.
+
+`pp`: a program named `pp-NAME` on your `PATH` is no longer a command.
+
+- pp looks for such a program in `~/.config/pp/commands/`, in each plugin
+  and in each `PP_PATH` folder, and reads no `PATH` for one. Other software
+  installs programs named `pp-*`, and on `PATH` such a program takes a
+  command's name or a unique prefix of it (`pp q`) and shows in `pp -h`. A
+  program of yours stays a command by moving it into
+  `~/.config/pp/commands/`, or by listing the folder it is in in `PP_PATH`.
+- Every Python command is still found before any such program, and the
+  programs in that folder order, so nothing pp found in those folders
+  moves.
+
+`pp queue`: the card reading and the calling session are named by you, with
+nvidia-smi and the process pp runs under as the defaults.
+
+- `[resources] gpu_gb = { probe = "CMD" }` reads the machine's cards with a
+  command of yours instead of nvidia-smi. CMD prints one line a card,
+  `index,name,total_MiB,used_MiB,util`, which is nvidia-smi's own
+  `--format=csv,noheader,nounits` line, and the index it prints is the one pp
+  reserves and publishes in `CUDA_VISIBLE_DEVICES`. The reading is cached for
+  the pool's `every` and taken under the probe's own claim, as any probe's is.
+  A probe in a `[queue.NAME.resources] gpu_gb` is still refused: one machine
+  has one set of cards.
+- `pp queue status --json` gains `cards_why`: why `cards` is null, and `""`
+  where the cards were read.
+- pp finds the calling session from the process it runs under: the nearest
+  process above pp that is neither a shell nor a wrapper, named with its pid,
+  its start time and this boot. So `--mine` and a job's `owner` are any
+  agent's with nothing set, since every command an agent runs is a child of
+  the agent's own process, and a person's terminal is a session the same way.
+  `PP_SESSION`, where it is set and not empty, is the name an agent gives its
+  own session instead, and wins over `CLAUDE_CODE_SESSION_ID`. A process pp
+  started itself, a job or its runner or a hook or a stop command, is no
+  session. pid 1 and an init are no session either, so a `wait` left running
+  by a shell that has returned, which the kernel reparents to an init, says
+  there is none instead of answering for another session's jobs. The session
+  is found once in a run, so such a wait reports the outcomes it selected to
+  the session that queued them and no later `wait --mine` of that session
+  reports them again. pp strips those variables from everything it starts.
+- `pp queue status --mine`, which `pp queue --mine` and `ls --mine` are too,
+  is the jobs this session queued, in every state, in the text view and in
+  `--json`'s `running`, `queued`, `held` and `recent`. It applies together
+  with `--here` and `--project`, and narrows the jobs shown and not what the
+  queues, the workers and the pools hold. Where there is no session it exits
+  2, as `wait --mine` does.
+
+`pp`: a command answers to a name of your own.
+
+- `[alias]` in `~/.config/pp/config.toml` names any command anything on this
+  machine: `st = "promote status"`, or a list of words. A word is resolved
+  as a command's own name, then `[alias]`, then a module's `ALIASES`, then a
+  unique prefix, so an alias hides no command and beats a prefix. `pp help
+  st` and `pp st <TAB>` follow the expansion.
+- An alias runs no other alias. One whose key is a command's name or `help`,
+  or outside `[a-z][a-z0-9_-]*`, or whose first word names no command, is
+  skipped and listed under `pp -h`'s "broken (skipped)". The table is read
+  only where a word is not a command's exact name, so a config file that
+  cannot be parsed leaves every command pp ships working.
+- `pp cmd alias` lists every alias of both kinds, with what it runs and
+  where it is declared (`--json` for the same as data). `pp cmd alias NAME
+  CMD [ARGS...]` adds one, `pp cmd alias NAME --rm` takes it back, and `-n`
+  prints the change and writes nothing. Those flags count wherever they
+  stand, so `pp cmd alias st promote status -n` is a dry run. A command line
+  of its own `-n`, `--rm` or `--json` goes after a `--`: `pp cmd alias dq --
+  queue drop -n`.
+- `pp cmd alias` is the one place pp writes `config.toml`: one line of the
+  `[alias]` table under a lock, the file's mode kept, every other byte as it
+  was. A change it cannot make as one line names the file to edit by hand.
+- `pp cmd ls` shows each command's aliases of both kinds, and its `--json`
+  rows gain `config_aliases` beside `aliases`.
+
+`pp queue`: the views, the plans and the help say more of what pp knows
+about your cards, your queues and your projects.
+
+- `status --json` publishes the gpu_gb pool of each scope in `pools` and
+  `shared`, an entry like every other pool's with one field of its own:
+  `per_card`, that scope's budget on each card of the reading and what its
+  running jobs reserve on that card. The text view shows those numbers card
+  by card. So a job is sized against the smallest budget of every scope its
+  queue draws from before it is queued, instead of being refused first.
+- `pp queue` covers every queue a `[queue.NAME]` table names, beside the
+  queues that hold records and the ones a worker is up for. Such a queue
+  with nothing in it is a section with nothing in it and an entry in
+  `--json`, and reading it creates no directory and no file. "no queues yet"
+  is for a machine with none of the three.
+- `pp queue add` warns on stderr where the job has no runner, no `.pp.toml`
+  is in or above its directory, and a directory directly below is a project
+  whose `[queue]` sets one. The warning names that directory and `--cwd`,
+  once per directory, and the job is queued as it asks.
+- The command `add` hands an agent names the ids it queued as ranges (`wait
+  8-13 20`), which is one word for a campaign of a hundred lines.
+- `clean` and `drop` say in their plan that they remove the records and pp's
+  own files for them, and that a log at a path a `log` pattern or `--log`
+  named stays.
+- The extra run of the project's stop command once a run is over writes to
+  the worker's log instead of the job's log. The stop a kill or a timeout
+  asked for still writes in the job's log.
+- `pp help queue` names the shape of each `--json`: one object with its keys
+  for `status`, one job and its watchers for `show`, and a list of `{queue,
+  pid, how, log, up}` for `worker status`.
+- `pp help queue` says that several selection forms are several words on one
+  verb, that a tag or a prefix selects every job of that name the store
+  holds, an earlier round's ended ones too, and that a campaign line's
+  `--cwd` is that line's own directory and so its project.
+
 ## v0.2.0
 
 The interface this minor version keeps. `pp help queue` says what is promised

{ppkit-0.2.0 → ppkit-0.2.2}/CONTRIBUTING.md

@@ -87,7 +87,9 @@ by running both.
 2. `def main(argv: list[str]) -> int`, which builds its parser with
    `ui.parser("NAME", __doc__)`.
 3. If you want short names for it, `ALIASES = ["x"]`, written as a literal
-   list.
+   list. A name one machine wants is `[alias]` in its own `config.toml`
+   instead (`pp cmd alias x NAME`), which beats both `ALIASES` and a
+   prefix and is checked against the command names before it is written.
 
 These rules keep pp working as commands come and go:
 
@@ -183,7 +185,9 @@ These rules keep pp working as commands come and go:
 | 3 | `pp queue wait` or `watch` gave up at its `--timeout` |
 | 130 | interrupted (Ctrl-C) |
 
-A `pp-NAME` program's own exit status passes through unchanged.
+A `pp-NAME` program in `~/.config/pp/commands/`, in a plugin or in a
+`PP_PATH` folder is a command, and its own exit status passes through
+unchanged. `PATH` is not read for one.
 
 ## How pp works
 
@@ -283,7 +287,7 @@ and `tests/test_constructs.py` reads the source for each:
   every write is one call and one whole transaction. Two sites outside it run a
   process of their own, and both are named exemptions: `reading`, which runs a
   user's probe under that probe's own claim, and `_cards`, which runs
-  nvidia-smi.
+  nvidia-smi where `[resources] gpu_gb` gives no probe of its own.
 - The purity rule. A function of `jobpolicy.py` reaches no clock, no store, no
   process, no signal and no file. It is handed records, readings, settings and
   `now`, and gives back a value, so a rule that could be raced is a rule no
@@ -347,8 +351,9 @@ A kill, pass by pass:
 
 ```
 kill:   ask_stop(merge_stop) -> worker_up(wake=True) -> SIGUSR1 to the worker
-worker: carry_out: the facts -> decide = TERM -> the project's stop command,
-        or the SIGTERM to the group, then txn marks `sent`
+worker: carry_out: the facts -> decide = TERM, and its txn records `going`
+     -> the project's stop command, or the SIGTERM to the group,
+        then txn marks `sent`
      -> (the grace) -> decide = KILL9 -> signal
      -> the wrapper ends, so the job's run claim is free
      -> decide = ENDED_AS -> _finish records the outcome and the hook it owes
@@ -363,11 +368,14 @@ own exit time and not the queue's poll period.
 
 The rules the worker follows are the ones `pp help queue` states under "How a
 job ends, whatever reached it", and that help text is their one statement.
-Two more are for contributors: which of the two a stop is comes from the
+Three more are for contributors. Which of the two a stop is comes from the
 `timeout` field a worker writes on the stop it wrote itself, never from the
-name of whoever asked; and an exit code the attempt wrote after its stop went
-out is that stop's outcome, with the code kept, since a container runner writes
-the code of a container the stop command ended.
+name of whoever asked. An exit code the attempt wrote after its stop began
+going out is that stop's outcome, with the code kept, since a container runner
+writes the code of a container the stop command ended. And that moment is the
+stop's `going`, which the decision's transaction records with its own clock
+before anything goes out: a worker can die between a signal and its record,
+and a job can end between its facts and its decision.
 
 `TestTheDecision` in `tests/test_queue.py` is a table over every combination
 of those facts. Each row carries the rule from that help as its own label,

{ppkit-0.2.0 → ppkit-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ppkit
-Version: 0.2.0
+Version: 0.2.2
 Summary: A CLI kit for user & agents
 Keywords: cli,job queue,gpu,agents,toolkit
 Author: The pp Authors
@@ -61,12 +61,16 @@ pp needs no packages beyond Python itself, and it completes in zsh and bash.
 
 Each command is one Python file. pp looks for them when it runs: its own in
 `pp/commands/`, yours in `~/.config/pp/commands/`, the plugins you added
-with `pp cmd add`, the folders listed in `PP_PATH`, and any program named
-`pp-NAME` on your `PATH`. The first one found wins, so a plugin cannot hide
-a built-in or one of yours. `pp` lists commands without loading them, so
-one broken command cannot break the others.
+with `pp cmd add`, and the folders listed in `PP_PATH`. A program named
+`pp-NAME` in one of those folders, pp's own aside, is a command too. The
+first one found wins, so a plugin cannot hide a built-in or one of yours.
+`pp` lists commands without loading them, so one broken command cannot
+break the others.
 `pp help NAME` prints a command's manual, with examples.
 
+A command answers to its file's name, to a unique prefix of it, and to any
+name you give it with `pp cmd alias`.
+
 Everything pp keeps is in plain files:
 
 ```
@@ -326,12 +330,27 @@ pp cmd rm REPO
 pp cmd ls                                   every command, and where it comes from
 ```
 
+Any command can have a name of your own:
+
+```
+pp cmd alias st promote status              `pp st` is `pp promote status`
+pp cmd alias                                every alias, and what it runs
+pp cmd alias st --rm                        take the name back
+```
+
+The names live in `[alias]` in `~/.config/pp/config.toml`, and this is the
+one place pp writes that file. A name that is a command's own is refused,
+so an alias never hides a command, and `pp help st` and `pp st <TAB>` say
+what `pp promote status` does.
+
 pp clones the plugin into `~/.local/share/pp/plugins/` and checks out the
 commit you said yes to. Only `pp cmd update` moves it, after showing you
 the diff. A plugin's code runs as you, so read it before you say yes.
 
-A program named `pp-NAME` on your `PATH`, in any language, is a command
-too. To add a command to pp itself, see [CONTRIBUTING.md](https://github.com/xflash96/pp/blob/main/CONTRIBUTING.md).
+A program named `pp-NAME` in `~/.config/pp/commands/`, in a plugin or in a
+`PP_PATH` folder, in any language, is a command too. Your `PATH` is not
+read, so a program named `pp-*` that other software installs takes no
+command's name. To add a command to pp itself, see [CONTRIBUTING.md](https://github.com/xflash96/pp/blob/main/CONTRIBUTING.md).
 
 ## Status
 

{ppkit-0.2.0 → ppkit-0.2.2}/README.md

@@ -39,12 +39,16 @@ pp needs no packages beyond Python itself, and it completes in zsh and bash.
 
 Each command is one Python file. pp looks for them when it runs: its own in
 `pp/commands/`, yours in `~/.config/pp/commands/`, the plugins you added
-with `pp cmd add`, the folders listed in `PP_PATH`, and any program named
-`pp-NAME` on your `PATH`. The first one found wins, so a plugin cannot hide
-a built-in or one of yours. `pp` lists commands without loading them, so
-one broken command cannot break the others.
+with `pp cmd add`, and the folders listed in `PP_PATH`. A program named
+`pp-NAME` in one of those folders, pp's own aside, is a command too. The
+first one found wins, so a plugin cannot hide a built-in or one of yours.
+`pp` lists commands without loading them, so one broken command cannot
+break the others.
 `pp help NAME` prints a command's manual, with examples.
 
+A command answers to its file's name, to a unique prefix of it, and to any
+name you give it with `pp cmd alias`.
+
 Everything pp keeps is in plain files:
 
 ```
@@ -304,12 +308,27 @@ pp cmd rm REPO
 pp cmd ls                                   every command, and where it comes from
 ```
 
+Any command can have a name of your own:
+
+```
+pp cmd alias st promote status              `pp st` is `pp promote status`
+pp cmd alias                                every alias, and what it runs
+pp cmd alias st --rm                        take the name back
+```
+
+The names live in `[alias]` in `~/.config/pp/config.toml`, and this is the
+one place pp writes that file. A name that is a command's own is refused,
+so an alias never hides a command, and `pp help st` and `pp st <TAB>` say
+what `pp promote status` does.
+
 pp clones the plugin into `~/.local/share/pp/plugins/` and checks out the
 commit you said yes to. Only `pp cmd update` moves it, after showing you
 the diff. A plugin's code runs as you, so read it before you say yes.
 
-A program named `pp-NAME` on your `PATH`, in any language, is a command
-too. To add a command to pp itself, see [CONTRIBUTING.md](https://github.com/xflash96/pp/blob/main/CONTRIBUTING.md).
+A program named `pp-NAME` in `~/.config/pp/commands/`, in a plugin or in a
+`PP_PATH` folder, in any language, is a command too. Your `PATH` is not
+read, so a program named `pp-*` that other software installs takes no
+command's name. To add a command to pp itself, see [CONTRIBUTING.md](https://github.com/xflash96/pp/blob/main/CONTRIBUTING.md).
 
 ## Status
 

{ppkit-0.2.0 → ppkit-0.2.2}/pp/__init__.py

@@ -1,4 +1,4 @@
 """pp: a CLI kit for user & agents. One file per subcommand, discovered at runtime."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 TAGLINE = "a CLI kit for user & agents"      # pp -h's header; README and pyproject say it too (tests/test_cli.py)

{ppkit-0.2.0 → ppkit-0.2.2}/pp/cli.py

@@ -6,11 +6,18 @@ A command is found in one of five places, first match wins (so a plugin cannot s
     user       ~/.config/pp/commands/<name>.py  this machine's own, never published
     plugin     ~/.local/share/pp/plugins/<plugin>/[commands/]<name>.py   added by `pp cmd add`, pinned to a commit
     path       <dir>/<name>.py for dir in $PP_PATH (os.pathsep-separated)
-    external   pp-<name> executable on $PATH   any language, git-style
+    external   pp-<name> executable in the user, plugin or $PP_PATH folder   any language, git-style
+
+Every Python command is found before any pp-<name> program, and the programs in the folder order above. $PATH
+is not read: other software installs programs named pp-*, and one of those would take a command's name.
 
 A Python command is a module whose docstring's first line is its summary and which defines main(argv) -> int.
 Listing reads modules with `ast` and never imports them, so a command whose file is absent, unparsable or whose
 imports fail cannot break `pp -h` or any other command. Publishing a subset of pp is deleting files.
+
+A word is resolved in one order: a command's exact name, then `[alias]` in config.toml, then a module's own
+`ALIASES`, then a unique prefix. `[alias]` names any command anything on this machine, and `pp cmd alias`
+writes it.
 """
 from __future__ import annotations
 
@@ -109,6 +116,11 @@ def _py_dirs() -> list[tuple[str, str]]:
     return dirs
 
 
+def _prog_dirs() -> list[str]:
+    """Where a pp-NAME program is a command: pp's own folders, less the one pp keeps its own modules in."""
+    return [d for origin, d in _py_dirs() if origin != "builtin"]
+
+
 def discover() -> dict[str, Command]:
     found: dict[str, Command] = {}
 
@@ -129,9 +141,9 @@ def discover() -> dict[str, Command]:
             path = os.path.join(d, fn)
             summary, aliases, err = _scan(path)
             add(Command(fn[:-3], origin, path, summary, aliases, err))
-    for d in os.environ.get("PATH", "").split(os.pathsep):
+    for d in _prog_dirs():
         try:
-            names = sorted(os.listdir(d or "."))
+            names = sorted(os.listdir(d))
         except OSError:
             continue
         for fn in names:
@@ -166,6 +178,85 @@ def resolve(name: str, cmds: dict[str, Command]) -> Command:
     ui.die(f"no command '{name}'{hint}", 2)
 
 
+# ---- [alias] ----------------------------------------------------------------------------------------------
+# `[alias]` in config.toml gives any command any name on this machine. The table is read where a word is not a
+# command's exact name, and for the listings and the completions below, so dispatching a command pp ships reads
+# no config file at all. One word in, one expansion out: an alias's own first word is resolved without the
+# table, so there is no chain to follow, and an alias can hide no command, since the exact name is read first.
+
+ALIAS_KEY = re.compile(r"[a-z][a-z0-9_-]*")
+
+
+def alias_table(cmds: dict[str, Command]) -> tuple[dict[str, tuple[list[str], str | None]], str | None]:
+    """`[alias]` as {name: (the words it runs, why it is skipped)}, and why config.toml could not be read.
+
+    This raises nothing: `pp -h` prints both as a note, and an entry that cannot work is skipped without
+    touching the entries beside it. The word that needs an alias is where an unreadable file becomes an error.
+    """
+    try:
+        table = config.load("alias")
+    except config.ConfigError as e:
+        return {}, str(e)
+    return {key: _alias_of(key, value, cmds) for key, value in table.items()}, None
+
+
+def _alias_of(key: str, value, cmds: dict[str, Command]) -> tuple[list[str], str | None]:
+    """One entry of `[alias]`: the words it runs, and why pp skips it."""
+    # a campaign line's own splitter: a shell's word rules, no shell, and no expansion of a variable or a `~`
+    from pp.lib import jobpolicy      # imported here: every command imports this module, and only this needs it
+    argv: list[str] = []
+    if isinstance(value, str):
+        try:
+            argv = jobpolicy.words_of(value)[0]
+        except ValueError as e:
+            return argv, str(e)
+    elif isinstance(value, list) and all(isinstance(w, str) for w in value):
+        argv = list(value)
+    else:
+        return argv, "a value is a command line or a list of words"
+    if not ALIAS_KEY.fullmatch(key):
+        return argv, "a name is a letter, then letters, digits, _ and -"
+    if key == "help":
+        return argv, "`pp help CMD` is pp's own"
+    if key in cmds:
+        return argv, f"the name of a {cmds[key].origin} command ({ui.printable(cmds[key].path)})"
+    if not argv:
+        return argv, "it names no command"
+    if not isinstance(find(argv[0], cmds), Command):
+        return argv, f"no command '{ui.printable(argv[0])}'"
+    return argv, None
+
+
+def expand(words: list[str], cmds: dict[str, Command], quiet: bool = False) -> list[str]:
+    """`words` with a leading `[alias]` name replaced once by what it stands for: the alias's own words, then
+    the words typed after it. Anything else comes back as it was.
+
+    A file that cannot be parsed is this word's error, as any bad config file is, unless `quiet`: a completion
+    offers what it can and says nothing.
+    """
+    if not words or words[0] in cmds:
+        return words
+    table, err = alias_table(cmds)
+    if err:
+        if quiet:
+            return words
+        raise config.ConfigError(err)
+    argv, why = table.get(words[0]) or ([], "not an alias")
+    return words if why else argv + words[1:]
+
+
+def alias_names(cmds: dict[str, Command]) -> list[tuple[str, list[str]]]:
+    """Each name `[alias]` gives with the words it runs, the skipped ones left out: what a listing offers."""
+    return sorted((n, argv) for n, (argv, why) in alias_table(cmds)[0].items() if not why)
+
+
+def aliases_of(cmd: Command, named: list[tuple[str, list[str]]]) -> list[str]:
+    """A command's own ALIASES, less a name `[alias]` gives away: the table is read before a module's ALIASES,
+    so that word runs what the table says and the module is not reached by it. A listing offers these."""
+    taken = {n for n, _argv in named}
+    return [a for a in cmd.aliases if a not in taken]
+
+
 def _load(cmd: Command):
     if cmd.origin == "builtin":
         return importlib.import_module(f"pp.commands.{cmd.name}")
@@ -213,7 +304,9 @@ def help_text(cmds: dict[str, Command], show_all: bool = False) -> str:
            ""]
     heads = {"builtin": "commands:", "user": f"user commands ({os.path.join(paths.config_dir(), 'commands')}):",
              "plugin": f"plugins ({paths.data_dir('plugins', create=False)}):", "path": "PP_PATH commands:",
-             "external": "external (pp-* on PATH):"}
+             "external": "external (pp-* in the user, plugin and PP_PATH folders):"}
+    table, unreadable = alias_table(cmds)
+    named = sorted((n, argv) for n, (argv, why) in table.items() if not why)
     for origin in ORIGINS:
         group = sorted((c for c in cmds.values() if c.origin == origin and not c.error), key=lambda c: c.name)
         if not group:
@@ -221,26 +314,37 @@ def help_text(cmds: dict[str, Command], show_all: bool = False) -> str:
         out.append(heads[origin])
         rows = []
         for c in group:
-            label = c.name + (f" ({', '.join(c.aliases)})" if c.aliases else "")
+            own = aliases_of(c, named)
+            label = c.name + (f" ({', '.join(own)})" if own else "")
             extra = f"  [{ui.printable(c.path)}]" if show_all else ""
             if show_all and c.shadows:
                 extra += "  shadows: " + ", ".join(f"{s.origin}:{ui.printable(s.path)}" for s in c.shadows)
             rows.append([ui.printable(label), ui.printable(c.summary) + extra])
         out.append(ui.table(rows, indent="  "))
         out.append("")
+    if named:
+        out.append("aliases (config.toml):")
+        out.append(ui.table([[ui.printable(n), ui.printable(" ".join(argv))] for n, argv in named], indent="  "))
+        out.append("")
     hidden = [s for c in cmds.values() for s in c.shadows if s.origin != "external"]
     if hidden and not show_all:      # a file someone wrote that can never run: say so where they look
         out.append(ui.c("hidden by a same-named command found first (rename to use):", "yellow"))
         out.append(ui.table([[ui.printable(h.name), f"{h.origin}  [{ui.printable(h.path)}]"]
                              for h in sorted(hidden, key=lambda h: h.name)], indent="  "))
         out.append("")
-    broken = sorted((c for c in cmds.values() if c.error), key=lambda c: c.name)
+    cfg = ui.printable(config.global_path())
+    broken = [[ui.printable(c.name), f"{ui.printable(c.error)}  [{ui.printable(c.path)}]"]
+              for c in sorted((c for c in cmds.values() if c.error), key=lambda c: c.name)]
+    broken += [[ui.printable(n), f"{ui.printable(why)}  [{cfg}]"]
+               for n, (argv, why) in sorted(table.items()) if why]
+    if unreadable:
+        broken.append(["[alias]", ui.printable(unreadable)])
     if broken:
         out.append(ui.c("broken (skipped):", "yellow"))
-        out.append(ui.table([[ui.printable(c.name), f"{ui.printable(c.error)}  [{ui.printable(c.path)}]"]
-                             for c in broken], indent="  "))
+        out.append(ui.table(broken, indent="  "))
         out.append("")
     out.append("Unique prefixes work (`pp pro` = `pp promote`). `pp cmd new NAME --user` writes one of your own.")
+    out.append("`pp cmd alias st promote status` makes `pp st` run `pp promote status` ([alias] in config.toml).")
     return "\n".join(out)
 
 
@@ -282,9 +386,11 @@ def _main(argv: list[str]) -> int:
     if not argv or set(argv) <= {"-h", "--help", "--all"}:
         print(help_text(cmds, show_all="--all" in argv))
         return 0
-    if argv[0] == "--commands":      # for shell completion: name<TAB>summary, aliases included
+    if argv[0] == "--commands":      # for shell completion: name<TAB>summary, aliases of both kinds included
+        named = alias_names(cmds)
         _for_a_shell([[n, c.summary] for c in sorted(cmds.values(), key=lambda c: c.name) if not c.error
-                      for n in (c.name, *c.aliases)])
+                      for n in (c.name, *aliases_of(c, named))]
+                     + [[n, " ".join(words)] for n, words in named])
         return 0
     if argv[0] == "--complete":      # for shell completion: candidates for the last of the words after `pp`
         _for_a_shell([[cand] for cand in complete(argv[1:], cmds)])
@@ -299,9 +405,11 @@ def _main(argv: list[str]) -> int:
         if not rest:
             print(help_text(cmds, show_all="--all" in argv))
             return 0
+        rest = expand(rest, cmds)       # `pp help st` is the help of what `st` runs: `pp promote status --help`
         return run(resolve(rest[0], cmds), rest[1:] + ["--help"])     # `pp help queue add` = `pp queue add -h`
     if argv[0].startswith("-"):
         ui.die(f"unknown option {argv[0]}; `pp -h` for usage", 2)
+    argv = expand(argv, cmds)
     return run(resolve(argv[0], cmds), argv[1:])
 
 
@@ -370,11 +478,13 @@ def complete(words: list[str], cmds: dict[str, Command]) -> list[str]:
         before = before[1:]
     if not before:
         names = {n for c in cmds.values() if not c.error for n in (c.name, *c.aliases)}
+        names |= {n for n, _ in alias_names(cmds)}
         if words[:1] != ["help"]:
             names.add("help")
         return sorted(n for n in names if n.startswith(cur))
     if "--" in before:          # past `--`: the rest is someone else's command line
         return []
+    before = expand(before, cmds, quiet=True)       # an alias completes as the words it stands for do
     cmd = find(before[0], cmds)
     if not isinstance(cmd, Command):
         return []