Metadata-Version: 2.5
Name: gestate
Version: 1.3.0
Summary: Set a minimum release age on local package managers to defend against zero-day supply chain attacks.
Project-URL: Repository, https://github.com/lincolnloop/gestate
Author-email: Lincoln Loop <chris@lincolnloop.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bun,cooldown,deno,npm,pip,pnpm,security,supply-chain,uv,yarn
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Installation/Setup
Requires-Python: >=3.11
Requires-Dist: rich>=13
Requires-Dist: ruamel-yaml>=0.19.1
Requires-Dist: tomli-w>=1.0
Description-Content-Type: text/markdown

# gestate

Set a minimum release age on local package managers so installs ignore versions younger than `N` days. Most malicious packages are caught and yanked within days of publishing; refusing fresh versions blocks the bulk of supply-chain attacks.

## Run

```
uvx gestate                  # interactive
uvx gestate set 3            # 3-day minimum, installed tools only
uvx gestate set 3 --all      # also pre-configure file-based tools (bun, deno, uv)
uvx gestate set 3 --local    # write per-project config files in the current repo
uvx gestate revert           # remove gestate's settings
uvx gestate revert --local   # remove the per-project gate from this repo
uvx gestate explain bun      # show how one tool's setting is stored
uvx gestate trust my-pkg --python  # exempt a package from the age delay
uvx gestate trust --rm my-pkg      # remove an exemption
uvx gestate trust                  # list trusted packages
```

Interactive mode always shows a plan and asks for explicit confirmation before touching anything. The subcommands skip the confirm — meant for scripts, not your daily shell. Running with no subcommand outside a TTY exits with an error.

Plain text output is used when stdout isn't a terminal (no Rich tables/colors).

## What it sets

| Tool | Where | Key (unit) |
|---|---|---|
| npm  | `~/.npmrc`               | `min-release-age` (days) |
| pnpm | global pnpm config       | `minimumReleaseAge` (minutes) |
| yarn | `~/.yarnrc.yml` (4.10+)  | `npmMinimalAgeGate` (minutes) |
| bun  | `~/.bunfig.toml`         | `[install] minimumReleaseAge` (seconds) |
| deno | shell profile            | `alias deno='command deno --minimum-dependency-age=P<N>D'` |
| pip  | user pip config          | `global.uploaded-prior-to` (`P<N>D`) |
| uv   | `~/.config/uv/uv.toml`   | `exclude-newer` (`"N days"`), plus a [git filter](#keeping-uvlock-stable) for `uv.lock` |

`gestate explain <tool>` prints that tool's current value and the exact mechanism `set` / `revert` use.

Scope:
- default — only configure installed tools
- `--all` — also pre-write config files for `bun`, `deno`, `uv` even if they aren't installed yet

## Project-local policy (`--local`)

`gestate set <days> --local` writes each tool's **native, committed-to-the-repo** config so the gate travels with the project and applies to anyone who clones it — even collaborators who never ran gestate. It only configures tools the repo gives evidence of (a lockfile, manifest, or existing tool config in the current directory), so it won't litter a JS repo with `uv.toml` or vice versa.

| Tool | Project file (cwd) | Key (unit) |
|---|---|---|
| npm  | `.npmrc`               | `min-release-age` (days) |
| pnpm | `pnpm-workspace.yaml`  | `minimumReleaseAge` (minutes) |
| yarn | `.yarnrc.yml`          | `npmMinimalAgeGate` (minutes) |
| bun  | `bunfig.toml`          | `[install] minimumReleaseAge` (seconds) |
| deno | `deno.json`            | `minimumDependencyAge` (`P<N>D`) |
| uv   | `uv.toml`              | `exclude-newer` (`"N days"`) |

`pip` has no per-project config (and no dependency-age gate), so it's skipped. If a `deno.json` has comments (JSONC), gestate won't rewrite it — it prints the line to add yourself. `revert --local` removes the key and deletes any file it leaves empty.

## Revert

`uvx gestate revert` removes everything gestate set:

- CLI tools — `config delete` / `config unset`
- `bun` / `uv` — remove the key; delete the file if it was the only key
- `deno` — remove our alias line; leave foreign `alias deno=` lines alone

Backups (`.bak`) are written next to any edited shell-profile or TOML file.

## Per-package exemptions (`trust`)

`gestate trust` lets you exempt specific packages from the age delay so they always get the latest version:

```
gestate trust @myorg/*              # auto-detects Node (scoped package)
gestate trust my-lib --python       # exempt in uv
 
gestate trust --rm my-lib --python  # remove exemption
gestate trust                       # list all trusted packages
gestate trust --python              # list Python ecosystem only
```

The `--python` / `--node` flags are optional — gestate auto-detects the ecosystem from scoped packages (`@scope/name` → Node) or the current directory (`pyproject.toml` → Python, `package.json` → Node). When it can't tell, it asks you to specify.

Supported tools: **bun**, **uv**, **yarn**, **pnpm**, **npm** (requires npm ≥ 11.17.0). **deno** and **pip** don't support per-package allowlists and print a warning. For manual config details, see [docs/allowlists.md](docs/allowlists.md).

## Caveats

- **yarn**: 4.10+ only. Older yarn is detected and skipped.
- **deno**: no global config exists; the shell alias only covers interactive shells. For CI, pass `--minimum-dependency-age=P<N>D` to `deno install`/`deno update`, or commit a project `deno.json` with `"minimumDependencyAge": "P<N>D"`.
- **npm trust**: requires npm ≥ 11.17.0. gestate skips npm with a note when the installed npm is older (global scope only — a project `.npmrc` is still written, since it's enforced by whoever installs). Early npm releases didn't honor `min-release-age-exclude` in `npx` or every reify path.
- **pip exclude**: none — `global.uploaded-prior-to` is global only.
- **uv lockfiles**: see [Keeping uv.lock stable](#keeping-uvlock-stable).

## Keeping uv.lock stable

uv writes the `exclude-newer` settings in effect into `uv.lock`'s `[options]`, including the ones from your global `uv.toml` ([astral-sh/uv#18775](https://github.com/astral-sh/uv/issues/18775)). Collaborators without that config strip them again, so the lock flip-flops between you, and a lock committed with them can trip `uv sync --locked` in CI or a Docker build.

So when it configures uv, `gestate set` also adds a global git clean filter:

- `filter.gestate-uv.clean = gestate uv-lock-clean %f` in your global git config (`uvx gestate …` if `gestate` isn't on your `PATH`)
- `uv.lock filter=gestate-uv` in your global attributes file (`core.attributesFile`, else `~/.config/git/attributes`)

Git then sees each `uv.lock` without the entries that came only from your global config, while uv keeps them in your working copy. Anything the project sets itself (`uv.toml`, or `[tool.uv]` in `pyproject.toml`, next to the lock) is left alone, as is every other option. `gestate revert` removes the filter.

Things to know:

- A repo whose committed `uv.lock` already contains your global settings shows the lock as modified; commit it to drop them.
- After a pull changes `uv.lock` and uv rewrites it, `git status` can list it as modified with an empty `git diff`: git sees the size change before it runs the filter. `git add uv.lock` clears it and stages nothing.
- If gestate can't run, git uses the file unfiltered, so the worst case is the old churn.
- Committing the setting with `gestate set N --local` is the other fix: everyone, CI included, then resolves the same way.

For PR-creation guards (Dependabot, Renovate) and adjacent layers, see [docs/complementary.md](docs/complementary.md).

## Development

```
uv sync
uv run pytest
```

Requires Python 3.11+, macOS or Linux.
