comma-command 0.1.0__py3-none-any.whl

comma_command/__init__.py

@@ -0,0 +1,4 @@
+"""comma-command — run any configured command as ``name, args``."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

comma_command/__main__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

comma_command/cli.py

@@ -0,0 +1,451 @@
+"""The ``comma`` command line.
+
+``comma`` is both the manager (``add``/``rm``/``ls``/``init``/...) and the
+dispatcher: when it is invoked through a ``name,`` shim, ``argv[0]`` tells it
+which registered command to run.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from . import __version__, paths
+from . import config as config_mod
+from .dispatch import dispatch, invoked_name
+
+USAGE = """\
+comma — run any configured command as `name, args`
+
+usage:
+  comma add NAME -- COMMAND [ARG...]   register NAME (creates the `NAME,` shim)
+  comma rm NAME                        unregister NAME
+  comma ls [--json]                    list registered commands
+  comma run NAME [--] [ARG...]         run NAME without going through the shim
+  comma which NAME                     show the shim and what NAME runs
+  comma init [--write] [--shell S]     print or install shell setup (PATH + completion)
+  comma doctor                         check the installation
+  comma completion SHELL               print completion for bash, zsh or fish
+  comma --version | --help
+
+example:
+  comma add gus -- too talk gus --
+  gus, hello world                     # runs: too talk gus -- hello world
+"""
+
+_SHELLS = ("bash", "zsh", "fish", "sh")
+
+
+class CliError(Exception):
+    """A user-facing mistake; printed without a traceback."""
+
+
+# --------------------------------------------------------------------------- helpers
+
+
+def _on_path(directory: Path) -> bool:
+    try:
+        target = directory.resolve()
+    except OSError:  # pragma: no cover - unreadable dir
+        target = directory
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        if not entry:
+            continue
+        try:
+            if Path(entry).expanduser().resolve() == target:
+                return True
+        except OSError:  # pragma: no cover
+            continue
+    return False
+
+
+def _launcher() -> Path:
+    """Absolute path of the ``comma`` executable the shims should point at."""
+    override = os.environ.get("COMMA_SHIM_TARGET")
+    if override:
+        return Path(override).expanduser().absolute()
+    found = shutil.which("comma")
+    if found:
+        return Path(found).absolute()
+    beside_python = Path(sys.executable).parent / "comma"
+    if beside_python.exists():
+        return beside_python.absolute()
+    raise CliError(
+        "cannot find the `comma` executable to link the shim to; "
+        "set COMMA_SHIM_TARGET to its path"
+    )
+
+
+def _is_our_shim(shim: Path) -> bool:
+    if not shim.is_symlink():
+        return False
+    try:
+        return shim.resolve() == _launcher().resolve()
+    except (OSError, CliError):
+        return False
+
+
+def _install_shim(name: str) -> Path:
+    target = _launcher()
+    shim = paths.shim_dir() / f"{name},"
+    paths.shim_dir().mkdir(parents=True, exist_ok=True)
+    if shim.is_symlink() or shim.exists():
+        shim.unlink()
+    shim.symlink_to(target)
+    return shim
+
+
+def _detect_shell() -> str:
+    base = os.path.basename(os.environ.get("SHELL", ""))
+    return base if base in _SHELLS else "bash"
+
+
+def _rc_path(shell: str) -> Path:
+    if shell == "fish":
+        return paths.home() / ".config" / "fish" / "config.fish"
+    if shell == "zsh":
+        return paths.home() / ".zshrc"
+    return paths.home() / ".bashrc"
+
+
+def _init_snippet(shell: str) -> str:
+    shim = paths.shim_dir()
+    if shell == "fish":
+        return (
+            "# comma (managed)\n"
+            f"set -gx PATH {shim} $PATH\n"
+            "comma completion fish | source\n"
+        )
+    completion = "" if shell == "sh" else f'source <(comma completion {shell})\n'
+    return f'# comma (managed)\nexport PATH="{shim}:$PATH"\n{completion}'
+
+
+# --------------------------------------------------------------------------- commands
+
+
+def _add(args: list[str]) -> int:
+    force = False
+    while args and args[0].startswith("-") and args[0] != "--":
+        flag = args.pop(0)
+        if flag in ("-f", "--force"):
+            force = True
+        elif flag in ("-h", "--help"):
+            print("usage: comma add [--force] NAME -- COMMAND [ARG...]")
+            return 0
+        else:
+            raise CliError(f"add: unknown option {flag}")
+
+    if len(args) < 3:
+        raise CliError("add: expected `comma add NAME -- COMMAND [ARG...]`")
+
+    name, tail = args[0], args[1:]
+    if tail[0] != "--":
+        raise CliError(
+            "add: put `--` between the name and the command, "
+            "e.g. `comma add gus -- too talk gus --`"
+        )
+    cmd_argv = tail[1:]
+    if not cmd_argv:
+        raise CliError("add: missing command after `--`")
+
+    config_mod.validate_name(name)
+
+    shim = paths.shim_dir() / f"{name},"
+    if (shim.exists() or shim.is_symlink()) and not force and not _is_our_shim(shim):
+        raise CliError(
+            f"add: {shim} already exists and was not created by comma "
+            "(rerun with --force to replace it)"
+        )
+
+    commands = config_mod.load(paths.config_path())
+    commands[name] = config_mod.Command(name=name, argv=tuple(cmd_argv))
+    config_mod.save(paths.config_path(), commands)
+    _install_shim(name)
+
+    print(f"added {name}, → {commands[name].display()}")
+    if not _on_path(paths.shim_dir()):
+        print(f"note: {paths.shim_dir()} is not on PATH — run `comma init --write`")
+    return 0
+
+
+def _rm(args: list[str]) -> int:
+    if not args:
+        raise CliError("rm: expected `comma rm NAME`")
+    name = args[0]
+    commands = config_mod.load(paths.config_path())
+    if name not in commands:
+        raise CliError(f"rm: no command named {name!r}")
+
+    removed = commands.pop(name)
+    config_mod.save(paths.config_path(), commands)
+
+    shim = paths.shim_dir() / f"{name},"
+    if shim.is_symlink() or shim.exists():
+        shim.unlink()
+
+    print(f"removed {name}, (was {removed.display()})")
+    return 0
+
+
+def _ls(args: list[str]) -> int:
+    commands = config_mod.load(paths.config_path())
+
+    if "--json" in args:
+        payload = {
+            name: {"cmd": list(cmd.argv), "shim": str(paths.shim_dir() / f"{name},")}
+            for name, cmd in sorted(commands.items())
+        }
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0
+
+    if not commands:
+        print("no commands registered yet — try: comma add gus -- too talk gus --")
+        return 0
+
+    width = max(len(name) for name in commands) + 1
+    for name in sorted(commands):
+        print(f"{name + ',':<{width}}  {commands[name].display()}")
+    return 0
+
+
+def _names(args: list[str]) -> int:
+    """Hidden helper for shell completion."""
+    for name in sorted(config_mod.load(paths.config_path())):
+        print(name)
+    return 0
+
+
+def _run(args: list[str]) -> int:
+    if not args:
+        raise CliError("run: expected `comma run NAME [--] [ARG...]`")
+    name, rest = args[0], args[1:]
+    if rest and rest[0] == "--":
+        rest = rest[1:]
+    return dispatch(name, rest)
+
+
+def _which(args: list[str]) -> int:
+    if not args:
+        raise CliError("which: expected `comma which NAME`")
+    name = args[0]
+    commands = config_mod.load(paths.config_path())
+    command = commands.get(name)
+    shim = paths.shim_dir() / f"{name},"
+
+    if command is None and not shim.exists():
+        print(f"{name}: not registered", file=sys.stderr)
+        return 1
+
+    print(f"name:  {name},")
+    print(f"shim:  {shim}" + ("" if shim.exists() else "  (missing)"))
+    print(
+        "path:  "
+        + ("on PATH" if _on_path(paths.shim_dir()) else "NOT on PATH — run `comma init --write`")
+    )
+    if command is not None:
+        print(f"runs:  {command.display()}")
+    return 0
+
+
+def _init(args: list[str]) -> int:
+    shell = _detect_shell()
+    write = False
+    index = 0
+    while index < len(args):
+        option = args[index]
+        if option == "--write":
+            write = True
+            index += 1
+        elif option == "--shell":
+            index += 1
+            if index >= len(args):
+                raise CliError("init: --shell needs a value")
+            shell = args[index]
+            index += 1
+        elif option in ("-h", "--help"):
+            print("usage: comma init [--write] [--shell bash|zsh|fish]")
+            return 0
+        else:
+            raise CliError(f"init: unknown option {option}")
+
+    if shell not in _SHELLS:
+        raise CliError(f"init: unsupported shell {shell!r} (bash, zsh, fish)")
+
+    snippet = _init_snippet(shell)
+    if not write:
+        print(snippet, end="")
+        return 0
+
+    rc = _rc_path(shell)
+    rc.parent.mkdir(parents=True, exist_ok=True)
+    existing = rc.read_text(encoding="utf-8") if rc.exists() else ""
+    if "# comma (managed)" in existing:
+        print(f"already configured in {rc}")
+        return 0
+
+    with rc.open("a", encoding="utf-8") as handle:
+        if existing and not existing.endswith("\n"):
+            handle.write("\n")
+        handle.write(snippet)
+    print(f"updated {rc} — open a new shell (or `source {rc}`)")
+    return 0
+
+
+def _doctor(args: list[str]) -> int:
+    config = paths.config_path()
+    shims = paths.shim_dir()
+    print(f"comma {__version__} (comma-command)")
+    print(f"config: {config}")
+    print(f"shims:  {shims}")
+
+    try:
+        commands = config_mod.load(config)
+    except config_mod.ConfigError as exc:
+        print(f"FAIL  config: {exc}")
+        return 1
+
+    count = len(commands)
+    print(f"ok    config parsed ({count} command{'s' if count != 1 else ''})")
+
+    problems = 0
+    if _on_path(shims):
+        print("ok    shim directory is on PATH")
+    else:
+        print("warn  shim directory is not on PATH — run `comma init --write`")
+
+    shell = _detect_shell()
+    rc = _rc_path(shell)
+    configured = rc.exists() and "# comma (managed)" in rc.read_text(
+        encoding="utf-8", errors="replace"
+    )
+    if configured:
+        print(f"ok    shell setup present in {rc}")
+    else:
+        print(f"warn  no shell setup in {rc} — run `comma init --write`")
+
+    for name in sorted(commands):
+        command = commands[name]
+        shim = shims / f"{name},"
+        issues = []
+        if not shim.exists():
+            issues.append("shim missing — re-run `comma add`")
+        elif not os.access(shim, os.X_OK):
+            issues.append("shim is not executable")
+        if shutil.which(command.argv[0]) is None:
+            issues.append(f"target {command.argv[0]!r} is not on PATH")
+        if issues:
+            print(f"FAIL  {name},: " + "; ".join(issues))
+            problems += 1
+        else:
+            print(f"ok    {name}, → {command.display()}")
+
+    return 1 if problems else 0
+
+
+_BASH_COMPLETION = """\
+# bash completion for comma
+_comma_complete() {
+    local cur prev
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    if [ "$COMP_CWORD" -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "add rm ls run which init doctor completion help" -- "$cur") )
+        return
+    fi
+    case "$prev" in
+        rm|run|which) COMPREPLY=( $(compgen -W "$(comma _names)" -- "$cur") ) ;;
+        completion)   COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") ) ;;
+    esac
+}
+complete -F _comma_complete comma
+# `name,` shims need no completion: they are real files on PATH, so the shell
+# completes them like any other executable.
+"""
+
+_ZSH_COMPLETION = """\
+#compdef comma
+_comma() {
+    local -a subcommands names
+    subcommands=(add rm ls run which init doctor completion help)
+    if (( CURRENT == 2 )); then
+        _describe 'command' subcommands
+        return
+    fi
+    case "${words[2]}" in
+        rm|run|which) names=(${(f)"$(comma _names)"}); _describe 'name' names ;;
+        completion)   _values 'shell' bash zsh fish ;;
+    esac
+}
+compdef _comma comma
+"""
+
+_FISH_COMPLETION = """\
+complete -c comma -f
+complete -c comma -n '__fish_use_subcommand' -a 'add rm ls run which init doctor completion help'
+complete -c comma -n '__fish_seen_subcommand_from rm run which' -a '(comma _names)'
+complete -c comma -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'
+"""
+
+
+def _completion(args: list[str]) -> int:
+    shell = args[0] if args else _detect_shell()
+    scripts = {
+        "bash": _BASH_COMPLETION,
+        "zsh": _ZSH_COMPLETION,
+        "fish": _FISH_COMPLETION,
+    }
+    script = scripts.get(shell)
+    if script is None:
+        raise CliError(f"completion: unsupported shell {shell!r} (bash, zsh, fish)")
+    print(script, end="")
+    return 0
+
+
+_HANDLERS = {
+    "add": _add,
+    "rm": _rm,
+    "ls": _ls,
+    "list": _ls,
+    "run": _run,
+    "which": _which,
+    "init": _init,
+    "doctor": _doctor,
+    "completion": _completion,
+    "_names": _names,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv if argv is None else argv)
+    prog = argv[0] if argv else "comma"
+    args = argv[1:]
+
+    # Reached through a `name,` shim: we are the dispatcher, not the manager.
+    name = invoked_name(prog)
+    if name is not None:
+        return dispatch(name, args)
+
+    if not args or args[0] in ("-h", "--help", "help"):
+        sys.stdout.write(USAGE)
+        return 0
+    if args[0] in ("-V", "--version", "version"):
+        print(f"comma {__version__} (comma-command)")
+        return 0
+
+    handler = _HANDLERS.get(args[0])
+    if handler is None:
+        print(f"comma: unknown command {args[0]!r}\n", file=sys.stderr)
+        sys.stderr.write(USAGE)
+        return 2
+
+    try:
+        return handler(args[1:])
+    except CliError as exc:
+        print(f"comma: {exc}", file=sys.stderr)
+        return 2
+    except config_mod.ConfigError as exc:
+        print(f"comma: {exc}", file=sys.stderr)
+        return 1

