comma-command 0.1.0__tar.gz

comma_command-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - name: lint
+        run: ruff check .
+      - name: test
+        run: pytest -q

comma_command-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.uv/
+*.swp
+.DS_Store

comma_command-0.1.0/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.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,112 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "comma-command"
+version = "0.1.0"
+description = "Run any configured command from any shell as `name, args` — register once, invoke everywhere."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "hak", email = "by3hak@users.noreply.github.com" }]
+keywords = ["cli", "shell", "alias", "dispatch", "multicall", "terminal"]
+dependencies = ['tomli>=2.0; python_version < "3.11"']
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Shells",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/by3hak/comma-command"
+Repository = "https://github.com/by3hak/comma-command"
+Issues = "https://github.com/by3hak/comma-command/issues"
+
+[project.scripts]
+comma = "comma_command.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/comma_command"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

comma_command-0.1.0/src/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-0.1.0/src/comma_command/__main__.py

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