gate-cache 0.4.0__tar.gz → 0.6.0__tar.gz

{gate_cache-0.4.0 → gate_cache-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gate-cache
-Version: 0.4.0
+Version: 0.6.0
 Summary: Skip lint and test gates that already passed on the exact same git tree.
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>
@@ -29,8 +29,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: cyclopts>=5.2.0,<6.0.0
-Requires-Dist: nclutils>=3.4.4,<4.0.0
+Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: platformdirs>=4.13.0,<5.0.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -41,14 +40,14 @@ Skip a command that already passed on the same code.
 
 A lint or test command often runs many times on code that did not change. It runs when you finish the work, in a pre-commit hook, after a rebase that changed nothing, and in a pre-push hook. When an agent works in the repository, it runs the same command again. If the command takes minutes, the repeat runs take most of the time between finished code and a pushed branch.
 
-gate-cache remembers which commands passed on which code. It wraps a command and gives it a name. When the command passes, gate-cache writes a marker for that name and for the exact content of the files in the working copy that git does not ignore. The next time the same name runs on the same content, gate-cache finds the marker, skips the command, and exits 0 at once.
+gate-cache remembers which commands passed on which code. It wraps a command, and the command line is the name of the gate. When the command passes, gate-cache writes a marker for that name and for the exact content of the files in the working copy that git does not ignore. The next time the same name runs on the same content, gate-cache finds the marker, skips the command, and exits 0 at once.
 
 ```console
-$ gate-cache --name pytest -- uv run pytest
+$ gate-cache -- uv run pytest
 ============================= 412 passed in 94.20s =============================
 
-$ gate-cache --name pytest -- uv run pytest
-gate-cache: pytest already passed on tree aaff74984ccc, skipping
+$ gate-cache -- uv run pytest
+gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping
 ```
 
 A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
@@ -65,14 +64,22 @@ The prek and pre-commit hooks install gate-cache themselves, so the hooks work w
 
 ## Run a command through gate-cache
 
-The name goes after `--name`, and the command goes after `--`:
+The command goes after `--`:
+
+```sh
+gate-cache -- uv run pytest
+gate-cache -- uv run ruff check .
+```
+
+The command and its arguments are the name of the gate. Each name has its own markers, so a pass of `uv run pytest -k unit` never skips `uv run pytest`.
+
+To choose the name yourself, put `--name` before `--`:
 
 ```sh
 gate-cache --name pytest -- uv run pytest
-gate-cache --name ruff -- uv run ruff check .
 ```
 
-Each name has its own markers. A command run under one name never skips because of a marker for another name.
+With `--name`, the name alone identifies the gate, and the arguments of the command are not part of it. Give a name when two different command lines do the same check and must share markers, or when a gate depends on [inputs that git does not track](#inputs-that-git-does-not-track).
 
 gate-cache exits with the exit code of the command, or with 0 when it skips the command. It writes a marker only when the command passes, so a command that failed runs again the next time.
 
@@ -89,18 +96,18 @@ repos:
     hooks:
       - id: gate-cache
         name: pytest
-        args: [--name, pytest, --, uv, run, pytest]
+        args: [--, uv, run, pytest]
         files: ^(src/|tests/)
       - id: gate-cache
         name: ruff
-        args: [--name, ruff, --, uv, run, ruff, check, .]
+        args: [--, uv, run, ruff, check, .]
 ```
 
 The hook runs at commit time and at push time. At commit time, gate-cache matches the content that you commit.
 
 The hook runs in its own virtual environment, and the wrapped command inherits that environment. A command started with `uv run`, or a project command such as `just test`, runs in the project environment. `uv run` prints a warning that `VIRTUAL_ENV` does not match the project. The warning has no effect on the run.
 
-Hooks, agents, and your terminal all read and write the same markers. When one of them runs `gate-cache --name pytest -- uv run pytest` and it passes, the others skip that name on the same content.
+Hooks, agents, and your terminal all read and write the same markers. When one of them runs `gate-cache -- uv run pytest` and it passes, the others skip `uv run pytest` on the same content.
 
 ## Examples
 
@@ -110,24 +117,26 @@ These examples show gate-cache inside the task runner of a project. When a recip
 
 ```just
 test:
-    gate-cache --name test -- uv run pytest
+    gate-cache -- uv run pytest
 
 lint:
-    gate-cache --name lint -- uv run ruff check .
+    gate-cache -- uv run ruff check .
 ```
 
 After `just test` passes, the next `just test` on the same content skips pytest.
 
 ### Recipes with arguments
 
-gate-cache identifies a command by its name alone, not by its arguments. If `just test -k unit` and `just test` ran under the same name, a pass of the unit tests would also skip the full suite. To keep them apart, put the arguments in the name:
+A recipe that passes its arguments to the command needs no `--name`. Each set of arguments gives a different command line, so each set has its own markers:
 
 ```just
 test *args:
-    gate-cache --name "{{ trim('test ' + args) }}" -- uv run pytest {{ args }}
+    gate-cache -- uv run pytest {{ args }}
 ```
 
-`just test` runs under the name `test`, and `just test -k unit` runs under the name `test -k unit`. Each set of arguments has its own markers. `trim` removes the trailing space when there are no arguments, so `gate-cache status --name test` finds the bare form.
+`just test` runs under the name `uv run pytest`, and `just test -k unit` runs under the name `uv run pytest -k unit`. A pass of the unit tests never skips the full suite.
+
+If the recipe gives `--name`, the arguments are not part of the name. Put them in the name, or a pass of `just test -k unit` also skips `just test`.
 
 ### Inputs that git does not track
 
@@ -143,7 +152,7 @@ integration:
     gate-cache --name "integration-$(git hash-object .env)" -- uv run pytest tests/integration
 ```
 
-`git hash-object` prints a hash of the file, so the name does not hold the secrets in `.env`. Do not put a secret value in a name, because the marker and `gate-cache status` record the name as plain text.
+`git hash-object` prints a hash of the file, so the name does not hold the secrets in `.env`. Do not put a secret value in a name, because the marker and `gate-cache status` record the name as plain text. Without `--name`, the command line is the name, so give `--name` to a command that takes a secret as an argument.
 
 The shell of the recipe expands `$(...)` before gate-cache starts. A hook `entry` or `args` list does not go through a shell, so put the command in a recipe and call the recipe from the hook. To look up the gate with `gate-cache status --name`, give the expanded name, such as `test-uv0.13.0`.
 
@@ -151,10 +160,10 @@ The shell of the recipe expands `$(...)` before gate-cache starts. A hook `entry
 
 ```make
 test:
-	gate-cache --name test -- uv run pytest
+	gate-cache -- uv run pytest
 
 lint:
-	gate-cache --name lint -- uv run ruff check .
+	gate-cache -- uv run ruff check .
 ```
 
 ### A hook that calls the recipe
@@ -200,17 +209,17 @@ GATE_CACHE_DISABLE=1 just test
 ```console
 $ gate-cache status
   tree:   aaff74984cccd156a469afa7d9ab10e4777beb24
-  passed: pytest
-  missed: ruff (exit code 1)
+  passed: uv run pytest
+  missed: uv run ruff check . (exit code 1)
 ```
 
 A name is missed when its command failed, or when it exited 0 but changed the files. A later pass of the same name removes it from the `missed` line.
 
-With `--name`, it reports on one name:
+With `--name`, it reports on one name. For a gate that ran without `--name`, give the command line as the name:
 
 ```console
-$ gate-cache status --name ruff
-  name:     ruff
+$ gate-cache status --name "uv run ruff check ."
+  name:     uv run ruff check .
   tree:     aaff74984cccd156a469afa7d9ab10e4777beb24
   marker:   /path/to/repo/.git/gate-cache/7d94ca2f57ec0a77f60d328fb405d339fb0c2a645991b97c042ac54403104e9e
   result:   miss
@@ -229,9 +238,9 @@ $ gate-cache status --json
   "enabled": true,
   "tree": "aaff74984cccd156a469afa7d9ab10e4777beb24",
   "reason": null,
-  "passed": ["pytest"],
+  "passed": ["uv run pytest"],
   "missed": [
-    {"name": "ruff", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
+    {"name": "uv run ruff check .", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
   ]
 }
 ```

{gate_cache-0.4.0 → gate_cache-0.6.0}/README.md

@@ -4,14 +4,14 @@ Skip a command that already passed on the same code.
 
 A lint or test command often runs many times on code that did not change. It runs when you finish the work, in a pre-commit hook, after a rebase that changed nothing, and in a pre-push hook. When an agent works in the repository, it runs the same command again. If the command takes minutes, the repeat runs take most of the time between finished code and a pushed branch.
 
-gate-cache remembers which commands passed on which code. It wraps a command and gives it a name. When the command passes, gate-cache writes a marker for that name and for the exact content of the files in the working copy that git does not ignore. The next time the same name runs on the same content, gate-cache finds the marker, skips the command, and exits 0 at once.
+gate-cache remembers which commands passed on which code. It wraps a command, and the command line is the name of the gate. When the command passes, gate-cache writes a marker for that name and for the exact content of the files in the working copy that git does not ignore. The next time the same name runs on the same content, gate-cache finds the marker, skips the command, and exits 0 at once.
 
 ```console
-$ gate-cache --name pytest -- uv run pytest
+$ gate-cache -- uv run pytest
 ============================= 412 passed in 94.20s =============================
 
-$ gate-cache --name pytest -- uv run pytest
-gate-cache: pytest already passed on tree aaff74984ccc, skipping
+$ gate-cache -- uv run pytest
+gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping
 ```
 
 A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
@@ -28,14 +28,22 @@ The prek and pre-commit hooks install gate-cache themselves, so the hooks work w
 
 ## Run a command through gate-cache
 
-The name goes after `--name`, and the command goes after `--`:
+The command goes after `--`:
+
+```sh
+gate-cache -- uv run pytest
+gate-cache -- uv run ruff check .
+```
+
+The command and its arguments are the name of the gate. Each name has its own markers, so a pass of `uv run pytest -k unit` never skips `uv run pytest`.
+
+To choose the name yourself, put `--name` before `--`:
 
 ```sh
 gate-cache --name pytest -- uv run pytest
-gate-cache --name ruff -- uv run ruff check .
 ```
 
-Each name has its own markers. A command run under one name never skips because of a marker for another name.
+With `--name`, the name alone identifies the gate, and the arguments of the command are not part of it. Give a name when two different command lines do the same check and must share markers, or when a gate depends on [inputs that git does not track](#inputs-that-git-does-not-track).
 
 gate-cache exits with the exit code of the command, or with 0 when it skips the command. It writes a marker only when the command passes, so a command that failed runs again the next time.
 
@@ -52,18 +60,18 @@ repos:
     hooks:
       - id: gate-cache
         name: pytest
-        args: [--name, pytest, --, uv, run, pytest]
+        args: [--, uv, run, pytest]
         files: ^(src/|tests/)
       - id: gate-cache
         name: ruff
-        args: [--name, ruff, --, uv, run, ruff, check, .]
+        args: [--, uv, run, ruff, check, .]
 ```
 
 The hook runs at commit time and at push time. At commit time, gate-cache matches the content that you commit.
 
 The hook runs in its own virtual environment, and the wrapped command inherits that environment. A command started with `uv run`, or a project command such as `just test`, runs in the project environment. `uv run` prints a warning that `VIRTUAL_ENV` does not match the project. The warning has no effect on the run.
 
-Hooks, agents, and your terminal all read and write the same markers. When one of them runs `gate-cache --name pytest -- uv run pytest` and it passes, the others skip that name on the same content.
+Hooks, agents, and your terminal all read and write the same markers. When one of them runs `gate-cache -- uv run pytest` and it passes, the others skip `uv run pytest` on the same content.
 
 ## Examples
 
@@ -73,24 +81,26 @@ These examples show gate-cache inside the task runner of a project. When a recip
 
 ```just
 test:
-    gate-cache --name test -- uv run pytest
+    gate-cache -- uv run pytest
 
 lint:
-    gate-cache --name lint -- uv run ruff check .
+    gate-cache -- uv run ruff check .
 ```
 
 After `just test` passes, the next `just test` on the same content skips pytest.
 
 ### Recipes with arguments
 
-gate-cache identifies a command by its name alone, not by its arguments. If `just test -k unit` and `just test` ran under the same name, a pass of the unit tests would also skip the full suite. To keep them apart, put the arguments in the name:
+A recipe that passes its arguments to the command needs no `--name`. Each set of arguments gives a different command line, so each set has its own markers:
 
 ```just
 test *args:
-    gate-cache --name "{{ trim('test ' + args) }}" -- uv run pytest {{ args }}
+    gate-cache -- uv run pytest {{ args }}
 ```
 
-`just test` runs under the name `test`, and `just test -k unit` runs under the name `test -k unit`. Each set of arguments has its own markers. `trim` removes the trailing space when there are no arguments, so `gate-cache status --name test` finds the bare form.
+`just test` runs under the name `uv run pytest`, and `just test -k unit` runs under the name `uv run pytest -k unit`. A pass of the unit tests never skips the full suite.
+
+If the recipe gives `--name`, the arguments are not part of the name. Put them in the name, or a pass of `just test -k unit` also skips `just test`.
 
 ### Inputs that git does not track
 
@@ -106,7 +116,7 @@ integration:
     gate-cache --name "integration-$(git hash-object .env)" -- uv run pytest tests/integration
 ```
 
-`git hash-object` prints a hash of the file, so the name does not hold the secrets in `.env`. Do not put a secret value in a name, because the marker and `gate-cache status` record the name as plain text.
+`git hash-object` prints a hash of the file, so the name does not hold the secrets in `.env`. Do not put a secret value in a name, because the marker and `gate-cache status` record the name as plain text. Without `--name`, the command line is the name, so give `--name` to a command that takes a secret as an argument.
 
 The shell of the recipe expands `$(...)` before gate-cache starts. A hook `entry` or `args` list does not go through a shell, so put the command in a recipe and call the recipe from the hook. To look up the gate with `gate-cache status --name`, give the expanded name, such as `test-uv0.13.0`.
 
@@ -114,10 +124,10 @@ The shell of the recipe expands `$(...)` before gate-cache starts. A hook `entry
 
 ```make
 test:
-	gate-cache --name test -- uv run pytest
+	gate-cache -- uv run pytest
 
 lint:
-	gate-cache --name lint -- uv run ruff check .
+	gate-cache -- uv run ruff check .
 ```
 
 ### A hook that calls the recipe
@@ -163,17 +173,17 @@ GATE_CACHE_DISABLE=1 just test
 ```console
 $ gate-cache status
   tree:   aaff74984cccd156a469afa7d9ab10e4777beb24
-  passed: pytest
-  missed: ruff (exit code 1)
+  passed: uv run pytest
+  missed: uv run ruff check . (exit code 1)
 ```
 
 A name is missed when its command failed, or when it exited 0 but changed the files. A later pass of the same name removes it from the `missed` line.
 
-With `--name`, it reports on one name:
+With `--name`, it reports on one name. For a gate that ran without `--name`, give the command line as the name:
 
 ```console
-$ gate-cache status --name ruff
-  name:     ruff
+$ gate-cache status --name "uv run ruff check ."
+  name:     uv run ruff check .
   tree:     aaff74984cccd156a469afa7d9ab10e4777beb24
   marker:   /path/to/repo/.git/gate-cache/7d94ca2f57ec0a77f60d328fb405d339fb0c2a645991b97c042ac54403104e9e
   result:   miss
@@ -192,9 +202,9 @@ $ gate-cache status --json
   "enabled": true,
   "tree": "aaff74984cccd156a469afa7d9ab10e4777beb24",
   "reason": null,
-  "passed": ["pytest"],
+  "passed": ["uv run pytest"],
   "missed": [
-    {"name": "ruff", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
+    {"name": "uv run ruff check .", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
   ]
 }
 ```

{gate_cache-0.4.0 → gate_cache-0.6.0}/pyproject.toml

@@ -4,17 +4,14 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
 ]
-dependencies = [
-    "cyclopts>=5.2.0,<6.0.0",
-    "nclutils>=3.4.4,<4.0.0",
-    "platformdirs>=4.13.0,<5.0.0",
-]
+dependencies = ["platformdirs>=4.13.0,<5.0.0"]
 description = "Skip lint and test gates that already passed on the exact same git tree."
 name = "gate-cache"
 readme = "README.md"
 requires-python = ">=3.11"
-version = "0.4.0"
+version = "0.6.0"
 
 [[project.authors]]
 name = "Nate Landau"
@@ -28,7 +25,7 @@ gate-cache = "gate_cache.cli:main"
 
 [build-system]
 build-backend = "uv_build"
-requires = ["uv_build>=0.11.0,<0.12.0"]
+requires = ["uv_build>=0.13.0,<0.14"]
 
 [tool.uv.build-backend]
 module-name = "gate_cache"

{gate_cache-0.4.0 → gate_cache-0.6.0}/pyproject.toml.orig

@@ -5,25 +5,24 @@
         "Programming Language :: Python :: 3.12",
         "Programming Language :: Python :: 3.13",
         "Programming Language :: Python :: 3.14",
+        "Programming Language :: Python :: 3.15",
     ]
     dependencies = [
-        "cyclopts>=5.2.0,<6.0.0",
-        "nclutils>=3.4.4,<4.0.0",
         "platformdirs>=4.13.0,<5.0.0",
-    ]
+]
     description = "Skip lint and test gates that already passed on the exact same git tree."
     license = { file = "LICENSE" }
     name = "gate-cache"
     readme = "README.md"
     requires-python = ">=3.11"
