@caddis/cli 0.4.84 → 0.4.86

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.
Files changed (35) hide show
  1. package/bundles/antigravity-plugin/plugin.json +1 -1
  2. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  3. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/caddis_prod_check.py +59 -11
  13. package/bundles/antigravity-plugin/scripts/caddis_roadmap.py +112 -194
  14. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +5 -25
  15. package/bundles/antigravity-plugin/skills/catchup/SKILL.md +2 -4
  16. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +0 -6
  17. package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md +2 -3
  18. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +0 -1
  19. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +0 -1
  20. package/bundles/manifest.json +2 -2
  21. package/dist/cli.js +7 -1
  22. package/package.json +1 -1
  23. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap_page.cpython-311.pyc +0 -0
  24. package/bundles/antigravity-plugin/scripts/caddis_roadmap_page.py +0 -1441
  25. package/bundles/antigravity-plugin/scripts/roadmap_assets/fonts.css +0 -5
  26. package/bundles/antigravity-plugin/scripts/roadmap_assets/icons.svg +0 -2
  27. package/dist/ui/fonts/LICENSE-Lucide.txt +0 -43
  28. package/dist/ui/fonts/OFL-Atkinson.txt +0 -93
  29. package/dist/ui/fonts/OFL-MapleMono.txt +0 -93
  30. /package/{bundles/antigravity-plugin/scripts/roadmap_assets → dist/export/licenses}/LICENSE-Lucide.txt +0 -0
  31. /package/{bundles/antigravity-plugin/scripts/roadmap_assets → dist/export/licenses}/OFL-Atkinson.txt +0 -0
  32. /package/{bundles/antigravity-plugin/scripts/roadmap_assets → dist/export/licenses}/OFL-MapleMono.txt +0 -0
  33. /package/dist/{export/fonts → ui/licenses}/LICENSE-Lucide.txt +0 -0
  34. /package/dist/{export/fonts → ui/licenses}/OFL-Atkinson.txt +0 -0
  35. /package/dist/{export/fonts → ui/licenses}/OFL-MapleMono.txt +0 -0
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "caddis",
3
- "version": "1.3.168",
3
+ "version": "1.3.170",
4
4
  "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
5
5
  }
@@ -5,6 +5,10 @@ succeeded (with --docs-only: the deploy job was skipped); (3) the version endpoi
5
5
  it; (4) the health endpoint JSON has every value `true`, not only HTTP 200; (5) optional: named background jobs were
6
6
  attempted after the deploy with zero failures. A repo with no profile gets items 1 and 2 only.
7
7
 
8
+ Push run (item 1): `[ci] workflow = "<name>"` names the workflow to check. Without it, when several workflows ran on
9
+ the merge SHA (a CI workflow and a Pages one), the run whose jobs hold the deploy job or a required job is used. A job
10
+ of a reusable workflow, listed as `<caller job> / <job>`, counts as `<job>`.
11
+
8
12
  Prints one PASS or FAIL line per item and a RESULT line. Exit 0 only when every item passes; 1 when one fails; 3 when
9
13
  the profile cannot be read; 4 when the SHA is ambiguous or not found. Read-only: it never writes to GitHub or prod.
10
14
 
@@ -69,6 +73,7 @@ def real_runner(cwd: Path) -> Runner:
69
73
  class Profile:
70
74
  found: bool = False
71
75
  branch: str = "main"
76
+ workflow: str | None = None # the push workflow to check, when the repo has more than one (e.g. a Pages one)
72
77
  required_jobs: list[str] = field(default_factory=list)
73
78
  deploy_job: str = "deploy_prod"
74
79
  push_run_wait_minutes: float = 10
@@ -82,7 +87,7 @@ class Profile:
82
87
 
83
88
 
84
89
  _KEY_TYPES: dict[str, type | tuple[type, ...]] = {
85
- "branch": str, "required_jobs": list, "deploy_job": str, "push_run_wait_minutes": (int, float),
90
+ "branch": str, "workflow": str, "required_jobs": list, "deploy_job": str, "push_run_wait_minutes": (int, float),
86
91
  "run_wait_minutes": (int, float), "version_url": str, "version_field": str, "health_url": str, "auth": str,
87
92
  "timeout_seconds": int,
88
93
  }
@@ -111,6 +116,9 @@ def load_profile(repo: Path, path: Path | None = None) -> Profile:
111
116
  if key == "required_jobs" and not all(isinstance(job, str) for job in value):
112
117
  raise ValueError(f"{path}: required_jobs must be a list of job names")
113
118
  setattr(profile, key, value)
119
+ if profile.workflow is not None and (not profile.workflow.strip()
120
+ or profile.workflow.lower().endswith((".yml", ".yaml"))):
121
+ raise ValueError(f"{path}: workflow must be the workflow's name (its `name:` line), not a file name")
114
122
  if profile.auth not in ("none", "ntlm"):
115
123
  raise ValueError(f"{path}: auth must be 'none' or 'ntlm'")
116
124
  if background is not None:
@@ -167,16 +175,42 @@ def resolve_sha(ctx: Context, sha: str) -> tuple[int, str]:
167
175
 
168
176
 
