claude-skills/marketplace
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

feat: evict closed issues from the local store

Browse Source 
The store is a working set, not an archive. Until now nothing removed a
closed issue from it: #10 put a filter on the write and said so explicitly
("existing store files are not cleaned"), and the migration was never
anybody's job. The only way out was rm past every script, followed by
rebuilding INDEX.md by hand.

issue_evict.py removes <id>.md and every sidecar under that slug for an
issue that is state: closed AND carries an origin: naming a tracker, then
rebuilds INDEX.md. --dry-run prints and writes nothing at all.

Two conditions, and the second one is the whole safety argument. An
origin: local issue IS the work — there is no other copy — so it is never
evicted, in any state, not even when named on the command line: it is
reported and kept. The only files that go are ones whose own metadata says
pull.py <n> brings them back, which is the trade push.py already makes
when it drops a file the tracker just confirmed.

The command lives in the domain layer, and the layering rule decides that
rather than convenience: state: and origin: are domain fields and the
answer is already on disk, so eviction needs no network, no login and no
tea. The domain also gains issue.slug_files — every file the store holds
under one slug, which is all_ids' "a slug has no dot in it" read the other
way round, and lets the domain remove an issue completely without learning
what a comment thread is.

skills/sync/scripts/evict.py is the bridge form, and it exists because a
local state: is only as fresh as the last pull: an issue closed in the web
UI still reads open here. It refreshes state: from Gitea, then calls
issue_evict.run — one implementation of "what may be evicted", in the
layer that owns the fields it reads. Same gate as push, one step earlier:
every candidate's state is fetched before anything is removed, each answer
must be an object carrying the number asked about and a state the domain
recognizes (confirmed_state, the counterpart of confirmed_number), and a
failed or unconfirmed call evicts nothing — not even the candidates whose
answers had already arrived, and no refreshed state: is written back
either. A candidate is an issue with a gitea: handle; origin: local has
none, is never asked about, and is never removed.

.remote.json is deliberately not pruned. It is the number -> slug ledger,
its entries are supposed to outlive the files they name, and an evicted
issue is in exactly the state a pushed one is.

