Metadata-Version: 2.4
Name: pywrit
Version: 0.1.10
Summary: Writ — the gate before the write. Allow/deny gate with a tamper-evident audit log
Project-URL: Homepage, https://withwrit.com
Project-URL: Documentation, https://docs.withwrit.com
Keywords: agents,audit-log,authorization,api-keys
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: polyglot
Requires-Dist: tree-sitter>=0.23; extra == "polyglot"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "polyglot"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "polyglot"
Dynamic: license-file

# pywrit

The Writ CLI — the gate before the write.

```bash
pip install pywrit
writ key --email you@company.com
```

**Find the consequential writes your agents can perform.** `writ scan .` is a
free, local scan (no API key) that lists the writes it finds in your agent code. Then gate
them: Writ is an allow/deny gate you put in front of your agent's writes, and each check
writes a tamper-evident receipt to your audit log. No more wondering who called what, or when.

![writ scan finds 4 writes in a Python agent; writ scan --apply gates all of them](https://withwrit.com/assets/scan-python.gif)

## What it does

- `writ key` — Get a free API key (1,000 receipts/month, no card)
- `writ check` — Ask the gate before a write (ALLOW or DENY)
- `writ revoke` — Kill switch: revoke a principal's tokens in one click
- `writ receipts` — See your audit log
- `writ scan` — Find writes in your repo (Python: scan + instrument; TS/JS: scan only)

## Scanning a repo

```bash
writ scan ./my-repo                       # report writes, print the diff, write writ-policy.json
writ scan ./my-repo --apply               # prompt, then insert gates (Python files only)
pip install 'pywrit[polyglot]'            # optional: also scan TypeScript / JavaScript
```

![writ scan on a TypeScript support agent: 1 of 5 write sites gated](https://withwrit.com/assets/scan-tsjs.gif)

- **Python** (`.py`): parsed with the stdlib `ast`, no extra dependencies.
  Finds DB calls, HTTP clients, file writes, email, queues, and AWS SDK
  writes. `writ scan --apply` inserts a `_writ_check(...)` gate at the top of
  each writing function.
- **TypeScript / JavaScript** (`.ts .tsx .js .jsx .mjs .cjs`): **scan only**,
  never rewritten, and needs the `polyglot` extra (tree-sitter). Without it,
  `writ scan` prints a one-line install hint and keeps scanning Python.
  Each finding is listed as `file:line [category] rule function(): snippet`,
  and its verb goes into `writ-policy.json` like a Python finding. Detected:
  - HTTP: `fetch` / `axios` / `got` / `ky` / `superagent` with a literal
    `POST`/`PUT`/`PATCH`/`DELETE` method, `axios.post|put|patch|delete`,
    `http(s).request` with a write method
  - Files: `fs.writeFile`, `appendFile`, `unlink`, `rm`, `rename`, `mkdir`, …
    plus `Sync` and `fs/promises` variants
  - SQL: literal `INSERT`/`UPDATE`/`DELETE`/`DROP`/`ALTER`/… strings passed to
    `query` / `execute` / `raw` (including tagged templates such as
    `prisma.$executeRaw`)
  - SDKs: Stripe `create|update|del` (e.g. `stripe.refunds.create`), Prisma
    `create|update|upsert|delete|deleteMany|updateMany`, knex/db builders
    `insert|update|del`, `child_process` `exec`/`spawn`
  - A function that already calls `writCheck(...)` / `writ_check(...)` counts
    as gated.
- Skipped: `node_modules`, `dist`, `build`, hidden dirs such as `.git` and
  `.next`, virtualenvs, and test files. TS/JS scanning also skips `vendor`,
  `*.d.ts`, `*.min.js`, and files over 1 MB, and respects `.gitignore` when
  the repo is a git checkout.
- TS/JS limitations: calls are matched by name, so HTTP methods, SQL strings,
  or options held in variables (`fetch(url, opts)`, `db.query(sql)`) are not
  detected, and route definitions like `router.post(...)` are deliberately
  not flagged. The Writ Score grades Python findings only; the
  `ts/js gated: N/M` line is the TS/JS coverage number.

## Docs

Full docs at [docs.withwrit.com](https://docs.withwrit.com). Quickstart at [docs.withwrit.com/quickstart](https://docs.withwrit.com/quickstart).

---

## Packaging notes (for maintainers)

Installable distribution of the Writ CLI. `pip install pywrit` gives you the
`writ` command — no `curl` + `chmod` dance.

### Layout

- `pyproject.toml` — package metadata, `writ` console-script entry point
- `writ_cli/__init__.py` — version
- `writ_cli/cli.py` — the CLI itself (stdlib-only: argparse, json, urllib;
  TS/JS scanning imports tree-sitter only when the `polyglot` extra is installed)
- `tests/` — scanner tests: `python -m unittest discover -s tests`
- Demo GIFs: recorded with [VHS](https://github.com/charmbracelet/vhs) from
  `docs/tapes/*.tape` (repo root: `docs/tapes/render.sh`)

### Relationship to `gate/web/writ`

`gate/web/writ` is the **self-contained single-file script** served by the Lambda
at `/writ` (the `curl -fsSL ... -o writ` download path). It must stay a single
file with no install step.

`writ_cli/cli.py` is the **PyPI package source**. The two files are currently
byte-identical by copy. If you change CLI behavior, update **both** and keep
them in sync — the download path and the pip path must behave the same.

### Build & test locally

```bash
cd cli
python -m build                    # needs `pip install build`
pip install -e .                   # editable install, creates the `writ` command
writ --help
```

### Publish

```bash
cd cli
python -m build
twine upload dist/*
```