169
177
  def push_runs(ctx: Context, limit: int = 20) -> list[dict]:
170
- return ctx.gh_json("run", "list", "--branch", ctx.profile.branch, "--event", "push", "--limit", str(limit),
171
- "--json", "databaseId,headSha,status,conclusion") # type: ignore[return-value]
178
+ args = ["run", "list", "--branch", ctx.profile.branch, "--event", "push", "--limit", str(limit),
179
+ "--json", "databaseId,headSha,status,conclusion,workflowName"]
180
+ if ctx.profile.workflow:
181
+ args[2:2] = ["--workflow", ctx.profile.workflow]
182
+ runs = ctx.gh_json(*args)
183
+ if ctx.profile.workflow: # also filter here: the list must never hold another workflow's run
184
+ runs = [r for r in runs if r.get("workflowName") == ctx.profile.workflow] # type: ignore[union-attr]
185
+ return runs # type: ignore[return-value]
186
+
187
+
188
+ def _pick_run(ctx: Context, candidates: list[dict]) -> tuple[dict | None, str]:
189
+ """(run, state): state is "sure", "wait" (no run lists the jobs yet: they are queued) or "guess" (nothing can
190
+ tell the runs apart). Several workflows can run on one push (serve-sight: `CI and Deploy` and `roadmap-pages`).
191
+ With no `workflow` in the profile, take the run whose jobs hold the deploy job or a required job."""
192
+ if len(candidates) <= 1:
193
+ return (candidates[0] if candidates else None), ("sure" if candidates else "wait")
194
+ wanted = [j for j in (ctx.profile.deploy_job, *ctx.profile.required_jobs) if j]
195
+ if not wanted: # no deploy job and no required jobs: waiting cannot help
196
+ return candidates[0], "guess"
197
+ for run in candidates:
198
+ view = ctx.gh_json("run", "view", str(run["databaseId"]), "--json", "jobs")
199
+ jobs = _jobs(view if isinstance(view, dict) else {})
200
+ if any(_job(jobs, name) is not None for name in wanted):
201
+ return run, "sure"
202
+ return candidates[0], "wait"
172
203
 
173
204
 
174
205
  def find_push_run(ctx: Context, sha: str) -> dict | None:
175
206
  """Wait up to the profile's minutes for a push run of `sha` to appear."""
176
207
  deadline = ctx.clock.now() + ctx.profile.push_run_wait_minutes * 60
177
208
  while True:
178
- run = next((r for r in push_runs(ctx) if r.get("headSha") == sha), None)
179
- if run or ctx.dry_run or ctx.clock.now() >= deadline:
209
+ run, state = _pick_run(ctx, [r for r in push_runs(ctx) if r.get("headSha") == sha])
210
+ if state != "wait" or ctx.dry_run or ctx.clock.now() >= deadline:
211
+ if run and state != "sure":
212
+ ctx.out(f"INFO 1 {sha[:12]} has several push runs and none lists {ctx.profile.deploy_job or 'the jobs'}"
213
+ f"; using run {run['databaseId']}. Set `workflow` in .caddis/prod-check.toml")
180
214
  return run
181
215
  ctx.clock.sleep(15)
182
216
 
@@ -197,9 +231,23 @@ def _jobs(view: dict) -> dict[str, str]:
197
231
  return {j.get("name", ""): (j.get("conclusion") or j.get("status") or "") for j in view.get("jobs", [])}
198
232
 
199
233
 
234
+ def _same_job(actual: str, name: str) -> bool:
235
+ """A job of a reusable workflow is listed as "<caller job> / <job>" (serve-sight: `ci / deploy_prod`)."""
236
+ return actual == name or actual.endswith(" / " + name)
237
+
238
+
239
+ def _job(jobs: dict[str, str], name: str) -> str | None:
240
+ """The state of job `name`, or None when the run has no such job. When several reusable workflows each have a
241
+ job of that name, a state that is not success wins, so one success never hides a failure."""
242
+ states = [state for actual, state in jobs.items() if _same_job(actual, name)]
243
+ if not states:
244
+ return None
245
+ return next((s for s in states if s != "success"), "success")
246
+
247
+
200
248
  def _deploy_done(view: dict, deploy_job: str) -> datetime | None:
201
249
  for job in view.get("jobs", []):
202
- if job.get("name") == deploy_job and job.get("completedAt"):
250
+ if _same_job(job.get("name", ""), deploy_job) and job.get("completedAt"):
203
251
  return _utc(job["completedAt"])
204
252
  return None
205
253
 
