Metadata-Version: 2.4
Name: gestate
Version: 1.0.1
Summary: Set a minimum release age on local package managers to defend against zero-day supply chain attacks.
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: 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 revert           # remove gestate's settings
uvx gestate explain bun      # show how one tool's setting is stored
```

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"`) |

`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

## 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.

## Allowlists

If you publish packages of your own and want them exempt from the delay, see [docs/allowlists.md](docs/allowlists.md). Most managers support an exclude list; npm and pip don't yet.

## 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 exclude**: tracked in [npm/cli#8994](https://github.com/npm/cli/issues/8994).
- **pip exclude**: none — `global.uploaded-prior-to` is global only.

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.
