comma-command 0.1.0__tar.gz → 0.2.0__tar.gz

{comma_command-0.1.0 → comma_command-0.2.0}/.gitignore

@@ -10,3 +10,6 @@ dist/
 .uv/
 *.swp
 .DS_Store
+
+# Rust build output
+target/

{comma_command-0.1.0 → comma_command-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comma-command
-Version: 0.1.0
+Version: 0.2.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
@@ -78,6 +78,11 @@ subcommands, applied to names:
    the config.
 3. It calls `os.execvpe("too", ["too", "talk", "gus", "--", "hello", "world"])`.
 
+If the shim directory is not on `PATH` — a CI job, a container, a repo where nobody
+ran `comma init` — `comma gus, hello world` reaches the same dispatch path. `comma`
+takes `NAME,` rather than bare `NAME` so that a registered name can never collide
+with the management subcommands (`ls`, `run`, `doctor`, ...).
+
 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.
@@ -105,17 +110,38 @@ cmd = ["too", "talk", "gus", "--"]
 cmd = "uv run ipython --"
 ```
 
+This `[commands.<name>]` table is the canonical schema: per-command options such as
+`env` and `cwd` will live in it. The `name = "..."` shorthand is accepted as input
+sugar and is shown here only so you can read someone else's config.
+
 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.
 
+Per-command settings live in the same table:
+
+```toml
+[commands.deploy]
+cmd = ["kubectl", "apply", "-f", "k8s/"]
+cwd = "~/src/infra"
+env = { KUBECONFIG = "~/.kube/staging" }
+env_unset = ["HTTP_PROXY"]
+```
+
+`env` is **merged into** the inherited environment, so `PATH` and `HOME` keep working,
+and `env_unset` drops inherited variables first — a name may not appear in both.
+`cwd` is `~`-expanded and applied before the target runs. The same options exist on
+the command line: `comma add --env K=V --unset K --cwd DIR NAME -- CMD...`.
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `comma add NAME -- CMD...` | register a name and create its `NAME,` shim |
+| `comma add [--env K=V] [--unset K] [--cwd DIR] NAME -- CMD...` | register a name and create its `NAME,` shim |
+| `comma edit` | open the config in `$EDITOR`, re-validate it, reconcile the shims |
 | `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 NAME, [ARG...]` | the shell spelling, without the shim on PATH (handy in CI) |
 | `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 |
@@ -125,10 +151,27 @@ Names must be shell-safe words: letters, digits, `.`, `_`, `+`, `-`. The comma i
 added for you, so `comma add gus, -- ...` is rejected rather than silently creating
 `gus,,`.
 
+## Design decisions
+
+Recorded so they do not get relitigated every release:
+
+- **No `command_not_found_handle` fallback.** The hook only fires when a PATH lookup
+  fails, so it cannot resolve a name whose `NAME,` file already exists; it is also
+  bash-only and fights the distro's own hook. `comma add` instead refuses to
+  overwrite a foreign `NAME,` unless you pass `--force`, and CI/scripts use
+  `comma NAME, ...`.
+- **`[commands.<name>]` is canonical.** Per-command options (`env`, `cwd`, ...)
+  live in that sub-table. The `name = "..."` shorthand stays as input sugar and
+  is not documented twice.
+- **No argument completion for target commands.** Command-position completion is
+  free because the shims are real files on `PATH`, and `comma`'s own subcommands
+  have completion. Completing a target's *arguments* would need a completion
+  protocol per target — out of scope for 0.1, and better designed once someone
+  actually needs it.
+
 ## 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.
+- POSIX first. Windows would need a `.cmd` shim layer, which is not implemented yet.
 - 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.
 

{comma_command-0.1.0 → comma_command-0.2.0}/README.md

@@ -47,6 +47,11 @@ subcommands, applied to names:
    the config.
 3. It calls `os.execvpe("too", ["too", "talk", "gus", "--", "hello", "world"])`.
 
+If the shim directory is not on `PATH` — a CI job, a container, a repo where nobody
+ran `comma init` — `comma gus, hello world` reaches the same dispatch path. `comma`
+takes `NAME,` rather than bare `NAME` so that a registered name can never collide
+with the management subcommands (`ls`, `run`, `doctor`, ...).
+
 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.
@@ -74,17 +79,38 @@ cmd = ["too", "talk", "gus", "--"]
 cmd = "uv run ipython --"
 ```
 
+This `[commands.<name>]` table is the canonical schema: per-command options such as
+`env` and `cwd` will live in it. The `name = "..."` shorthand is accepted as input
+sugar and is shown here only so you can read someone else's config.
+
 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.
 
+Per-command settings live in the same table:
+
+```toml
+[commands.deploy]
+cmd = ["kubectl", "apply", "-f", "k8s/"]
+cwd = "~/src/infra"
+env = { KUBECONFIG = "~/.kube/staging" }
+env_unset = ["HTTP_PROXY"]
+```
+
+`env` is **merged into** the inherited environment, so `PATH` and `HOME` keep working,
+and `env_unset` drops inherited variables first — a name may not appear in both.
+`cwd` is `~`-expanded and applied before the target runs. The same options exist on
+the command line: `comma add --env K=V --unset K --cwd DIR NAME -- CMD...`.
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `comma add NAME -- CMD...` | register a name and create its `NAME,` shim |
+| `comma add [--env K=V] [--unset K] [--cwd DIR] NAME -- CMD...` | register a name and create its `NAME,` shim |
+| `comma edit` | open the config in `$EDITOR`, re-validate it, reconcile the shims |
 | `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 NAME, [ARG...]` | the shell spelling, without the shim on PATH (handy in CI) |
 | `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 |
@@ -94,10 +120,27 @@ Names must be shell-safe words: letters, digits, `.`, `_`, `+`, `-`. The comma i
 added for you, so `comma add gus, -- ...` is rejected rather than silently creating
 `gus,,`.
 
+## Design decisions
+
+Recorded so they do not get relitigated every release:
+
+- **No `command_not_found_handle` fallback.** The hook only fires when a PATH lookup
+  fails, so it cannot resolve a name whose `NAME,` file already exists; it is also
+  bash-only and fights the distro's own hook. `comma add` instead refuses to
+  overwrite a foreign `NAME,` unless you pass `--force`, and CI/scripts use
+  `comma NAME, ...`.
+- **`[commands.<name>]` is canonical.** Per-command options (`env`, `cwd`, ...)
+  live in that sub-table. The `name = "..."` shorthand stays as input sugar and
+  is not documented twice.
+- **No argument completion for target commands.** Command-position completion is
+  free because the shims are real files on `PATH`, and `comma`'s own subcommands
+  have completion. Completing a target's *arguments* would need a completion
+  protocol per target — out of scope for 0.1, and better designed once someone
+  actually needs it.
+
 ## 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.
+- POSIX first. Windows would need a `.cmd` shim layer, which is not implemented yet.
 - 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.
 

comma_command-0.2.0/crates/comma-command/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "comma-command"
+version = "0.0.1"

comma_command-0.2.0/crates/comma-command/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "comma-command"
+version = "0.0.1"
+edition = "2021"
+description = "Name reservation for the comma-command CLI; the native Rust implementation is not available yet."
+readme = "README.md"
+license = "MIT"
+repository = "https://github.com/by3hak/comma-command"
+keywords = ["cli", "shell", "dispatch"]
+
+[lib]
+path = "src/lib.rs"

comma_command-0.2.0/crates/comma-command/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.

comma_command-0.2.0/crates/comma-command/README.md

@@ -0,0 +1,11 @@
+# comma-command (Rust crate placeholder)
+
+This crate reserves the `comma-command` name on crates.io for the
+[comma-command project](https://github.com/by3hak/comma-command).
+
+The usable implementation is currently the Python CLI (`pip install comma-command`).
+This Rust crate contains no command-line binary or supported API yet; do not add it
+as a dependency expecting functionality. A native Rust implementation may be
+published in a future version.
+
+This placeholder is MIT licensed, matching the project repository.

comma_command-0.2.0/crates/comma-command/src/lib.rs

@@ -0,0 +1,6 @@
+//! Name-reservation placeholder for the `comma-command` project.
+//!
+//! The supported implementation is currently the Python CLI. This crate does not
+//! expose a usable API or binary; a native Rust implementation may be added later.
+
+#![forbid(unsafe_code)]

{comma_command-0.1.0 → comma_command-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "comma-command"
-version = "0.1.0"
+version = "0.2.0"
 description = "Run any configured command from any shell as `name, args` — register once, invoke everywhere."
 readme = "README.md"
 license = { text = "MIT" }

{comma_command-0.1.0 → comma_command-0.2.0}/src/comma_command/__init__.py

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

{comma_command-0.1.0 → comma_command-0.2.0}/src/comma_command/cli.py

@@ -9,7 +9,9 @@ from __future__ import annotations
 
 import json
 import os
+import shlex
 import shutil
+import subprocess
 import sys
 from pathlib import Path
 
@@ -21,10 +23,13 @@ USAGE = """\
 comma — run any configured command as `name, args`
 
 usage:
-  comma add NAME -- COMMAND [ARG...]   register NAME (creates the `NAME,` shim)
+  comma add [--env K=V]... [--unset K]... [--cwd DIR] [--force] NAME -- COMMAND...
+                                       register NAME (creates the `NAME,` shim)
+  comma edit                           open the config in $EDITOR, then re-validate
   comma rm NAME                        unregister NAME
   comma ls [--json]                    list registered commands
   comma run NAME [--] [ARG...]         run NAME without going through the shim
+  comma NAME, [ARG...]                 same as `NAME,`, for shells without the shim on PATH
   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
@@ -128,12 +133,35 @@ def _init_snippet(shell: str) -> str:
 
 def _add(args: list[str]) -> int:
     force = False
+    env: dict[str, str] = {}
+    env_unset: list[str] = []
+    cwd: str | None = None
+
     while args and args[0].startswith("-") and args[0] != "--":
         flag = args.pop(0)
         if flag in ("-f", "--force"):
             force = True
+        elif flag in ("-e", "--env"):
+            if not args:
+                raise CliError("add: --env needs KEY=VALUE")
+            pair = args.pop(0)
+            key, sep, value = pair.partition("=")
+            if not sep or not key:
+                raise CliError(f"add: --env expects KEY=VALUE, got {pair!r}")
+            env[key] = value
+        elif flag in ("-u", "--unset"):
+            if not args:
+                raise CliError("add: --unset needs a variable name")
+            env_unset.append(args.pop(0))
+        elif flag == "--cwd":
+            if not args:
+                raise CliError("add: --cwd needs a directory")
+            cwd = args.pop(0)
         elif flag in ("-h", "--help"):
-            print("usage: comma add [--force] NAME -- COMMAND [ARG...]")
+            print(
+                "usage: comma add [--force] [--env KEY=VALUE]... [--unset KEY]... "
+                "[--cwd DIR] NAME -- COMMAND [ARG...]"
+            )
             return 0
         else:
             raise CliError(f"add: unknown option {flag}")
@@ -161,7 +189,13 @@ def _add(args: list[str]) -> int:
         )
 
     commands = config_mod.load(paths.config_path())
-    commands[name] = config_mod.Command(name=name, argv=tuple(cmd_argv))
+    commands[name] = config_mod.Command(
+        name=name,
+        argv=tuple(cmd_argv),
+        cwd=cwd,
+        env=env,
+        env_unset=tuple(env_unset),
+    )
     config_mod.save(paths.config_path(), commands)
     _install_shim(name)
 
@@ -194,10 +228,16 @@ 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())
-        }
+        payload = {}
+        for name, cmd in sorted(commands.items()):
+            entry = {"cmd": list(cmd.argv), "shim": str(paths.shim_dir() / f"{name},")}
+            if cmd.cwd:
+                entry["cwd"] = cmd.cwd
+            if cmd.env:
+                entry["env"] = dict(cmd.env)
+            if cmd.env_unset:
+                entry["env_unset"] = list(cmd.env_unset)
+            payload[name] = entry
         print(json.dumps(payload, indent=2, ensure_ascii=False))
         return 0
 
@@ -207,7 +247,11 @@ def _ls(args: list[str]) -> int:
 
     width = max(len(name) for name in commands) + 1
     for name in sorted(commands):
-        print(f"{name + ',':<{width}}  {commands[name].display()}")
+        line = f"{name + ',':<{width}}  {commands[name].display()}"
+        modifiers = commands[name].modifiers()
+        if modifiers:
+            line += "  [" + " ".join(modifiers) + "]"
+        print(line)
     return 0
 
 
@@ -336,6 +380,8 @@ def _doctor(args: list[str]) -> int:
             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 command.cwd and not Path(os.path.expanduser(command.cwd)).is_dir():
+            issues.append(f"cwd {command.cwd!r} is not a directory")
         if issues:
             print(f"FAIL  {name},: " + "; ".join(issues))
             problems += 1
@@ -404,6 +450,55 @@ def _completion(args: list[str]) -> int:
     return 0
 
 
+def _reconcile(commands: dict[str, config_mod.Command]) -> None:
+    """Make the shim directory match the config (used after `comma edit`)."""
+    paths.shim_dir().mkdir(parents=True, exist_ok=True)
+    for name in commands:
+        _install_shim(name)
+    for shim in paths.shim_dir().iterdir():
+        if not shim.name.endswith(",") or shim.name[:-1] in commands:
+            continue
+        try:
+            ours = _is_our_shim(shim)
+        except (OSError, CliError):
+            ours = False
+        if ours:
+            shim.unlink()
+
+
+def _edit(args: list[str]) -> int:
+    if args and args[0] in ("-h", "--help"):
+        print("usage: comma edit — opens the config in $VISUAL/$EDITOR, then re-validates")
+        return 0
+    if args:
+        raise CliError("edit: takes no arguments; it opens the whole config file")
+
+    path = paths.config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        config_mod.save(path, {})
+
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR") or "vi"
+    try:
+        result = subprocess.run([*shlex.split(editor), str(path)])
+    except OSError as exc:
+        raise CliError(f"edit: cannot run editor {editor!r}: {exc}") from exc
+    if result.returncode != 0:
+        return result.returncode
+
+    try:
+        commands = config_mod.load(path)
+    except config_mod.ConfigError as exc:
+        print(f"comma: {exc}", file=sys.stderr)
+        print(f"comma: fix {path} and run `comma edit` again", file=sys.stderr)
+        return 1
+
+    _reconcile(commands)
+    count = len(commands)
+    print(f"{path}: {count} command{'s' if count != 1 else ''}, shims up to date")
+    return 0
+
+
 _HANDLERS = {
     "add": _add,
     "rm": _rm,
@@ -414,6 +509,7 @@ _HANDLERS = {
     "init": _init,
     "doctor": _doctor,
     "completion": _completion,
+    "edit": _edit,
     "_names": _names,
 }
 
@@ -428,6 +524,12 @@ def main(argv: list[str] | None = None) -> int:
     if name is not None:
         return dispatch(name, args)
 
+    # `comma NAME, args...` — the same spelling as the shell form, for machines
+    # where the shim directory is not on PATH. Not `comma NAME args`: that would
+    # collide with the management subcommands (an alias called `ls` or `run`).
+    if args and len(args[0]) > 1 and args[0].endswith(","):
+        return dispatch(args[0][:-1], args[1:])
+
     if not args or args[0] in ("-h", "--help", "help"):
         sys.stdout.write(USAGE)
         return 0

comma_command-0.2.0/src/comma_command/config.py

@@ -0,0 +1,211 @@
+"""Reading and writing ``config.toml``.
+
+The canonical schema is a table per command::
+
+    [commands.gus]
+    cmd = ["too", "talk", "gus", "--"]
+    cwd = "~/work"
+    env = { TOO_PROFILE = "work" }
+    env_unset = ["HTTP_PROXY"]
+
+``cwd``, ``env`` and ``env_unset`` are optional. ``env`` is merged into the
+inherited environment; ``env_unset`` removes inherited variables first, so a key
+may not appear in both. The shorthand ``[commands] gus = "too talk gus --"`` is
+accepted as input sugar.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+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_-]+$")
+_KNOWN_KEYS = frozenset({"cmd", "command", "cwd", "env", "env_unset"})
+
+
+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, ...]
+    cwd: str | None = None
+    env: Mapping[str, str] = field(default_factory=dict)
+    env_unset: tuple[str, ...] = ()
+
+    def display(self) -> str:
+        return " ".join(shlex.quote(part) for part in self.argv)
+
+    def modifiers(self) -> list[str]:
+        """Human-readable list of the non-default settings, for `comma ls`."""
+        out = []
+        if self.cwd:
+            out.append(f"cwd={self.cwd}")
+        if self.env:
+            out.append("env=" + ",".join(sorted(self.env)))
+        if self.env_unset:
+            out.append("unset=" + ",".join(self.env_unset))
+        return out
+
+
+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_env(name: str, raw: object) -> dict[str, str]:
+    if not isinstance(raw, dict):
+        raise ConfigError(f"[commands.{name}].env must be a table of KEY = \"VALUE\"")
+    env: dict[str, str] = {}
+    for key, value in raw.items():
+        if not key or "=" in key:
+            raise ConfigError(f"[commands.{name}].env: invalid variable name {key!r}")
+        if not isinstance(value, str):
+            raise ConfigError(
+                f"[commands.{name}].env.{key} must be a string "
+                f"(got {type(value).__name__})"
+            )
+        env[key] = value
+    return env
+
+
+def _coerce_env_unset(name: str, raw: object) -> tuple[str, ...]:
+    if not isinstance(raw, list) or not all(isinstance(item, str) for item in raw):
+        raise ConfigError(f"[commands.{name}].env_unset must be a list of variable names")
+    for item in raw:
+        if not item or "=" in item:
+            raise ConfigError(f"[commands.{name}].env_unset: invalid variable name {item!r}")
+    return tuple(raw)
+
+
+def _coerce(name: str, value: object) -> Command:
+    if isinstance(value, str):
+        argv = shlex.split(value)
+        cwd = None
+        env: dict[str, str] = {}
+        env_unset: tuple[str, ...] = ()
+    elif isinstance(value, dict):
+        unknown = set(value) - _KNOWN_KEYS
+        if unknown:
+            raise ConfigError(
+                f"[commands.{name}]: unknown key(s) {', '.join(sorted(unknown))} "
+                f"(known: {', '.join(sorted(_KNOWN_KEYS))})"
+            )
+        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")
+
+        cwd = value.get("cwd")
+        if cwd is not None and (not isinstance(cwd, str) or not cwd):
+            raise ConfigError(f"[commands.{name}].cwd must be a non-empty string")
+
+        env = _coerce_env(name, value["env"]) if "env" in value else {}
+        env_unset = (
+            _coerce_env_unset(name, value["env_unset"]) if "env_unset" in value else ()
+        )
+    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")
+
+    overlap = sorted(set(env) & set(env_unset))
+    if overlap:
+        raise ConfigError(
+            f"[commands.{name}]: {', '.join(overlap)} in both env and env_unset — "
+            "pick one, the order would be ambiguous"
+        )
+
+    return Command(name=name, argv=tuple(argv), cwd=cwd, env=env, env_unset=env_unset)
+
+
+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] = _coerce(name, value)
+    return commands
+
+
+def _toml_key(name: str) -> str:
+    return name if _BARE_KEY_RE.match(name) else _toml_string(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}]")
+        if command.cwd:
+            lines.append(f"cwd = {_toml_string(command.cwd)}")
+        if command.env:
+            pairs = ", ".join(
+                f"{_toml_string(key)} = {_toml_string(value)}"
+                for key, value in sorted(command.env.items())
+            )
+            lines.append(f"env = {{ {pairs} }}")
+        if command.env_unset:
+            keys = ", ".join(_toml_string(key) for key in command.env_unset)
+            lines.append(f"env_unset = [{keys}]")
+        lines.append("")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines), encoding="utf-8")