-    version = "0.4.0"
+    version = "0.6.0"
 
     [project.scripts]
         gate-cache = "gate_cache.cli:main"
 
 [build-system]
     build-backend = "uv_build"
-    requires      = ["uv_build>=0.11.0,<0.12.0"]
+    requires      = ["uv_build>=0.13.0,<0.14"]
 
 [tool.uv.build-backend]
     module-name = "gate_cache"

{gate_cache-0.4.0 → gate_cache-0.6.0}/src/gate_cache/__init__.py

@@ -1,3 +1,3 @@
 """Skip lint and test gates that already passed on the exact same git tree."""
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"

gate_cache-0.6.0/src/gate_cache/cli.py

@@ -0,0 +1,247 @@
+"""Command line interface for gate-cache."""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+import sys
+from typing import TYPE_CHECKING
+
+from gate_cache import __version__
+from gate_cache.console import say
+from gate_cache.gate import clear_cache, gate_status, run_gate
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+_USAGE_ERROR = 2
+_INTERRUPTED = 130
+_INFO_FLAGS = {"-h", "--help", "--version"}
+_NAME_NEEDS_VALUE = "--name needs a value, e.g. gate-cache --name pytest -- uv run pytest"
+_NEEDS_SEPARATOR = "put -- before the command, e.g. gate-cache -- uv run pytest"
+_NAME_REPEATED = "--name given more than once"
+_NO_COMMAND = "no command given after --"
+
+_USAGE = """\
+gate-cache [--name NAME] -- COMMAND [ARGS...]
+       gate-cache status [--name NAME] [--json]
+       gate-cache clear"""
+
+_HELP = """\
+Skip a lint or test command that already passed on the same git tree. gate-cache
+runs the command, records a pass keyed on the git tree of the working copy
+(tracked and untracked, non-ignored files), and skips the command next time the
+tree is identical. A pass on uncommitted work therefore skips when the same
+content is committed.
+
+-- is required, and only --name may come before it. Everything after -- is the
+command, verbatim. Without --name, the gate name is the command itself, so each
+set of arguments has its own records. Give --name to share records between
+commands that check the same thing, or to key on inputs that the tree does not
+cover.
+
+Exit codes:
+  run     the command's own exit code, or 0 when a recorded pass lets it skip.
+          Usage errors exit 2.
+  status  0 when the named gate, or any gate without --name, passed on the
+          current tree. 1 otherwise. --json prints one JSON object instead.
+  clear   0 on success, 1 on failure.
+
+GATE_CACHE_DISABLE and CI are on when the value is not empty, 0, or false (any
+case). If GATE_CACHE_DISABLE is on, the command always runs without the cache.
+If it is 0 or false, caching stays on. If it is empty or not set, CI decides the
+same way.
+Set GATE_CACHE_MAX_AGE_DAYS to a positive whole number to change how many days a
+recorded pass lasts (default 30).
+
+Only the name and the file content are keyed. The working directory is not, so
+a command whose meaning depends on it needs a distinct --name. To also key on an
+ignored file, an environment variable, or a tool version, put its value in
+--name. A changed value gives a new name, so the command runs again. Never put a
+secret in a name, because markers and status store it as plain text. Without
+--name the command line is the name, so give --name to a command that takes a
+secret argument. Never wrap checks that depend on the commit message or the
+branch name.
+
+Typical use:
+  gate-cache -- uv run pytest -x
+  gate-cache --name pytest -- uv run pytest -x
+  gate-cache --name "test-$(git hash-object .env)" -- uv run pytest
+"""
+
+_RUN_HELP = """\
+subcommands:
+  status       Report whether gates would skip, without running anything.
+  clear        Delete every recorded pass for this repository.
+
+run:
+  gate-cache [--name NAME] -- COMMAND [ARGS...] runs COMMAND unless it already
+  passed on the current git tree. On a skip, it prints one line to stderr and
+  exits 0 without running anything. Otherwise it runs the command and exits with
+  its exit code. The command runs without caching (and nothing is recorded) when
+  GATE_CACHE_DISABLE or CI turns caching off, the tree is unknown (for example an
+  unmerged index), or this is not a git repository. A pass is recorded only when
+  the command exits 0 and the run leaves the tree unchanged.
+
+Run gate-cache SUBCOMMAND --help for the options of a subcommand.
+"""
+
+_STATUS_HELP = """\
+Report whether gates would skip, without running anything.
+
+With --name, print the tree hash (or why it is unknown), the marker path,
+hit or miss, and how the last run on this tree failed when it did. Exit 0 on a
+hit, 1 otherwise.
+
+Without --name, list the gates that passed on the current tree and the gates
+that ran on it without passing. Exit 0 when at least one gate passed, 1 otherwise.
+"""
+
+_CLEAR_HELP = """\
+Delete every recorded pass for this repository.
+
+Use after something outside git changes, such as a tool upgrade. Exits 1 outside a
+git repository.
+"""
+
+
+class _UsageError(Exception):
+    """A malformed run invocation, reported as one line on stderr with exit code 2."""
+
+
+class _StoreOnce(argparse.Action):
+    """Store an option's value, rejecting a second occurrence instead of overwriting the first."""
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: str | Sequence[object] | None,
+        option_string: str | None = None,
+    ) -> None:
+        if getattr(namespace, self.dest) is not None:
+            parser.error(f"{option_string} given more than once")
+        setattr(namespace, self.dest, values)
+
+
+def _main_parser() -> argparse.ArgumentParser:
+    """Build the top-level parser, which serves only --help and --version.
+
+    The run form is not parsed here because everything after -- must reach the wrapped
+    command verbatim. The parser still declares --name so that --help documents it.
+    """
+    parser = argparse.ArgumentParser(
+        prog="gate-cache",
+        usage=_USAGE,
+        description=_HELP,
+        epilog=_RUN_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument(
+        "--name",
+        metavar="NAME",
+        help="Gate name. Records match only when the name and the tree both match. "
+        "Defaults to the command and its arguments, quoted as a shell would.",
+    )
+    return parser
+
+
+def _status_parser() -> argparse.ArgumentParser:
+    """Build the parser for the status subcommand."""
+    parser = argparse.ArgumentParser(
+        prog="gate-cache status",
+        description=_STATUS_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "--name",
+        action=_StoreOnce,
+        help="Gate name to look up. Omit it to list every gate that ran on this tree.",
+    )
+    parser.add_argument(
+        "--json",
+        dest="as_json",
+        action="store_true",
+        help="Print one JSON object to stdout instead of text. Exit codes are unchanged.",
+    )
+    return parser
+
+
+def _clear_parser() -> argparse.ArgumentParser:
+    """Build the parser for the clear subcommand."""
+    return argparse.ArgumentParser(
+        prog="gate-cache clear",
+        description=_CLEAR_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+
+
+def _split_run(tokens: list[str]) -> tuple[str | None, list[str]]:
+    """Split a run invocation into its --name value and the command after the first --.
+
+    Only `--name X` or `--name=X` may precede `--`, so a stray option such as `--version`
+    or the first word of the command can never be mistaken for one of ours.
+
+    Raises:
+        _UsageError: When anything else precedes `--`, `--` is missing, or `--name` is
+            missing its value or given twice.
+    """
+    name: str | None = None
+    index = 0
+    while index < len(tokens):
+        arg = tokens[index]
+        if arg == "--":
+            return name, tokens[index + 1 :]
+        if arg == "--name":
+            if index + 1 == len(tokens) or tokens[index + 1] == "--":
+                raise _UsageError(_NAME_NEEDS_VALUE)
+            value = tokens[index + 1]
+            index += 2
+        elif arg.startswith("--name="):
+            value = arg.removeprefix("--name=")
+            index += 1
+        else:
+            break
+        if name is not None:
+            raise _UsageError(_NAME_REPEATED)
+        name = value
+    raise _UsageError(_NEEDS_SEPARATOR)
+
+
+def _dispatch(tokens: list[str]) -> int:
+    """Run the invocation in tokens and return its exit code.
+
+    Raises:
+        _UsageError: When a run invocation is malformed.
+    """
+    if tokens and tokens[0] in _INFO_FLAGS:
+        _main_parser().parse_args(tokens)  # prints help or the version, then exits
+    if tokens and tokens[0] == "status":
+        args = _status_parser().parse_args(tokens[1:])
+        return gate_status(args.name, as_json=args.as_json)
+    if tokens and tokens[0] == "clear":
+        _clear_parser().parse_args(tokens[1:])
+        return clear_cache()
+
+    name, command = _split_run(tokens)
+    if not command:
+        raise _UsageError(_NO_COMMAND)
+    if name == "":
+        raise _UsageError(_NAME_NEEDS_VALUE)
+    return run_gate(shlex.join(command) if name is None else name, command)
+
+
+def main() -> None:
+    """Run the gate-cache command line interface and exit with its code."""
+    try:
+        code = _dispatch(sys.argv[1:])
+    except _UsageError as error:
+        say(str(error))
+        sys.exit(_USAGE_ERROR)
+    except KeyboardInterrupt:
+        sys.exit(_INTERRUPTED)
+    sys.exit(code)

gate_cache-0.6.0/src/gate_cache/console.py

@@ -0,0 +1,43 @@
+"""User-facing gate-cache messages."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+
+
+def say(message: str) -> None:
+    """Print a gate-cache message to stderr, verbatim.
+
+    Args:
+        message: Text to print after the `gate-cache: ` prefix.
+    """
+    print(f"gate-cache: {message}", file=sys.stderr)  # noqa: T201
+
+
+def _use_color() -> bool:
+    """Return True when stdout is a terminal that accepts ANSI styling."""
+    if os.environ.get("NO_COLOR") or os.environ.get("TERM") == "dumb":
+        return False
+    return sys.stdout.isatty()
+
+
+def kv(rows: dict[str, str]) -> None:
+    """Print key/value rows on stdout with the values aligned in one column.
+
+    Args:
+        rows: Labels mapped to their values, printed in insertion order.
+    """
+    if not rows:
+        return
+    cell_width = max(len(key) for key in rows) + len(": ")
+    dim, reset = (_DIM, _RESET) if _use_color() else ("", "")
+    for key, value in rows.items():
+        pad = " " * (cell_width - len(key) - len(": "))
+        first, *rest = value.splitlines() or [""]
+        print(f"  {dim}{key}{reset}: {pad}{first}")  # noqa: T201
+        for line in rest:
+            print(f"{' ' * (2 + cell_width)}{line}")  # noqa: T201

{gate_cache-0.4.0 → gate_cache-0.6.0}/src/gate_cache/gate.py

@@ -7,9 +7,7 @@ import json
 import os
 from typing import TYPE_CHECKING, Any
 
-from nclutils import pp
-
-from gate_cache.console import say
+from gate_cache.console import kv, say
 from gate_cache.markers import (
     clear_markers,
     marker_exists,
@@ -285,7 +283,7 @@ def _named_status(name: str, snapshot: Snapshot, common_dir: Path | None, *, as_
     }
     if last_run is not None:
         rows["last run"] = str(last_run["reason"])
-    pp.kv(rows)
+    kv(rows)
     return 0 if hit else 1
 
 
@@ -312,14 +310,14 @@ def _list_gates(snapshot: Snapshot, common_dir: Path | None, *, as_json: bool) -
         return code
 
     if tree is None:
-        pp.kv({"tree": f"unknown: {snapshot.reason}"})
+        kv({"tree": f"unknown: {snapshot.reason}"})
         return 1
     if common_dir is None:
-        pp.kv({"tree": tree, "passed": f"unknown: {_NO_COMMON_DIR_REASON}"})
+        kv({"tree": tree, "passed": f"unknown: {_NO_COMMON_DIR_REASON}"})
         return 1
     if not passed and not missed:
-        pp.kv({"tree": tree})
-        pp.console().print("No gates match the current tree", markup=False, highlight=False)
+        kv({"tree": tree})
+        print("No gates match the current tree")  # noqa: T201
         return 1
     rows = {"tree": tree}
     if passed:
@@ -328,7 +326,7 @@ def _list_gates(snapshot: Snapshot, common_dir: Path | None, *, as_json: bool) -
         rows["missed"] = ", ".join(
             f"{m['name']} ({m['reason']})" if m["reason"] else m["name"] for m in missed
         )
-    pp.kv(rows)
+    kv(rows)
     return code
 
 

gate_cache-0.6.0/src/gate_cache/git.py

@@ -0,0 +1,98 @@
+"""Run git subcommands and capture their output."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+class GitError(Exception):
+    """Base class for every error raised while running git."""
+
+
+class GitNotFoundError(GitError):
+    """Raised when the git executable is not on PATH."""
+
+
+class GitFailedError(GitError):
+    """Raised when git cannot start in the requested directory or exits with an error."""
+
+
+@dataclass(frozen=True, slots=True)
+class GitResult:
+    """The exit code and decoded output of a finished git command.
+
+    Attributes:
+        returncode: The exit code of the git process.
+        stdout: Standard output with trailing newlines removed.
+        stderr: Standard error with trailing newlines removed.
+    """
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def run_git(
+    *args: str,
+    cwd: Path | str | None = None,
+    env: Mapping[str, str] | None = None,
+    check: bool = True,
+) -> GitResult:
+    """Run `git` with the given arguments and return its decoded output.
+
+    Output is decoded as strict UTF-8 from raw bytes. Text mode would use the locale
+    encoding and translate carriage returns in NUL-delimited path listings.
+
+    Args:
+        *args: The git subcommand and its arguments.
+        cwd: Directory to run git in. None inherits the process working directory.
+        env: Environment that replaces the inherited one, or None to inherit it.
+        check: Raise GitFailedError when git exits with a non-zero code.
+
+    Returns:
+        The exit code and output of the command.
+
+    Raises:
+        GitNotFoundError: git is not on PATH.
+        GitFailedError: cwd is not a directory, git cannot start, or git fails under check.
+        UnicodeDecodeError: git printed output that is not valid UTF-8.
+    """
+    argv = ["git", *args]
+    resolved: Path | None = None
+    if cwd is not None:
+        resolved = Path(cwd).expanduser().resolve()
+        # Popen reports a missing cwd as FileNotFoundError, the same as a missing git.
+        if not resolved.is_dir():
+            msg = f"Cannot enter directory {resolved}: not a directory"
+            raise GitFailedError(msg)
+    try:
+        proc = subprocess.run(  # noqa: S603
+            argv,
+            cwd=resolved,
+            env=dict(env) if env is not None else None,
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError as e:
+        msg = "git not found on PATH"
+        raise GitNotFoundError(msg) from e
+    except OSError as e:
+        msg = f"Failed to start git: {e}"
+        raise GitFailedError(msg) from e
+
+    result = GitResult(
+        returncode=proc.returncode,
+        stdout=proc.stdout.decode("utf-8").rstrip("\n"),
+        stderr=proc.stderr.decode("utf-8").rstrip("\n"),
+    )
+    if check and result.returncode != 0:
+        msg = f"git {' '.join(args)} failed with exit code {result.returncode}: {result.stderr}"
+        raise GitFailedError(msg)
+    return result

{gate_cache-0.4.0 → gate_cache-0.6.0}/src/gate_cache/markers.py

@@ -8,11 +8,10 @@ import json
 import shutil
 import tempfile
 import time
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from nclutils.utils import iso_timestamp
-
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
@@ -125,7 +124,8 @@ def write_miss(
 def _write_json(path: Path, payload: dict[str, object]) -> None:
     """Write a timestamped JSON record via a temp file and rename, so readers never see half."""
     path.parent.mkdir(parents=True, exist_ok=True)
-    payload = {**payload, "timestamp": iso_timestamp()}
+    timestamp = datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
+    payload = {**payload, "timestamp": timestamp}
     tmp_name: str | None = None
     try:
         with tempfile.NamedTemporaryFile(

{gate_cache-0.4.0 → gate_cache-0.6.0}/src/gate_cache/snapshot.py

@@ -7,10 +7,8 @@ import shutil
 from dataclasses import dataclass
 from pathlib import Path
 
-from nclutils.git import run_git
-from nclutils.sh import ShellCommandError, ShellCommandNotFoundError
-
 from gate_cache import scratch
+from gate_cache.git import GitError, GitNotFoundError, run_git
 
 
 @dataclass(frozen=True)
@@ -327,16 +325,16 @@ def take_snapshot(cwd: Path | None = None) -> Snapshot:
     try:
         env = _git_env(cwd)
         state = _inspect(cwd, env)
-    except ShellCommandNotFoundError:
+    except GitNotFoundError:
         return Snapshot(tree=None, reason="git not found")
-    except (ShellCommandError, UnicodeDecodeError):
+    except (GitError, UnicodeDecodeError):
         return Snapshot(tree=None, reason="could not inspect git state")
     if state.reason or state.root is None:
         return Snapshot(tree=None, reason=state.reason or "could not locate work tree")
 
     try:
         return _private_snapshot(cwd, state.root, env)
-    except (ShellCommandError, OSError, UnicodeDecodeError):
+    except (GitError, OSError, UnicodeDecodeError):
         return Snapshot(tree=None, reason="could not hash working copy")
 
 
@@ -351,7 +349,7 @@ def git_common_dir(cwd: Path | None = None) -> Path | None:
     """
     try:
         result = run_git("rev-parse", "--git-common-dir", cwd=cwd)
-    except (ShellCommandError, UnicodeDecodeError):
+    except (GitError, UnicodeDecodeError):
         return None
     output = result.stdout.strip()
     if not output or "\n" in output:

gate_cache-0.4.0/src/gate_cache/cli.py

@@ -1,169 +0,0 @@
-"""Command line interface for gate-cache."""
-
-from __future__ import annotations
-
-import sys
-from typing import Annotated
-
-from cyclopts import App, Parameter
-
-from gate_cache import __version__
-from gate_cache.console import say
-from gate_cache.gate import clear_cache, gate_status, run_gate
-
-_USAGE_ERROR = 2
-_INTERRUPTED = 130
-_SUBCOMMANDS = {"status", "clear"}
-_INFO_FLAGS = {"-h", "--help", "--version"}
-
-_HELP = """\
-Skip a lint or test command that already passed on the same git tree. gate-cache
-runs the command, records a pass keyed on the git tree of the working copy
-(tracked and untracked, non-ignored files), and skips the command next time the
-tree is identical. A pass on uncommitted work therefore skips when the same
-content is committed.
-
-Both --name and -- are required, and only --name may come before --. Everything
-after -- is the command, verbatim.
-
-Exit codes:
-  run     the command's own exit code, or 0 when a recorded pass lets it skip.
-          Usage errors exit 2.
-  status  0 when the named gate, or any gate without --name, passed on the
-          current tree. 1 otherwise. --json prints one JSON object instead.
-  clear   0 on success, 1 on failure.
-
-GATE_CACHE_DISABLE and CI are on when the value is not empty, 0, or false (any
-case). If GATE_CACHE_DISABLE is on, the command always runs without the cache.
-If it is 0 or false, caching stays on. If it is empty or not set, CI decides the
-same way.
-Set GATE_CACHE_MAX_AGE_DAYS to a positive whole number to change how many days a
-recorded pass lasts (default 30).
-
-Only the name and the file content are keyed. To also key on recipe arguments,
-an ignored file, an environment variable, or a tool version, put its value in
---name. A changed value gives a new name, so the command runs again. Never put a
-secret in a name, because markers and status store it as plain text. Never wrap
-checks that depend on the commit message or the branch name.
-
-Typical use:
-  gate-cache --name pytest -- uv run pytest -x
-  gate-cache --name "pytest -k unit" -- uv run pytest -k unit
-  gate-cache --name "test-$(git hash-object .env)" -- uv run pytest
-"""
-
-app = App(
-    name="gate-cache",
-    version=__version__,
-    help=_HELP,
-    help_format="plaintext",
-    usage=(
-        "Usage: gate-cache --name NAME -- COMMAND [ARGS...]\n"
-        "       gate-cache status [--name NAME] [--json]\n"
-        "       gate-cache clear"
-    ),
-    result_action="return_int_as_exit_code_else_zero",
-)
-
-
-@app.default
-def run(
-    command: Annotated[
-        list[str], Parameter(allow_leading_hyphen=True, negative_iterable="", show_default=False)
-    ],
-    /,
-    *,
-    name: str,
-) -> int:
-    """Run COMMAND unless it already passed on the current git tree.
-
-    On a skip, prints one line to stderr and exits 0 without running anything. Otherwise
-    runs the command and exits with its exit code. The command runs without caching
-    (and nothing is recorded) when GATE_CACHE_DISABLE or CI turns caching off, the tree
-    is unknown (for example an unmerged index), or this is not a git repository. A pass is recorded only
-    when the command exits 0 and the run leaves the tree unchanged.
-
-    Parameters
-    ----------
-    command
-        The command and its arguments, given after `--`. Example: -- uv run pytest -x
-    name
-        Gate name. Records match only when the name and the tree both match.
-        Include arguments or other inputs that the tree does not cover.
-    """
-    if not command:
-        say("no command given after --")
-        return _USAGE_ERROR
-    return run_gate(name, command)
-
-
-@app.command
-def status(
-    *,
-    name: str | None = None,
-    as_json: Annotated[bool, Parameter(name="--json", negative="")] = False,
-) -> int:
-    """Report whether gates would skip, without running anything.
-
-    With --name, print the tree hash (or why it is unknown), the marker path,
-    hit or miss, and how the last run on this tree failed when it did. Exit 0 on a
-    hit, 1 otherwise.
-
-    Without --name, list the gates that passed on the current tree and the gates
-    that ran on it without passing. Exit 0 when at least one gate passed, 1 otherwise.
-
-    Parameters
-    ----------
-    name
-        Gate name to look up. Omit it to list every gate that ran on this tree.
-    as_json
-        Print one JSON object to stdout instead of text. Exit codes are unchanged.
-    """
-    return gate_status(name, as_json=as_json)
-
-
-@app.command
-def clear() -> int:
-    """Delete every recorded pass for this repository.
-
-    Use after something outside git changes, such as a tool upgrade. Exits 1 outside a
-    git repository.
-    """
-    return clear_cache()
-
-
-def _usage_error(tokens: list[str]) -> str | None:
-    """Return the usage problem with a run invocation, or None when it is well formed.
-
-    Only `--name X` or `--name=X` may precede `--`, so a stray option such as `--version`
-    or the first word of the command can never be mistaken for one of ours.
-    """
-    if not tokens or tokens[0] in _SUBCOMMANDS | _INFO_FLAGS:
-        return None
-    index = 0
-    while index < len(tokens):
-        arg = tokens[index]
-        if arg == "--":
-            return None
-        if arg == "--name":
-            if index + 1 == len(tokens) or tokens[index + 1] == "--":
-                return "--name needs a value, e.g. gate-cache --name pytest -- uv run pytest"
-            index += 2
-        elif arg.startswith("--name="):
-            index += 1
-        else:
-            break
-    return "put -- before the command, e.g. gate-cache --name pytest -- uv run pytest"
-
-
-def main() -> None:
-    """Run the gate-cache command line interface and exit with its code."""
-    tokens = sys.argv[1:]
-    if problem := _usage_error(tokens):
-        say(problem)
-        sys.exit(_USAGE_ERROR)
-    try:
-        code = app(tokens)
-    except KeyboardInterrupt:
-        sys.exit(_INTERRUPTED)
-    sys.exit(code)

gate_cache-0.4.0/src/gate_cache/console.py

@@ -1,14 +0,0 @@
-"""User-facing gate-cache messages."""
-
-from __future__ import annotations
-
-from nclutils import pp
-
-
-def say(message: str) -> None:
-    """Print a gate-cache message to stderr, verbatim.
-
-    Args:
-        message: Text to print after the `gate-cache: ` prefix.
-    """
-    pp.err_console().print(f"gate-cache: {message}", markup=False, highlight=False, soft_wrap=True)