@@ -232,13 +280,13 @@ def check_ci(ctx: Context, sha: str, docs_only: bool) -> tuple[list[str], dict |
232
280
  ctx.out("jobs: " + ", ".join(f"{name}={state}" for name, state in jobs.items()))
233
281
  deploy = ctx.profile.deploy_job
234
282
  if docs_only:
235
- if jobs.get(deploy) == "skipped" and conclusion == "success":
283
+ if _job(jobs, deploy) == "skipped" and conclusion == "success":
236
284
  ctx.out(f"PASS 2 docs-only: {deploy} skipped, run conclusion success")
237
285
  return [], view
238
286
  if conclusion != "success":
239
287
  ctx.out(f"FAIL 2 docs-only merge, but the run concluded {conclusion}")
240
288
  return ["2 jobs"], view
241
- ctx.out(f"FAIL 2 docs-only merge, but {deploy} = {jobs.get(deploy, 'absent')}; run the full prod check")
289
+ ctx.out(f"FAIL 2 docs-only merge, but {deploy} = {_job(jobs, deploy) or 'absent'}; run the full prod check")
242
290
  return ["2 jobs"], view
243
291
  if not ctx.profile.found:
244
292
  if conclusion == "success":
@@ -246,11 +294,11 @@ def check_ci(ctx: Context, sha: str, docs_only: bool) -> tuple[list[str], dict |
246
294
  return [], view
247
295
  ctx.out(f"FAIL 2 run conclusion {conclusion}")
248
296
  return ["2 jobs"], view
249
- bad = {name: jobs.get(name, "absent") for name in ctx.profile.required_jobs if jobs.get(name) != "success"}
250
- if deploy and jobs.get(deploy) != "success":
297
+ bad = {name: _job(jobs, name) or "absent" for name in ctx.profile.required_jobs if _job(jobs, name) != "success"}
298
+ if deploy and _job(jobs, deploy) != "success":
251
299
  # A code merge that did not deploy fails, also when the job is not listed as required.
252
300
  # A repo with no deploy job sets `deploy_job = ""` in its profile.
253
- bad[deploy] = jobs.get(deploy, "absent")
301
+ bad[deploy] = _job(jobs, deploy) or "absent"
254
302
  if bad:
255
303
  skipped = " (skipped without --docs-only)" if bad.get(deploy) == "skipped" else ""
256
304
  ctx.out("FAIL 2 " + ", ".join(f"{n}={c}" for n, c in bad.items()) + skipped)
@@ -104,7 +104,7 @@ except ModuleNotFoundError as exc:
104
104
  _NO_WINDOW = 0x08000000 if os.name == "nt" else 0
105
105
 
106
106
  SCRIPTS_DIR = Path(__file__).resolve().parent
107
- # This module object, taken while it loads. `render` hands it to the page builder. A lookup by name at call time
107
+ # This module object, taken while it loads. build() uses it unless a test passes a stand-in. A lookup by name at call time
108
108
  # (`sys.modules[__name__]`) can return a different copy when the file was loaded twice in one process.
109
109
  _THIS_MODULE = sys.modules[__name__]
110
110
  STATUSES = ("todo", "in-progress", "code-done/data-pending", "done", "not-needed")
@@ -248,7 +248,7 @@ def default_branch(root: Path) -> str:
248
248
  if proc.returncode == 0 and ref.startswith("refs/remotes/origin/"):
249
249
  return ref[len("refs/remotes/origin/"):]
250
250
  if not FETCH:
251
- # No network when fetch is off (the collector, `render --no-fetch`): use the one local origin branch.
251
+ # No network when fetch is off (the hub collector): use the one local origin branch.
252
252
  found = [name for name in ("main", "master")
253
253
  if _git(root, "rev-parse", "--verify", "--quiet", f"refs/remotes/origin/{name}^{{commit}}",
254
254
  check=False).returncode == 0]
@@ -265,7 +265,7 @@ def default_branch(root: Path) -> str:
265
265
  caddis_exit.NOT_RUN)
266
266
 
267
267
 
268
- FETCH = True # `render --no-fetch` (the waiting hook) turns it off for one command: read the origin refs it has
268
+ FETCH = True # the hub collector turns it off for one call: read the origin refs the repo has
269
269
 
270
270
 
271
271
  def fetch(root: Path) -> str:
@@ -2204,20 +2204,120 @@ def list_roadmaps_checked(root: Path) -> tuple[list[str], set[str] | None]:
2204
2204
  return sorted(slugs), folders
2205
2205
 
2206
2206
 
2207
+ # ---- roadmap detail (R68): status() plus the plan headers, the Tracker cells and the runner -------------------
2208
+
2209
+ PHASE_HEADER = re.compile(r"^###\s+Phase\s+(\d+)[a-z]?\s*[-–—:]\s*(.+?)\s*(?:[✅⏳\U0001F532].*)?$",
2210
+ re.MULTILINE)
2211
+ _FACT = re.compile(r"\*\*(Model|Lane|Risk):\*\*\s*([^\n]+?)\s*(?=\*\*(?:Model|Lane|Risk):\*\*|$)",
2212
+ re.MULTILINE)
2213
+
2214
+
2215
+ def _read_json(path: Path | None):
2216
+ """(data, error): data is a dict or None; error names a file that exists but cannot be read."""
2217
+ if path is None:
2218
+ return None, ""
2219
+ try:
2220
+ raw = Path(path).read_text(encoding="utf-8")
2221
+ except FileNotFoundError:
2222
+ return None, ""
2223
+ except (OSError, UnicodeDecodeError) as exc:
2224
+ return None, f"{Path(path).name}: {getattr(exc, 'strerror', None) or exc}"
2225
+ try:
2226
+ data = json.loads(raw)
2227
+ except ValueError:
2228
+ return None, f"{Path(path).name}: not JSON"
2229
+ return (data, "") if isinstance(data, dict) else (None, f"{Path(path).name}: not a JSON object")
2230
+
2231
+
2232
+ def phase_facts(plan_text: str | None) -> dict[int, dict]:
2233
+ """Phase number -> {name, model, lane, risk} from the plan's `### Phase <n> - <name>` sections."""
2234
+ if not plan_text:
2235
+ return {}
2236
+ heads = list(PHASE_HEADER.finditer(plan_text))
2237
+ out: dict[int, dict] = {}
2238
+ for i, m in enumerate(heads):
2239
+ body = plan_text[m.end():heads[i + 1].start() if i + 1 < len(heads) else len(plan_text)]
2240
+ body = body.split("\n## ", 1)[0] # stop at the next level-2 section (Tracker, Risks, ...)
2241
+ facts = {k.lower(): v.strip() for k, v in _FACT.findall(body)}
2242
+ out.setdefault(int(m.group(1)), {"name": m.group(2).strip(), "model": facts.get("model", ""),
2243
+ "lane": facts.get("lane", ""), "risk": facts.get("risk", "")})
2244
+ return out
2245
+
2246
+
2247
+ def tile_state(tracker_cell: str, state: str) -> str:
2248
+ """todo | in-progress | done | moved | blocked, from the Tracker cell (origin), falling back to status()."""
2249
+ cell = (tracker_cell or "").strip().lstrip("*").strip().lower()
2250
+ if cell.startswith("moved") or "moved" in cell.split(" - ", 1)[0]:
2251
+ return "moved"
2252
+ if cell.startswith(("done", "✅", "merged")):
2253
+ return "done"
2254
+ if cell.startswith(("blocked", "halt", "waiting")):
2255
+ return "blocked"
2256
+ if cell.startswith(("in progress", "in-progress", "active", "building", "built", "⏳")):
2257
+ return "in-progress"
2258
+ return "done" if state == "done" else "todo"
2259
+
2260
+
2261
+ def build(root: Path, slug: str, roadmap_mod=None) -> dict:
2262
+ """status() plus per-phase Tracker cell, name, model, lane, risk and tile state; open owner gates; the runner;
2263
+ the origin commit. `roadmap_mod` is this module unless a test passes a stand-in. No session marks are read: the
2264
+ hub has live sessions of its own."""
2265
+ mod = roadmap_mod or _THIS_MODULE
2266
+ root = Path(root)
2267
+ model = mod.status(root, slug)
2268
+ plans: dict[str, tuple[dict[int, str], dict[int, dict]]] = {}
2269
+ lanes: list[str] = []
2270
+ for ms in model["milestones"]:
2271
+ for ph in ms["phases"]:
2272
+ m = mod.REF_RE.match(ph["ref"])
2273
+ ph.update(plan="", num=0, tracker="", name="", model="", lane="", risk="")
2274
+ if not m:
2275
+ ph["tile"] = "todo"
2276
+ continue
2277
+ plan, num = m.group(1), int(m.group(2))
2278
+ if plan not in plans:
2279
+ text = mod.show(root, model["branch"], f".caddis/plans/{plan}.md")
2280
+ if text is None:
2281
+ text = mod.show(root, model["branch"], f".caddis/plans/done/{plan}.md")
2282
+ plans[plan] = (mod.parse_tracker(text) if text else {}, phase_facts(text))
2283
+ lanes.append(plan)
2284
+ rows, facts = plans[plan]
2285
+ ph.update(plan=plan, num=num, tracker=rows.get(num, ""), **{k: v for k, v in facts.get(num, {}).items()})
2286
+ ph["tile"] = tile_state(ph["tracker"], ph["state"])
2287
+ model["lanes"] = lanes
2288
+ model["waiting"] = [{"milestone": ms["id"], "reason": b["reason"], "check": b["check"]}
2289
+ for ms in model["milestones"] for b in ms["blockers"]
2290
+ if b["type"] == "owner-gate" and ms["status"] not in mod.FINISHED]
2291
+
2292
+ lock_path = mod.runner_lock_path(root, "roadmap", slug)
2293
+ lock, lock_err = _read_json(lock_path)
2294
+ if lock is not None and not all(lock.get(k) not in (None, "") for k in ("batch", "pid", "started_utc")):
2295
+ lock_err = lock_err or f"{Path(lock_path).name}: missing batch, pid or started_utc"
2296
+ lock = None
2297
+ live = False
2298
+ if lock is not None and lock_path is not None:
2299
+ try:
2300
+ live = mod.runner_lock_stale(lock_path) is False
2301
+ except Exception: # a judgement that cannot be made is not "running"
2302
+ live = False
2303
+ stop, stop_err = _read_json(mod.last_stop_path(root, "roadmap", slug))
2304
+ model["runner"] = {"lock": lock if live else None, "stale_lock": lock if (lock and not live) else None,
2305
+ "last_stop": stop, "errors": [e for e in (lock_err, stop_err) if e]}
2306
+ try:
2307
+ model["origin_commit"] = mod._git(root, "rev-parse", "--short", f"origin/{model['branch']}",
2308
+ check=False).stdout.strip()
2309
+ except Exception:
2310
+ model["origin_commit"] = ""
2311
+ return model
2312
+
2313
+
2207
2314
  _PR_REF_RE = re.compile(r"#(\d+)")
2208
2315
 
2209
2316
 
2210
2317
  def _roadmap_detail(root: Path, slug: str) -> dict:
2211
2318
  """status() plus the hub's detail (R45): per phase name, model, lane, risk, Tracker cell, tile and the PR numbers
2212
- the cell names; per roadmap lanes, open owner gates, the runner and the origin commit. The page module owns
2213
- this logic. Its machine-local session marks and its clock text are left out."""
2214
- scripts_dir = str(Path(__file__).resolve().parent)
2215
- if scripts_dir not in sys.path:
2216
- sys.path.insert(0, scripts_dir)
2217
- import caddis_roadmap_page
2218
- model = caddis_roadmap_page.build(Path(root), slug, _THIS_MODULE, sessions=False)
2219
- model.pop("sessions", None)
2220
- model.pop("generated", None)
2319
+ the cell names; per roadmap lanes, open owner gates, the runner and the origin commit."""
2320
+ model = build(Path(root), slug)
2221
2321
  for ms in model["milestones"]:
2222
2322
  for ph in ms["phases"]:
2223
2323
  ph["prs"] = sorted({int(n) for n in _PR_REF_RE.findall(str(ph.get("tracker", "")))})
@@ -2283,146 +2383,9 @@ def _build_parser() -> argparse.ArgumentParser:
2283
2383
  p = add("rollup", write=True)
2284
2384
  p.add_argument("--id", required=True)
2285
2385
  add("recheck", write=True)
2286
- p = sub.add_parser("render")
2287
- which = p.add_mutually_exclusive_group(required=True)
2288
- which.add_argument("--roadmap")
2289
- which.add_argument("--all", action="store_true", help="every roadmap on origin (used by hooks and commands)")
2290
- p.add_argument("--root", default=".")
2291
- p.add_argument("--out", default=None, help="the HTML file (default ~/.caddis/roadmap-pages/<repo>/<slug>.html)")
2292
- p.add_argument("--site", default=None, metavar="DIR",
2293
- help="with --all: build the shared copy (no live sessions or runners, a banner) in DIR/build and "
2294
- "publish only the safe files to DIR/public (for GitHub Pages)")
2295
- p.add_argument("--no-fetch", action="store_true",
2296
- help="use the origin refs this checkout has; no git fetch (the waiting hook's background render)")
2297
- p.add_argument("--delay", type=int, default=0,
2298
- help="wait this many seconds (at most 60) first: the waiting hook's follow-up render")
2299
2386
  return parser
2300
2387
 
2301
2388
 
2302
- RENDER_LOCK_STALE_S = 600 # a render lock older than this is left by a killed render
2303
- PENDING_NAME = ".roadmap-render.pending" # session_waiting.py writes it beside its debounce stamp
2304
-
2305
-
2306
- def _clear(path: Path | None) -> bool:
2307
- """Delete `path`; True when it was there."""
2308
- if path is None:
2309
- return False
2310
- try:
2311
- path.unlink()
2312
- return True
2313
- except FileNotFoundError:
2314
- return False
2315
- except OSError:
2316
- return path.exists()
2317
-
2318
-
2319
- def _take_render_lock(lock: Path) -> bool:
2320
- """One render per repo at a time (robustness #8): create `lock` with O_EXCL, never wait. A lock older than
2321
- RENDER_LOCK_STALE_S is taken over once. False: another render holds it."""
2322
- lock.parent.mkdir(parents=True, exist_ok=True)
2323
- for attempt in range(2):
2324
- try:
2325
- fd = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
2326
- except FileExistsError:
2327
- pass
2328
- except PermissionError: # Windows: a deleted lock whose delete is still pending
2329
- return False
2330
- else:
2331
- with os.fdopen(fd, "w", encoding="utf-8") as fh:
2332
- fh.write(str(os.getpid()))
2333
- return True
2334
- try:
2335
- stale = time.time() - lock.stat().st_mtime > RENDER_LOCK_STALE_S
2336
- except FileNotFoundError:
2337
- stale = True # released between the create and the stat: try again
2338
- except OSError: # Windows: a lock being deleted cannot be read either
2339
- return False
2340
- if attempt or not stale:
2341
- return False
2342
- try:
2343
- lock.unlink()
2344
- except FileNotFoundError:
2345
- pass
2346
- except OSError:
2347
- return False
2348
- return False
2349
-
2350
-
2351
- def _render(root: Path, args: argparse.Namespace, site_dir: Path | None = None) -> int:
2352
- """`render`: the pages, the prune and the hub. The caller holds the repo's render lock. `site_dir` (the shared
2353
- copy's build folder, `render --site`) replaces the pages root and takes no lock."""
2354
- import caddis_roadmap_page
2355
- slugs, on_origin = list_roadmaps_checked(root) if args.all else ([args.roadmap], None)
2356
- failed = written = pruned = 0
2357
- site_kw = {} if site_dir is None else {"site_dir": site_dir} # the normal calls stay exactly as they were
2358
- for slug in slugs: # --all: one bad roadmap must not stop the others
2359
- try:
2360
- path = caddis_roadmap_page.write_page(root, slug, Path(args.out) if args.out else None,
2361
- _THIS_MODULE, **site_kw)
2362
- if path is None: # a newer caddis owns this page: kept, and neither written nor failed
2363
- continue
2364
- written += 1
2365
- print(f"[ROADMAP] page written: {path.resolve()}")
2366
- except Exception as exc: # --all: one roadmap must never stop the others
2367
- if not args.all:
2368
- raise
2369
- failed += 1
2370
- print(f"[ROADMAP] {slug}: page not written: {exc}", file=sys.stderr)
2371
- try: # the hub is a convenience: nothing below ever fails a render or changes its exit code
2372
- if args.all and on_origin is not None: # a roadmap removed from origin leaves the hub too; a listing
2373
- # that failed removes nothing, and a folder still on origin keeps its page even if its render failed
2374
- pruned = caddis_roadmap_page.prune_folder(
2375
- caddis_roadmap_page.default_page_path(root, "_", base=site_dir).parent, on_origin | set(slugs))
2376
- if site_dir is not None:
2377
- site_kw["banner"] = caddis_roadmap_page.site_banner(root)
2378
- hub = caddis_roadmap_page.write_hub(**site_kw) if not args.out and (written or pruned) else None
2379
- if hub is not None: # None: a newer caddis owns the hub (write_hub said so)
2380
- print(f"[ROADMAP] hub written: {hub.resolve()}")
2381
- except Exception as exc:
2382
- print(f"[ROADMAP] hub not written: {exc}", file=sys.stderr)
2383
- if site_dir is not None: # the shared copy is published, so a hub that failed is a failed render
2384
- failed += 1
2385
- if site_dir is not None and not failed and not written:
2386
- print("[ROADMAP] site not rendered: no roadmap was rendered (none on origin, or the listing failed)",
2387
- file=sys.stderr)
2388
- return caddis_exit.BLOCKED
2389
- return caddis_exit.BLOCKED if failed else caddis_exit.CLEAN
2390
-
2391
-
2392
- def _render_site(root: Path, args: argparse.Namespace) -> int:
2393
- """`render --all --site DIR`: build the shared copy in DIR/build (no render lock, no version gate, no stamp: CI is
2394
- the only writer), then publish its allow-list to DIR/public. A render that failed publishes nothing."""
2395
- import caddis_roadmap_page
2396
- site = Path(args.site)
2397
- build, public = site / "build", site / "public"
2398
- global FETCH
2399
- FETCH = not args.no_fetch
2400
- try: # a reused DIR keeps the last run's index.html: only one written by THIS run may be published
2401
- (build / "index.html").unlink(missing_ok=True)
2402
- except OSError as exc:
2403
- raise RoadmapError(f"site not published: the old {build / 'index.html'} cannot be removed: {exc}",
2404
- caddis_exit.ERROR) from exc
2405
- try:
2406
- code = _render(root, args, site_dir=build)
2407
- finally:
2408
- FETCH = True
2409
- if code != caddis_exit.CLEAN:
2410
- print("[ROADMAP] site not published: the render did not finish clean (see above); the last public/ is kept",
2411
- file=sys.stderr)
2412
- return code
2413
- if not (build / "index.html").is_file():
2414
- print("[ROADMAP] site not published: the hub (index.html) was not written", file=sys.stderr)
2415
- return caddis_exit.BLOCKED
2416
- try:
2417
- paths = caddis_roadmap_page.export_site(build, public)
2418
- except ValueError as exc:
2419
- raise RoadmapError(f"site not published: {exc}", caddis_exit.ERROR) from exc
2420
- for rel in paths:
2421
- print(f"[ROADMAP] site file: {rel}")
2422
- print(f"[ROADMAP] site published: {len(paths)} file(s) in {public.resolve()}")
2423
- return caddis_exit.CLEAN
2424
-
2425
-
2426
2389
  def _dispatch(args: argparse.Namespace) -> int:
2427
2390
  root = _repo_root(args.root)
2428
2391
  if args.cmd == "list" and args.json:
@@ -2469,51 +2432,6 @@ def _dispatch(args: argparse.Namespace) -> int:
2469
2432
  return rollup(root, args.roadmap, args.id, args.dry_run)
2470
2433
  if args.cmd == "recheck":
2471
2434
  return recheck(root, args.roadmap, args.dry_run)
2472
- if args.cmd == "render":
2473
- import caddis_roadmap_page # the page is separate; only `render` needs it
2474
- if args.site is not None:
2475
- if args.out:
2476
- raise RoadmapError("--site and --out cannot be used together: --out is one self-contained page, "
2477
- "--site is the shared copy of every roadmap", caddis_exit.ERROR)
2478
- if not args.all:
2479
- raise RoadmapError("--site works with --all, not with --roadmap", caddis_exit.ERROR)
2480
- if args.delay > 0:
2481
- raise RoadmapError("--site and --delay cannot be used together: a CI render does not wait",
2482
- caddis_exit.ERROR)
2483
- return _render_site(root, args)
2484
- if args.all and args.out:
2485
- raise RoadmapError("--out works with one --roadmap, not with --all", caddis_exit.ERROR)
2486
- if args.delay > 0:
2487
- time.sleep(min(args.delay, 60))
2488
- folder = caddis_roadmap_page.default_page_path(root, "_").parent.name
2489
- lock = caddis_roadmap_page.pages_root() / ".locks" / f"{folder}.lock"
2490
- # The waiting hook's debounce (and a render that finds the lock held) leaves PENDING_NAME: the render that
2491
- # holds the lock renders once more at its end, so the last mark change always reaches the page.
2492
- state = caddis_roadmap_page.main_checkout(root) / ".caddis" / "session-state"
2493
- pending = state / PENDING_NAME if args.all and not args.out else None
2494
- if not _take_render_lock(lock):
2495
- if pending is not None and state.is_dir():
2496
- try:
2497
- pending.write_text(str(os.getpid()), encoding="utf-8")
2498
- except OSError:
2499
- pass
2500
- print("[ROADMAP] another render of this repo is running; skipped")
2501
- return caddis_exit.CLEAN
2502
- global FETCH
2503
- FETCH = not args.no_fetch
2504
- try:
2505
- _clear(pending) # this render reads the marks as they are now
2506
- code = _render(root, args)
2507
- if _clear(pending): # a mark changed while it ran: once more, under the same lock
2508
- code = _render(root, args)
2509
- return code
2510
- finally:
2511
- FETCH = True
2512
- try: # only our own lock: a render that ran past the stale age may have been taken over
2513
- if lock.read_text(encoding="utf-8").strip() == str(os.getpid()):
2514
- lock.unlink()
2515
- except (OSError, UnicodeDecodeError):
2516
- pass
2517
2435
  return caddis_exit.ERROR
2518
2436
 
2519
2437
 
@@ -219,7 +219,7 @@ def session_env(base: dict | None = None) -> dict:
219
219
 
220
220
 
221
221
  def runner_env() -> dict:
222
- """The environment of the runner's own caddis_roadmap.py children (writes, merge chain, render): headless_env
222
+ """The environment of the runner's own caddis_roadmap.py children (writes, merge chain): headless_env
223
223
  plus the runner's gh login. Never given to a session."""
224
224
  env = headless_env()
225
225
  env.update(caddis_roadmap.AUTH_ENV)
@@ -1257,32 +1257,13 @@ def run(*, repo: Path, plan: str | None = None, roadmap: str | None = None, caps
1257
1257
  caddis_roadmap.AUTH_ENV["GH_TOKEN"] = value # the runner's own calls only; never a session's env
1258
1258
  if roadmap is not None:
1259
1259
  rm_cmd = list(roadmap_cmd or default_roadmap_cmd())
1260
- try:
1261
- return _run_roadmap(ctx, template, dry_run, after_session, rm_cmd,
1262
- hostname or socket.gethostname(), publish or default_publish,
1263
- pr_merged or default_pr_merged, worktree_root,
1264
- delete_remote_branch or default_delete_remote_branch, pr_closed or default_pr_closed)
1265
- finally:
1266
- if not dry_run:
1267
- _render_page(ctx, rm_cmd) # the page shows where the run stopped and what waits for the owner
1260
+ return _run_roadmap(ctx, template, dry_run, after_session, rm_cmd,
1261
+ hostname or socket.gethostname(), publish or default_publish,
1262
+ pr_merged or default_pr_merged, worktree_root,
1263
+ delete_remote_branch or default_delete_remote_branch, pr_closed or default_pr_closed)
1268
1264
  return _run_plan(ctx, template, dry_run, after_session)
1269
1265
 
1270
1266
 
1271
- PAGE_RENDER_TIMEOUT_S = 120
1272
-
1273
-
1274
- def _render_page(ctx: "_Ctx", roadmap_cmd: Sequence[str]) -> None:
1275
- """Re-render the local roadmap page (roadmap-page Phase 3). Best effort: a failure is one stderr line, never a stop."""
1276
- argv = [*roadmap_cmd, "render", "--roadmap", ctx.target.slug, "--root", str(ctx.repo)]
1277
- try:
1278
- proc = subprocess.run(argv, cwd=ctx.repo, env=runner_env(), stdin=subprocess.DEVNULL, capture_output=True,
1279
- text=True, encoding="utf-8", errors="replace", timeout=PAGE_RENDER_TIMEOUT_S)
1280
- if proc.returncode != 0:
1281
- print(f"caddis_roadmap_run: page not rendered (exit {proc.returncode})", file=sys.stderr)
1282
- except Exception as exc: # a page must never change how a run ends
1283
- print(f"caddis_roadmap_run: page not rendered: {type(exc).__name__}", file=sys.stderr)
1284
-
1285
-
1286
1267
  def _dry_run_tail(ctx: _Ctx, template: Path, prompt: str, cwd: Path | None = None) -> None:
1287
1268
  caps = ctx.caps
1288
1269
  cmd = build_command(ctx.engine, ctx.model, "<resume prompt>", usd=min(caps.max_usd_per_session, caps.max_usd_total),
@@ -2159,7 +2140,6 @@ def _run_roadmap(ctx: _Ctx, template: Path, dry_run: bool, after_session: Callab
2159
2140
  finally:
2160
2141
  s.record.setdefault("status", "FAILED")
2161
2142
  ctx.log(s.record)
2162
- _render_page(ctx, roadmap_cmd)
2163
2143
  if after_session is not None:
2164
2144
  after_session(sessions)
2165
2145
  except _Stop as stop:
@@ -46,10 +46,8 @@ Keep it short enough to read at a glance. Roughly:
46
46
  - **The next step**, if one is recorded. Say which file it came from.
47
47
  - **Uncommitted work**, if `git status` is dirty — this is the thing most likely to be lost, and
48
48
  the state file does not track it. Check it; do not assume clean.
49
- - **The roadmap page**, when the repo has a roadmap (`.caddis/roadmaps/`): re-render it with
50
- `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_roadmap.py" render --all` (best effort) and give the path it prints
51
- (`~/.caddis/roadmap-pages/<repo>/<slug>.html`); it shows every session waiting for the owner. The hub of every
52
- repo on this machine is `~/.caddis/roadmap-pages/index.html`.
49
+ - **The roadmap**, when the repo has one (`.caddis/roadmaps/`): open the hub: `caddis hub open`, repo, Roadmap
50
+ tab. The hub also lists every live session that waits for the owner.
53
51
 
54
52
  Leave out anything already done unless the user asks. "What is finished" is a different question
55
53
  from "where are we", and the completed list is usually the longest part of both files.
@@ -336,12 +336,6 @@ un-indexed note, or `caddis_tidy.py --apply` for a finished artifact in the wron
336
336
  not a failure of the handoff: the row is `done` when all three ran. If a script is missing, the row is
337
337
  `skipped: <script> not installed`.
338
338
 
339
- Then, when the repo has a roadmap (`.caddis/roadmaps/`), re-render its page so phases built by hand show too
340
- (best effort, not a checklist row; it writes only under `~/.caddis/roadmap-pages/`, never in this checkout):
341
- ```
342
- python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_roadmap.py" render --all
343
- ```
344
-
345
339
  ## Step 6d — remove this session's own worktrees and scratch folders
346
340
  Checklist row 12, `own-cleanup`. It runs in every checkout, a shared one too, after the Step 0 `finish`
347
341
  (falls back to `scripts/caddis_created.py` in a source checkout; if the script is missing, or exits 2 because
@@ -190,9 +190,8 @@ If the default branch triggers an automated deployment pipeline:
190
190
  - Delete the **local** feature branch: `git branch -d <branch>` (use `-D` only if squashed after verifying tree contents match).
191
191
  - Delete the **remote** feature branch: `git push origin --delete <branch>` (if not deleted by forge).
192
192
  - Drop the temporary `backup/<branch>-preship` ref if one was created in Step 4.
193
- - If the repo has a roadmap (`.caddis/roadmaps/`), re-render its page, because the merge changed a Tracker on origin:
194
- `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_roadmap.py" render --all` (best effort; a failure is a note, not a
195
- stop). The page is `~/.caddis/roadmap-pages/<repo>/<slug>.html`.
193
+ - If the repo has a roadmap (`.caddis/roadmaps/`), the merge changed a Tracker on origin. To see it: open the hub:
194
+ `caddis hub open`, repo, Roadmap tab.
196
195
 
197
196
  If deploy validation failed: **skip cleanup** entirely and report why — never delete a branch whose
198
197
  work may need re-work.
@@ -70,7 +70,6 @@ process tree on timeout.
70
70
 
71
71
  ```bash
72
72
  python scripts/caddis_roadmap.py status --roadmap <slug> [--json] # "<done> of <total> done; next <id>; ..."
73
- python scripts/caddis_roadmap.py render --roadmap <slug> | --all [--out <html>] # page: ~/.caddis/roadmap-pages/<repo>/<slug>.html; hub of every repo: ~/.caddis/roadmap-pages/index.html
74
73
  python scripts/caddis_roadmap.py next --roadmap <slug> [--json] # exit 0 found, 1 nothing ready (reasons)
75
74
  python scripts/caddis_roadmap.py check --roadmap <slug> # parse errors, unknown refs or types
76
75
  python scripts/caddis_roadmap.py set --roadmap <slug> --id S1 --col Status|Owner|Target --value <v> [--by-owner] [--reason "<r>"]
@@ -70,7 +70,6 @@ process tree on timeout.
70
70
 
71
71
  ```bash
72
72
  python scripts/caddis_roadmap.py status --roadmap <slug> [--json] # "<done> of <total> done; next <id>; ..."
73
- python scripts/caddis_roadmap.py render --roadmap <slug> | --all [--out <html>] # page: ~/.caddis/roadmap-pages/<repo>/<slug>.html; hub of every repo: ~/.caddis/roadmap-pages/index.html
74
73
  python scripts/caddis_roadmap.py next --roadmap <slug> [--json] # exit 0 found, 1 nothing ready (reasons)
75
74
  python scripts/caddis_roadmap.py check --roadmap <slug> # parse errors, unknown refs or types
76
75
  python scripts/caddis_roadmap.py set --roadmap <slug> --id S1 --col Status|Owner|Target --value <v> [--by-owner] [--reason "<r>"]