{comma_command-0.1.0 → comma_command-0.2.0}/src/comma_command/dispatch.py

@@ -3,6 +3,10 @@
 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.
+
+Per-command ``cwd``/``env``/``env_unset`` are applied here, in that order:
+change directory, then build the environment (drop inherited variables, overlay
+the configured ones), then exec.
 """
 
 from __future__ import annotations
@@ -22,6 +26,15 @@ def invoked_name(prog: str) -> str | None:
     return None
 
 
+def build_env(command: config_mod.Command, base: dict[str, str] | None = None) -> dict[str, str]:
+    """Inherited environment, minus ``env_unset``, plus ``env``."""
+    env = dict(os.environ if base is None else base)
+    for key in command.env_unset:
+        env.pop(key, None)
+    env.update(command.env)
+    return env
+
+
 def dispatch(name: str, args: list[str]) -> int:
     """Replace this process with the command registered under ``name``."""
     try:
@@ -38,9 +51,21 @@ def dispatch(name: str, args: list[str]) -> int:
         print(f"  add one:    comma add {name} -- your-command --", file=sys.stderr)
         return 127
 
+    if command.cwd:
+        target = os.path.expanduser(command.cwd)
+        try:
+            os.chdir(target)
+        except OSError as exc:
+            print(
+                f"comma: cannot change to cwd {command.cwd!r} for {name!r}: {exc}",
+                file=sys.stderr,
+            )
+            return 1
+
     argv = [*command.argv, *args]
+    env = build_env(command)
     try:
-        os.execvpe(argv[0], argv, os.environ)
+        os.execvpe(argv[0], argv, env)
     except FileNotFoundError:
         print(f"comma: command not found: {argv[0]!r} (registered as {name!r})", file=sys.stderr)
         return 127

{comma_command-0.1.0 → comma_command-0.2.0}/tests/conftest.py

@@ -11,6 +11,14 @@ ROOT = Path(__file__).resolve().parents[1]
 SRC = ROOT / "src"
 
 
+#: Only these inherited variables reach a test subprocess. Anything else — API
+#: keys, tokens, cloud credentials — must not leak into a test environment, a
+#: child process, or a pytest assertion dump.
+SAFE_INHERIT = frozenset(
+    {"PATH", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TERM", "USER", "SYSTEMROOT"}
+)
+
+
 @pytest.fixture
 def env(tmp_path: Path) -> dict[str, str]:
     """A hermetic environment: throwaway HOME, XDG dirs, src on PYTHONPATH."""
@@ -19,8 +27,9 @@ def env(tmp_path: Path) -> dict[str, str]:
     pythonpath = str(SRC)
     if os.environ.get("PYTHONPATH"):
         pythonpath += os.pathsep + os.environ["PYTHONPATH"]
+    inherited = {k: v for k, v in os.environ.items() if k in SAFE_INHERIT}
     return {
-        **os.environ,
+        **inherited,
         "HOME": str(home),
         "XDG_CONFIG_HOME": str(tmp_path / "config"),
         "XDG_DATA_HOME": str(tmp_path / "data"),

{comma_command-0.1.0 → comma_command-0.2.0}/tests/test_cli.py

@@ -116,7 +116,10 @@ def test_completion_scripts(comma, env) -> None:
 
 
 def test_version_and_help(comma, env) -> None:
-    assert "comma 0.1.0" in comma("--version").stdout
+    from comma_command import __version__
+
+    assert f"comma {__version__}" in comma("--version").stdout
     usage = comma("--help").stdout
-    assert "comma add NAME" in usage
+    assert "comma add" in usage and "NAME -- COMMAND" in usage
+    assert "comma edit" in usage
     assert comma("bogus").returncode == 2

{comma_command-0.1.0 → comma_command-0.2.0}/tests/test_dispatch.py

@@ -88,3 +88,19 @@ def test_broken_config_is_reported(comma, env, launcher, echoargs) -> None:
 
     assert result.returncode == 1
     assert "invalid TOML" in result.stderr
+
+
+def test_name_comma_sugar_without_shim(comma, env, launcher, echoargs) -> None:
+    comma("add", "gus", "--", str(echoargs), "--")
+
+    result = comma("gus,", "hello", "world")
+
+    assert result.returncode == 0
+    assert result.stdout.splitlines() == ["--", "hello", "world"]
+
+
+def test_name_comma_sugar_unknown_name(comma, env, launcher) -> None:
+    result = comma("ghost,", "hi")
+
+    assert result.returncode == 127
+    assert "no command named 'ghost'" in result.stderr

comma_command-0.2.0/tests/test_env_cwd.py

@@ -0,0 +1,173 @@
+"""Per-command ``cwd`` / ``env`` / ``env_unset`` and ``comma edit``."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from conftest import activate, run_shim, shim_dir
+
+
+def write_config(env: dict[str, str], body: str) -> Path:
+    path = Path(env["XDG_CONFIG_HOME"]) / "comma" / "config.toml"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+    return path
+
+
+def make_shim(env: dict[str, str], launcher: Path, name: str) -> Path:
+    shim = shim_dir(env) / f"{name},"
+    shim.parent.mkdir(parents=True, exist_ok=True)
+    shim.symlink_to(launcher)
+    return shim
+
+
+def test_add_records_env_and_cwd(comma, env, launcher, tmp_path) -> None:
+    work = tmp_path / "work"
+    work.mkdir()
+
+    result = comma(
+        "add", "--env", "PROFILE=work", "--env", "X=1", "--cwd", str(work),
+        "gus", "--", "/bin/echo", "hi",
+    )
+
+    assert result.returncode == 0, result.stderr
+    text = (Path(env["XDG_CONFIG_HOME"]) / "comma" / "config.toml").read_text()
+    assert "cwd = " in text
+    assert "env = { " in text
+
+    payload = json.loads(comma("ls", "--json").stdout)
+    assert payload["gus"]["env"] == {"PROFILE": "work", "X": "1"}
+    assert payload["gus"]["cwd"] == str(work)
+
+
+def test_ls_text_shows_modifiers(comma, env, launcher, tmp_path) -> None:
+    work = tmp_path / "work"
+    work.mkdir()
+    comma("add", "--env", "A=1", "--cwd", str(work), "gus", "--", "/bin/echo", "hi")
+
+    listing = comma("ls").stdout
+
+    assert "cwd=" in listing
+    assert "env=A" in listing
+
+
+def test_env_overlays_inherited_environment(comma, env, launcher) -> None:
+    comma(
+        "add", "--env", "A=from-config", "envtest", "--",
+        "/bin/sh", "-c", 'printf "%s\\n" "$A" "$B"',
+    )
+    activate(env)
+    env["B"] = "inherited"
+
+    result = run_shim(env, "envtest,")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.splitlines() == ["from-config", "inherited"]
+
+
+def test_env_unset_removes_inherited_variable(comma, env, launcher) -> None:
+    write_config(
+        env,
+        '[commands.check]\n'
+        'cmd = ["/bin/sh", "-c", \'printf "%s\\n" "${TOKEN:-absent}"\']\n'
+        'env_unset = ["TOKEN"]\n',
+    )
+    make_shim(env, launcher, "check")
+    activate(env)
+    env["TOKEN"] = "inherited-value"
+
+    result = run_shim(env, "check,")
+
+    assert result.stdout.splitlines() == ["absent"]
+
+
+def test_cwd_is_applied(comma, env, launcher, tmp_path) -> None:
+    work = tmp_path / "proj"
+    work.mkdir()
+    comma("add", "--cwd", str(work), "here", "--", "/bin/sh", "-c", "pwd")
+    activate(env)
+
+    result = run_shim(env, "here,")
+
+    assert os.path.realpath(result.stdout.strip()) == os.path.realpath(work)
+
+
+def test_missing_cwd_fails_cleanly(comma, env, launcher) -> None:
+    comma("add", "--cwd", "/nope/nowhere", "gone", "--", "/bin/echo", "hi")
+    activate(env)
+
+    result = run_shim(env, "gone,")
+
+    assert result.returncode == 1
+    assert "cannot change to cwd" in result.stderr
+
+
+def test_env_and_env_unset_overlap_is_rejected(comma, env, launcher) -> None:
+    write_config(
+        env,
+        '[commands.bad]\ncmd = ["/bin/echo", "hi"]\nenv = { A = "1" }\nenv_unset = ["A"]\n',
+    )
+
+    result = comma("ls")
+
+    assert result.returncode == 1
+    assert "both env and env_unset" in result.stderr
+
+
+def test_unknown_key_is_rejected(comma, env, launcher) -> None:
+    write_config(env, '[commands.typo]\ncmd = ["/bin/echo", "hi"]\nevn = { A = "1" }\n')
+
+    result = comma("ls")
+
+    assert result.returncode == 1
+    assert "unknown key" in result.stderr
+
+
+def _editor(tmp_path: Path, body: str) -> str:
+    script = tmp_path / "fake-editor.py"
+    script.write_text("#!/usr/bin/env python3\nimport sys\n" + body, encoding="utf-8")
+    script.chmod(0o755)
+    return str(script)
+
+
+def test_edit_reconciles_shims(comma, env, launcher, tmp_path) -> None:
+    editor = _editor(
+        tmp_path,
+        "open(sys.argv[1], 'a').write('\\n[commands.ed]\\ncmd = [\"/bin/echo\", \"edited\"]\\n')\n",
+    )
+
+    result = comma("edit", env_overrides={"EDITOR": editor})
+
+    assert result.returncode == 0, result.stderr
+    assert (shim_dir(env) / "ed,").is_symlink()
+    activate(env)
+    assert run_shim(env, "ed,").stdout.strip() == "edited"
+
+
+def test_edit_removes_orphan_shims(comma, env, launcher, tmp_path) -> None:
+    make_shim(env, launcher, "orphan")
+    editor = _editor(tmp_path, "pass\n")
+
+    result = comma("edit", env_overrides={"EDITOR": editor})
+
+    assert result.returncode == 0, result.stderr
+    assert not (shim_dir(env) / "orphan,").exists()
+
+
+def test_edit_reports_broken_config(comma, env, launcher, tmp_path) -> None:
+    editor = _editor(tmp_path, "open(sys.argv[1], 'a').write('\\n[commands.broken\\n')\n")
+
+    result = comma("edit", env_overrides={"EDITOR": editor})
+
+    assert result.returncode == 1
+    assert "invalid TOML" in result.stderr
+
+
+def test_add_unset_flag(comma, env, launcher) -> None:
+    comma("add", "--unset", "TOKEN", "clean", "--", "/bin/echo", "hi")
+
+    payload = json.loads(comma("ls", "--json").stdout)
+
+    assert payload["clean"]["env_unset"] == ["TOKEN"]

comma_command-0.1.0/src/comma_command/config.py

@@ -1,130 +0,0 @@
-"""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")