pyworklog 0.3.0__py3-none-any.whl

worklog/db.py

@@ -0,0 +1,92 @@
+"""SQLite connection and migration runner for worklog.
+
+Functions take their DB path / migrations directory as arguments instead of
+reading module-level globals — `cli.py` keeps the `DB_PATH` / `MIGRATIONS_DIR`
+globals (because `main()` mutates `DB_PATH` per the `--db` flag) and passes
+them in via thin wrappers.
+
+This keeps the schema-upgrade logic isolated and importable from anywhere
+that already has a path, without depending on cli.py's module state.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+def db_connect(db_path: Path) -> sqlite3.Connection:
+    """Open a connection (creating parent dirs if missing). Row factory =
+    sqlite3.Row, foreign-key enforcement enabled."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    con = sqlite3.connect(db_path)
+    con.row_factory = sqlite3.Row
+    con.execute("PRAGMA foreign_keys = ON")
+    return con
+
+
+def migration_files(migrations_dir: Path) -> list[Path]:
+    """Return migration files sorted by NNNN_ numeric prefix; skip filenames
+    without a numeric prefix."""
+    if not migrations_dir.exists():
+        return []
+    files = []
+    for p in migrations_dir.glob("*.sql"):
+        prefix = p.stem.split("_", 1)[0]
+        if prefix.isdigit():
+            files.append((int(prefix), p))
+    files.sort(key=lambda x: x[0])
+    return [p for _, p in files]
+
+
+def db_version(con: sqlite3.Connection) -> int:
+    """The highest migration number applied to this DB (`PRAGMA user_version`)."""
+    return con.execute("PRAGMA user_version").fetchone()[0]
+
+
+def run_migrations(con: sqlite3.Connection, migrations_dir: Path, verbose: bool = False) -> list[Path]:
+    """Apply every migration whose number > `PRAGMA user_version`.
+
+    Each migration runs in its own transaction; `user_version` is bumped
+    per file, so a mid-sequence failure leaves the DB at the last
+    successfully-applied number — re-run after fixing.
+
+    Downgrade guard: if `PRAGMA user_version` exceeds the highest migration
+    number shipped, the DB was written by a newer worklog and must not be
+    touched by older code — abort with a clear message.
+    """
+    files = migration_files(migrations_dir)
+    max_n = max((int(p.stem.split("_", 1)[0]) for p in files), default=0)
+    current = db_version(con)
+    if current > max_n:
+        raise SystemExit(
+            f"✗ DB at user_version={current} but this worklog build only ships "
+            f"migrations up to {max_n}. The DB was written by a newer version; "
+            f"upgrade worklog (e.g. `pip install --upgrade pyworklog`) and retry."
+        )
+    applied = []
+    for path in files:
+        n = int(path.stem.split("_", 1)[0])
+        if n <= current:
+            continue
+        sql = path.read_text(encoding="utf-8")
+        try:
+            con.executescript(sql)
+            con.execute(f"PRAGMA user_version = {n}")
+            con.commit()
+        except Exception:
+            con.rollback()
+            raise
+        if verbose:
+            print(f"✓ applied migration {path.stem}")
+        applied.append(path)
+    return applied
+
+
+def ensure_db(db_path: Path, migrations_dir: Path) -> None:
+    """Open the DB (creating the file if missing) and run any pending migrations."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    con = db_connect(db_path)
+    try:
+        run_migrations(con, migrations_dir)
+    finally:
+        con.close()

worklog/helpers.py

@@ -0,0 +1,288 @@
+"""Pure utility helpers for worklog.
+
+No I/O, no sqlite, no rich — these all take args / strings and return
+args / strings (or types like Path/datetime). Tested in isolation and
+safely importable from any other module without side effects.
+"""
+from __future__ import annotations
+
+
+# generic-dimension tags (planning attributes / priority / type) -- excluded from focus --related, which links only on project/topic tags
+GENERIC_TAGS = {
+    "work", "personal", "planned", "unplanned",
+    "P0", "P1", "P2", "habit", "meeting", "followup",
+    "dev", "ai", "sync", "strategy", "reflection", "reading",
+    "family", "health", "morning_check", "slack_scan",
+}
+
+
+def _status_marker(status):
+    return {
+        None: "[ ]",
+        "TODO": "[ ]",
+        "DOING": "[/]",
+        "LATER": "[>]",
+        "WAIT": "[?]",
+        "DONE": "[x]",
+        "DEFERRED": "[>]",
+        "CANCELED": "[-]",
+    }.get(status, "[ ]")
+
+
+def _resolve_window(args):
+    """Resolve a time window to (since, until) YYYY-MM-DD pair. Priority: week > month > since/until > this Monday to today."""
+    from datetime import date, timedelta
+
+    if getattr(args, "week", None):
+        y, w = args.week.split("-W")
+        monday = date.fromisocalendar(int(y), int(w), 1)
+        return monday.isoformat(), (monday + timedelta(days=6)).isoformat()
+    if getattr(args, "month", None):
+        y, m = (int(x) for x in args.month.split("-"))
+        first = date(y, m, 1)
+        nxt = date(y + 1, 1, 1) if m == 12 else date(y, m + 1, 1)
+        return first.isoformat(), (nxt - timedelta(days=1)).isoformat()
+    today = date.today()
+    since = getattr(args, "since", None) or (today - timedelta(days=today.weekday())).isoformat()
+    until = getattr(args, "until", None) or today.isoformat()
+    return since, until
+
+
+def _resolve_concrete_date(s):
+    """Resolve today/yesterday/tomorrow/day-before-yesterday/day-after-tomorrow/YYYY-MM-DD (and Chinese aliases) to a concrete date string.
+    English aliases are case-insensitive."""
+    from datetime import date, timedelta
+
+    s = s.strip()
+    lower = s.lower()
+    rel = {
+        "today": 0, "今天": 0,
+        "yesterday": -1, "昨天": -1,
+        "day-before-yesterday": -2, "前天": -2,
+        "tomorrow": 1, "明天": 1,
+        "day-after-tomorrow": 2, "后天": 2,
+    }
+    if s in rel:
+        return (date.today() + timedelta(days=rel[s])).isoformat()
+    if lower in rel:
+        return (date.today() + timedelta(days=rel[lower])).isoformat()
+    date.fromisoformat(s)  # validate; raises ValueError on bad input
+    return s
+
+def _resolve_at_ts(at, default_now=True):
+    """Parse --at: HH:MM (today + that time) / YYYY-MM-DD (that day, current time) /
+    YYYY-MM-DD HH:MM[:SS] / ISO with 'T' separator. None -> now.
+    Validates range (rejects 25:00 / month 13); raises ValueError on error.
+    """
+    from datetime import datetime as _dt
+    import re as _re
+    if not at:
+        return _dt.now().strftime("%Y-%m-%d %H:%M:%S") if default_now else None
+    at = at.strip()
+    today = _dt.now().strftime("%Y-%m-%d")
+    if _re.fullmatch(r"\d{2}:\d{2}", at):
+        _dt.strptime(at, "%H:%M")
+        return f"{today} {at}:00"
+    if _re.fullmatch(r"\d{4}-\d{2}-\d{2}", at):
+        _dt.strptime(at, "%Y-%m-%d")
+        return f"{at} {_dt.now().strftime('%H:%M:%S')}"
+    if _re.fullmatch(r"\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2})?", at):
+        ts = at.replace("T", " ")
+        if len(ts) == 16:
+            ts += ":00"
+        _dt.strptime(ts, "%Y-%m-%d %H:%M:%S")
+        return ts
+    raise ValueError(f"invalid --at '{at}': supported formats: HH:MM / YYYY-MM-DD / YYYY-MM-DD HH:MM[:SS]")
+
+
+def _term_width():
+    """Terminal column count. No TTY (pipe/redirect) -> default 80."""
+    import shutil
+    try:
+        return shutil.get_terminal_size().columns or 80
+    except OSError:
+        return 80
+
+def _truncate_log_body(body, indent_cols, full=False):
+    """Truncate log body to one line (terminal width - indent - safety margin), append … at end. full=True keeps body untouched.
+    indent_cols is the column width already occupied before body (indent + marker).
+    CJK characters may take 2 columns; this approximation by character count is acceptable.
+    """
+    if full:
+        return body
+    width = _term_width()
+    # available columns = width - indent_cols - small safety margin (2 cols to avoid edge wrap)
+    avail = max(20, width - indent_cols - 2)
+    # CJK chars take 2 cols; estimate effective usage
+    used = 0
+    out_chars = []
+    for ch in body:
+        w = 2 if ord(ch) > 0x7F else 1
+        if used + w > avail - 1:  # reserve 1 col for …
+            out_chars.append("…")
+            return "".join(out_chars)
+        out_chars.append(ch)
+        used += w
+    return body
+
+
+def _is_brief(args, *extras):
+    """Brief mode: -q/--brief or any extra flag (no_logs/no_timeline/no_body etc.) triggers it.
+    Usage: brief = _is_brief(args, "no_logs", "no_timeline")
+    """
+    if getattr(args, "brief", False):
+        return True
+    return any(getattr(args, e, False) for e in extras)
+
+def _resolve_log_tail(args, brief, default_tail=3):
+    """Unified log tail resolution. Shared by all commands that show log lists.
+
+    Priority (high to low):
+    - brief / --no-logs / --no-timeline / --no-body -> 0 (none shown)
+    - --all-logs (or --all-timeline) -> None (full expansion)
+    - --log-tail N (or --timeline-tail N / --tail N) -> N
+    - otherwise -> default_tail (usually 3)
+    """
+    if brief:
+        return 0
+    if (getattr(args, "all_logs", False) or getattr(args, "all_timelines", False)
+            or getattr(args, "all_timeline", False)):
+        return None
+    for attr in ("log_tail", "timeline_tail", "tail"):
+        v = getattr(args, attr, None)
+        if v is not None:
+            return v
+    return default_tail
+
+
+def _norm_sched(s):
+    """Normalize user-input scheduled time. Returns normalized string; raises ValueError on bad input; empty returns None.
+    Accepts YYYY-MM-DD / YYYY-MM / YYYY-Www / YYYY-Qn / YYYY / someday
+    + relative words today|tomorrow|next-week|next-month|next-quarter."""
+    import re as _re
+    import datetime as _dt
+    if s is None:
+        return None
+    s = s.strip()
+    if not s:
+        return None
+    today = _dt.date.today()
+    if s in ("today", "今天"):
+        return today.isoformat()
+    if s in ("tomorrow", "明天"):
+        return (today + _dt.timedelta(days=1)).isoformat()
+    if s in ("next-week", "下周", "下个星期"):
+        y, w, _ = (today + _dt.timedelta(days=7)).isocalendar()
+        return f"{y}-W{w:02d}"
+    if s in ("next-month", "下月", "下个月"):
+        y, m = (today.year + 1, 1) if today.month == 12 else (today.year, today.month + 1)
+        return f"{y}-{m:02d}"
+    if s in ("next-quarter", "下季", "下个季度"):
+        q = (today.month - 1) // 3 + 1
+        ny, nq = (today.year + 1, 1) if q == 4 else (today.year, q + 1)
+        return f"{ny}-Q{nq}"
+    if s in ("someday", "以后", "有空", "总有一天"):
+        return "someday"
+    if _re.fullmatch(r"\d{4}-\d{2}-\d{2}", s):
+        _dt.date.fromisoformat(s)  # validate; raises ValueError on bad input
+        return s
+    if _re.fullmatch(r"\d{4}-\d{2}", s):
+        if not 1 <= int(s[5:7]) <= 12:
+            raise ValueError(f"invalid month: {s}")
+        return s
+    if _re.fullmatch(r"\d{4}-W\d{2}", s):
+        if not 1 <= int(s[6:]) <= 53:
+            raise ValueError(f"invalid week: {s}")
+        return s
+    if _re.fullmatch(r"\d{4}-Q[1-4]", s):
+        return s
+    if _re.fullmatch(r"\d{4}", s):
+        return s
+    raise ValueError(
+        f"unrecognized scheduled time '{s}' (use YYYY-MM-DD / YYYY-MM / YYYY-Www / YYYY-Qn / YYYY / someday / tomorrow / next-week / next-month / next-quarter)")
+
+def _sched_kind(s):
+    """Normalized value -> granularity: day/week/month/quarter/year/someday/fuzzy"""
+    import re as _re
+    if not s:
+        return None
+    if s == "someday":
+        return "someday"
+    if _re.fullmatch(r"\d{4}-\d{2}-\d{2}", s):
+        return "day"
+    if _re.fullmatch(r"\d{4}-W\d{2}", s):
+        return "week"
+    if _re.fullmatch(r"\d{4}-\d{2}", s):
+        return "month"
+    if _re.fullmatch(r"\d{4}-Q[1-4]", s):
+        return "quarter"
+    if _re.fullmatch(r"\d{4}", s):
+        return "year"
+    return "fuzzy"
+
+def _sched_anchor(s):
+    """Normalized value -> anchor date (for sorting). someday/fuzzy -> far-future, sorts last."""
+    import datetime as _dt
+    k = _sched_kind(s)
+    try:
+        if k == "day":
+            return s
+        if k == "month":
+            return s + "-01"
+        if k == "year":
+            return s + "-01-01"
+        if k == "quarter":
+            y, q = int(s[:4]), int(s[6])
+            return f"{y}-{(q - 1) * 3 + 1:02d}-01"
+        if k == "week":
+            return _dt.date.fromisocalendar(int(s[:4]), int(s[6:]), 1).isoformat()
+    except (ValueError, IndexError):
+        # fromisoformat / fromisocalendar / int() / slice out of range -> treat as unparseable, use sentinel
+        pass
+    return "9999-12-31"
+
+def _sched_sort_key(s):
+    """Sort key (anchor date, granularity rank). Coarser granularities sort later; someday/fuzzy last. Callers compose final keys."""
+    rank = {"day": 0, "week": 1, "month": 2, "quarter": 3, "year": 4, "someday": 9, "fuzzy": 9}
+    return (_sched_anchor(s), rank.get(_sched_kind(s), 9))
+
+def _sched_display(s):
+    """Display: precise dates show MM-DD only (current-year context); fuzzy values shown as-is (month/week/quarter/year/someday)."""
+    if not s:
+        return ""
+    return s[5:] if _sched_kind(s) == "day" else s
+
+
+def _fmt_dur(minutes):
+    """Compact duration format: [2h30m] / [45m] / [0] hidden. ASCII-safe, no reliance on emoji widths."""
+    if not minutes or minutes <= 0:
+        return ""
+    h, m = divmod(int(minutes), 60)
+    if h:
+        return f"[{h}h{m}m]" if m else f"[{h}h]"
+    return f"[{m}m]"
+
+
+def _apply_top_limit(rows, args):
+    """Truncate the list by args.top / args.limit; return (rows, total_before).
+    `--top` takes the first N (rows are already in target order); `--limit` further truncates the display.
+    """
+    total = len(rows)
+    top = getattr(args, "top", None)
+    if top is not None and top > 0:
+        rows = rows[:top]
+    limit = getattr(args, "limit", None)
+    if limit is not None and limit > 0:
+        rows = rows[:limit]
+    return rows, total
+
+
+def _log_full(args):
+    """args.log_format == 'full' -> True; otherwise (including None / 'oneline') -> False."""
+    return getattr(args, "log_format", "oneline") == "full"
+
+
+# SQL / kind constants shared between command modules
+_ORDER_BY_PRI_ID = "ORDER BY priority NULLS LAST, id"
+_TIME_KINDS = {"lifetime", "decade", "year", "quarter", "month", "week", "day"}
+

worklog/migrations/0001_initial_schema.sql

@@ -0,0 +1,90 @@
+-- worklog schema v0
+-- main table: node (one id space spans lifetime / decade / year / quarter / month / week / day / area / project / task / signal / habit / any custom kind)
+-- tree: parent_id self-reference
+-- multi-log: log table hangs off node
+-- multi-tag: tag table (many-to-many)
+-- multi-field: prop table (UDA-style key/value)
+-- vault wikilink: link table
+
+CREATE TABLE IF NOT EXISTS node (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    parent_id    INTEGER REFERENCES node(id) ON DELETE SET NULL,
+    title        TEXT NOT NULL,
+    kind         TEXT NOT NULL,        -- lifetime/decade/year/quarter/month/week/day/area/project/task/signal/habit/meetlog/...
+    status       TEXT,                 -- TODO/DOING/LATER/WAIT/DONE/DEFERRED/CANCELED (task-like kinds only)
+    priority     TEXT,                 -- A/B/C (task-like kinds only)
+    created_at   TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+    scheduled_at TEXT,                 -- planned start / appearance date (task-like kinds)
+    deadline_at  TEXT,                 -- hard deadline
+    closed_at    TEXT,                 -- completion / cancel time
+    body         TEXT                  -- optional long content
+);
+
+CREATE INDEX IF NOT EXISTS idx_node_parent ON node(parent_id);
+CREATE INDEX IF NOT EXISTS idx_node_kind ON node(kind);
+CREATE INDEX IF NOT EXISTS idx_node_status ON node(status);
+
+CREATE TABLE IF NOT EXISTS tag (
+    node_id INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+    tag     TEXT NOT NULL,
+    PRIMARY KEY (node_id, tag)
+);
+
+CREATE INDEX IF NOT EXISTS idx_tag_tag ON tag(tag);
+
+CREATE TABLE IF NOT EXISTS log (
+    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+    node_id   INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+    logged_at TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+    body      TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_log_node ON log(node_id);
+CREATE INDEX IF NOT EXISTS idx_log_time ON log(logged_at);
+
+-- forward planning (calendar-like, decoupled from log): pin tasks to a specific day / recurrence rule
+-- on_date and rrule are mutually exclusive; a task can have multiple rows (multi-day / one-off + recurring together)
+-- `wl day` derives planned (hit by sched) vs unplanned (logged with no sched) from this table
+CREATE TABLE IF NOT EXISTS sched (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    node_id    INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+    on_date    TEXT,                 -- a specific day YYYY-MM-DD (one-off)
+    rrule      TEXT,                 -- recurrence rule: daily / weekly:Mon,Wed,Fri
+    created_at TEXT NOT NULL DEFAULT (datetime('now', 'localtime'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_sched_node ON sched(node_id);
+CREATE INDEX IF NOT EXISTS idx_sched_date ON sched(on_date);
+
+-- date metadata (calendar-like): holiday / vacation / makeup-workday / solar-term context; weekday is computed, not stored
+-- can be bulk-imported (e.g. national holidays) plus user customization (personal vacation / makeup days); independent of day-node existence
+CREATE TABLE IF NOT EXISTS date_meta (
+    date  TEXT PRIMARY KEY,        -- YYYY-MM-DD
+    label TEXT NOT NULL            -- e.g. "Labor Day holiday" / "makeup workday" / "solar term: Lesser Fullness" / "annual leave"
+);
+
+CREATE TABLE IF NOT EXISTS prop (
+    node_id INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+    key     TEXT NOT NULL,
+    value   TEXT NOT NULL,
+    PRIMARY KEY (node_id, key)
+);
+
+CREATE TABLE IF NOT EXISTS link (
+    node_id   INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+    vault_doc TEXT NOT NULL,     -- vault document name (no .md suffix)
+    PRIMARY KEY (node_id, vault_doc)
+);
+
+CREATE INDEX IF NOT EXISTS idx_link_doc ON link(vault_doc);
+
+-- view: tree path (used by `wl tree` for display)
+CREATE VIEW IF NOT EXISTS v_node_path AS
+WITH RECURSIVE path(id, depth, label) AS (
+    SELECT id, 0, title FROM node WHERE parent_id IS NULL
+    UNION ALL
+    SELECT n.id, p.depth + 1, p.label || ' / ' || n.title
+    FROM node n
+    JOIN path p ON n.parent_id = p.id
+)
+SELECT * FROM path;

worklog/queries.py

@@ -0,0 +1,216 @@
+"""sqlite-backed query helpers for worklog.
+
+These take a sqlite3.Connection as an argument and don't touch any
+module-level state, so they're safe to import from any module that
+already has a connection. They sit between the pure utilities in
+helpers.py and the command handlers in cli.py.
+"""
+from __future__ import annotations
+
+import sqlite3
+import sys
+from .helpers import GENERIC_TAGS  # noqa: F401
+from .helpers import _resolve_concrete_date
+
+
+def _insert_log(con, nid, entry):
+    """Insert a log. entry can carry a historical date + time:
+    - dict{date, time, body}: date=YYYY-MM-DD / today / yesterday / day-before-yesterday; time=HH:MM optional
+    - string prefixed with 'YYYY-MM-DD content': date only
+    - plain body: use NOW (DB DEFAULT)
+    """
+    import re as _re
+    date, time_part, body = None, None, entry
+    if isinstance(entry, dict):
+        date, time_part, body = entry.get("date"), entry.get("time"), entry["body"]
+    else:
+        m = _re.match(r"^(\d{4}-\d{2}-\d{2})[ T](.*)$", entry)
+        if m:
+            date, body = m.group(1), m.group(2)
+    if date:
+        # parse short form ("yesterday/today/day-before-yesterday/tomorrow/day-after-tomorrow" or YYYY-MM-DD)
+        date = _resolve_concrete_date(date)
+        if time_part:
+            if not _re.match(r"^(?:[01]?\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$", time_part):
+                raise ValueError(f"invalid --time '{time_part}' (expected HH:MM or HH:MM:SS)")
+            # pad seconds
+            if time_part.count(":") == 1:
+                time_part += ":00"
+            logged_at = f"{date} {time_part}"
+        else:
+            logged_at = date
+        con.execute("INSERT INTO log (node_id, logged_at, body) VALUES (?, ?, ?)", (nid, logged_at, body))
+    elif time_part:
+        # no date but time given -> today + that time
+        from datetime import date as _date
+        if not _re.match(r"^(?:[01]?\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$", time_part):
+            raise ValueError(f"invalid --time '{time_part}' (expected HH:MM or HH:MM:SS)")
+        if time_part.count(":") == 1:
+            time_part += ":00"
+        logged_at = f"{_date.today().isoformat()} {time_part}"
+        con.execute("INSERT INTO log (node_id, logged_at, body) VALUES (?, ?, ?)", (nid, logged_at, body))
+    else:
+        con.execute("INSERT INTO log (node_id, body) VALUES (?, ?)", (nid, body))
+
+def _project_members(con, proj_id):
+    """Set of task/meetlog/habit ids linked to a project: structural children (parent) + shared semantic tags"""
+    ids = set()
+    proj_tags = {r["tag"] for r in con.execute("SELECT tag FROM tag WHERE node_id = ?", (proj_id,))} - GENERIC_TAGS
+    for r in con.execute(
+        "SELECT id FROM node WHERE parent_id = ? AND kind IN ('task','meetlog','habit')", (proj_id,)
+    ):
+        ids.add(r["id"])
+    if proj_tags:
+        qm = ",".join("?" * len(proj_tags))
+        for r in con.execute(
+            f"SELECT DISTINCT n.id FROM node n JOIN tag t ON n.id = t.node_id "
+            f"WHERE t.tag IN ({qm}) AND n.kind IN ('task','meetlog','habit')",
+            list(proj_tags),
+        ):
+            ids.add(r["id"])
+    return ids
+
+def _ancestors_chain(con, node_id):
+    """Return the path list[Row] from the top-level root to node (inclusive)."""
+    chain = []
+    cur = con.execute("SELECT * FROM node WHERE id = ?", (node_id,)).fetchone()
+    if not cur:
+        return chain
+    chain.append(cur)
+    while cur["parent_id"]:
+        cur = con.execute("SELECT * FROM node WHERE id = ?", (cur["parent_id"],)).fetchone()
+        if not cur:
+            break
+        chain.append(cur)
+    return list(reversed(chain))
+
+def _node_bucket(con, nid):
+    """Bucket a node into work / personal / other by work/personal tag."""
+    tags = {r["tag"] for r in con.execute("SELECT tag FROM tag WHERE node_id = ?", (nid,))}
+    if "work" in tags:
+        return "work"
+    if "personal" in tags:
+        return "personal"
+    return "other"
+
+def _node_project(con, nid):
+    """Return the project ancestor (id, title) of a node, or (None, '(unassigned)') if none."""
+    for p in _ancestors_chain(con, nid):
+        if p["kind"] == "project":
+            return p["id"], p["title"]
+    return None, "(unassigned)"
+
+def _node_plan(con, nid, sched_ids):
+    """Derive planned/unplanned: schedule-hit = planned; otherwise check transitional planned/unplanned tag; neither -> unplanned (untagged)."""
+    if nid in sched_ids:
+        return "planned"
+    tags = {r["tag"] for r in con.execute("SELECT tag FROM tag WHERE node_id = ?", (nid,))}
+    if "planned" in tags:
+        return "planned"
+    if "unplanned" in tags:
+        return "unplanned"
+    return "unplanned (untagged)"
+
+def _sec_group(con, nid, n, by, sched_ids):
+    """(key, display title) for the secondary group. by in project/priority/plan."""
+    if by == "priority":
+        label = {"A": "P0", "B": "P1", "C": "P2"}.get(n["priority"], "—")
+        return label, label
+    if by == "plan":
+        label = _node_plan(con, nid, sched_ids)
+        return label, label
+    pid, ptitle = _node_project(con, nid)
+    return (pid if pid is not None else ptitle), ptitle
+
+def _collect_descendants(con, root_id):
+    """Recursively collect all descendant ids of a node (excluding self)."""
+    acc = []
+    stack = [root_id]
+    while stack:
+        pid = stack.pop()
+        children = con.execute("SELECT id FROM node WHERE parent_id = ?", (pid,)).fetchall()
+        for c in children:
+            acc.append(c["id"])
+            stack.append(c["id"])
+    return acc
+
+def _has_tag(con, nid, tag):
+    return con.execute("SELECT 1 FROM tag WHERE node_id = ? AND tag = ? LIMIT 1", (nid, tag)).fetchone() is not None
+
+def _node_clock_min(con, nid):
+    """Total minutes spent on this node, auto-combined: CLOCK_OUT elapsed sum union log timestamp span.
+    Takes the greater so "no wl start/stop, only wl log" workflows still get a rough duration.
+    Design choice: auto-compute, no explicit --duration field. Auto-calc surfaces drift; an explicit field
+    rarely gets updated and pollutes upper-level aggregations.
+    """
+    import re as _re
+
+    # 1. CLOCK_OUT elapsed total (precise, from wl start/stop)
+    clock = 0
+    for r in con.execute("SELECT body FROM log WHERE node_id = ? AND body LIKE 'CLOCK_OUT%'", (nid,)):
+        m = _re.search(r"elapsed=(\d+)min", r["body"])
+        if m:
+            clock += int(m.group(1))
+
+    # 2. ordinary log timestamp span (rough, max - min, excluding CLOCK_*)
+    #    multiple logs at the same timestamp count as one "batch-backfilled instant", not duplicated
+    rows = list(con.execute(
+        "SELECT DISTINCT logged_at FROM log WHERE node_id = ? AND body NOT LIKE 'CLOCK_%' ESCAPE '\\' ORDER BY logged_at",
+        (nid,),
+    ))
+    span = 0
+    if len(rows) >= 2:
+        try:
+            from datetime import datetime
+            first = datetime.fromisoformat(rows[0]["logged_at"])
+            last = datetime.fromisoformat(rows[-1]["logged_at"])
+            span = max(0, int((last - first).total_seconds() / 60))
+        except (ValueError, TypeError):
+            pass
+
+    return max(clock, span)
+
+def _node_exists(con, node_id):
+    return con.execute("SELECT 1 FROM node WHERE id = ?", (node_id,)).fetchone() is not None
+
+
+def _node_tags(con, nid):
+    """Return the tag list for a node (insertion order)."""
+    return [r["tag"] for r in con.execute("SELECT tag FROM tag WHERE node_id = ?", (nid,))]
+
+
+def _check_ids_exist(con, ids):
+    """Batch existence check; sys.exit if any id is missing. Used by multi-id commands."""
+    for nid in ids:
+        if not _node_exists(con, nid):
+            sys.exit(f"✗ node #{nid} not found")
+
+
+def _upsert_prop(con, nid, key, value):
+    """Unified prop UPSERT (no commit; caller controls the transaction). Batch-friendly.
+    `_set_prop` is the commit version for single daily operations."""
+    con.execute("INSERT OR REPLACE INTO prop (node_id, key, value) VALUES (?, ?, ?)", (nid, key, value))
+
+
+# generic ORDER BY fragment: priority A/B/C first, NULL last; same priority by id ascending.
+# Usage: f"SELECT * FROM node WHERE ... {_ORDER_BY_PRI_ID}"
+# Note: when joining, write the qualified column "n.priority"; that case stays inline.
+
+
+def _status_filter_sql(include_canceled=False, hide_done=False, col="status"):
+    """Build a `status` column filter SQL fragment + params. Used uniformly across cmds, avoids scattered string-concat.
+    Returns (where_fragment, params_list); when nothing is filtered returns ("", []).
+
+    Usage:
+        frag, params = _status_filter_sql(inc_cancel, hide_done=not args.all)
+        if frag: where.append(frag); sql_params.extend(params)
+    """
+    excluded = []
+    if hide_done:
+        excluded.append("DONE")
+    if not include_canceled:
+        excluded.append("CANCELED")
+    if not excluded:
+        return "", []
+    ph = ",".join("?" * len(excluded))
+    return f"({col} IS NULL OR {col} NOT IN ({ph}))", excluded