pyworklog 0.4.0__tar.gz → 0.5.0__tar.gz

{pyworklog-0.4.0 → pyworklog-0.5.0}/CHANGELOG.md

@@ -6,6 +6,19 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-06-05
+
+### Added
+- **Shared `--tag` / `--kind` / `--status` filter across `wl ls` / `tree` / `day` / `logs` / `agenda`** — one filter with the same meaning everywhere (wired through a parent parser, like the existing time-window flags), instead of each command rolling its own. `-t` / `--tag` is comma-separated **AND** (the node must carry every listed tag); `--kind` / `--status` are equality. So `wl day -t work` shows only the work bucket (empty buckets/groups aren't rendered, and the summary line counts the filtered set), `wl tree -t work` prunes the tree to matching nodes plus the ancestor paths that lead to them, and `ls` / `logs` / `agenda` filter identically. An explicit `--status DONE/CANCELED` overrides the default terminal-status hide. `-t` is now the short form on all five (matching `wl add -t`).
+- **`wl day` header states the day's nature** — every day now reads at a glance: `workday` (Mon–Fri) or `weekend` (Sat/Sun) by default, refined to `holiday` / `leave` / `workday` when a `wl dateinfo` label says so, with the label appended for context — e.g. `2026-06-01 Mon · Children's Day holiday`, `2026-06-13 Sat · makeup workday`, `2026-05-21 Thu · workday (Grain Buds solar term)`. Previously the header showed a label only when one existed, so a bare day told you nothing about its working status.
+
+### Changed
+- **Timestamps follow an `at`/`date` convention — precise instants stored UTC, literal dates kept local.** A column named `*_at` (or bare `at`: `created_at` / `closed_at` / `logged_at` / `metric.at` / `clock.start_at` / `end_at` / `sched.created_at`) is a precise instant, now stored as UTC and rendered in local time; a column holding a calendar *day* is named `*date` and kept verbatim as a local date. As part of this, `node.scheduled_at` → **`scheduled_date`** and `node.deadline_at` → **`deadline_date`** (they hold a planned/deadline day, plus fuzzy `@2026-06` pins — not instants). "Local" is the machine zone by default; `$WORKLOG_TZ` pins a fixed offset (e.g. `+08:00`) for reproducibility / overriding. Day-grouping (`wl day` / `summary` / `logs --date` / habit month-to-date) converts UTC→local before bucketing, so a log near local midnight lands on the right day. **Migration 0007** converts pre-existing rows from local (+08:00) to UTC (bare `YYYY-MM-DD` values left untouched) and renames the two date columns; new installs are unaffected.
+- **Habit month-to-date label is English** — `(本月 N/M)` → `(this month N/M)` in `wl day` / `wl tree`, matching the rest of the output.
+
+### Internal
+- **A zero-dependency single-table CRUD layer (`db_table`).** All hand-written single-table SQL — inserts, updates, deletes, selects, dynamically-assembled `WHERE` / `SET`, and `INSERT OR IGNORE/REPLACE` — now goes through a small helper (`insert` / `update` / `delete` / `query` / `query_one` / `get` / `exists` / `count` / `clause`) with identifier validation and parameter binding throughout; SQL `datetime('now')` is gone (all timestamps flow through `timeutil`). No behavior change — a maintainability/safety refactor, codified as design goal **G3** (few deps: stdlib + `rich`; simple explicit SQL over query-builder DSLs; small helpers over an ORM). Genuinely-complex queries (display JOINs, `GROUP BY`, correlated subqueries) stay raw by design. The test fixtures were also de-Chinese'd to English (the relative-date input aliases like `明天` / `下周` remain — they're a feature).
+
 ## [0.4.0] — 2026-06-05
 
 ### Fixed
@@ -81,16 +94,24 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
 Initial open-source release of `worklog-cli` (`wl`).
 
 ### Added
-- 37 subcommands covering create / log / done / state transitions / tree / projects / day / summary / changes / find / focus / show.
-- Bulk loaders: `wl import` (JSON) and `wl apply` (wl-diff format, symmetric with the rendered tree output).
-- Compound flags on `wl add` / `done` / `cancel` — create + log + close + timestamp + vault-link + schedule in one shot.
-- Brief mode `-q` on every command (skip log body / timeline / detail; ~50–90% character savings for AI consumers).
-- `rich`-based highlighting with `dark` / `light` / `mono` themes, auto-detected via `$COLORFGBG` / OSC 11 terminal background probe.
-- Shell completion (fish / bash / zsh) generated at runtime by `wl print-completion`; loaded via init-load (the starship / direnv / zoxide pattern).
+- **Single-table execution-system model** — one `node` table holds the whole hierarchy across 13 kinds (`lifetime` / `decade` / `year` / `quarter` / `month` / `week` / `day` / `area` / `project` / `task` / `habit` / `signal` / `meetlog`), sharing one id space and tree-linked via a `parent_id` self-reference. Six sibling tables hang off it: `log` (timestamped entries), `tag` (labels), `sched` (scheduling), `prop` (key-value attributes), `link` (vault-doc references), `date_meta`.
+- **Seven-state task lifecycle** — `TODO` / `DOING` / `LATER` / `WAIT` / `DONE` / `DEFERRED` / `CANCELED`, a superset of the markdown `[ ]` / `[/]` / `[>]` / `[x]` four-state set that adds `LATER` (deferred to the future) vs. `WAIT` (blocked on someone). Plus `A` / `B` / `C` priority (rendered `[#A]` = P0) and auto-stamped `closed_at`.
+- **37 subcommands** — create/edit (`add` / `set` / `link` / `init`), logging (`log` / `unlog` / `relog`), state transitions (`done` / `defer` / `start` / `stop` / `spent` / `active` / `wait` / `reopen` / `cancel` / `tick` / `checkin`), views (`show` / `ls` / `tree` / `focus` / `ancestors` / `descendants` / `projects` / `changes` / `summary` / `day`), meta fields (`goal` / `recap`), scheduling (`sched` / `dateinfo`), bulk I/O (`import` / `apply`), search (`find` / `logs`), and display (`themes` / `print-completion`). Most carry short aliases.
+- **Scheduling with recurrence** — the `sched` table records both one-off dates (`on_date`) and recurrence rules (`rrule`: `daily`, `weekly:Mon,Wed,Fri`); a task scheduled for a given day counts as planned, derived from `sched` rather than a manual tag.
+- **Time tracking** — `wl start` / `stop` / `spent` / `active` / `wait` record work intervals and report durations per node.
+- **Project association via shared tags** — `wl projects` rolls a project's members up by structural children plus shared semantic tags, with a `GENERIC_TAGS` set (work / personal / planned / unplanned / P0–P2 / habit / meeting / …) excluded so generic dimension tags don't cross-link unrelated work.
+- **Bulk loaders** — `wl import` (JSON) and `wl apply` (wl-diff format, symmetric with the rendered tree output) for scripted/AI-driven batch entry.
+- **Compound flags on `wl add` / `done` / `cancel`** — create + log + close + timestamp + vault-link + schedule in one shot.
+- **Date aliases** — `today` / `yesterday` / `tomorrow` / `day-before-yesterday` / … and Chinese equivalents resolve to concrete dates wherever a date is accepted.
+- **Brief mode `-q`** on every command (skip log body / timeline / detail; ~50–90% character savings for AI consumers).
+- **`rich`-based highlighting** with `dark` / `light` / `mono` themes, auto-detected via `$COLORFGBG` / OSC 11 terminal-background probe; manual override via `--theme` or `$WL_COLOR` / `$WL_THEME` / `$NO_COLOR`.
+- **Shell completion** (fish / bash / zsh) generated at runtime by `wl print-completion`; loaded via init-load (the starship / direnv / zoxide pattern).
+- **Vault integration** — `wl link` associates a node with one or more Obsidian vault docs (`[[doc]]`), kept in the `link` table for a two-way knowledge graph.
 - Bilingual project documentation (English + Chinese for README / DESIGN / SKILL).
 - MIT License.
 
-[Unreleased]: https://github.com/xyb/worklog/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/xyb/worklog/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/xyb/worklog/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/xyb/worklog/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/xyb/worklog/compare/v0.2.0...v0.3.0
 

{pyworklog-0.4.0 → pyworklog-0.5.0}/DESIGN.md

@@ -7,7 +7,7 @@
 
 ## 0. Design goals (north star, override every specific convention)
 
-These two trade-offs are foundational. Pass them before adding or changing any feature; when they conflict with a specific convention below, they win.
+These goals are foundational. Pass them before adding or changing any feature; when they conflict with a specific convention below, they win.
 
 ### G1 Structured-first (no string matching)
 
@@ -24,6 +24,15 @@ The tool must be simple enough to **use without reading the manual**, for both h
 - Self-check any new design with three questions: (1) how many new concepts does it add? (2) does using it force AI/humans to make a choice ("A or B?")? (3) can you guess it right without docs? If any answer is poor, simplify further.
 - When G1 and G2 conflict, find the "structured AND fewest-concepts" answer — don't pile on new tables / fields / commands just to be structured.
 
+### G3 Few dependencies, simple logic, easy to maintain
+
+worklog deliberately stays **dependency-light and low-abstraction**: runtime is **stdlib + `rich` only**, and new features prefer **zero new dependencies**. Logic stays **explicit and direct** — plain SQL over query-builder DSLs, small purpose-built helpers over frameworks/ORMs that hide what is happening. The bar: a maintainer (human or AI) can read any code path top-to-bottom without first learning a hidden layer.
+
+- **Borrow the technique, not the library.** Prefer writing a tens-of-lines, zero-dependency helper over pulling in a package (e.g. a dict→`INSERT` helper in the spirit of sqlite-utils, *not* an ORM; a `field__op`→`WHERE` helper, *not* a query builder).
+- **No ORM / no query builder.** Wrap only the uniform ~80 % (single-table CRUD + existence/count) in thin helpers that map transparently to one SQL statement; keep the complex ~20 % (JOIN / CTE / CASE / time-window) as explicit SQL. Don't reinvent SQL as a kwargs DSL.
+- **Each table / module maintainable on its own.** Minimize forced coupling (hard FK cascades, cross-cutting magic, triggers that hide intent) so one part can change — or be migrated / synced — without rippling everywhere. Lean toward avoiding irreversible operations (prefer soft-delete / status over `DELETE`) where they create cross-table consistency burdens.
+- When a "clever" abstraction conflicts with G3, choose the boringly-simple version. Fewer moving parts beats elegance.
+
 ## 1. Command style (todo.sh school)
 
 - Verb first: `wl <verb> [args] [--flags]`

{pyworklog-0.4.0 → pyworklog-0.5.0}/DESIGN.zh.md

@@ -7,7 +7,7 @@
 
 ## 0. 设计目标（北极星，凌驾于一切具体约定之上）
 
-下面两条取舍是地基。加任何功能、改任何设计前先过这两关；跟下文具体约定冲突时，以这两条为准。
+下面几条是地基。加任何功能、改任何设计前先过这几关；跟下文具体约定冲突时，以这几条为准。
 
 ### G1 结构化优先（不靠字符串匹配）
 
@@ -24,6 +24,15 @@ worklog 的整个职责就是把工作记录**结构化**，让信息能被精
 - 任何新设计自检三问：(1) 它新增了几个概念？(2) 用它要不要逼人 / AI 做选择（"用 A 还是 B？"）？(3) 不看文档能不能猜对用法？任一条答得不好，就再简化。
 - G1 和 G2 冲突时，找"既结构化又最少概念"的答案——别为了结构化就堆新表 / 新字段 / 新命令。
 
+### G3 依赖少、逻辑简单、易维护
+
+worklog 刻意保持**少依赖、低抽象**：运行时只有 **stdlib + `rich`**，新功能优先**零新依赖**。逻辑保持**显式直白**——宁可裸 SQL 也不上 query-builder DSL，宁可写小而专的 helper 也不引入藏掉细节的框架 / ORM。底线:维护者(人或 AI)能把任一条代码路径从头读到尾,不必先学一层隐藏机制。
+
+- **借技法,不借库**:宁可写几十行零依赖 helper,也别拉一个包(例如照 sqlite-utils 思路写 dict→`INSERT` helper,而**不是** ORM;写 `field__op`→`WHERE` helper,而**不是** query builder)。
+- **不上 ORM / 不上 query builder**:只把均匀的 ~80%(单表 CRUD + 存在/计数)包成**透明映射到一条 SQL**的薄 helper;复杂的 ~20%(JOIN / CTE / CASE / 时间窗)留显式 SQL。别把 SQL 重新发明成一套 kwargs DSL。
+- **每张表 / 每个模块能各自维护**:尽量减少强制耦合(硬 FK 级联、跨切面魔法、藏意图的 trigger),让一处能改动 / 迁移 / 同步而不牵连全局。在会造成跨表一致性负担的地方,倾向**避免不可逆操作**(用软删除 / 状态标记替代 `DELETE`)。
+- "聪明"的抽象跟 G3 冲突时,选无聊但简单的版本。零件少胜过优雅。
+
 ## 1. 命令风格（todo.sh 派）
 
 - 动词在前：`wl <verb> [args] [--flags]`

{pyworklog-0.4.0 → pyworklog-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyworklog
-Version: 0.4.0
+Version: 0.5.0
 Summary: SQLite-backed worklog tool with a todo.sh-style CLI
 Project-URL: Homepage, https://github.com/xyb/worklog
 Project-URL: Repository, https://github.com/xyb/worklog

{pyworklog-0.4.0 → pyworklog-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyworklog"
-version = "0.4.0"
+version = "0.5.0"
 description = "SQLite-backed worklog tool with a todo.sh-style CLI"
 readme = "README.md"
 license = "MIT"

{pyworklog-0.4.0 → pyworklog-0.5.0}/skills/worklog-cli/SKILL.md

@@ -32,7 +32,7 @@ Likewise, before adding a dev todo under a project, check that project's existin
 | Schedule task to a date / repeat (drives "planned") | `wl sched <id> 2026-06-15` (also accepts `tomorrow` / `day-after-tomorrow`) / `--clear`. `--recur` supports period start / end: `daily` / `weekly:Mon,Fri` (also 1-7 / -1..-7) / `monthly:1` (month start) · `monthly:-1` (month end) / `quarterly:1-1` (quarter start) · `quarterly:-1` (quarter end) / `yearly:01-01` (year start) · `yearly:-1` (year end); `-1` always means period end. A task scheduled to a day shows up in `wl day` as "planned · not yet logged" even with no log |
 | Meta info (end-of-day summary / Top5 / today's goal) | History-preserving typed logs (`log.tag`), not props: `wl goal "..."` (day) / `wl recap "..."` (day summary) / `wl set <month> top5 "..."` / `wl set <week> overview "..."`. Each write appends; the latest is current. `wl day` shows them at the top as a blockquote. Prefer `wl recap`/`wl goal` over `wl set` for day fields (read-back + stale-warning) |
 | Date context (holidays / vacation / makeup days) | `wl dateinfo 2026-05-01 Labor-Day-holiday` / `wl dateinfo --import holidays.json` (`{"YYYY-MM-DD":"label"}`) / `wl dateinfo <date> --clear`. Weekday auto-computed; `wl day` header shows "date weekday · label" |
-| Reproduce a day's progress (like markdown worklog) | `wl day [YYYY-MM-DD]` (log-date based: work/personal split → secondary group → task → indented logs + stats). **Default `--by plan`** (planned / unplanned / unplanned-unmarked — anything without `planned`/`unplanned` tag is treated as unplanned); switch dimensions with `--by project` / `--by priority` (P0/P1/P2) |
+| Reproduce a day's progress (like markdown worklog) | `wl day [YYYY-MM-DD]` (log-date based: work/personal split → secondary group → task → indented logs + stats). **Default `--by plan`** (planned / unplanned). **Planned = has a `sched`/recur entry firing that day (source of truth, set via `wl sched`); everything else = unplanned.** The legacy `:planned:` tag is honored only as a transitional fallback — do NOT add it to new tasks, use `wl sched`. Switch dimensions with `--by project` / `--by priority` (P0/P1/P2) |
 | List all active projects | `wl projects` |
 | Tree view | `wl tree` (**default = overview: timeline expanded to today [year→quarter→month→week→today + today's tasks] + areas only listed as names, ~30 lines to avoid flooding**) / `wl tree --root <area>` (projects + tasks under that area) / `wl tree --root <week/month>` (per-day activity) / `wl tree --depth N` (fully expanded from lifetime) / `wl tree --by project/tag/direction` (switch dimension). Time nodes sorted by date; **day node expansion = tasks that have logs that day + only their logs from that day** |
 | Time-range progress (weekly report input) | `wl changes --week 2026-W22` / `wl summary --week ... --by project/day` |
@@ -224,7 +224,7 @@ echo '{
 
 ```
   #6 [day] 2026-05-29 Friday      ← anchor: locate existing node as parent, don't modify
-+   [x] [#A] morning-check :planned:P0:   ← add (indent = child), [x]=DONE
++   [x] [#A] morning-check          ← add (indent = child), [x]=DONE; for planned use `wl sched`, not a :planned: tag
 +     @log check key points
 ~ [x] #14                         ← change #14 status (single-line shorthand)
 ~ #20                             ← complex update: lock + field operations

{pyworklog-0.4.0 → pyworklog-0.5.0}/src/worklog/cli.py

@@ -183,6 +183,14 @@ def build_parser():
     window.add_argument("--week", help="YYYY-Www (ISO week, overrides since/until)")
     window.add_argument("--month", help="YYYY-MM (overrides since/until)")
 
+    # node-filter parent parser (reused by ls/tree/day/logs/agenda so every list/view
+    # command takes the SAME --tag/--kind/--status, with the same meaning — see
+    # make_node_filter). --tag is comma-separated AND.
+    filters = argparse.ArgumentParser(add_help=False)
+    filters.add_argument("-t", "--tag", help="comma-separated tags, AND filter (e.g. -t work)")
+    filters.add_argument("--kind", help="filter by kind (task/habit/meetlog/project/area/...)")
+    filters.add_argument("--status", help="filter by status (TODO/DOING/DONE/WAIT/LATER/CANCELED)")
+
     _real_sub = p.add_subparsers(dest="cmd", required=False)
 
     # wrap add_parser to inject user aliases (cross-shell uniform: wl d == wl day)
@@ -279,7 +287,7 @@ Differences from related commands:
     a.add_argument("--proj", help="project (stored as prop)")
     a.add_argument("--parent", type=int, help="parent node id")
     a.add_argument("--status")
-    a.add_argument("--scheduled", help="(rough hint, writes node.scheduled_at) scheduled time: YYYY-MM-DD / YYYY-MM / YYYY-Www / YYYY-Qn / YYYY / someday / tomorrow / next-week / next-month / next-quarter")
+    a.add_argument("--scheduled", help="(rough hint, writes node.scheduled_date) scheduled time: YYYY-MM-DD / YYYY-MM / YYYY-Www / YYYY-Qn / YYYY / someday / tomorrow / next-week / next-month / next-quarter")
     a.add_argument("--sched", help="(precise, writes the sched table = visible as planned in `wl day` for that date) date: YYYY-MM-DD / today / yesterday / tomorrow / day-after-tomorrow")
     a.add_argument("--deadline", help="deadline date YYYY-MM-DD")
     a.add_argument("--body", help="optional body text")
@@ -337,7 +345,7 @@ Inverse of wl reopen (undo DONE back to TODO).""")
     d.add_argument("--at", help="closed_at + log use this timestamp (HH:MM / YYYY-MM-DD [HH:MM[:SS]])")
 
     df = sub.add_parser("defer",
-        help="defer a task to a future point (LATER + scheduled_at; fuzzy times supported)",
+        help="defer a task to a future point (LATER + scheduled_date; fuzzy times supported)",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Common examples:
@@ -347,7 +355,7 @@ Common examples:
   wl defer 42 someday        # no scheduled time
 
 Differences from wl sched:
-  - wl defer  -> status=LATER + scheduled_at field (rough hint, does NOT appear as "planned" in wl day on that day)
+  - wl defer  -> status=LATER + scheduled_date field (rough hint, does NOT appear as "planned" in wl day on that day)
   - wl sched  -> writes to sched table (precise, appears as "planned" in wl day on that day)
 To schedule it as planned for a specific day, use wl sched. defer is for "set aside, vaguely revisit later".""")
     df.add_argument("id", type=int)
@@ -358,12 +366,12 @@ To schedule it as planned for a specific day, use wl sched. defer is for "set as
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Common examples:
-  wl start 42                       # start timing now (inserts CLOCK_IN log)
+  wl start 42                       # start timing now (opens a clock interval)
   wl start 42 43                    # multiple tasks at once (parallel timers)
   wl start 42 --at 09:00            # backfill 9am start (forgot to clock in)
   wl start 42 --at 2026-05-30 14:30 # full ts
 
-Related: close with wl stop <id>; see what's running via wl active; wl spent records a CLOCK pair from a duration.""")
+Related: close with wl stop <id>; see what's running via wl active; wl spent records a clock interval from a duration.""")
     s.add_argument("ids", type=int, nargs="+", help="node id(s)")
     s.add_argument("--at", help="backfill start time: HH:MM (today) / YYYY-MM-DD / YYYY-MM-DD HH:MM[:SS]")
 
@@ -372,17 +380,17 @@ Related: close with wl stop <id>; see what's running via wl active; wl spent rec
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Common examples:
-  wl stop 42                            # stop now, write CLOCK_OUT elapsed=Nmin
+  wl stop 42                            # stop now, close the interval (elapsed=Nmin)
   wl stop 42 43                         # batch stop
-  wl stop 42 --at 11:30                 # backfill 11:30 end (must be later than CLOCK_IN)
+  wl stop 42 --at 11:30                 # backfill 11:30 end (must be later than the clock start)
   wl stop 42 --at 2026-05-30 16:00      # full ts
 
-Difference from wl spent: stop pairs with a prior CLOCK_IN; spent creates a pair directly from a duration.""")
+Difference from wl spent: stop closes a prior open clock; spent creates a closed interval directly from a duration.""")
     st.add_argument("ids", type=int, nargs="+", help="node id(s)")
-    st.add_argument("--at", help="backfill end time (must be later than CLOCK_IN)")
+    st.add_argument("--at", help="backfill end time (must be later than the clock start)")
 
     sp = sub.add_parser("spent",
-        help="record a past time spent (build CLOCK pair from duration, good for retrospective entries)",
+        help="record a past time spent (build a clock interval from a duration, good for retrospective entries)",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Common examples:
@@ -392,14 +400,14 @@ Common examples:
   wl spent 42 2h               # 2 hours
   wl spent 42 30m --at 14:30   # end at 14:30, backfill start at 14:00
 
-Difference from wl start/stop: spent builds CLOCK_IN+OUT pair from a duration in one step; no need to start first. Good for "forgot to clock, recording it after the fact".""")
+Difference from wl start/stop: spent builds a closed clock interval from a duration in one step; no need to start first. Good for "forgot to clock, recording it after the fact".""")
     sp.add_argument("id", type=int, help="node id")
     sp.add_argument("duration", help="duration: 90 / 90m / 1h30m / 2h")
     sp.add_argument("--at", help="end timestamp (default NOW); start = at - duration")
 
     ac = sub.add_parser("active",
-        help="tasks running right now (open CLOCK_IN) + today's elapsed + latest log",
-        description="List tasks that are timing right now (open CLOCK_IN). Shows current session elapsed, today's total, and the most recent log. Good for live focus check and finding tasks you forgot to stop.",
+        help="tasks running right now (open clock) + today's elapsed + latest log",
+        description="List tasks that are timing right now (an open clock interval). Shows current session elapsed, today's total, and the most recent log. Good for live focus check and finding tasks you forgot to stop.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Use cases:
@@ -409,14 +417,14 @@ Use cases:
 
 Difference from wl day:
   - wl day        = full progress for the day (includes done / not-yet-started planned items), for end-of-day review
-  - wl active     = what's timing right now (open CLOCK_IN), for live focus check
+  - wl active     = what's timing right now (open clock), for live focus check
 
 Output includes: current session elapsed + today's total (to decide stop or continue) + latest log (context).
 Brief mode -q: id + elapsed only. Full log body: --log-format full.""")
     # ac has no other flags but we keep the variable for future args (e.g. --since to look at past activity)
 
     wa = sub.add_parser("wait",
-        help="mark WAIT (blocked on others / external input); auto-closes CLOCK; multiple ids",
+        help="mark WAIT (blocked on others / external input); auto-closes the clock; multiple ids",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Common examples:
@@ -424,7 +432,7 @@ Common examples:
   wl wait 42 --note "waiting on review" # add a log explaining what we're waiting on
   wl wait 42 43 --note "waiting on approval" # batch
 
-Note: marking WAIT auto-closes any open CLOCK_IN (WAIT = suspended, no longer timing). Use wl reopen to revert to TODO.""")
+Note: marking WAIT auto-closes any open clock (WAIT = suspended, no longer timing). Use wl reopen to revert to TODO.""")
     wa.add_argument("ids", type=int, nargs="+", help="node id(s)")
     wa.add_argument("--note", help="add a log explaining what you're waiting on")
 
@@ -537,7 +545,8 @@ Differences from related commands:
     sh.add_argument("--all-timelines", action="store_true",
                     help="full timeline, no elision")
 
-    ls = sub.add_parser("ls", help="list nodes (default limit 20; see shell ls -t / -S / -r-style dimensions)",
+    ls = sub.add_parser("ls", parents=[filters],
+                        help="list nodes (default limit 20; see shell ls -t / -S / -r-style dimensions)",
                         formatter_class=argparse.RawDescriptionHelpFormatter,
                         epilog="""\
 Common examples (precise queries, shell-ls multi-dimensional):
@@ -553,9 +562,6 @@ Common examples (precise queries, shell-ls multi-dimensional):
   wl ls --all                           remove the 20-row limit + include DONE/CANCELED
 
 See also: wl find <q> / wl day / wl active / wl projects (each has a dedicated entry point sharper than ls)""")
-    ls.add_argument("--kind", help="filter by kind (task/habit/meetlog/project/area/...)")
-    ls.add_argument("--status", help="filter by status (TODO/DOING/DONE/WAIT/LATER/CANCELED)")
-    ls.add_argument("--tag", help="comma-separated tags, AND filter")
     ls.add_argument("--parent", type=int, help="only direct children of this node")
     ls.add_argument("--all", action="store_true", help="include DONE/CANCELED + remove the limit cap")
     ls.add_argument("--limit", type=int, metavar="N",
@@ -574,7 +580,7 @@ See also: wl find <q> / wl day / wl active / wl projects (each has a dedicated e
     ls.add_argument("--ids", type=int, nargs="+", metavar="id",
                     help="list specific ids directly, skipping filters (like shell `ls file1 file2`)")
 
-    tr = sub.add_parser("tree",
+    tr = sub.add_parser("tree", parents=[filters],
         help="tree view of nodes (default: timeline up to today + areas one level, ~30 rows)",
         description="Tree view of nodes. Default: timeline expanded up to today (year -> quarter -> month -> week -> today + today's tasks) + areas one level, ~30 rows to avoid scrolling. Use --root <id> to drill into a node.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -593,7 +599,6 @@ Differences from related commands:
   - wl day             log-date-driven view of a single day (not tied to tree)
   - wl projects        list projects as cards (subtask counts, no tree expansion)
   - wl ls --parent <N> flat list of direct children, no recursion""")
-    tr.add_argument("--kind")
     tr.add_argument("--proj")
     tr.add_argument("--root", type=int, help="start tree from this node id")
     tr.add_argument("--by", choices=["project", "tag", "direction"], help="regroup by dimension (flat 2-level)")
@@ -632,7 +637,7 @@ Related: wl show is self + timeline only; wl ancestors/descendants only go one d
     de.add_argument("id", type=int)
     de.add_argument("--depth", type=int, help="max depth")
 
-    ag = sub.add_parser("agenda",
+    ag = sub.add_parser("agenda", parents=[filters],
         help="cross-time-range scheduling overview: everything scheduled in [start, end]",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
@@ -714,15 +719,16 @@ Dedup: by default a task appearing in multiple projects (via parent + shared tag
     sm.add_argument("--no-dedup", action="store_true",
                     help="no dedup: a task across multiple projects is repeated in each bucket (old behavior)")
 
-    dy = sub.add_parser("day",
+    dy = sub.add_parser("day", parents=[filters],
         help="full view of a day (default today): bucket -> project/plan -> task -> log",
-        description="Full view of one day: work/personal/other -> (planned/unplanned/project/priority) -> task -> indented logs. Top shows end-of-day summary + today's goal + Top5 (if set). Defaults to log-date-driven (works for past days too).",
+        description="Full view of one day: work/personal/other -> (planned/unplanned/project/priority) -> task -> indented logs. The header states the day's nature (workday / weekend, refined to holiday / leave / makeup by a `wl dateinfo` label). Top shows end-of-day summary + today's goal + Top5 (if set). Defaults to log-date-driven (works for past days too).",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Common examples:
   wl day                              # today
   wl day 2026-05-30                   # historical day
   wl day yesterday                    # short form (yesterday / day-before-yesterday / tomorrow / day-after-tomorrow)
+  wl day -t work                      # only work items (filter; -t/--tag, AND); -t personal for personal
   wl day --by project                 # change grouping (default plan: planned/unplanned)
   wl day --by priority                # group by P0/P1/P2
   wl day --log-tail 1                 # logs default to last 3, narrow to 1
@@ -770,7 +776,7 @@ Common examples:
   wl recap --date yesterday            # read yesterday's recap
 
 wl day shows "Recap: ... (written at MM-DD HH:MM)" at the top;
-if there are new non-CLOCK logs after recap, wl day shows "⚠ N changes after recap, consider rewriting".
+if there are new logs after recap, wl day shows "⚠ N changes after recap, consider rewriting".
 Using wl set <day_id> summary "..." directly does not stamp the timestamp; not recommended.""")
     rc.add_argument("text", nargs="?", help="no arg = read; with text = write")
     rc.add_argument("--date", help="target day (YYYY-MM-DD / today / yesterday / 昨天 ...); default today")
@@ -804,20 +810,20 @@ Common examples:
   wl unlog #L282                      # exact delete by log id
   wl unlog L282                       # same (# optional)
   wl unlog 282                        # same (plain number)
-  wl unlog --node 39                  # delete the latest non-CLOCK log for #39 today
+  wl unlog --node 39                  # delete the latest log for #39 today
   wl unlog --node 39 --date yesterday # latest log that day
-  wl unlog --node 39 --all            # delete all non-CLOCK logs for #39 that day
+  wl unlog --node 39 --all            # delete all logs for #39 that day
 
 Find a log id: wl show <node_id> or wl logs --id <node_id> displays #L<id> in the timeline.
-CLOCK_IN/OUT logs cannot be deleted (would break timing pairs). Edit a mistyped log with wl relog #L<id> instead.""")
+Edit a mistyped log with wl relog #L<id> instead. (Timing lives in the clock table, not logs — fix a clock with wl stop --at.)""")
     ul.add_argument("log_id", type=_log_id_arg, nargs="?",
                     help="log id (e.g. #L282 / L282 / 282; from wl show / wl logs timeline)")
-    ul.add_argument("--node", type=int, help="delete by node id (default: latest non-CLOCK log today)")
+    ul.add_argument("--node", type=int, help="delete by node id (default: latest log today)")
     ul.add_argument("--date", help="with --node: delete logs from that day (default today)")
-    ul.add_argument("--all", action="store_true", help="with --node: delete all non-CLOCK logs for that node that day")
+    ul.add_argument("--all", action="store_true", help="with --node: delete all logs for that node that day")
 
     rl = sub.add_parser("relog",
-        help="rewrite a log: new body / new time / editor (CLOCK not accepted)",
+        help="rewrite a log: new body / new time / editor",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\
 Common examples:
@@ -827,7 +833,7 @@ Common examples:
   wl relog #L282 --at 2026-05-30     # only change date (keep time)
   wl relog #L282                     # no body/--at -> open $EDITOR
 
-CLOCK_IN/OUT logs cannot be edited (would break timing pairs); use wl stop --at to fix CLOCK times.
+Timing lives in the clock table, not logs — to fix a clock interval use wl stop --at.
 Cannot move a log across nodes (that's unlog + log).""")
     rl.add_argument("log_id", type=_log_id_arg,
                     help="log id (#L282 / L282 / 282; from wl show / wl logs)")
@@ -1018,7 +1024,7 @@ Before writing a new task / log, run wl find to check if there's an existing nod
     fd.add_argument("--limit", type=int, metavar="N", help="show only the first N (default 20; use 0 or --all for no cap)")
     fd.add_argument("--all", action="store_true", help="no row limit")
 
-    lg = sub.add_parser("logs", parents=[window],
+    lg = sub.add_parser("logs", parents=[window, filters],
         help="list log entries (default last 7 days; preset today/yesterday/week/recent)",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""\

{pyworklog-0.4.0 → pyworklog-0.5.0}/src/worklog/commands/bulk.py

@@ -11,6 +11,8 @@ from datetime import datetime, timedelta
 from pathlib import Path
 
 from .. import render
+from .. import db_table as _db
+from .. import timeutil as _tu
 from ..helpers import (
     _apply_top_limit,
     _fmt_dur,
@@ -181,27 +183,23 @@ def cmd_apply(args, con):
                 # recursive subtree delete: node self-ref is ON DELETE SET NULL, only deleting the parent would orphan children, so we must explicitly collect descendants
                 ids = [f["id"]] + _collect_descendants(con, f["id"])
                 for did in ids:
-                    con.execute("DELETE FROM node WHERE id = ?", (did,))
+                    _db.delete(con, "node", id=did)
                 counts["delete"] += len(ids)
                 continue
             # pfx == "+": add new node
             parent_id = stack.get(depth - 1) if depth > 0 else None
             status = _MARKER_STATUS.get(f.get("marker", " "), "TODO")
             kind = f.get("kind", "task")
+            now = _tu.utc_now()
+            node_row = {
+                "parent_id": parent_id, "title": f["title"], "kind": kind,
+                "status": status, "priority": f.get("priority"), "created_at": now,
+            }
             if status == "DONE":
-                cur = con.execute(
-                    "INSERT INTO node (parent_id,title,kind,status,priority,closed_at) "
-                    "VALUES (?,?,?,?,?, datetime('now','localtime'))",
-                    (parent_id, f["title"], kind, status, f.get("priority")),
-                )
-            else:
-                cur = con.execute(
-                    "INSERT INTO node (parent_id,title,kind,status,priority) VALUES (?,?,?,?,?)",
-                    (parent_id, f["title"], kind, status, f.get("priority")),
-                )
-            nid = cur.lastrowid
+                node_row["closed_at"] = now
+            nid = _db.insert(con, "node", node_row)
             for t in f.get("tags", []):
-                con.execute("INSERT OR IGNORE INTO tag (node_id,tag) VALUES (?,?)", (nid, t))
+                _db.insert(con, "tag", {"node_id": nid, "tag": t}, or_="ignore")
             for kind_, val in o["subs"]:
                 _apply_sub(con, nid, kind_, val)
             counts["add"] += 1
@@ -229,48 +227,40 @@ def _import_node(con, spec, parent_id, ref_map, dry, counters):
         if spec["parent_ref"] not in ref_map:
             raise ValueError(f"parent_ref '{spec['parent_ref']}' undefined (must appear before reference)")
         pid = ref_map[spec["parent_ref"]]
-    closed_at = None
-    if status == "DONE":
-        closed_at = "datetime_now"  # placeholder; the SQL below uses datetime('now','localtime')
-
     if dry:
         nid = f"<ref:{spec.get('ref', '?')}>"
         counters["add"] += 1
     else:
-        if closed_at:
-            cur = con.execute(
-                "INSERT INTO node (parent_id,title,kind,status,priority,scheduled_at,deadline_at,body,closed_at) "
-                "VALUES (?,?,?,?,?,?,?,?, datetime('now','localtime'))",
-                (pid, title, kind, status, spec.get("priority"), sched,
-                 spec.get("deadline"), spec.get("body")),
-            )
-        else:
-            cur = con.execute(
-                "INSERT INTO node (parent_id,title,kind,status,priority,scheduled_at,deadline_at,body) "
-                "VALUES (?,?,?,?,?,?,?,?)",
-                (pid, title, kind, status, spec.get("priority"), sched,
-                 spec.get("deadline"), spec.get("body")),
-            )
-        nid = cur.lastrowid
+        now = _tu.utc_now()
+        node_row = {
+            "parent_id": pid, "title": title, "kind": kind, "status": status,
+            "priority": spec.get("priority"), "scheduled_date": sched,
+            "deadline_date": spec.get("deadline"), "body": spec.get("body"),
+            "created_at": now,
+        }
+        if status == "DONE":
+            node_row["closed_at"] = now
+        nid = _db.insert(con, "node", node_row)
         counters["add"] += 1
         for t in spec.get("tags", []):
-            con.execute("INSERT OR IGNORE INTO tag (node_id,tag) VALUES (?,?)", (nid, t))
+            _db.insert(con, "tag", {"node_id": nid, "tag": t}, or_="ignore")
         for k, v in (spec.get("props") or {}).items():
             _upsert_prop(con, nid, k, str(v))
         for d in spec.get("links", []):
-            con.execute("INSERT OR IGNORE INTO link (node_id,vault_doc) VALUES (?,?)", (nid, d))
+            _db.insert(con, "link", {"node_id": nid, "vault_doc": d}, or_="ignore")
         for entry in spec.get("logs", []):
             _insert_log(con, nid, entry)
             # a log entry may carry structured datapoints: {"body":..., "metrics":[{tag,value,unit}]}
             if isinstance(entry, dict) and entry.get("metrics"):
                 log_id = con.execute("SELECT last_insert_rowid()").fetchone()[0]
-                log_at = con.execute("SELECT logged_at FROM log WHERE id = ?", (log_id,)).fetchone()["logged_at"]
+                log_at = _db.get(con, "log", log_id)["logged_at"]
                 for mspec in entry["metrics"]:
                     import_metric(con, log_id, nid, mspec, default_at=log_at)
         # node-level metrics → a dedicated carrier log (1 carrier → N datapoints, e.g. a CGM import)
         if spec.get("metrics"):
-            con.execute("INSERT INTO log (node_id, body, tag) VALUES (?, '', ?)", (nid, _CARRIER_TYPE))
-            log_id = con.execute("SELECT last_insert_rowid()").fetchone()[0]
+            log_id = _db.insert(con, "log", {
+                "node_id": nid, "logged_at": _tu.utc_now(), "body": "", "tag": _CARRIER_TYPE,
+            })
             for mspec in spec["metrics"]:
                 import_metric(con, log_id, nid, mspec)
             counters["metric"] = counters.get("metric", 0) + len(spec["metrics"])
@@ -299,24 +289,20 @@ def _import_update(con, spec, dry, counters):
         return
     if "parent" in spec and spec["parent"] is not None and not _node_exists(con, spec["parent"]):
         raise ValueError(f"update #{nid}: parent #{spec['parent']} does not exist")
-    fields, vals = [], []
-    for col in ("status", "priority", "title", "scheduled_at", "deadline_at", "body"):
-        if col in spec:
-            fields.append(f"{col} = ?")
-            vals.append(spec[col])
-    if "parent" in spec:  # move; parent_id column name differs from spec key, handled separately
-        fields.append("parent_id = ?")
-        vals.append(spec["parent"])
+    changes = {col: spec[col] for col in
+               ("status", "priority", "title", "scheduled_date", "deadline_date", "body") if col in spec}
+    if "parent" in spec:  # move; spec key 'parent' maps to the parent_id column
+        changes["parent_id"] = spec["parent"]
     if spec.get("status") == "DONE" and "closed_at" not in spec:
-        fields.append("closed_at = datetime('now','localtime')")
-    if fields:
-        con.execute(f"UPDATE node SET {', '.join(fields)} WHERE id = ?", (*vals, nid))
+        changes["closed_at"] = _tu.utc_now()
+    if changes:
+        _db.update(con, "node", nid, changes)
     for t in spec.get("add_tags", []):
-        con.execute("INSERT OR IGNORE INTO tag (node_id,tag) VALUES (?,?)", (nid, t))
+        _db.insert(con, "tag", {"node_id": nid, "tag": t}, or_="ignore")
     for t in spec.get("remove_tags", []):
-        con.execute("DELETE FROM tag WHERE node_id = ? AND tag = ?", (nid, t))
+        _db.delete(con, "tag", node_id=nid, tag=t)
     for d in spec.get("add_links", []):
-        con.execute("INSERT OR IGNORE INTO link (node_id,vault_doc) VALUES (?,?)", (nid, d))
+        _db.insert(con, "link", {"node_id": nid, "vault_doc": d}, or_="ignore")
     for entry in spec.get("add_logs", []):
         _insert_log(con, nid, entry)
     counters["update"] += 1
@@ -460,7 +446,7 @@ def _parse_wld(text):
 
 _STATUSES = {"TODO", "DOING", "LATER", "WAIT", "DONE", "DEFERRED", "CANCELED"}
 _SET_COL = {"status": "status", "priority": "priority", "title": "title",
-            "parent": "parent_id", "scheduled": "scheduled_at", "deadline": "deadline_at"}
+            "parent": "parent_id", "scheduled": "scheduled_date", "deadline": "deadline_date"}
 
 def _validate_fieldop(con, lineno, action, field, value, errs):
     if field == "status" and action == "set" and value not in _STATUSES:
@@ -485,7 +471,7 @@ def _exec_update(con, o):
         if field in _SET_COL:
             col = _SET_COL[field]
             if action == "clear":
-                con.execute(f"UPDATE node SET {col} = NULL WHERE id = ?", (nid,))
+                _db.update(con, "node", nid, {col: None})
             else:
                 if field == "parent":
                     v = int(value)
@@ -493,27 +479,27 @@ def _exec_update(con, o):
                     v = _norm_sched(value)
                 else:
                     v = value
-                con.execute(f"UPDATE node SET {col} = ? WHERE id = ?", (v, nid))
+                _db.update(con, "node", nid, {col: v})
                 if field == "status" and value == "DONE":
-                    con.execute("UPDATE node SET closed_at = datetime('now','localtime') WHERE id = ? AND closed_at IS NULL", (nid,))
+                    con.execute("UPDATE node SET closed_at = ? WHERE id = ? AND closed_at IS NULL", (_tu.utc_now(), nid))
         elif field == "tag":
             if action == "add":
-                con.execute("INSERT OR IGNORE INTO tag (node_id,tag) VALUES (?,?)", (nid, value))
+                _db.insert(con, "tag", {"node_id": nid, "tag": value}, or_="ignore")
             else:
-                con.execute("DELETE FROM tag WHERE node_id = ? AND tag = ?", (nid, value))
+                _db.delete(con, "tag", node_id=nid, tag=value)
         elif field == "log":
             _insert_log(con, nid, value)
         elif field == "link":
             if action == "add":
-                con.execute("INSERT OR IGNORE INTO link (node_id,vault_doc) VALUES (?,?)", (nid, value))
+                _db.insert(con, "link", {"node_id": nid, "vault_doc": value}, or_="ignore")
             else:
-                con.execute("DELETE FROM link WHERE node_id = ? AND vault_doc = ?", (nid, value))
+                _db.delete(con, "link", node_id=nid, vault_doc=value)
         elif field == "prop":
             if action == "set":
                 k, v = value
                 _upsert_prop(con, nid, k, v)
             else:
-                con.execute("DELETE FROM prop WHERE node_id = ? AND key = ?", (nid, value))
+                _db.delete(con, "prop", node_id=nid, key=value)
 
 def _fieldop_desc(action, field, value):
     if action == "clear":
@@ -530,7 +516,7 @@ def _apply_sub(con, nid, kind, val):
     if kind == "log":
         _insert_log(con, nid, val)
     elif kind == "link":
-        con.execute("INSERT OR IGNORE INTO link (node_id,vault_doc) VALUES (?,?)", (nid, val))
+        _db.insert(con, "link", {"node_id": nid, "vault_doc": val}, or_="ignore")
     elif kind == "prop":
         if "=" in val:
             k, v = val.split("=", 1)