AGENTS.md gains the rule the tracker side never wrote down: pull by number
fetches an issue in any state — an address is not a query. Eviction does
not revoke it, so a closed issue pulled after a cleanup is on disk again,
and that is the tracker answering what it was asked.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
naudachu
2026-08-10 17:28:13 +05:00
parent 2ac301550e
commit 2f82b501bd
10 changed files with 1088 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/sync/SKILL.md
+52
View File
@@ -40,6 +40,7 @@ the `tea-guard` hook reads. No pin → exit with a pointer to `/tea:auth`.
| `remote.py [--state] [--label] [--milestone] [-q TEXT]` | discovery: one line per Gitea issue to stdout, writes nothing |
| `pull.py <key…>` or `pull.py --milestone M \| --label L \| -q TEXT` | Gitea → `tmp/issues/<id>.md`, plus `<id>.comments.md` when the thread is not empty |
| `push.py [id…] [--update] [--dry-run]` | local → Gitea; validates first, **deletes the local file on success** and prints where it lives now |
| `evict.py [id…] [--dry-run]` | refresh `state:` from Gitea, then evict the issues it reports closed; `origin: local` is never asked about and never removed |
| `comment.py <id> --file F \| --body TEXT [--edit N]` | post or edit a comment, then refetch the thread |
| `labels.py [--dry-run] [--fix]` | bootstrap the canonical `type/*` + `severity/*` set in a repo; exact names left alone, lookalikes reported, drift fixed only with `--fix` |
| `map.py`, `_gitea.py` | the two layers the commands import — not commands |
@@ -308,6 +309,57 @@ a git repo no `ref` is sent and a warning names the issues that went up without
one. Reading the branch is the only thing these scripts ask git for — they
never check out, create, or write anything.
## Evicting what the tracker says is closed
```bash
python3 <skill-base-dir>/scripts/evict.py --dry-run # ask, report, change nothing
python3 <skill-base-dir>/scripts/evict.py # and remove them
python3 <skill-base-dir>/scripts/evict.py old-thing # just this one
```
Eviction itself belongs to `/tea:issue` (`issue_evict.py`) and is offline: the
decision is `state: closed` plus an `origin:` that names a tracker, both read
off the file. This script adds one thing in front of it — a `state:` that is not
stale — and then calls that same decision. There is one implementation of "what
may be evicted" and it is in the domain.
Why it exists: a local `state:` is only as fresh as the last pull, so an issue
closed in the web UI still reads `open` here and the offline command correctly
leaves it alone. The workaround was `pull.py 11 12 13 14 15` — which writes the
five closed files back to disk before anything can remove them.
Order of operations, and it is the safety argument:
1. every candidate's state is fetched — **all** of them, before anything is
removed;
2. each answer must be an object carrying the number that was asked about and a
state the domain recognizes (`evict.confirmed_state`, the counterpart of
`push.confirmed_number`);
3. only then does the eviction run.
**A failed call evicts nothing** — not even the candidates whose answers had
already arrived, and no refreshed `state:` is written back either. Stricter than
push, which deletes as it goes, and free: evictions have no order between them,
so there is no reason to start before every answer is in.
- A **candidate** is an issue carrying a `gitea:` handle. `origin: local` has
none, is never asked about, and is never removed. An `origin: gitea` issue
whose handle is missing or unparseable cannot be verified — it is reported on
stderr and kept.
- No `--repo`: the repo comes from each issue's own handle, so a store holding
issues from two repos is checked against both.
- One GET per candidate. The store is a working set that push keeps small, and a
wrong answer here deletes a file — so each issue is asked about by its own
address rather than inferred from a list a `--limit` could have truncated.
- A state that disagrees with the file is written back, so the store stops lying
about the issues that stay too. `--dry-run` makes no writes at all.
- `.remote.json` is not pruned; see [How the slug comes
back](#how-the-slug-comes-back) — an evicted issue is exactly as findable as a
pushed one.
- **`pull.py <n>` still fetches a closed issue.** A number is an address, not a
query. A closed issue pulled after an eviction is back on disk, and that is
the tracker answering the question it was asked, not a regression.
## What crosses the boundary, and what does not
| domain | Gitea | note |
skills/sync/scripts/evict.py
+164
View File
@@ -0,0 +1,164 @@
#!/usr/bin/env python3
"""
evict.py — ask Gitea which stored issues are closed, then evict those.
evict.py check every synced issue in the store, evict the
ones Gitea says are closed
evict.py old-thing … only these
evict.py --dry-run ask, report, change nothing
The offline command is `/tea:issue`'s `issue_evict.py`, and it is the one that
decides and deletes — this script adds exactly one thing in front of it: a
`state:` that is not stale. A local `state:` is only as fresh as the last pull,
so an issue closed in the web UI an hour ago still reads `open` here and the
offline command will (correctly) leave it alone. That is the gap this closes,
and it is the observed workflow: before this existed the operator had to
`pull.py 11 12 13 14 15` first, which re-wrote the five closed files onto disk
before anything could remove them.
Order of operations, and it is the whole safety argument:
1. every candidate's state is fetched — ALL of them, before anything is
removed;
2. each answer must be an object carrying the number we asked about and a
state from the domain's own vocabulary (`confirmed_state`);
3. only then is the eviction run, by handing the refreshed issues to
`issue_evict.run` — the same decision, the same deletion, the same
protection of `origin: local`, in one place.
A `tea` that will not run, a non-2xx, an answer for another issue, a state
nobody recognizes: the run stops at step 2 and NOTHING is deleted, not even the
issues whose answers had already arrived. That is stricter than `push.py`, which
deletes as it goes, and it costs nothing here — there is no ordering constraint
between evictions, so there is no reason to start before every answer is in.
A candidate is an issue carrying a `gitea:` handle. `origin: local` work has
none, is never asked about, and is never evicted — it is not in the tracker to
be closed. An `origin: gitea` issue whose handle is missing or unparseable
cannot be verified, so it is reported and kept rather than guessed at.
Cost: one GET per candidate. The store is a working set that push keeps small,
and a wrong answer here deletes a file, so each issue is asked about by its own
address rather than inferred from a list that a `--limit` could have truncated.
Login: the operator's pin from .claude/settings.local.json (see /tea:auth).
"""
import argparse
import os
import sys
_HERE = os.path.dirname(os.path.abspath(__file__))
sys.path[:0] = [_HERE, os.path.normpath(os.path.join(_HERE, "..", "..", "issue", "scripts"))]
import _gitea # noqa: E402
import issue # noqa: E402
import issue_evict # noqa: E402
import map as gmap # noqa: E402
def candidates(issues, ids=None):
"""(checkable, unverifiable) — which issues the tracker can be asked about.
checkable is [(id, repo, number)] read off the `gitea:` handle, so an issue
that lives in another repo is asked about there. unverifiable is
[(id, why)]: it names a tracker but carries no handle to reach it by, which
is a file to report, never one to delete on a guess.
An `origin: local` issue is in neither list. It has no handle because it has
never left this machine, and asking Gitea about it is not a question that
has an answer.
"""
checkable, unverifiable = [], []
for id in (list(ids) if ids else sorted(issues)):
iss = issues[id]
if iss.is_local:
continue
repo, number = gmap.parse_remote_key(iss.extra.get("gitea", ""))
if not repo or not number:
unverifiable.append((id, "origin: %s but no usable `gitea:` handle"
% iss.origin))
continue
checkable.append((id, repo, number))
return checkable, unverifiable
def confirmed_state(got, number):
"""The state Gitea confirmed for `number`, or None — the deletion gate.
The counterpart of `push.confirmed_number`, and written the same way: boring,
and saying no by default, because everything downstream of a `str` return
here may delete a file. An answer counts only when it is a dict, carries the
very number we asked about, and names a state the domain recognizes.
`bool` is rejected explicitly: `True` is an `int` in Python, and an answer
about issue `true` is not an answer about issue 42.
What it does not have to catch, because it never gets here: a non-2xx or a
`tea` that would not run at all — `_gitea.api` exits on both.
"""
if not isinstance(got, dict):
return None
n = got.get("number")
if isinstance(n, bool) or not isinstance(n, int) or n != number:
return None
state = got.get("state")
return state if state in issue.STATES else None
def main(argv=None):
ap = argparse.ArgumentParser(
description="Evict issues Gitea reports as closed from the local store")
ap.add_argument("ids", nargs="*",
help="issue ids (default: every synced issue in the store)")
ap.add_argument("--dry-run", action="store_true",
help="ask the tracker and report; write and delete nothing")
ap.add_argument("--out", default=issue.ISSUE_ROOT,
help="store root (default: <repo>/tmp/issues)")
args = ap.parse_args(argv)
root = args.out
if not issue.store_exists(root):
_gitea.die("store %s does not exist — nothing to evict" % root)
issues = issue.load_all(root)
missing = [i for i in args.ids if i not in issues]
if missing:
_gitea.die("no such issue(s) in the store: %s" % ", ".join(missing))
checkable, unverifiable = candidates(issues, args.ids)
for id, why in unverifiable:
_gitea.warn("%s: %s — kept, and not asked about" % (id, why))
if not checkable:
print("nothing to check: no issue in the store carries a `gitea:` handle")
return 0
login = _gitea.require_login()
# ---- every answer first, deletions after -----------------------------
fresh = {}
for id, repo, number in checkable:
got = _gitea.api(login, "%s/issues/%d" % (_gitea.repo_base(repo), number))
state = confirmed_state(got, number)
if state is None:
_gitea.die("%s: the tracker's answer for %s#%d does not confirm a state "
"(%.200r). Nothing was evicted."
% (id, repo, number, got))
fresh[id] = state
# The store stops lying even about the issues that stay: an answer already
# paid for is written back when it disagrees with the file. This is the only
# write this script makes, and a dry run makes none.
for id, state in sorted(fresh.items()):
was = issues[id].state
if was == state:
continue
print("state %s %s -> %s" % (id, was, state))
issues[id].state = state
if not args.dry_run:
issue.save(root, issues[id])
issue_evict.run(root, issues, [id for id, _, _ in checkable], args.dry_run)
return 0
if __name__ == "__main__":
sys.exit(main())