@caddis/cli 0.4.97 → 0.4.99
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -0
- package/bundles/antigravity-plugin/plugin.json +1 -1
- package/bundles/antigravity-plugin/repo_hygiene.py +134 -20
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/caddis_gate.py +18 -1
- package/bundles/antigravity-plugin/scripts/caddis_guide.json +2 -2
- package/bundles/antigravity-plugin/scripts/caddis_handoff.py +235 -0
- package/bundles/antigravity-plugin/scripts/caddis_hub_collect.py +23 -12
- package/bundles/antigravity-plugin/scripts/caddis_review.py +12 -0
- package/bundles/antigravity-plugin/scripts/caddis_tidy.py +152 -51
- package/bundles/antigravity-plugin/scripts/caddis_todo.py +136 -17
- package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +60 -1
- package/bundles/antigravity-plugin/scripts/schemas/hub-plans.schema.json +60 -1
- package/bundles/antigravity-plugin/scripts/setup_project_ai.py +60 -2
- package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +6 -0
- package/bundles/antigravity-plugin/skills/handoff/SKILL.md +80 -15
- package/bundles/antigravity-plugin/skills/implement/SKILL.md +6 -0
- package/bundles/antigravity-plugin/skills/park/SKILL.md +7 -2
- package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md +1 -0
- package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md +1 -0
- package/bundles/manifest.json +2 -2
- package/dist/cli.js +451 -170
- package/dist/export/assets/export-B3cUoxL1.js +150 -0
- package/dist/export/assets/export-DQss44R1.css +1 -0
- package/dist/export/index.html +2 -2
- package/dist/ui/assets/Activity-D69HiVjS.js +6 -0
- package/dist/ui/assets/{Guide-D-lZVEKf.js → Guide-BUXTwb19.js} +1 -1
- package/dist/ui/assets/Guide-DTd261-c.css +1 -0
- package/dist/ui/assets/RoadmapTab-CjYa5fye.js +31 -0
- package/dist/ui/assets/index--fRgH-8i.js +236 -0
- package/dist/ui/assets/index-9pdDzLVp.css +1 -0
- package/dist/ui/index.html +2 -2
- package/package.json +1 -1
- package/dist/export/assets/export-B5Lzo-9e.css +0 -1
- package/dist/export/assets/export-PF4z_ff4.js +0 -150
- package/dist/ui/assets/Activity-DN1XBfsH.js +0 -6
- package/dist/ui/assets/Guide-D-Zy4cUT.css +0 -1
- package/dist/ui/assets/RoadmapTab-tqQd2sYq.js +0 -31
- package/dist/ui/assets/index-CWslZIzV.js +0 -231
- package/dist/ui/assets/index-CwgRPpjT.css +0 -1
- package/dist/ui/assets/time-D00tu2ZP.js +0 -1
package/README.md
CHANGED
|
@@ -137,6 +137,10 @@ the prompt for CI.
|
|
|
137
137
|
A local web page (127.0.0.1 only) with your repos, PRs, plans and live sessions. `caddis hub start`
|
|
138
138
|
starts it in the background; `caddis hub stop` stops it.
|
|
139
139
|
|
|
140
|
+
**Updates by itself.** A running hub checks npm for a new `@caddis/cli` 60 s after it starts, then every 30 minutes. When a newer version is published, the hub installs it (`npm i -g @caddis/cli@<version>`), checks the installed version, and restarts on the same port. Open tabs show "caddis hub updated to X, reloading" and reload. A manual `npm i -g @caddis/cli` also restarts the hub within a minute. A failed install keeps the old hub running and tries again after an hour. Only a hub that runs from the global npm install installs updates: a hub from a dev checkout or `npx` only logs "update available". To check and log only, set `"auto_update": false` in `~/.caddis/hub/config.json`. Each step goes to `~/.caddis/hub/hub.log`.
|
|
141
|
+
|
|
142
|
+
**Start at logon.** `caddis hub autostart enable` starts the hub after each logon, so it comes back after a reboot. On Windows it creates the logon task `caddis-hub`. When Windows refuses the task ("Access is denied" for a user who is not an administrator), it puts `caddis-hub.vbs` in your Startup folder instead, and the message says which one it used. `caddis hub autostart status` shows which is in place; `caddis hub autostart disable` removes both.
|
|
143
|
+
|
|
140
144
|
**Logins that last.** Run `caddis hub open` to get a one-time login code and open the hub. Your session lasts 7 days without use and 30 days at most, and it survives a hub restart.
|
|
141
145
|
|
|
142
146
|
**Timeline first, Board second.** Roadmaps and plans open on the Timeline view by default, with the Board view as the second option. Click any phase tile on the Timeline to open the phase panel and read its Tracker status, PR links and plan section text.
|
|
@@ -3,13 +3,13 @@
|
|
|
3
3
|
Plan: `.caddis/plans/repo-hygiene-report.md` (Phase 3). `repo_freshness._report` calls `report_lines()`, so Claude
|
|
4
4
|
Code, Codex and agy all get the report through one function, one process and one time budget.
|
|
5
5
|
|
|
6
|
-
REPORT ONLY. Nothing here deletes, moves or changes anything. The
|
|
7
|
-
`<git-common-dir>/caddis-hygiene-prs.json`. Removal is `caddis_tidy.py --hygiene --apply`, which re-proves every
|
|
6
|
+
REPORT ONLY. Nothing here deletes, moves or changes anything. The only files it writes are the gh cache
|
|
7
|
+
`<git-common-dir>/caddis-hygiene-prs.json` and the Orca cache `~/.caddis/orca-worktrees.json`. Removal is `caddis_tidy.py --hygiene --apply`, which re-proves every
|
|
8
8
|
candidate with the deletion-grade test in `caddis_finished.py`.
|
|
9
9
|
|
|
10
10
|
Every decision lives in `caddis_finished.py` (stdlib only). This module holds the I/O and the formatting. Every git
|
|
11
|
-
call goes through the `git(cwd, *args) -> (code, stdout)` seam (`repo_freshness._git` in the hook). gh
|
|
12
|
-
through a `subprocess.run`-shaped seam
|
|
11
|
+
call goes through the `git(cwd, *args) -> (code, stdout)` seam (`repo_freshness._git` in the hook). gh goes
|
|
12
|
+
through a `subprocess.run`-shaped seam and orca through a `Popen`-shaped one; neither opens a console window.
|
|
13
13
|
"""
|
|
14
14
|
from __future__ import annotations
|
|
15
15
|
|
|
@@ -49,6 +49,14 @@ PR_CACHE_MAX_AGE_S = 600 # the same as repo_freshness.FETCH_MAX_AGE_S
|
|
|
49
49
|
GH_FIELDS = "headRefName,state,number,headRefOid"
|
|
50
50
|
GH_TIMEOUT_S = 5.0 # the most gh may take; less when less of the session-start budget is left
|
|
51
51
|
ORCA_TIMEOUT_S = 3.0 # the same for orca
|
|
52
|
+
# Orca lists the worktrees of every repo, so one cache under ~/.caddis serves all repos. A cold `orca worktree
|
|
53
|
+
# list` took 9.5 s on the owner's server (warm: 0.66 s), so a slow call is never killed: it keeps writing its
|
|
54
|
+
# `orca-worktrees.<pid>.out` file, and the next session start promotes that file to the cache.
|
|
55
|
+
ORCA_CACHE_NAME = "orca-worktrees.json"
|
|
56
|
+
ORCA_CACHE_FRESH_S = 600 # a younger cache answers with no orca call
|
|
57
|
+
ORCA_CACHE_MAX_AGE_S = 86400 # an older cache is never used
|
|
58
|
+
ORCA_PARTIAL_MAX_AGE_S = 3600 # an unreadable .out file older than this is a dead call: delete it
|
|
59
|
+
ORCA_CLOCK_SKEW_S = 60 # a cache this far in the "future" is still used (clock resolution); more is not
|
|
52
60
|
NO_TIME_LEFT = "no time left in the session-start budget"
|
|
53
61
|
|
|
54
62
|
# No child opens a console window on Windows; git never takes an optional lock or asks for a credential.
|
|
@@ -249,22 +257,18 @@ def fetch_prs(top: Path, git_dir: Path, run: Callable, now: float,
|
|
|
249
257
|
return prs, ""
|
|
250
258
|
|
|
251
259
|
|
|
252
|
-
def
|
|
253
|
-
"""
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
except (OSError, subprocess.SubprocessError) as exc:
|
|
263
|
-
return None, f"orca could not start: {exc}"
|
|
264
|
-
if proc.returncode != 0:
|
|
265
|
-
return None, _last_line(proc, "orca")
|
|
260
|
+
def _start_orca(argv: list[str], out: Path, err: Path) -> subprocess.Popen:
|
|
261
|
+
"""The default orca seam: start `argv` with stdout to `out` and stderr to `err`, and do not wait. The caller
|
|
262
|
+
waits with `proc.wait(timeout)`. On a timeout nothing kills the child: it finishes and fills `out`."""
|
|
263
|
+
with open(out, "wb") as fo, open(err, "wb") as fe:
|
|
264
|
+
return subprocess.Popen(argv, stdout=fo, stderr=fe, stdin=subprocess.DEVNULL,
|
|
265
|
+
env={**os.environ, **_ENV_OVERRIDES}, creationflags=_NO_WINDOW)
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def _parse_orca(text: str) -> tuple[dict[str, str] | None, str]:
|
|
269
|
+
"""`orca worktree list --json` output -> (path key -> Orca id, "") or (None, reason)."""
|
|
266
270
|
try:
|
|
267
|
-
data = json.loads(
|
|
271
|
+
data = json.loads(text)
|
|
268
272
|
except ValueError:
|
|
269
273
|
return None, "orca returned unreadable JSON"
|
|
270
274
|
if not isinstance(data, dict) or data.get("ok") is not True:
|
|
@@ -281,6 +285,115 @@ def orca_worktrees(run: Callable, which: Callable, timeout_s: float = ORCA_TIMEO
|
|
|
281
285
|
return mapping, ""
|
|
282
286
|
|
|
283
287
|
|
|
288
|
+
def _read_text(path: Path) -> str | None:
|
|
289
|
+
try:
|
|
290
|
+
return path.read_text(encoding="utf-8", errors="replace")
|
|
291
|
+
except OSError:
|
|
292
|
+
return None
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def _remove(*paths: Path) -> None:
|
|
296
|
+
for p in paths:
|
|
297
|
+
try:
|
|
298
|
+
p.unlink()
|
|
299
|
+
except OSError:
|
|
300
|
+
pass # gone already, or still open: a later session start removes it
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def _promote_finished(cache_dir: Path, now: float) -> None:
|
|
304
|
+
"""Move the newest complete `orca-worktrees.<pid>.out` (from an earlier slow call) over the cache. Delete the
|
|
305
|
+
complete ones it does not use, and unreadable ones older than ORCA_PARTIAL_MAX_AGE_S. A young unreadable file is
|
|
306
|
+
a call that still runs: leave it."""
|
|
307
|
+
complete: list[tuple[float, Path]] = []
|
|
308
|
+
for out in cache_dir.glob("orca-worktrees.*.out"):
|
|
309
|
+
err = out.with_suffix(".err")
|
|
310
|
+
try:
|
|
311
|
+
mtime = out.stat().st_mtime
|
|
312
|
+
except OSError:
|
|
313
|
+
continue
|
|
314
|
+
text = _read_text(out)
|
|
315
|
+
if text is not None and _parse_orca(text)[0] is not None:
|
|
316
|
+
complete.append((mtime, out))
|
|
317
|
+
elif now - mtime > ORCA_PARTIAL_MAX_AGE_S:
|
|
318
|
+
_remove(out, err)
|
|
319
|
+
complete.sort(reverse=True)
|
|
320
|
+
cache = cache_dir / ORCA_CACHE_NAME
|
|
321
|
+
for i, (mtime, out) in enumerate(complete):
|
|
322
|
+
try:
|
|
323
|
+
newer = i == 0 and (not cache.exists() or mtime > cache.stat().st_mtime)
|
|
324
|
+
if newer:
|
|
325
|
+
os.replace(out, cache)
|
|
326
|
+
except OSError:
|
|
327
|
+
newer = False
|
|
328
|
+
if not newer:
|
|
329
|
+
_remove(out)
|
|
330
|
+
_remove(out.with_suffix(".err"))
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
def _read_orca_cache(cache_dir: Path, now: float) -> tuple[dict[str, str] | None, float]:
|
|
334
|
+
"""(mapping, age in seconds) from the cache, or (None, 0) when it is missing, unreadable or too old."""
|
|
335
|
+
cache = cache_dir / ORCA_CACHE_NAME
|
|
336
|
+
try:
|
|
337
|
+
age = now - cache.stat().st_mtime
|
|
338
|
+
except OSError:
|
|
339
|
+
return None, 0.0
|
|
340
|
+
text = _read_text(cache)
|
|
341
|
+
# time.time() can lag a file's mtime by a few ms on Windows, so a just-written cache can look a little "future"
|
|
342
|
+
if text is None or not -ORCA_CLOCK_SKEW_S <= age < ORCA_CACHE_MAX_AGE_S:
|
|
343
|
+
return None, 0.0
|
|
344
|
+
return _parse_orca(text)[0], max(age, 0.0)
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
def orca_worktrees(start: Callable, which: Callable, timeout_s: float = ORCA_TIMEOUT_S,
|
|
348
|
+
cache_dir: Path | None = None, now: float | None = None) -> tuple[dict[str, str] | None, str]:
|
|
349
|
+
"""Every path Orca manages -> its Orca id, keyed by `_key(path)`. (None, reason) when Orca cannot answer
|
|
350
|
+
completely: not on PATH, a non-zero exit, bad JSON, `ok` false, or `result.truncated` true.
|
|
351
|
+
|
|
352
|
+
A cache younger than ORCA_CACHE_FRESH_S answers with no orca call. Otherwise orca runs, and the hook waits at
|
|
353
|
+
most `timeout_s`. When orca is slower, the last cache (up to ORCA_CACHE_MAX_AGE_S old) answers; with no cache it
|
|
354
|
+
is a skip. The slow call is not killed, so the next session start has a fresh cache."""
|
|
355
|
+
now = time.time() if now is None else now
|
|
356
|
+
cache_dir = Path.home() / ".caddis" if cache_dir is None else Path(cache_dir)
|
|
357
|
+
try:
|
|
358
|
+
cache_dir.mkdir(parents=True, exist_ok=True)
|
|
359
|
+
_promote_finished(cache_dir, now)
|
|
360
|
+
except OSError:
|
|
361
|
+
pass # no cache this time: orca still answers below
|
|
362
|
+
cached, age = _read_orca_cache(cache_dir, now)
|
|
363
|
+
if cached is not None and age < ORCA_CACHE_FRESH_S:
|
|
364
|
+
return cached, ""
|
|
365
|
+
exe = which("orca")
|
|
366
|
+
if not exe:
|
|
367
|
+
return None, "orca not on PATH"
|
|
368
|
+
out = cache_dir / f"orca-worktrees.{os.getpid()}.out"
|
|
369
|
+
err = out.with_suffix(".err")
|
|
370
|
+
try:
|
|
371
|
+
proc = start([exe, "worktree", "list", "--limit", "10000", "--json"], out, err)
|
|
372
|
+
except (OSError, subprocess.SubprocessError) as exc:
|
|
373
|
+
return None, f"orca could not start: {exc}"
|
|
374
|
+
try:
|
|
375
|
+
code = proc.wait(timeout=timeout_s)
|
|
376
|
+
except subprocess.TimeoutExpired:
|
|
377
|
+
if cached is not None:
|
|
378
|
+
return cached, ""
|
|
379
|
+
return None, f"orca took longer than {timeout_s:g} s (its answer is cached for the next session start)"
|
|
380
|
+
text, err_text = _read_text(out) or "", _read_text(err) or ""
|
|
381
|
+
if code != 0:
|
|
382
|
+
_remove(out, err)
|
|
383
|
+
last = err_text.strip() or text.strip()
|
|
384
|
+
return None, last.splitlines()[-1].strip() if last else f"orca exited {code}"
|
|
385
|
+
mapping, reason = _parse_orca(text)
|
|
386
|
+
if mapping is None:
|
|
387
|
+
_remove(out, err)
|
|
388
|
+
return None, reason
|
|
389
|
+
try:
|
|
390
|
+
os.replace(out, cache_dir / ORCA_CACHE_NAME)
|
|
391
|
+
except OSError:
|
|
392
|
+
_remove(out)
|
|
393
|
+
_remove(err)
|
|
394
|
+
return mapping, ""
|
|
395
|
+
|
|
396
|
+
|
|
284
397
|
def orca_id(mapping: dict[str, str] | None, path: str) -> str | None:
|
|
285
398
|
"""The Orca id of `path`, matched case- and slash-insensitively; None when Orca does not manage it."""
|
|
286
399
|
return mapping.get(_key(path)) if mapping else None
|
|
@@ -448,7 +561,8 @@ def start_jobs(top: Path, git: Callable, remaining: Callable[[], float], *, want
|
|
|
448
561
|
gh = (pool.submit(fetch_prs, main, git_dir, _run, time.time(), gh_s) if gh_s > 0
|
|
449
562
|
else _done((None, NO_TIME_LEFT)))
|
|
450
563
|
if any_linked:
|
|
451
|
-
orca = pool.submit(orca_worktrees,
|
|
564
|
+
orca = (pool.submit(orca_worktrees, _start_orca, _which, orca_s, home / ".caddis") if orca_s > 0
|
|
565
|
+
else _done((None, NO_TIME_LEFT)))
|
|
452
566
|
finally:
|
|
453
567
|
pool.shutdown(wait=False) # the submitted calls still run; their timeouts bound them
|
|
454
568
|
return Jobs(main, roots, any_linked, gh, orca)
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc
CHANGED
|
Binary file
|
|
@@ -712,14 +712,28 @@ def review_tier(files: list[tuple[str, int]], plan_risk: str = "normal") -> str:
|
|
|
712
712
|
return "1"
|
|
713
713
|
|
|
714
714
|
|
|
715
|
+
def area_reviewers(files: list[tuple[str, int]], phase_type: str | None = None) -> list[str]:
|
|
716
|
+
"""Area reviewers for a diff: `security-analyst` when the auth trigger fires on a non-tier-0 path,
|
|
717
|
+
`ui-design-reviewer` when the plan phase's Type is `ui`. Never both for the wrong reason: docs and tests are tier 0."""
|
|
718
|
+
non_tier0 = [(p, lines) for p, lines in files if not is_tier0_file(p)]
|
|
719
|
+
names = []
|
|
720
|
+
fired = review_triggers([p for p, _ in non_tier0], 0)
|
|
721
|
+
if any(label == "auth" for label, _, _ in fired):
|
|
722
|
+
names.append("security-analyst")
|
|
723
|
+
if (phase_type or "").strip().lower() == "ui":
|
|
724
|
+
names.append("ui-design-reviewer")
|
|
725
|
+
return names
|
|
726
|
+
|
|
727
|
+
|
|
715
728
|
def gate_review_tier(
|
|
716
729
|
repo_root: Path,
|
|
717
730
|
rev_range: str | None = None,
|
|
718
731
|
plan: Path | str | None = None,
|
|
719
732
|
phase: int | str | None = None,
|
|
720
733
|
) -> int:
|
|
721
|
-
"""Print the tier
|
|
734
|
+
"""Print the tier, reviewer count and area reviewers for the diff and plan phase."""
|
|
722
735
|
risk = "normal"
|
|
736
|
+
ptype = None
|
|
723
737
|
if plan and phase is None:
|
|
724
738
|
risk = "high" # fail closed: a plan without a phase cannot give a risk
|
|
725
739
|
elif plan and phase is not None:
|
|
@@ -730,6 +744,7 @@ def gate_review_tier(
|
|
|
730
744
|
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
731
745
|
import caddis_review
|
|
732
746
|
risk = caddis_review.phase_risk(Path(plan), phase)
|
|
747
|
+
ptype = caddis_review.phase_type(Path(plan), phase)
|
|
733
748
|
except Exception:
|
|
734
749
|
# Fail closed: a plan risk we cannot read counts as high (tier 2).
|
|
735
750
|
risk = "high"
|
|
@@ -739,11 +754,13 @@ def gate_review_tier(
|
|
|
739
754
|
sys.stderr.write(f"caddis-gate: review-tier could not read the diff ({exc}); counting it as tier 2\n")
|
|
740
755
|
print("TIER: 2")
|
|
741
756
|
print("REVIEWERS: 1")
|
|
757
|
+
print("AREA: none")
|
|
742
758
|
return EXIT_OK
|
|
743
759
|
tier = review_tier(files, plan_risk=risk)
|
|
744
760
|
reviewers = TIER_REVIEWERS.get(tier, 1)
|
|
745
761
|
print(f"TIER: {tier}")
|
|
746
762
|
print(f"REVIEWERS: {reviewers}")
|
|
763
|
+
print(f"AREA: {', '.join(area_reviewers(files, ptype)) or 'none'}")
|
|
747
764
|
return EXIT_OK
|
|
748
765
|
|
|
749
766
|
|
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
"""The checkpoint tier of /caddis:handoff: a cheap mid-phase handoff in two calls.
|
|
2
2
|
|
|
3
|
+
`tidy-targets --own-files <f> [--root <dir>]` (full handoff Step 4) prints the finished top-level plans, prompts
|
|
4
|
+
and parking-lot items in this session's own-files list, one per line, for `caddis_tidy.py --apply --only`.
|
|
5
|
+
`carry --to <worktree> <path>...` (Step 4 on the default branch) copies those files, with their uncommitted edits,
|
|
6
|
+
into the docs-PR worktree; it never changes this checkout. `release --branch <docs-pr branch> <path>...` then restores
|
|
7
|
+
each one here, only when the pushed branch holds its moved copy, so no edit is lost and no move stays staged here.
|
|
8
|
+
|
|
3
9
|
PREPARE (`checkpoint --session-id <id> [--name <ws>] [--plan <path> --phase <id>]`) reads the relay hash
|
|
4
10
|
BEFORE the model composes the new relay, and prints the exact FINISH command. FINISH (`--relay-file` given)
|
|
5
11
|
writes the relay with `put --require-status --expected-hash`, so a peer's change made in between is never
|
|
@@ -369,6 +375,215 @@ def _after_put(args: argparse.Namespace, name: str, rows: dict[str, str], state:
|
|
|
369
375
|
return 0
|
|
370
376
|
|
|
371
377
|
|
|
378
|
+
_TIDY_KINDS = ("plans", "prompts", "parking-lot")
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def _caddis_rel(raw: str) -> str | None:
|
|
382
|
+
"""`.caddis/<kind>/<file>.md` for an own-files line that names a top-level plan, prompt or parking-lot
|
|
383
|
+
file, whichever checkout it was edited in (this one, or the Step 0 worktree); else None."""
|
|
384
|
+
item = raw.strip()
|
|
385
|
+
if item.startswith("- "):
|
|
386
|
+
item = item[2:].strip()
|
|
387
|
+
if len(item) >= 2 and item.startswith("`") and item.endswith("`"):
|
|
388
|
+
item = item[1:-1]
|
|
389
|
+
norm = "/" + item.replace("\\", "/").lstrip("/")
|
|
390
|
+
at = norm.rfind("/.caddis/")
|
|
391
|
+
if at < 0:
|
|
392
|
+
return None
|
|
393
|
+
parts = norm[at + 1:].split("/")
|
|
394
|
+
if len(parts) != 3 or parts[1] not in _TIDY_KINDS or not parts[2].lower().endswith(".md"):
|
|
395
|
+
return None
|
|
396
|
+
return "/".join(parts)
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
def tidy_targets(root: Path, own_files: Path, movable: bool = False) -> int:
|
|
400
|
+
"""Print the finished top-level artifacts in this session's own-files list, one repo-relative path per
|
|
401
|
+
line: what `caddis_tidy.py --apply --only` should get at handoff Step 4. Another session's finished item
|
|
402
|
+
is never printed, so a handoff cannot sweep it (2026-11-07). Nothing printed means none.
|
|
403
|
+
|
|
404
|
+
By default a colliding item and a plan held for open Tracker rows are printed too: the `--only` run reports
|
|
405
|
+
them (exit 1 / exit 2). `movable` prints only what tidy would move now: Step 4 carries just those into the
|
|
406
|
+
docs-PR worktree, so a held or colliding item is never taken out of this checkout."""
|
|
407
|
+
root = Path(root).resolve()
|
|
408
|
+
try:
|
|
409
|
+
lines = own_files.read_text(encoding="utf-8", errors="replace").splitlines()
|
|
410
|
+
except OSError:
|
|
411
|
+
lines = []
|
|
412
|
+
own = {rel for rel in map(_caddis_rel, lines) if rel}
|
|
413
|
+
if not own:
|
|
414
|
+
return 0
|
|
415
|
+
caddis_tidy = _tidy_module()
|
|
416
|
+
report = caddis_tidy.tidy(root, apply=False)
|
|
417
|
+
finished = list(report.would_move) # would_move never holds a collision
|
|
418
|
+
if not movable:
|
|
419
|
+
finished += [*report.collisions, *(path for path, _ in report.open_rows_held)]
|
|
420
|
+
for rel in sorted({path.relative_to(root).as_posix() for path in finished} & own):
|
|
421
|
+
print(rel)
|
|
422
|
+
return 0
|
|
423
|
+
|
|
424
|
+
|
|
425
|
+
def _tidy_module():
|
|
426
|
+
if str(_HERE) not in sys.path:
|
|
427
|
+
sys.path.insert(0, str(_HERE))
|
|
428
|
+
import caddis_tidy # ships beside this file
|
|
429
|
+
|
|
430
|
+
return caddis_tidy
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
def _tracked(root: Path, rel: str) -> bool | None:
|
|
434
|
+
try:
|
|
435
|
+
res = subprocess.run(["git", "-C", str(root), "ls-files", "--error-unmatch", "--", rel],
|
|
436
|
+
capture_output=True, text=True, encoding="utf-8", errors="replace")
|
|
437
|
+
except OSError:
|
|
438
|
+
return None
|
|
439
|
+
if res.returncode == 0:
|
|
440
|
+
return True
|
|
441
|
+
return False if "did not match" in (res.stderr or "") else None
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
def _artifact_paths(root: Path, paths: list[str], verb: str) -> list[str] | None:
|
|
445
|
+
"""The deduplicated repo-relative artifact paths, or None (after a refusal line) when one is not a real
|
|
446
|
+
top-level file of `.caddis/{plans,prompts,parking-lot}/` in `root` (a symlink is refused too)."""
|
|
447
|
+
out: list[str] = []
|
|
448
|
+
for raw in paths:
|
|
449
|
+
rel = raw.replace("\\", "/")
|
|
450
|
+
while rel.startswith("./"):
|
|
451
|
+
rel = rel[2:]
|
|
452
|
+
src = root / rel
|
|
453
|
+
if _caddis_rel(rel) != rel or src.is_symlink() or src.resolve() != src:
|
|
454
|
+
print(f"{verb}: refused: {raw} is not a top-level file in .caddis/plans/, .caddis/prompts/ or "
|
|
455
|
+
".caddis/parking-lot/; nothing was changed")
|
|
456
|
+
return None
|
|
457
|
+
if rel not in out:
|
|
458
|
+
out.append(rel)
|
|
459
|
+
return out
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
def carry(root: Path, to: Path, paths: list[str]) -> int:
|
|
463
|
+
"""Copy this session's own artifacts, with their uncommitted edits, from this checkout into the Step 4
|
|
464
|
+
docs-PR worktree, at the same relative paths (2026-11-08). The worktree comes from origin/<default>, so
|
|
465
|
+
without this the session's local status flips are not in it. COPIES ONLY: this checkout is never changed
|
|
466
|
+
(`release` restores it later, once the docs PR branch holds the moves).
|
|
467
|
+
|
|
468
|
+
All files are copied and checked byte-equal first. If any copy fails, every file this run wrote in the
|
|
469
|
+
worktree is put back as it was (deleted when it was new) and the exit is 1. Prints `CARRIED: <path>`."""
|
|
470
|
+
root, to = Path(root).resolve(), Path(to).resolve()
|
|
471
|
+
if root == to:
|
|
472
|
+
print("CARRY: refused: --to is this checkout")
|
|
473
|
+
return 1
|
|
474
|
+
if not to.is_dir():
|
|
475
|
+
print(f"CARRY: refused: no worktree at {to}")
|
|
476
|
+
return 1
|
|
477
|
+
rels = _artifact_paths(root, paths, "CARRY")
|
|
478
|
+
if rels is None:
|
|
479
|
+
return 1
|
|
480
|
+
for rel in rels:
|
|
481
|
+
if not (root / rel).is_file():
|
|
482
|
+
print(f"CARRY: refused: {rel} does not exist in this checkout; nothing was changed")
|
|
483
|
+
return 1
|
|
484
|
+
written: list[tuple[Path, bytes | None]] = [] # (worktree file, its bytes before this run; None = new)
|
|
485
|
+
try:
|
|
486
|
+
for rel in rels:
|
|
487
|
+
data = (root / rel).read_bytes()
|
|
488
|
+
dst = to / rel
|
|
489
|
+
before = dst.read_bytes() if dst.is_file() else None
|
|
490
|
+
dst.parent.mkdir(parents=True, exist_ok=True)
|
|
491
|
+
written.append((dst, before))
|
|
492
|
+
dst.write_bytes(data)
|
|
493
|
+
if dst.read_bytes() != data:
|
|
494
|
+
raise OSError(f"the copy of {rel} differs from this checkout")
|
|
495
|
+
except OSError as exc:
|
|
496
|
+
print(f"CARRY: failed: {exc}; the worktree is put back, this checkout was not changed")
|
|
497
|
+
for dst, before in reversed(written):
|
|
498
|
+
try:
|
|
499
|
+
if before is None:
|
|
500
|
+
dst.unlink(missing_ok=True)
|
|
501
|
+
else:
|
|
502
|
+
dst.write_bytes(before)
|
|
503
|
+
except OSError as undo:
|
|
504
|
+
print(f"CARRY: could not put back {dst}: {undo}")
|
|
505
|
+
return 1
|
|
506
|
+
for rel in rels:
|
|
507
|
+
print(f"CARRIED: {rel}")
|
|
508
|
+
return 0
|
|
509
|
+
|
|
510
|
+
|
|
511
|
+
def _blob_id(root: Path, rel: str, data: bytes) -> str | None:
|
|
512
|
+
"""The blob id git would store for `data` at `rel` (its clean filters, such as CRLF to LF, applied)."""
|
|
513
|
+
try:
|
|
514
|
+
res = subprocess.run(["git", "-C", str(root), "hash-object", "--stdin", f"--path={rel}"], input=data,
|
|
515
|
+
capture_output=True)
|
|
516
|
+
except OSError:
|
|
517
|
+
return None
|
|
518
|
+
return res.stdout.decode("ascii", "replace").strip() if res.returncode == 0 else None
|
|
519
|
+
|
|
520
|
+
|
|
521
|
+
def release(root: Path, branch: str, paths: list[str]) -> int:
|
|
522
|
+
"""After the Step 4 docs PR is open, restore each carried artifact in this checkout, but only when the
|
|
523
|
+
pushed branch holds it, moved: `origin/<branch>:.caddis/<kind>/done/<file>` must be the same blob as this
|
|
524
|
+
checkout's file (as git would store it), or as that file with the `status: done` that tidy writes into a
|
|
525
|
+
plan whose Tracker is complete. Then a tracked file is restored (`git checkout -- <path>`) and an untracked
|
|
526
|
+
one deleted. Anything else is left as it is with `kept: <path> (<reason>)`. Exit 0 when all were released."""
|
|
527
|
+
root = Path(root).resolve()
|
|
528
|
+
rels = _artifact_paths(root, paths, "RELEASE")
|
|
529
|
+
if rels is None:
|
|
530
|
+
return 1
|
|
531
|
+
if not re.fullmatch(r"[A-Za-z0-9._/-]+", branch) or branch.startswith("-"):
|
|
532
|
+
print(f"RELEASE: refused: {branch!r} is not a branch name")
|
|
533
|
+
return 1
|
|
534
|
+
fetched = _git(root, "fetch", "--quiet", "origin", f"+refs/heads/{branch}:refs/remotes/origin/{branch}")
|
|
535
|
+
if fetched is None:
|
|
536
|
+
for rel in rels:
|
|
537
|
+
print(f"kept: {rel} (cannot fetch origin/{branch})")
|
|
538
|
+
return 1
|
|
539
|
+
caddis_tidy = _tidy_module()
|
|
540
|
+
kept = 0
|
|
541
|
+
for rel in rels:
|
|
542
|
+
kind, name = rel.split("/")[1], rel.split("/")[2]
|
|
543
|
+
done_rel = f".caddis/{kind}/done/{name}"
|
|
544
|
+
src = root / rel
|
|
545
|
+
reason = None
|
|
546
|
+
remote = _git(root, "rev-parse", "--verify", "--quiet", f"refs/remotes/origin/{branch}:{done_rel}")
|
|
547
|
+
tracked = _tracked(root, rel)
|
|
548
|
+
try:
|
|
549
|
+
data = src.read_bytes() if src.is_file() else None
|
|
550
|
+
except OSError as exc:
|
|
551
|
+
data, reason = None, f"cannot read it: {exc}"
|
|
552
|
+
if reason is None and data is None:
|
|
553
|
+
reason = "it is no longer in this checkout"
|
|
554
|
+
elif reason is None and not remote:
|
|
555
|
+
reason = f"origin/{branch} has no {done_rel}"
|
|
556
|
+
elif reason is None and tracked is None:
|
|
557
|
+
reason = "git cannot say whether it is tracked"
|
|
558
|
+
elif reason is None and tracked and _git(root, "diff", "--cached", "--name-only", "--", rel):
|
|
559
|
+
reason = "it has a staged change"
|
|
560
|
+
if reason is None:
|
|
561
|
+
candidates = {_blob_id(root, rel, data)}
|
|
562
|
+
text = data.decode("utf-8", "replace")
|
|
563
|
+
flipped = caddis_tidy._set_header(text, {"status": "done"}) if kind == "plans" else None
|
|
564
|
+
if flipped is not None:
|
|
565
|
+
candidates.add(_blob_id(root, rel, flipped.encode("utf-8")))
|
|
566
|
+
if remote not in candidates:
|
|
567
|
+
reason = f"it differs from {done_rel} on origin/{branch}"
|
|
568
|
+
if reason is None:
|
|
569
|
+
try:
|
|
570
|
+
if tracked:
|
|
571
|
+
res = subprocess.run(["git", "-C", str(root), "checkout", "--", rel], capture_output=True,
|
|
572
|
+
text=True, encoding="utf-8", errors="replace")
|
|
573
|
+
if res.returncode != 0:
|
|
574
|
+
reason = "git could not restore it: " + (res.stderr or "").strip()[:160]
|
|
575
|
+
else:
|
|
576
|
+
src.unlink()
|
|
577
|
+
except OSError as exc:
|
|
578
|
+
reason = f"could not restore it: {exc}"
|
|
579
|
+
if reason is None:
|
|
580
|
+
print(f"released: {rel}")
|
|
581
|
+
else:
|
|
582
|
+
kept += 1
|
|
583
|
+
print(f"kept: {rel} ({reason})")
|
|
584
|
+
return 1 if kept else 0
|
|
585
|
+
|
|
586
|
+
|
|
372
587
|
def main(argv: list[str] | None = None) -> int:
|
|
373
588
|
try:
|
|
374
589
|
sys.stdout.reconfigure(encoding="utf-8")
|
|
@@ -376,6 +591,10 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
376
591
|
pass
|
|
377
592
|
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
|
378
593
|
sub = parser.add_subparsers(dest="cmd", required=True)
|
|
594
|
+
t = sub.add_parser("tidy-targets", help="print this session's finished top-level artifacts (handoff Step 4)")
|
|
595
|
+
t.add_argument("--own-files", required=True, type=Path,
|
|
596
|
+
help="the Step 0 temp file: this session's `## Files changed this session` lines")
|
|
597
|
+
t.add_argument("--root", type=Path, help="the checkout tidy runs in (default: the git top level of the cwd)")
|
|
379
598
|
p = sub.add_parser("checkpoint", help="prepare (no --relay-file) or finish (--relay-file) a checkpoint")
|
|
380
599
|
p.add_argument("--session-id", required=True)
|
|
381
600
|
p.add_argument("--name", help="workstream name (default: caddis_workstreams.py resolve)")
|
|
@@ -385,7 +604,23 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
385
604
|
p.add_argument("--expected-hash", help="FINISH: the hash PREPARE printed")
|
|
386
605
|
p.add_argument("--kt", help="FINISH: done | skipped:<reason>")
|
|
387
606
|
p.add_argument("--idle", action="store_true", help="FINISH: no agent or background command runs")
|
|
607
|
+
t.add_argument("--movable", action="store_true",
|
|
608
|
+
help="print only what tidy would move now (no held plan, no collision): the set to carry")
|
|
609
|
+
c = sub.add_parser("carry", help="copy own artifacts with their edits into the Step 4 docs-PR worktree")
|
|
610
|
+
c.add_argument("--to", required=True, type=Path, help="the WORKTREE: path that caddis_docs_pr.py start printed")
|
|
611
|
+
c.add_argument("--root", type=Path, help="this checkout (default: the git top level of the cwd)")
|
|
612
|
+
c.add_argument("paths", nargs="+", help="repo-relative paths that tidy-targets --movable printed")
|
|
613
|
+
r = sub.add_parser("release", help="restore carried artifacts here once origin/<branch> holds their moves")
|
|
614
|
+
r.add_argument("--branch", required=True, help="the docs-PR branch that caddis_docs_pr.py finish pushed")
|
|
615
|
+
r.add_argument("--root", type=Path, help="this checkout (default: the git top level of the cwd)")
|
|
616
|
+
r.add_argument("paths", nargs="+", help="the paths given to carry")
|
|
388
617
|
args = parser.parse_args(argv)
|
|
618
|
+
if args.cmd == "tidy-targets":
|
|
619
|
+
return tidy_targets(args.root or _repo_root(), args.own_files, movable=args.movable)
|
|
620
|
+
if args.cmd == "carry":
|
|
621
|
+
return carry(args.root or _repo_root(), args.to, args.paths)
|
|
622
|
+
if args.cmd == "release":
|
|
623
|
+
return release(args.root or _repo_root(), args.branch, args.paths)
|
|
389
624
|
try:
|
|
390
625
|
args.root = _repo_root() # once: every path and every sibling call uses it
|
|
391
626
|
return finish(args) if args.relay_file else prepare(args)
|