ckb/.agents/skills/ckb-routine/scripts/routines.py
Michał Kopeć 000e633cdb Template 1.16.0: session title asked at start, routines in ckb.yaml
- Rule E opens a new session with the title question (conversations.ask_title);
  save_conversation.py --set-title stores it, saved transcripts and workload use it
- New ckb-routine skill + routines.py: time-since-last actions in ckb.yaml,
  checked at session start, run after the user's request, last_run committed
- Docs EN/PL, D-0005, smoke test coverage for both scripts

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-21 21:47:36 +02:00

275 lines
10 KiB
Python
Executable file

#!/usr/bin/env python3
"""Routines: actions that fire when a period has elapsed since they last ran.
Definitions and state both live in the `routines:` block of ckb.yaml:
routines:
- name: weekly-lint
do: "Lint" # any phrase from the AGENTS.md routing table, or a plain instruction
every: 7d # Nh | Nd | Nw
confirm: false # true: ask before running instead of running after the request
last_run: 2026-10-21 # written by --mark when the action completes; blank = never ran
routines.py --due [--today YYYY-MM-DD] # one line per due routine; exit 1 when any is due, 0 otherwise
routines.py --list # every routine with last run, next due date and confirm flag
routines.py --mark <name> [--today ...] # set last_run to today
routines.py --add --name X --do "..." --every 7d [--confirm]
routines.py --remove <name>
Edits are line-level: only the lines of the routine named are touched, the
rest of ckb.yaml is left byte for byte. Python 3.8+, standard library only.
"""
import argparse
import re
import sys
from datetime import date, datetime, timedelta
from pathlib import Path
PERIOD = re.compile(r"^(\d+)([hdw])$")
NAME = re.compile(r"^[a-z0-9][a-z0-9-]*$")
FORBIDDEN = ("ckb-reset", "ckb-sync-changes", "reset the wiki", "sync changes", "sync with origin")
KEYS = ("name", "do", "every", "confirm", "last_run")
# ---------------------------------------------------------------- parsing
def strip_comment(line: str) -> str:
out, quote = [], None
for ch in line:
if quote:
out.append(ch)
if ch == quote:
quote = None
elif ch in "\"'":
quote = ch
out.append(ch)
elif ch == "#":
break
else:
out.append(ch)
return "".join(out).rstrip()
def unquote(v: str) -> str:
v = v.strip()
if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
return v[1:-1]
return v
def parse(path: Path):
"""Return (lines, block) where block is None when there is no `routines:` key,
else a dict with start/end line indexes and a list of routine items, each
carrying its own line span and key->(value, line_index)."""
lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
start = None
for i, raw in enumerate(lines):
if strip_comment(raw).strip() == "routines:" and not raw.startswith((" ", "\t")):
start = i
break
if strip_comment(raw).strip().startswith("routines:") and not raw.startswith((" ", "\t")):
# `routines: []` or similar inline value
start = i
break
if start is None:
return lines, None
end = len(lines)
for j in range(start + 1, len(lines)):
raw = lines[j]
if raw.strip() and not raw.startswith((" ", "\t")) and not raw.lstrip().startswith("#"):
end = j
break
items, cur = [], None
for j in range(start + 1, end):
text = strip_comment(lines[j])
if not text.strip():
continue
m = re.match(r"^(\s*)-\s*(.*)$", text)
if m:
cur = {"first": j, "last": j, "indent": len(m.group(1)), "fields": {}}
items.append(cur)
rest = m.group(2)
if ":" in rest:
k, v = rest.split(":", 1)
cur["fields"][k.strip()] = (unquote(v), j)
continue
if cur is not None and ":" in text:
k, v = text.strip().split(":", 1)
cur["fields"][k.strip()] = (unquote(v), j)
cur["last"] = j
inline = strip_comment(lines[start]).split(":", 1)[1].strip()
return lines, {"start": start, "end": end, "items": items, "inline_empty": inline in ("[]", "")}
def routine(item):
f = item["fields"]
get = lambda k: f.get(k, ("", None))[0]
return {
"name": get("name"), "do": get("do"), "every": get("every"),
"confirm": get("confirm").lower() in ("true", "yes", "on"),
"last_run": get("last_run"),
}
def period_delta(spec: str) -> timedelta:
m = PERIOD.match(spec.strip())
if not m:
raise ValueError(f"bad period {spec!r}: use Nh, Nd or Nw (e.g. 24h, 7d, 2w)")
n, unit = int(m.group(1)), m.group(2)
return {"h": timedelta(hours=n), "d": timedelta(days=n), "w": timedelta(weeks=n)}[unit]
def parse_day(s: str):
try:
return datetime.strptime(s.strip(), "%Y-%m-%d")
except ValueError:
return None
def status(r, today: datetime):
"""(due: bool, next_due: datetime|None, detail: str). last_run is a date, taken at 00:00,
so hour periods are coarse: 24h behaves like 1d."""
if not r["every"]:
return False, None, "no period"
try:
every = period_delta(r["every"])
except ValueError as e:
return False, None, str(e)
if not r["last_run"]:
return True, today, "never ran"
last = parse_day(r["last_run"])
if last is None:
return True, today, f"unreadable last_run {r['last_run']!r}"
nxt = last + every
if nxt <= today:
over = today - nxt
return True, nxt, f"overdue by {over.days}d" if over.days else "due today"
return False, nxt, f"next {nxt.strftime('%Y-%m-%d')}"
# ---------------------------------------------------------------- writing
def write(path: Path, lines):
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
def find(block, name):
for it in block["items"]:
if it["fields"].get("name", ("",))[0] == name:
return it
return None
def cmd_mark(path, name, today):
lines, block = parse(path)
it = block and find(block, name)
if not it:
sys.exit(f"error: no routine named {name!r} in {path}")
stamp = today.strftime("%Y-%m-%d")
if "last_run" in it["fields"]:
j = it["fields"]["last_run"][1]
lines[j] = re.sub(r"(last_run:\s*)\S*", r"\g<1>" + stamp, lines[j], count=1)
else:
pad = " " * (it["indent"] + 2)
lines.insert(it["last"] + 1, f"{pad}last_run: {stamp}")
write(path, lines)
print(f"marked {name}: last_run {stamp}")
def cmd_add(path, name, do, every, confirm):
if not NAME.match(name):
sys.exit("error: name must be lower-case letters, digits and hyphens")
period_delta(every)
low = do.lower()
if any(f in low for f in FORBIDDEN):
sys.exit("error: a routine may not run ckb-reset or ckb-sync-changes (destructive / touches the remote)")
lines, block = parse(path)
if block and find(block, name):
sys.exit(f"error: routine {name!r} already exists; --remove it first")
do_q = '"' + do.replace('"', "'") + '"'
item = [f" - name: {name}", f" do: {do_q}", f" every: {every}",
f" confirm: {'true' if confirm else 'false'}", f" last_run:"]
if block is None:
if lines and lines[-1].strip():
lines.append("")
lines.append("routines: # actions that fire when `every` has elapsed since `last_run`")
lines.extend(item)
else:
if block["inline_empty"]:
# `routines: [] # comment` -> `routines: # comment`: drop the brackets, keep the width
lines[block["start"]] = lines[block["start"]].replace("[]", " ", 1).rstrip()
lines[block["end"]:block["end"]] = item
write(path, lines)
print(f"added {name}: {do} every {every}" + (" (confirm first)" if confirm else "") + " — fires at the next session start")
def cmd_remove(path, name):
lines, block = parse(path)
it = block and find(block, name)
if not it:
sys.exit(f"error: no routine named {name!r} in {path}")
del lines[it["first"]:it["last"] + 1]
if len(block["items"]) == 1: # that was the last one: leave an explicit empty list
head = lines[block["start"]]
if re.match(r"^routines:\s{3,}#", head): # width was kept by --add: put the brackets back
lines[block["start"]] = re.sub(r"^routines: ", "routines: []", head, count=1)
else:
lines[block["start"]] = "routines: []"
write(path, lines)
print(f"removed {name}")
# ---------------------------------------------------------------- main
def main(argv=None):
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
g = ap.add_mutually_exclusive_group(required=True)
g.add_argument("--due", action="store_true")
g.add_argument("--list", action="store_true")
g.add_argument("--mark", metavar="NAME")
g.add_argument("--add", action="store_true")
g.add_argument("--remove", metavar="NAME")
ap.add_argument("--name"); ap.add_argument("--do"); ap.add_argument("--every")
ap.add_argument("--confirm", action="store_true")
ap.add_argument("--root", default=".", help="KB root (default: current directory)")
ap.add_argument("--today", help="override today's date, YYYY-MM-DD (tests)")
a = ap.parse_args(argv)
path = Path(a.root) / "ckb.yaml"
today = parse_day(a.today) if a.today else datetime.combine(date.today(), datetime.min.time())
if today is None:
sys.exit("error: --today must be YYYY-MM-DD")
if a.mark:
cmd_mark(path, a.mark, today); return 0
if a.add:
if not (a.name and a.do and a.every):
sys.exit("error: --add needs --name, --do and --every")
cmd_add(path, a.name, a.do, a.every, a.confirm); return 0
if a.remove:
cmd_remove(path, a.remove); return 0
_, block = parse(path)
items = [routine(it) for it in (block["items"] if block else [])]
if a.list:
if not items:
print("no routines in ckb.yaml"); return 0
for r in items:
due, _, detail = status(r, today)
flag = "DUE " if due else " "
print(f"{flag}{r['name']:<20} every {r['every']:<5} last {r['last_run'] or 'never':<10} {detail}"
+ (" [confirm]" if r["confirm"] else "") + f" — {r['do']}")
return 0
# --due
due_items = []
for r in items:
due, _, detail = status(r, today)
if due:
due_items.append((r, detail))
for r, detail in due_items:
print(f"{r['name']} {r['do']} {detail}" + (" [confirm]" if r["confirm"] else ""))
return 1 if due_items else 0
if __name__ == "__main__":
sys.exit(main())