comma_command/config.py

@@ -0,0 +1,130 @@
+"""Reading and writing ``config.toml``.
+
+Two ways to declare a command, both equivalent::
+
+    [commands.gus]
+    cmd = ["too", "talk", "gus", "--"]
+
+    [commands]
+    gus = "too talk gus --"
+
+The list form is the canonical one: it survives arguments containing spaces
+without quoting games.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - 3.10 only
+    import tomli as tomllib  # type: ignore[no-redef]
+
+#: Names become ``<name>,`` file names, so keep them boring: no slashes, no
+#: leading dash (looks like a flag), no trailing comma (ambiguous on dispatch).
+_NAME_RE = re.compile(r"^[A-Za-z0-9_+][A-Za-z0-9._+-]*$")
+_BARE_KEY_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+class ConfigError(Exception):
+    """Raised when the config file exists but cannot be understood."""
+
+
+@dataclass(frozen=True)
+class Command:
+    """One registered name."""
+
+    name: str
+    argv: tuple[str, ...]
+
+    def display(self) -> str:
+        return " ".join(shlex.quote(part) for part in self.argv)
+
+
+def validate_name(name: str) -> str:
+    if not name:
+        raise ConfigError("name cannot be empty")
+    if name.endswith(","):
+        raise ConfigError(f"invalid name {name!r}: the comma is added for you")
+    if name.startswith("-"):
+        raise ConfigError(f"invalid name {name!r}: must not start with '-'")
+    if name in (".", ".."):
+        raise ConfigError(f"invalid name {name!r}")
+    if not _NAME_RE.match(name):
+        raise ConfigError(
+            f"invalid name {name!r}: use letters, digits, '.', '_', '+', '-'"
+        )
+    return name
+
+
+def _coerce(name: str, value: object) -> tuple[str, ...]:
+    if isinstance(value, str):
+        argv = shlex.split(value)
+    elif isinstance(value, dict):
+        key = "cmd" if "cmd" in value else "command" if "command" in value else None
+        if key is None:
+            raise ConfigError(f"[commands.{name}] needs a 'cmd' key")
+        raw = value[key]
+        if isinstance(raw, str):
+            argv = shlex.split(raw)
+        elif isinstance(raw, list) and all(isinstance(part, str) for part in raw):
+            argv = list(raw)
+        else:
+            raise ConfigError(f"[commands.{name}].cmd must be a string or a list of strings")
+    else:
+        raise ConfigError(
+            f"[commands.{name}] must be a string or a table with a 'cmd' key"
+        )
+    if not argv:
+        raise ConfigError(f"command {name!r} is empty")
+    return tuple(argv)
+
+
+def load(path: Path) -> dict[str, Command]:
+    """Parse ``path``. A missing file is an empty config, not an error."""
+    if not path.exists():
+        return {}
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise ConfigError(f"{path}: invalid TOML: {exc}") from exc
+
+    table = raw.get("commands", {})
+    if not isinstance(table, dict):
+        raise ConfigError(f"{path}: 'commands' must be a table")
+
+    commands: dict[str, Command] = {}
+    for name, value in table.items():
+        validate_name(name)
+        commands[name] = Command(name=name, argv=_coerce(name, value))
+    return commands
+
+
+def _toml_key(name: str) -> str:
+    return name if _BARE_KEY_RE.match(name) else json.dumps(name)
+
+
+def _toml_string(text: str) -> str:
+    # JSON string escapes are a subset of TOML basic-string escapes.
+    return json.dumps(text, ensure_ascii=False)
+
+
+def save(path: Path, commands: dict[str, Command]) -> None:
+    lines = [
+        "# comma config — manage it with `comma add NAME -- COMMAND...`",
+        "# docs: https://github.com/by3hak/comma-command",
+        "",
+    ]
+    for name in sorted(commands):
+        command = commands[name]
+        rendered = ", ".join(_toml_string(part) for part in command.argv)
+        lines.append(f"[commands.{_toml_key(name)}]")
+        lines.append(f"cmd = [{rendered}]")
+        lines.append("")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines), encoding="utf-8")

comma_command/dispatch.py

@@ -0,0 +1,50 @@
+"""Turning ``name, args...`` into the configured command.
+
+Dispatch ends in :func:`os.execvpe`: the process is replaced, so the child
+inherits the terminal, the foreground process group, stdin, and its exit
+status reaches the shell untouched. No wrapper process, no signal proxying.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from . import config as config_mod
+from . import paths
+
+
+def invoked_name(prog: str) -> str | None:
+    """Return the registered name if ``prog`` is a ``name,`` shim."""
+    base = os.path.basename(prog)
+    if len(base) > 1 and base.endswith(","):
+        return base[:-1]
+    return None
+
+
+def dispatch(name: str, args: list[str]) -> int:
+    """Replace this process with the command registered under ``name``."""
+    try:
+        commands = config_mod.load(paths.config_path())
+    except config_mod.ConfigError as exc:
+        print(f"comma: {exc}", file=sys.stderr)
+        return 1
+
+    command = commands.get(name)
+    if command is None:
+        print(f"comma: no command named {name!r}.", file=sys.stderr)
+        known = ", ".join(sorted(commands)) or "(none yet)"
+        print(f"  registered: {known}", file=sys.stderr)
+        print(f"  add one:    comma add {name} -- your-command --", file=sys.stderr)
+        return 127
+
+    argv = [*command.argv, *args]
+    try:
+        os.execvpe(argv[0], argv, os.environ)
+    except FileNotFoundError:
+        print(f"comma: command not found: {argv[0]!r} (registered as {name!r})", file=sys.stderr)
+        return 127
+    except PermissionError:
+        print(f"comma: permission denied: {argv[0]!r} (registered as {name!r})", file=sys.stderr)
+        return 126
+    return 126  # pragma: no cover - execvpe either replaces us or raises

