Metadata-Version: 2.4
Name: dotslot
Version: 0.5.0
Summary: Let agents fill the blanks in a file, and prove they touched nothing else.
License-Expression: MIT
Project-URL: Homepage, https://github.com/ao3575911/dotslot
Project-URL: Source, https://github.com/ao3575911/dotslot
Project-URL: Issues, https://github.com/ao3575911/dotslot/issues
Project-URL: Documentation, https://github.com/ao3575911/dotslot#readme
Project-URL: Changelog, https://github.com/ao3575911/dotslot/blob/main/CHANGELOG.md
Keywords: templates,fixed-width,ai-agents,mcp,pre-commit,lint
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wcwidth>=0.2.6
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: treesitter
Requires-Dist: tree-sitter>=0.23; extra == "treesitter"
Requires-Dist: tree-sitter-python; extra == "treesitter"
Requires-Dist: tree-sitter-javascript; extra == "treesitter"
Requires-Dist: tree-sitter-typescript; extra == "treesitter"
Requires-Dist: tree-sitter-go; extra == "treesitter"
Requires-Dist: tree-sitter-rust; extra == "treesitter"
Requires-Dist: tree-sitter-c; extra == "treesitter"
Requires-Dist: tree-sitter-java; extra == "treesitter"
Requires-Dist: tree-sitter-bash; extra == "treesitter"
Dynamic: license-file

[![M8ven Score](https://m8ven.ai/badge/mcp/ao3575911-dotslot-ia87ds?v=c3035f8aeacd04053e6285ac74d5eccb)](https://m8ven.ai/mcp/ao3575911-dotslot-ia87ds?s=readme)

```
dotslot: let agents fill the blanks, and prove they touched nothing else.

Owner: `<./owner:____________>`   Status: `<./status~:____________>`

$ dotslot fill release.md --set owner=Adam --set status="ready for tag" -i
$ dotslot check release.md --git-base HEAD
release.md: fill-safe (2 slot(s) changed)

CLI · pre-commit · GitHub Action · MCP server (Claude Code, Cursor, aider)
```

[![ci](https://github.com/ao3575911/dotslot/actions/workflows/ci.yml/badge.svg)](https://github.com/ao3575911/dotslot/actions/workflows/ci.yml) · MIT · v0.3.0 · [Spec](SPEC.md) · [Experiments](EXPERIMENTS.md) · [Changelog](CHANGELOG.md)

## What it is

Mark the parts of a file that may change with `<./________>`. An agent or script fills those blanks and nothing else. `dotslot check` proves the diff touched only the blanks, and that each blank kept its width, so columns and line wraps stay put. It works in docs, configs and code comments.

A file with slots is **fill-only**. That turns "don't touch the rest" into a rule a machine can check.

## Install

Install from PyPI:

```bash
pip install dotslot
dotslot --help
```

Requires Python 3.10+ and `wcwidth`.

## Use

```bash
dotslot new notes --width 26 --lines 3 --comment '# '   # generate a slot or block
dotslot scan FILE                                         # list slots, widths, capacity
dotslot fill FILE --set name=value -i                     # fill in place, width kept
dotslot check FILE --git-base HEAD [--allow a,b]          # prove only slots changed
dotslot check FILE --git-base HEAD --ignore-whitespace    # ...ignoring trailing whitespace outside slots
dotslot repad FILE --base OLD -i                          # restore padding after a hand edit
dotslot fit FILE --targets 80,100,120                     # where will lines wrap?
```

Slot forms: `<./______>` (unnamed), `<./owner:____>` (named), `<./status~:____>` (ellipsis on overflow). In Markdown, put slots in backticks. Full grammar: [SPEC.md](SPEC.md).

## Integrations

| tool | files | what it does |
|---|---|---|
| MCP server | `dotslot-mcp --root . [--allow a,b]` | `dotslot_scan`, `dotslot_fill`, `dotslot_check` over stdio; schema-validated arguments; `dry_run` diffs; per-call `allow`; fill verifies before writing; paths confined to root |
| Claude Code | [`integrations/claude-code/`](integrations/claude-code) | `.mcp.json`, a `PostToolUse` hook that exits 2 on a violation, and a skill |
| Cursor | [`integrations/cursor/.cursor/`](integrations/cursor/.cursor) | `mcp.json` and a fill-only rule |
| aider | [`integrations/aider/`](integrations/aider) | `lint-cmd: dotslot check --git-base HEAD` with auto-lint |
| any agent | [`integrations/AGENTS.md`](integrations/AGENTS.md) | snippet to paste into your `AGENTS.md` |
| pre-commit | [`.pre-commit-hooks.yaml`](.pre-commit-hooks.yaml) | `dotslot-check`, `dotslot-lint` |
| GitHub Action | [`action.yml`](action.yml) | checks PR files against the base SHA, writes a JSON report to the step summary |

Setup for each agent: [`integrations/README.md`](integrations/README.md).

pre-commit (run dotslot after formatters):

```yaml
- repo: https://github.com/ao3575911/dotslot
  rev: v0.3.1
  hooks:
    - id: dotslot-check
    - id: dotslot-lint
```

GitHub Action:

```yaml
- uses: actions/checkout@v5
  with: { fetch-depth: 0 }
- uses: ao3575911/dotslot@v0.3.1
  with: { files: "docs/**/*.md config/*.yaml", allow: "status,owner" }
```

Inputs: `files` (required), `allow`, `base` (default: the PR base SHA), `ignore-whitespace`, `report`
(default `dotslot-report.json`). The step summary lists violations and the JSON report (one array, one entry per
file). No matched files is a pass; a missing base revision is a failure.

## Limits

dotslot is a check, not a sandbox. The comment finder is a line heuristic unless you install `dotslot[treesitter]`; formatters such as gofmt can move columns, so run dotslot after them; trailing whitespace counts as a change unless you pass `--ignore-whitespace`. See [CHANGELOG.md](CHANGELOG.md) for open items and [PLAN.md](PLAN.md) for the roadmap.

## Repository layout

- `dotslot/`: the package (CLI, MCP server).
- `slot/`, `bin/slot`: the v0.1 reference, kept only so `experiments/run.sh` reproduces findings (a)–(g). Not installed.
- `tests/`: 70 tests (12 v0.1, 33 v0.2, 25 v0.3 including the h1–h9 exit gate). Run `pip install -e ".[test]" && pytest -q`.
- `experiments/`: `run.sh` (a–g) and `run_v02.sh` (v02, h, i), with recorded output in `out/`.

## Licence

MIT. See [LICENSE](LICENSE). Releases are GPG-signed in CI and carry SHA256SUMS and build provenance; see [RELEASING.md](RELEASING.md).
