dotslot 0.2.1__tar.gz

dotslot-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ao3575911
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dotslot-0.2.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: dotslot
+Version: 0.2.1
+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: Changelog, https://github.com/ao3575911/dotslot/blob/main/CHANGELOG.md
+Keywords: templates,fixed-width,ai-agents,mcp,pre-commit,lint
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Quality Assurance
+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"
+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.2.1 · [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 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 .` | `dotslot_scan`, `dotslot_fill`, `dotslot_check` over stdio; 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 |
+
+pre-commit:
+
+```yaml
+- repo: https://github.com/ao3575911/dotslot
+  rev: v0.2.1
+  hooks: [{ id: dotslot-check }]
+```
+
+GitHub Action:
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- uses: ao3575911/dotslot@v0.2.1
+  with: { files: "docs/**/*.md config/*.yaml", allow: "status,owner" }
+```
+
+## Limits
+
+dotslot is a check, not a sandbox. The comment finder is a heuristic until tree-sitter lands; formatters such as gofmt can move columns, so run dotslot after them; trailing whitespace counts as a change. See [CHANGELOG.md](CHANGELOG.md) for open items and [PLAN.md](PLAN.md) for the roadmap.
+
+## Repository layout
+
+- `dotslot/`: the v0.2 package (CLI, MCP server).
+- `slot/`, `bin/slot`: the v0.1 reference, kept only so `experiments/run.sh` reproduces findings (a)–(g). Not installed.
+- `tests/`: 45 tests (12 v0.1, 33 v0.2). 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).

dotslot-0.2.1/README.md

