Skip to content

An always-on second brain you talk to. Voice notes in Telegram → typed, linked knowledge in your Obsidian vault. Runs 24/7 on the Claude subscription you already have.

feat(cron): self-management CLI (python -m d_brain.cron)

smixsb154ec0ac93e
diff --git a/src/d_brain/cron.py b/src/d_brain/cron.py
new file mode 100644
index 0000000..00ee229
--- /dev/null
+++ b/src/d_brain/cron.py
@@ -0,0 +1,176 @@
+"""Self-management CLI for cron jobs: ``python -m d_brain.cron``.
+
+This is the brain's interface to its own schedule — the brain (a Claude
+Code session with Bash) calls it; the in-bot ticker picks the file up on
+the next tick. Standalone on purpose: it must run without the bot's
+required env (tokens), so it never imports Settings. Defaults follow the
+same env vars Settings reads (RUNTIME_DIR, TZ).
+"""
+
+import argparse
+import os
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from d_brain.services.cron_store import (
+ CronJob,
+ CronStore,
+ compute_next_run,
+ parse_schedule,
+)
+
+
+def _default_cron_dir() -> str:
+ runtime = Path(os.environ.get("RUNTIME_DIR", "~/.dbrain")).expanduser()
+ return str(runtime / "cron")
+
+
+def _default_tz() -> str:
+ return os.environ.get("TZ") or "UTC"
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(
+ prog="python -m d_brain.cron",
+ description="Manage d-brain scheduled jobs (jobs.json)",
+ )
+ sub = parser.add_subparsers(dest="command", required=True)
+
+ def add_dir(p: argparse.ArgumentParser) -> None:
+ p.add_argument("--dir", default=_default_cron_dir(), help="cron state dir")
+
+ p_add = sub.add_parser("add", help="add a job")
+ add_dir(p_add)
+ p_add.add_argument("--prompt", required=True, help="instruction for the run")
+ p_add.add_argument("--at", help="one-shot ISO datetime")
+ p_add.add_argument("--every", type=int, help="interval in seconds")
+ p_add.add_argument("--cron", help="5-field cron expression")
+ p_add.add_argument("--tz", default=_default_tz(), help="IANA timezone")
+ p_add.add_argument("--id", dest="job_id", help="job id (default: generated)")
+ p_add.add_argument("--chat-id", type=int, help="Telegram chat for delivery")
+ p_add.add_argument("--delete-after-run", action="store_true")
+
+ p_list = sub.add_parser("list", help="list jobs")
+ add_dir(p_list)
+
+ p_remove = sub.add_parser("remove", help="remove a job")
+ p_remove.add_argument("job_id")
+ add_dir(p_remove)
+
+ p_enable = sub.add_parser("enable", help="re-enable an auto-disabled job")
+ p_enable.add_argument("job_id")
+ add_dir(p_enable)
+
+ return parser
+
+
+def _fmt_schedule(job: CronJob) -> str:
+ s = job.schedule
+ if s.kind == "at":
+ return f"at {s.at}"
+ if s.kind == "every":
+ return f"every {s.every_seconds}s"
+ return f"cron '{s.expr}' ({s.tz})"
+
+
+def _cmd_add(args: argparse.Namespace) -> int:
+ store = CronStore(Path(args.dir))
+ now = datetime.now(timezone.utc)
+ schedule = parse_schedule(
+ at=args.at, every=args.every, cron=args.cron, tz=args.tz, default_tz=args.tz
+ )
+ next_run = compute_next_run(schedule, now=now)
+ if schedule.kind == "at" and next_run is not None and next_run <= now:
+ raise ValueError(f"--at {args.at} is in the past")
+ job = CronJob(
+ id=args.job_id or f"{schedule.kind}-{uuid.uuid4().hex[:6]}",
+ prompt=args.prompt,
+ schedule=schedule,
+ chat_id=args.chat_id,
+ delete_after_run=args.delete_after_run,
+ created_at=now.isoformat(),
+ )
+ job.state.next_run = next_run.isoformat() if next_run else None
+
+ def insert(jobs: list[CronJob]) -> None:
+ if any(j.id == job.id for j in jobs):
+ raise ValueError(f"job id already exists: {job.id}")
+ jobs.append(job)
+
+ store.mutate(insert)
+ print(f"added {job.id} ({_fmt_schedule(job)}); next run {job.state.next_run}")
+ return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+ jobs = CronStore(Path(args.dir)).load()
+ if not jobs:
+ print("no jobs")
+ return 0
+ for j in jobs:
+ flags = "" if j.enabled else " [disabled]"
+ oneshot = " [one-shot]" if j.delete_after_run else ""
+ print(
+ f"{j.id}: {_fmt_schedule(j)}{oneshot}{flags}\n"
+ f" next: {j.state.next_run} last: {j.state.last_run or '-'} "
+ f"({j.state.last_status or '-'})\n"
+ f" prompt: {j.prompt}"
+ )
+ return 0
+
+
+def _find(jobs: list[CronJob], job_id: str) -> CronJob:
+ for j in jobs:
+ if j.id == job_id:
+ return j
+ raise ValueError(f"no such job: {job_id}")
+
+
+def _cmd_remove(args: argparse.Namespace) -> int:
+ store = CronStore(Path(args.dir))
+
+ def drop(jobs: list[CronJob]) -> None:
+ jobs.remove(_find(jobs, args.job_id))
+
+ store.mutate(drop)
+ print(f"removed {args.job_id}")
+ return 0
+
+
+def _cmd_enable(args: argparse.Namespace) -> int:
+ store = CronStore(Path(args.dir))
+ now = datetime.now(timezone.utc)
+
+ def fix(jobs: list[CronJob]) -> None:
+ job = _find(jobs, args.job_id)
+ job.enabled = True
+ job.state.consecutive_errors = 0
+ nxt = compute_next_run(job.schedule, now=now)
+ job.state.next_run = nxt.isoformat() if nxt else None
+
+ store.mutate(fix)
+ print(f"enabled {args.job_id}")
+ return 0
+
+
+_COMMANDS = {
+ "add": _cmd_add,
+ "list": _cmd_list,
+ "remove": _cmd_remove,
+ "enable": _cmd_enable,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+ args = build_parser().parse_args(argv)
+ try:
+ return _COMMANDS[args.command](args)
+ except (ValueError, OSError) as exc:
+ print(f"error: {exc}", file=sys.stderr)
+ return 2
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/test_cron_cli.py b/tests/test_cron_cli.py
new file mode 100644
index 0000000..f479ed6
--- /dev/null
+++ b/tests/test_cron_cli.py
@@ -0,0 +1,177 @@
+"""Tests for the self-management CLI (python -m d_brain.cron).
+
+The CLI is what the brain calls via Bash, so its contract is the UX:
+human-readable output, exit 0 on success, exit 2 on bad input.
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from d_brain.cron import main
+from d_brain.services.cron_store import CronStore
+
+
+def _dir(tmp_path):
+ return str(tmp_path / "cron")
+
+
+def _future_iso():
+ return (datetime.now(timezone.utc) + timedelta(hours=2)).isoformat()
+
+
+def test_add_every_writes_job_and_prints_id(tmp_path, capsys):
+ rc = main(
+ ["add", "--dir", _dir(tmp_path), "--prompt", "check inbox", "--every", "3600"]
+ )
+ assert rc == 0
+ out = capsys.readouterr().out
+ jobs = CronStore(tmp_path / "cron").load()
+ assert len(jobs) == 1
+ assert jobs[0].prompt == "check inbox"
+ assert jobs[0].state.next_run is not None
+ assert jobs[0].id in out
+ assert "next run" in out
+
+
+def test_add_cron_with_explicit_id_and_tz(tmp_path, capsys):
+ rc = main(
+ [
+ "add",
+ "--dir",
+ _dir(tmp_path),
+ "--prompt",
+ "morning brief",
+ "--cron",
+ "0 9 * * *",
+ "--tz",
+ "Asia/Tashkent",
+ "--id",
+ "morning-brief",
+ ]
+ )
+ assert rc == 0
+ jobs = CronStore(tmp_path / "cron").load()
+ assert jobs[0].id == "morning-brief"
+ assert jobs[0].schedule.tz == "Asia/Tashkent"
+ assert "morning-brief" in capsys.readouterr().out
+
+
+def test_add_oneshot_at_with_delete_after_run(tmp_path):
+ rc = main(
+ [
+ "add",
+ "--dir",
+ _dir(tmp_path),
+ "--prompt",
+ "remind about the call",
+ "--at",
+ _future_iso(),
+ "--delete-after-run",
+ ]
+ )
+ assert rc == 0
+ jobs = CronStore(tmp_path / "cron").load()
+ assert jobs[0].delete_after_run is True
+ assert jobs[0].schedule.kind == "at"
+
+
+def test_add_at_in_the_past_exits_2(tmp_path, capsys):
+ past = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
+ rc = main(["add", "--dir", _dir(tmp_path), "--prompt", "x", "--at", past])
+ assert rc == 2
+ assert "past" in capsys.readouterr().err
+
+
+def test_add_two_kinds_exits_2(tmp_path, capsys):
+ rc = main(
+ [
+ "add",
+ "--dir",
+ _dir(tmp_path),
+ "--prompt",
+ "x",
+ "--every",
+ "60",
+ "--cron",
+ "0 9 * * *",
+ ]
+ )
+ assert rc == 2
+ assert capsys.readouterr().err
+
+
+def test_add_duplicate_id_exits_2(tmp_path):
+ args = [
+ "add",
+ "--dir",
+ _dir(tmp_path),
+ "--prompt",
+ "x",
+ "--every",
+ "60",
+ "--id",
+ "dup",
+ ]
+ assert main(args) == 0
+ assert main(args) == 2
+
+
+def test_list_is_human_readable(tmp_path, capsys):
+ main(
+ [
+ "add",
+ "--dir",
+ _dir(tmp_path),
+ "--prompt",
+ "morning brief",
+ "--cron",
+ "0 9 * * *",
+ "--tz",
+ "Asia/Tashkent",
+ "--id",
+ "morning-brief",
+ ]
+ )
+ capsys.readouterr()
+ rc = main(["list", "--dir", _dir(tmp_path)])
+ assert rc == 0
+ out = capsys.readouterr().out
+ assert "morning-brief" in out
+ assert "0 9 * * *" in out
+ assert "next" in out.lower()
+
+
+def test_list_empty_store(tmp_path, capsys):
+ rc = main(["list", "--dir", _dir(tmp_path)])
+ assert rc == 0
+ assert "no jobs" in capsys.readouterr().out.lower()
+
+
+def test_remove_deletes_job(tmp_path):
+ main(
+ ["add", "--dir", _dir(tmp_path), "--prompt", "x", "--every", "60", "--id", "z"]
+ )
+ assert main(["remove", "z", "--dir", _dir(tmp_path)]) == 0
+ assert CronStore(tmp_path / "cron").load() == []
+
+
+def test_remove_unknown_id_exits_2(tmp_path, capsys):
+ assert main(["remove", "ghost", "--dir", _dir(tmp_path)]) == 2
+ assert "ghost" in capsys.readouterr().err
+
+
+def test_enable_reenables_and_resets_errors(tmp_path):
+ main(
+ ["add", "--dir", _dir(tmp_path), "--prompt", "x", "--every", "60", "--id", "e"]
+ )
+ store = CronStore(tmp_path / "cron")
+
+ def break_it(jobs):
+ jobs[0].enabled = False
+ jobs[0].state.consecutive_errors = 3
+
+ store.mutate(break_it)
+ assert main(["enable", "e", "--dir", _dir(tmp_path)]) == 0
+ job = store.load()[0]
+ assert job.enabled is True
+ assert job.state.consecutive_errors == 0
+ assert job.state.next_run is not None