comma_command/paths.py

@@ -0,0 +1,37 @@
+"""XDG-ish locations used by comma-command.
+
+Everything is resolved at call time so tests can point ``HOME``,
+``XDG_CONFIG_HOME`` and ``XDG_DATA_HOME`` at throwaway directories.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def home() -> Path:
+    raw = os.environ.get("HOME")
+    return Path(raw) if raw else Path.home()
+
+
+def _xdg(var: str, fallback: Path) -> Path:
+    raw = os.environ.get(var)
+    return Path(raw).expanduser() if raw else fallback
+
+
+def config_dir() -> Path:
+    return _xdg("XDG_CONFIG_HOME", home() / ".config") / "comma"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.toml"
+
+
+def data_dir() -> Path:
+    return _xdg("XDG_DATA_HOME", home() / ".local" / "share") / "comma"
+
+
+def shim_dir() -> Path:
+    """Directory holding the executable ``name,`` shims."""
+    return data_dir() / "bin"

comma_command-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: comma-command
+Version: 0.1.0
+Summary: Run any configured command from any shell as `name, args` — register once, invoke everywhere.
+Project-URL: Homepage, https://github.com/by3hak/comma-command
+Project-URL: Repository, https://github.com/by3hak/comma-command
+Project-URL: Issues, https://github.com/by3hak/comma-command/issues
+Author-email: hak <by3hak@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: alias,cli,dispatch,multicall,shell,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# comma-command
+
+Run any command you have installed from any shell, as if it were a shell builtin:
+
+```console
+$ gus, hello world
+# → too talk gus -- hello world
+```
+
+Register an entry once. From then on, `NAME, any words` is the whole interface — no
+aliases to source, no shell hook, no TUI.
+
+## Install
+
+```console
+$ uv tool install comma-command    # or: pipx install comma-command
+$ comma init --write               # puts the shim directory on PATH
+$ exec $SHELL                      # or open a new terminal
+```
+
+## Quickstart
+
+```console
+$ comma add gus -- too talk gus --
+added gus, → too talk gus --
+
+$ comma add pyi -- uv run ipython --
+added pyi, → uv run ipython --
+
+$ gus, hello world          # runs: too talk gus -- hello world
+$ pyi, --pdb script.py      # runs: uv run ipython -- --pdb script.py
+$ comma ls
+gus,  too talk gus --
+pyi,  uv run ipython --
+```
+
+`comma add` does two things: writes the entry to `~/.config/comma/config.toml` and
+creates an executable named exactly `gus,` in `~/.local/share/comma/bin`.
+
+## How it works
+
+The shim is a multicall dispatcher — the same trick `busybox` and `git` use for
+subcommands, applied to names:
+
+1. `gus,` is a symlink to the `comma` executable.
+2. `comma` looks at `argv[0]`, sees a trailing comma, strips it, and finds `gus` in
+   the config.
+3. It calls `os.execvpe("too", ["too", "talk", "gus", "--", "hello", "world"])`.
+
+Because the final step *replaces* the process instead of spawning a child, the
+target command inherits the terminal, stdin, signals and job control directly, and
+its exit status reaches your shell unchanged. `comma,` adds no wrapping layer.
+
+Why not the alternatives:
+
+- **Shell aliases/functions.** `gus,` is not a portable function name in bash or
+  fish, and functions only exist in interactive shells you have sourced.
+- **`command_not_found_handle` hooks.** Bash-only, collides with distro handlers
+  (Nix, Debian's package suggestion hook), and silently does nothing in
+  non-interactive shells, `sh -c`, cron, or most editors' task runners.
+- **Shims on `PATH`.** Work everywhere a real executable works, including
+  `xargs`, `find -exec`, CI scripts, Makefiles and shell completion.
+
+## Configuration
+
+`~/.config/comma/config.toml` — managed by `comma`, but hand-editable:
+
+```toml
+[commands.gus]
+cmd = ["too", "talk", "gus", "--"]
+
+# shorthand is fine too
+[commands.pyi]
+cmd = "uv run ipython --"
+```
+
+Arguments are appended verbatim, so `--` at the end of `cmd` is the usual way to
+keep flags from being swallowed by the target's own option parser.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `comma add NAME -- CMD...` | register a name and create its `NAME,` shim |
+| `comma rm NAME` | unregister a name and remove its shim |
+| `comma ls [--json]` | list registered names |
+| `comma run NAME [--] [ARG...]` | run a name without going through the shim |
+| `comma which NAME` | show the shim path and the command it runs |
+| `comma init [--write] [--shell S]` | print or install PATH + completion setup |
+| `comma doctor` | check config, PATH, shims and targets |
+| `comma completion bash\|zsh\|fish` | print a completion script |
+
+Names must be shell-safe words: letters, digits, `.`, `_`, `+`, `-`. The comma is
+added for you, so `comma add gus, -- ...` is rejected rather than silently creating
+`gus,,`.
+
+## Limits
+
+- POSIX first. Windows needs a `.cmd` shim layer, which is not in 0.1.
+- No per-command `env`/`cwd` yet; use `cmd = ["sh", "-c", "..."]` as an escape hatch.
+- The `comma-command` crate on crates.io is a name reservation for a future native
+  binary; the Python implementation is the one to install today.
+
+## Development
+
+```console
+$ uv venv && uv pip install -e '.[dev]'
+$ uv run pytest
+$ uv run ruff check .
+```
+
+MIT licensed.

comma_command-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+comma_command/__init__.py,sha256=KNA9OATXcemoKZw6_ryyQB8Gptqm6we_QlJnzeUwY4s,119
+comma_command/__main__.py,sha256=40c3JGxDOKeEEdfKw5o6A8E_rhK9fFv8AYlmd-ngtcI,119
+comma_command/cli.py,sha256=g8cUY21MqGqyBH85-5qGUoSGemkxCwy5UqbspXG32oY,13697
+comma_command/config.py,sha256=vj2IfMIKzkUrLMqip8IcAegF4Cgt-_OsYbg1c5bXRLo,4151
+comma_command/dispatch.py,sha256=wN5lAjPU5OOLw5xb7QIMZ66w-cK9_tfmqAUMs5H1roU,1738
+comma_command/paths.py,sha256=r7My124OkSgXIlKF91W1T02471SN08HATz-_L1JBius,861
+comma_command-0.1.0.dist-info/METADATA,sha256=1GXxuglh-Wl9kh9O6JGgoaUeio2sVQmux0bCLjxUfd8,5087
+comma_command-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+comma_command-0.1.0.dist-info/entry_points.txt,sha256=6aUEhMA1wmcTYDSrvLk9Yc-6MK3P6jqxp2uX0FqZkaI,49
+comma_command-0.1.0.dist-info/licenses/LICENSE,sha256=v-zUf9Iol9k8xzf6xuzL8cupU5NxU_Rd6uEn5Gcg__A,1060
+comma_command-0.1.0.dist-info/RECORD,,

comma_command-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

comma_command-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+comma = comma_command.cli:main

comma_command-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.