@@ -0,0 +1,89 @@
+[![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.2.1 · [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 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 .` | `dotslot_scan`, `dotslot_fill`, `dotslot_check` over stdio; 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 |
+
+pre-commit:
+
+```yaml
+- repo: https://github.com/ao3575911/dotslot
+  rev: v0.2.1
+  hooks: [{ id: dotslot-check }]
+```
+
+GitHub Action:
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- uses: ao3575911/dotslot@v0.2.1
+  with: { files: "docs/**/*.md config/*.yaml", allow: "status,owner" }
+```
+
+## Limits
+
+dotslot is a check, not a sandbox. The comment finder is a heuristic until tree-sitter lands; formatters such as gofmt can move columns, so run dotslot after them; trailing whitespace counts as a change. See [CHANGELOG.md](CHANGELOG.md) for open items and [PLAN.md](PLAN.md) for the roadmap.
+
+## Repository layout
+
+- `dotslot/`: the v0.2 package (CLI, MCP server).
+- `slot/`, `bin/slot`: the v0.1 reference, kept only so `experiments/run.sh` reproduces findings (a)–(g). Not installed.
+- `tests/`: 45 tests (12 v0.1, 33 v0.2). 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).

dotslot-0.2.1/dotslot/__init__.py

@@ -0,0 +1,3 @@
+from .core import scan_text, fill_text, SlotError  # noqa
+from .verify import verify  # noqa
+__version__ = "0.2.1"

dotslot-0.2.1/dotslot/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())

dotslot-0.2.1/dotslot/cli.py

@@ -0,0 +1,204 @@
+"""dotslot scan | fill | check | fit"""
+from __future__ import annotations
+import argparse, json, subprocess, sys
+from .core import scan_text, fill_text, SlotError
+from .verify import verify
+from .width import layout, preview, legacy_ends, display_width
+
+def read(p): return sys.stdin.read() if p == '-' else open(p, encoding='utf-8').read()
+
+def parse_sets(items):
+    out = {}
+    for it in items or []:
+        k, sep, v = it.partition('=')
+        if not sep: raise SystemExit(f'--set needs name=value, got {it!r}')
+        out[k] = v
+    return out
+
+def cmd_scan(a):
+    rows = []
+    for p in a.files:
+        slots, issues = scan_text(read(p), p, a.mode)
+        for s in slots:
+            rows.append(dict(file=p, line=s.line + 1, col=s.col, index=s.index, name=s.name, role=s.role,
+                             width=s.width, lines=1 + len(s.conts), capacity=s.capacity + sum(c.capacity for c in s.conts),
+                             filled=s.filled, value=(s.block_value() if s.conts else s.value) if s.filled else None,
+                             policy=s.policy, in_comment=s.in_comment))
+        for sev, l, c, m in issues: print(f'{p}:{l+1}:{c}: {sev}: {m}', file=sys.stderr)
+    if a.json: print(json.dumps(rows, ensure_ascii=False, indent=1)); return 0
+    for r in rows:
+        v = '' if r['value'] is None else repr(r['value'])
+        print(f"{r['file']}:{r['line']}:{r['col']}  @{r['index']} {r['name'] or '-':12} {r['role']:6} "
+              f"w={r['width']:<3} x{r['lines']} cap={r['capacity']:<3} {'filled' if r['filled'] else 'empty ':6} "
+              f"{r['policy'] or '':8} {'#' if r['in_comment'] else ' '} {v}")
+    return 0
+
+def cmd_fill(a):
+    vals = parse_sets(a.set)
+    if a.json_values: vals.update(json.load(open(a.json_values)))
+    rc = 0
+    allow = set(a.allow.split(',')) if a.allow else None
+    for p in a.files:
+        try:
+            out = fill_text(read(p), vals, p, a.mode, a.overflow, tuple(a.clear or ()), allow)
+        except SlotError as e:
+            print(f'{p}: error: {e}', file=sys.stderr); rc = 2; continue
+        if a.in_place and p != '-':
+            open(p, 'w', encoding='utf-8').write(out)
+        else:
+            sys.stdout.write(out)
+    return rc
+
+def fit_report(text, path, mode, targets, tab, show_preview):
+    slots, _ = scan_text(text, path, mode)
+    lines = text.split('\n'); out = []; bad = {t: 0 for t in targets}
+    by_line = {}
+    for s in slots:
+        for x in [s] + s.conts: by_line.setdefault(x.line, []).append((s, x))
+    for li in sorted(by_line):
+        ln = lines[li]
+        cl = layout([(ln, 'line')], tab)
+        lw = cl[-1].col + cl[-1].width if cl else 0
+        leg = legacy_ends([(ln, 'line')], tab)[-1]
+        grows = any(h.policy == 'grow' for h, _ in by_line[li])
+        for head, x in by_line[li]:
+            end = display_width(ln[:x.end], 0, tab)
+            st = {}
+            for t in targets:
+                s_ = 'over' if end > t else 'pushes' if lw > t else 'maybe' if leg > t else 'ok'
+                st[t] = s_
+                if s_ != 'ok': bad[t] += 1
+            label = (head.name or f'@{head.index}') + ('' if x is head else f'[+{x.line - head.line}]')
+            out.append(f"{path}:{li+1}: slot {label} col {x.col}..{end} (line {lw}{'' if leg == lw else f', per-codepoint {leg}'})"
+                       f" {'grow' if grows else 'static'}  " + '  '.join(f'{t}:{v}' for t, v in st.items()))
+            if show_preview:
+                for t in targets:
+                    if st[t] in ('over', 'pushes') and (p := preview(cl, t)):
+                        out.append(f"    @{t}: {p['note']}" + (' (2-cell glyph straddles edge)' if p['straddle'] else ''))
+                        out.append(f"      word │{p['word'][0]}\n           │{p['word'][1]}")
+    return out, bad
+
+def cmd_fit(a):
+    targets = sorted(int(t) for t in a.targets.split(','))
+    rc = 0
+    for p in a.files:
+        text = read(p)
+        if a.set:
+            try: text = fill_text(text, parse_sets(a.set), p, a.mode, a.overflow)
+            except SlotError as e: print(f'{p}: error: {e}', file=sys.stderr); rc = 2; continue
+        out, bad = fit_report(text, p, a.mode, targets, a.tab, a.preview)
+        print('\n'.join(out)) if out else None
+        if bad.get(a.fail_at or targets[0]): rc = max(rc, 1)
+    return rc
+
+def base_text(a, p):
+    if a.base: return read(a.base)
+    if a.git_base:
+        r = subprocess.run(['git', 'show', f'{a.git_base}:./{p}'], capture_output=True, text=True,
+                           cwd=None)
+        return r.stdout if r.returncode == 0 else None   # new file: nothing to compare
+    return None
+
+def cmd_new(a):
+    pol = a.policy or ''
+    head = f'{a.name}{pol}:' if a.name else (f'{pol}:' if pol else '')
+    if a.width < len(head) + 1: raise SystemExit(f'width {a.width} leaves no room after {head!r}')
+    pre, post = a.comment, (' ' + CLOSE[a.comment.strip()] if a.comment.strip() in CLOSE else '')
+    lines = [pre + '<./' + head + a.pad * (a.width - len(head)) + '>' + post]
+    for _ in range(a.lines - 1):
+        lines.append(pre + '<./|' + a.pad * (a.width - 1) + '>' + post)
+    if a.md: lines = ['`' + l + '`' for l in lines]
+    print('\n'.join(lines)); return 0
+
+CLOSE = {'<!--': '-->', '/*': '*/'}
+
+def cmd_repad(a):
+    from .core import scan_text as sc, render
+    base, text = read(a.base), read(a.files[0])
+    bs, _ = sc(base, a.files[0], a.mode); ns, _ = sc(text, a.files[0], a.mode)
+    if len(bs) != len(ns): print('slot count differs; cannot repad', file=sys.stderr); return 2
+    lines = text.split('\n'); fixed = 0
+    for b, n in sorted(zip(bs, ns), key=lambda p: (p[1].line, -p[1].start)):
+        if b.width != n.width and not n.conts and b.policy != 'grow' and b.header == n.header:
+            if len(n.raw_value) and __import__('dotslot.width', fromlist=['cells']).cells(n.header + n.raw_value) <= b.width:
+                ln = lines[n.line]
+                lines[n.line] = ln[:n.start] + '<./' + render(n.header, n.raw_value, b.width, b.pad) + '>' + ln[n.end:]
+                fixed += 1
+    out = '\n'.join(lines)
+    if a.in_place: open(a.files[0], 'w', encoding='utf-8').write(out)
+    else: sys.stdout.write(out)
+    print(f'repadded {fixed} slot(s)', file=sys.stderr); return 0
+
+def cmd_check(a):
+    rc = 0
+    req = set((a.require or '').split(',')) - {''}
+    allow = set(a.allow.split(',')) if a.allow else None
+    reports = []
+    for p in a.files:
+        text = read(p)
+        b = base_text(a, p)
+        if b is not None:
+            r = verify(b, text, p, a.mode, allow); r['file'] = p; reports.append(r)
+            if not a.json:
+                for c in r['changed']: print(f"{p}:{c['line']}: filled {c['slot']}: {c['before']!r} -> {c['after']!r}")
+                for x in r['violations']: print(f'{p}: VIOLATION: {x}')
+                print(f"{p}: {'fill-safe' if r['ok'] else 'NOT fill-safe'} ({len(r['changed'])} slot(s) changed)")
+            if not r['ok']: rc = 1
+            continue
+        slots, issues = scan_text(text, p, a.mode)
+        probs = [(sev, l, c, m) for sev, l, c, m in issues]
+        for s in slots:
+            if (a.require_filled or (s.name in req)) and not s.filled:
+                probs.append(('E', s.line, s.col, f'{s.name or "@%d" % s.index} is empty'))
+        names = {s.name for s in slots}
+        for n in req - names: probs.append(('E', 0, 0, f'required slot {n!r} not found'))
+        if a.fit:
+            out, bad = fit_report(text, p, a.mode, [a.fit], a.tab, False)
+            for o in out:
+                if f'{a.fit}:ok' not in o: probs.append(('E', 0, 0, 'fit: ' + o.split(': ', 1)[1]))
+        for sev, l, c, m in probs:
+            if not a.json: print(f'{p}:{l+1}:{c}: {sev}: {m}')
+            if sev == 'E' or (a.strict and sev == 'W'): rc = 1
+        if not probs and not a.json: print(f'{p}: ok ({len(slots)} slots)')
+    if a.json: print(json.dumps(reports, ensure_ascii=False, indent=1))
+    return rc
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog='dotslot', description='fixed-width <./____> slots (v0.2)')
+    sub = ap.add_subparsers(dest='cmd', required=True)
+    def common(sp):
+        sp.add_argument('files', nargs='+')
+        sp.add_argument('--mode', choices=['auto', 'prose', 'comments'], default='auto',
+                        help='auto: bare slots only in prose files (.md .txt …); everything else comment-only')
+    s = sub.add_parser('scan'); common(s); s.add_argument('--json', action='store_true')
+    for name in ('fill', 'fit'):
+        f = sub.add_parser(name); common(f)
+        f.add_argument('--set', action='append', help='name=value or @N=value')
+        f.add_argument('--overflow', choices=['error', 'ellipsis', 'truncate', 'grow'], default='error',
+                       help='policy for slots without a !/~/+ marker')
+        f.add_argument('--allow', help='comma list of slot names/@N that may be filled')
+        if name == 'fill':
+            f.add_argument('--json-values'); f.add_argument('-i', '--in-place', action='store_true')
+            f.add_argument('--clear', action='append', help='empty a slot again (name or @N)')
+        else:
+            f.add_argument('--targets', default='80,100,120'); f.add_argument('--tab', type=int, default=8)
+            f.add_argument('--preview', action='store_true'); f.add_argument('--fail-at', type=int)
+    n = sub.add_parser('new', help='print a correctly sized slot or block')
+    n.add_argument('name', nargs='?'); n.add_argument('--width', type=int, required=True)
+    n.add_argument('--lines', type=int, default=1); n.add_argument('--policy', choices=['!', '~', '+'])
+    n.add_argument('--comment', default='', help="prefix such as '# ' or '<!-- '"); n.add_argument('--pad', default='_')
+    n.add_argument('--md', action='store_true', help='wrap in backticks (Markdown code span)')
+    n.set_defaults(indent_only=False)
+    r = sub.add_parser('repad', help='restore slot widths from a base file (fixes agents that drop padding)')
+    r.add_argument('files', nargs=1); r.add_argument('--base', required=True); r.add_argument('-i', '--in-place', action='store_true')
+    r.add_argument('--mode', choices=['auto', 'prose', 'comments'], default='auto')
+    c = sub.add_parser('check'); common(c)
+    c.add_argument('--require', help='comma list of names that must be filled')
+    c.add_argument('--require-filled', action='store_true'); c.add_argument('--strict', action='store_true')
+    c.add_argument('--fit', type=int, help='also fail lines wider than N cells'); c.add_argument('--tab', type=int, default=8)
+    c.add_argument('--base', help='fill-safe check: compare against this earlier version of the file')
+    c.add_argument('--git-base', help='fill-safe check against a git revision (e.g. HEAD, origin/main)')
+    c.add_argument('--allow', help='with --base: only these slots may change')
+    c.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+    return dict(scan=cmd_scan, fill=cmd_fill, check=cmd_check, fit=cmd_fit, new=cmd_new, repad=cmd_repad)[a.cmd](a)