pyworklog 0.6.0__tar.gz → 0.7.0__tar.gz

{pyworklog-0.6.0 → pyworklog-0.7.0}/.github/workflows/release.yml

@@ -2,7 +2,8 @@ name: Release
 
 # Pushing a vX.Y.Z tag:
 #   1. verifies the tag matches pyproject.toml version,
-#   2. runs the test suite (release gate),
+#   2. requires the full Test matrix (test.yml: 3.11/3.12/3.13 × ubuntu/macos) to be green for
+#      this commit — depends on that run, does not re-run a single-version gate,
 #   3. builds the wheel + sdist with uv,
 #   4. publishes to PyPI via OIDC Trusted Publisher (no token needed),
 #   5. creates a GitHub Release with auto-generated notes + the dist/ files attached.
@@ -17,6 +18,7 @@ jobs:
     permissions:
       contents: write   # for creating the GitHub Release
       id-token: write   # for PyPI Trusted Publisher (OIDC)
+      actions: read     # to read the Test workflow's run status for this commit (release gate)
     steps:
       - uses: actions/checkout@v4
         with:
@@ -32,18 +34,39 @@ jobs:
             exit 1
           fi
 
+      # Release gate: require the FULL Test matrix (test.yml: 3.11/3.12/3.13 × ubuntu/macos) to
+      # have passed for this exact commit. The tag points at a commit already pushed to main, so
+      # test.yml has run (or is running) for this SHA — we depend on that result instead of
+      # re-running a single 3.12 gate here (which missed e.g. a 3.13-only argparse difference).
+      - name: Require the Test matrix green for this commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          sha="${{ github.sha }}"
+          echo "Waiting for the Test matrix (test.yml) to pass on $sha ..."
+          for i in $(seq 1 80); do          # up to ~20 min (matrix takes a couple minutes)
+            run=$(gh run list --workflow=test.yml --commit "$sha" -L 1 \
+                  --json status,conclusion,url 2>/dev/null || echo '[]')
+            status=$(echo "$run" | jq -r '.[0].status // "missing"')
+            concl=$(echo "$run" | jq -r '.[0].conclusion // ""')
+            url=$(echo "$run" | jq -r '.[0].url // ""')
+            echo "  test.yml: status=$status conclusion=$concl $url"
+            if [ "$status" = "completed" ]; then
+              [ "$concl" = "success" ] && { echo "Test matrix green — publishing."; exit 0; }
+              echo "::error::Test matrix for $sha did not pass (conclusion=$concl). Refusing to publish. $url"
+              exit 1
+            fi
+            sleep 15
+          done
+          echo "::error::Timed out (~20 min) waiting for the Test matrix on $sha."
+          exit 1
+
       - name: Install uv
         uses: astral-sh/setup-uv@v6
         with:
           python-version: '3.12'
           enable-cache: true
 
-      - name: Sync deps
-        run: uv sync --all-groups
-
-      - name: Run tests (release gate)
-        run: uv run pytest -q --no-cov
-
       - name: Build wheel + sdist
         run: uv build
 

{pyworklog-0.6.0 → pyworklog-0.7.0}/.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: ['3.11', '3.12', '3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
 
     steps:
       - uses: actions/checkout@v4

{pyworklog-0.6.0 → pyworklog-0.7.0}/AGENTS.md

@@ -64,6 +64,7 @@ wl --db /tmp/scratch.db add "..."
 - **Status / priority / theme key names** are enumerated in DESIGN §3/§5/§19; add to `_THEME_KEYS` when introducing a new palette entry — `test_themes_have_same_keys` catches misses.
 - **No bare `print()` for renderable content**; all rows go through `out()` + `_c()`.
 - **Bulk writes default to `--dry-run`.** `wl apply` and `wl import` validate first, then execute as a single transaction (`_collect_descendants` recurses for the `-` delete prefix because the FK is `ON DELETE SET NULL`, not cascade). Update flags strictly: only fields that appear in the diff are touched — see DESIGN §18.2 "anti-wipe" rule.
+- **No internal task-tracker ids in the repo.** This is a public repo; the maintainer tracks work in a private system whose ids are meaningless to outside readers. Never write a `WL#NNN` or a bareword `#NNN` design backref in source comments, docstrings, tests, the changelog, or commit / PR text — a bare `#NNN` also renders as a GitHub issue/PR link and misleads. Describe the change in prose instead ("the dedup-warning feature", "the focus-on-day-node fix"); if you must label it, write `task NNN` without the `#`. **Preserved** (these are not backrefs): illustrative example ids in usage snippets (`wl show 42`), the `#L<id>` / `node #123` format documentation, and the deliberately-nonexistent ids in apply/import test fixtures (`#999` / `#888`).
 - **i18n layout.** README + DESIGN are bilingual (`*.zh.md`), `src/worklog/cli.py` strings + tests + SKILL.md are English. CJK fixtures in tests are intentional (they exercise unicode width / sort / title handling).
 - **`tmp_path_home` test fixture pattern.** When a test changes `$HOME` to assert path resolution, it must also `monkeypatch.delenv("XDG_CONFIG_HOME")` + `delenv("XDG_DATA_HOME")` — CI runners preset XDG vars and otherwise leak through. See `TestUserAliasesIni._setup_aliases` for the working pattern.
 

{pyworklog-0.6.0 → pyworklog-0.7.0}/CHANGELOG.md

@@ -6,6 +6,55 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-06-09
+
+### Added
+- **Signed relative-delta dates for quick entry** — `+1` / `-2` / `+1d` / `-2day` / `+3w` /
+  `-2week` / `+1m` / `-1y`: a signed number plus an optional unit (`d`/`day[s]` default, `w`/`week[s]`,
+  `m`/`month[s]`, `y`/`year[s]`), resolved from today. Added in the one central resolver
+  (`_resolve_concrete_date`), so every date-accepting command gets it — `wl day -2`, `wl sched 42 +3w`,
+  `wl log 42 "..." --date -1d`, `wl defer 42 +2w`, `wl agenda +0 +1m`, … Month/year deltas clamp the day
+  (Jan 31 `+1m` → Feb 28); `wl defer` accepts a delta as a precise day hint alongside its fuzzy forms.
+  A negative delta with a unit (`-2week`, `-2d`) works as a positional on every supported Python —
+  `_WlParser` widens argparse's negative-number matcher (3.9–3.13 would otherwise reject it as an
+  unknown option; 3.14 already accepts it).
+- **Relative date words resolve everywhere, connector- and case-insensitive.** `next-week` /
+  `next-month` / `next-quarter` now resolve to that period's first day, so `wl sched` / `wl day`
+  accept them (alongside `wl defer`, which keeps the coarser week/month bucket). All relative words
+  match ignoring case and connector chars — `NEXT_WEEK`, `next week`, `Day After Tomorrow` all parse
+  — and plural units (`+2weeks` == `+2week` == `+2w`) work. `someday` stays `defer`-only; `wl sched`'s
+  error message now points there for fuzzy values.
+- **`wl agent` — bind the current AI agent session to a task.** `wl agent <id>` ties the current
+  Claude Code session (read from `$WL_SESSION_ID` / `$CLAUDE_CODE_SESSION_ID`, failing closed if
+  neither is set) to a node, so the agent knows which task it's on and a status line / hook can
+  surface it. `wl agent` shows the current binding, `wl agent ls` lists all session→task bindings,
+  `wl agent rm` unbinds. Stored as the `agent_session.claude` prop on the node (prefix
+  `agent_session.` shared across apps; no new table); rebinding moves the prop off the old node so
+  the reverse lookup stays unique.
+- **`wl agent <id> --record` — keep a node's session history.** The `agent_session.claude` prop is
+  the *live pointer* (one session → one node, moves on rebind) and stays log-free by default;
+  `--record` additionally appends a one-off log + an `agent_session` metric carrying the *full*
+  session id, which stays on the node permanently. Recover every session a node was worked under
+  with `wl metric ls <id> --tag agent_session --all`. Only the bind event is recorded (not every
+  later write), so it costs one row per association. Follows the new design rule (DESIGN §2): extra
+  per-log data goes on a metric, never a new `log` column — the log body stays thin.
+
+### Changed
+- **`wl set` / `wl prop set` and import `props` refuse reserved node-field names** (`status`,
+  `priority`, `title`, `parent`, `tags`, `kind`, `scheduled`, `deadline`, …) so a prop can't
+  silently shadow a real column — that had produced two conflicting `status` values in `wl show`.
+  Each rejection points to the right editor (`wl done`/`defer`, `wl node edit`, `wl node reparent`).
+  Generalizes the earlier `tags`-only guard.
+- **Wider Python support: 3.9 – 3.14** (was 3.11+). No code used a 3.10/3.11-only feature, so the
+  floor dropped to 3.9 (matching the lone dependency, `rich`); the CI matrix now tests 3.9 / 3.10 /
+  3.11 / 3.12 / 3.13 / 3.14 on Ubuntu + macOS, and the classifiers list the full range.
+
+### Docs
+- **README reframed around the AI-first / local-first thesis** — short scannable Why / Features
+  bullets, a Quickstart, and the Python requirement in prose (EN + 中文 in sync).
+- **Internal task-tracker ids dropped from the public repo** (comments, docstrings, tests,
+  changelog) and a hard rule added to `AGENTS.md`.
+
 ## [0.6.0] - 2026-06-07
 
 ### Added
@@ -28,20 +77,20 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
   splash now points to it. Topic set expanded to 18 — added log / tag / sched / done / defer /
   tree / ls / find / link / meta / prop alongside the seed concepts/guides.
 - **`wl node` entity group — `node add / ls / show / edit / rm / reparent`.** The start of
-  reshaping the command surface to the metric-style `<entity> <verb>` form (WL#486). The
+  reshaping the command surface to the metric-style `<entity> <verb>` form. The
   high-frequency `add` / `ls` / `show` are reachable both as `wl node <verb>` and as the
   existing top-level shortcut (`wl add` == `wl node add`), one handler each, args defined
   once so the two forms can't drift. Three new primitives close node's CRUD to the metric
   bar: `node edit <id>` (edit a node's own fields — title / priority / kind / body /
   scheduled / deadline; rejects an empty title), `node reparent <id> <parent|none|0>`
-  (change the real `parent_id`, with cycle / self-parent guards — WL#485), and `node rm <id>`
+  (change the real `parent_id`, with cycle / self-parent guards —), and `node rm <id>`
   (soft-delete a node + subtree, reversible). Every current command keeps working unchanged.
-- **`wl prop` and `wl clock` entity groups (WL#486), filling two CRUD gaps.** `wl prop
+- **`wl prop` and `wl clock` entity groups, filling two CRUD gaps.** `wl prop
   set / ls / rm` — `set` keeps its top-level shortcut and `rm` gains the new shortcut
   `wl unset <id> <key>` (you can finally *remove* a custom prop, not just overwrite it).
   `wl clock ls / edit / rm` — list / fix (edit start-end, recomputing the duration) /
   remove a time interval; intervals are still created by `wl start` / `stop` / `spent`.
-- **`wl link` entity group + a default-verb mechanism for name-collision entities (WL#486).**
+- **`wl link` entity group + a default-verb mechanism for name-collision entities.**
   `wl link add / ls / rm` — `link add` keeps the top-level shortcut, `rm` gains the
   `wl unlink <id> <doc>` shortcut, and `link ls` is a new primitive (list a node's links).
   Because the entity name `link` is itself the everyday verb, the parser learned a
@@ -49,33 +98,33 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
   so `wl link 42 doc` still means `wl link add 42 doc` while `wl link ls / rm / -h` route to
   the group. Leaf ids are always integers, so id-vs-verb is unambiguous. This unblocks the
   same treatment for the other collision entities (`log` / `tag` / `sched`).
-- **`wl tag` reshaped into a metric-style group (WL#486), the second default-verb entity.**
+- **`wl tag` reshaped into a metric-style group, the second default-verb entity.**
   `wl tag add / ls / rm`. `add` is the default verb, so the everyday `wl tag <id> +work
   -planned` keeps working unchanged (full +add / -remove / bare-add / empty-list grammar);
   `tag ls` lists, `tag rm` removes by plain name. `tag` joins `link` in the default-verb
   table — `wl tag 42 +work` → `wl tag add 42 +work`, while `wl tag ls / rm / -h` route to
   the group; id-first disambiguation means `wl tag 1 ls` adds the tag `ls` whereas `wl tag
   ls 1` lists. Tag update stays atomic (no `edit` verb).
-- **`wl log` reshaped into a metric-style group (WL#486), the third default-verb entity.**
+- **`wl log` reshaped into a metric-style group, the third default-verb entity.**
   `wl log add / ls / edit / rm`. `add` is the default verb, so the everyday `wl log <id>
   "body"` keeps working unchanged (auto TODO→DOING, `--date` / `--time` / `--metric` /
   `--keep-status`). `log edit` and `log rm` reuse the `relog` / `unlog` handlers — both keep
   their top-level shortcuts — and `log ls <id>` is a new node-scoped lister (the full
   filterable / windowed stream view stays at `wl logs`). id-first disambiguation: `wl log 1
   ls` adds a log bodied `ls`, whereas `wl log ls 1` lists.
-- **`wl sched` reshaped into a metric-style group (WL#486), the fourth (and final collision)
+- **`wl sched` reshaped into a metric-style group, the fourth (and final collision)
   default-verb entity.** `wl sched add / ls / rm`. `add` is the default verb, so `wl sched
   <id> <when>` / `wl sched <id> --recur …` / `wl sched <id> --clear` all keep working
   unchanged (full when / `--recur` / `--clear` / list-when-empty grammar). `sched ls` lists,
   `sched rm` clears; `wl defer` (status=LATER + rough hint) stays its own command. With this,
   every collision entity (`link` / `tag` / `log` / `sched`) is reshaped.
-- **`date_meta` reshaped into a clean `wl date` group (WL#486) — completing the reshape.**
+- **`date_meta` reshaped into a clean `wl date` group — completing the reshape.**
   `wl date set / ls / rm / import`. Unlike the collision entities this is a *clean* group
   (no default verb — `date` doesn't collide with any leaf); `wl dateinfo` stays as the
   polymorphic everyday shortcut (sets when given a label, lists when not, `--clear` /
   `--import` variants) over the same table. **With this, every entity now has a full
   `<entity> <verb>` group.**
-- **`wl meta` group for the history-preserving typed-log fields (WL#486).** `wl meta set / ls
+- **`wl meta` group for the history-preserving typed-log fields.** `wl meta set / ls
   / rm <node> <field>` for `goal` / `summary` / `overview` / `top5` (each edit appends a typed
   log, latest = current — distinct from props, which are static single-value). `wl set` / `wl
   unset` are now *key-routed* shortcuts: a meta key routes to `wl meta set` / `wl meta rm`,
@@ -101,7 +150,7 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
   recap -h` now show the morning→evening→weekly→monthly planning rhythm — and their stale
   pre-reshape wording ("prop 'goal'", "summary_at") was corrected (they're history-preserving
   meta fields, not props).
-- **Single-letter short flags for the daily-workflow args (WL#487):** `-d` for `--date`
+- **Single-letter short flags for the daily-workflow args:** `-d` for `--date`
   (`wl log 1 "…" -d yesterday`, also on `logs` / `recap` / `unlog`) and `-n` for `--note`
   (`wl tick 1 -n "6 pullups"`, also on `wait` / `metric`).
 - **Help cross-references the shortcut ↔ canonical pair both ways** (now a documented
@@ -141,11 +190,11 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
   terminals (`render.HELP_MAX_WIDTH`, 100 cols) so help stays readable; everything shares the one
   `render.help_width()`, so columns line up.
 - **Removals are now reversible — soft-delete tombstones instead of `DELETE`, foreign keys
-  off (WL#501).** Every table gained a `deleted_at` tombstone; deleting a tag / link / log /
+  off.** Every table gained a `deleted_at` tombstone; deleting a tag / link / log /
   node sets it instead of removing the row, and reads filter it out, so an accidental
   `wl unlog` / `wl tag -x` / `wl apply '- #id'` is recoverable (clear `deleted_at`). FK
   enforcement is turned off and the app maintains consistency (app-level cascade), decoupling
-  the tables — preparation for multi-end / CRDT sync (#57). Re-adding a removed tag / link
+  the tables — preparation for multi-end / CRDT sync. Re-adding a removed tag / link
   revives its tombstone (a new `upsert` replaces `INSERT OR IGNORE/REPLACE`). Migration 0008
   is additive (nullable column, no data touched); 0009 makes the `v_node_path` view
   tombstone-aware. Internally this also moved ~19 single-table reads still on raw SQL onto
@@ -183,30 +232,29 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
   the index's topic-name column is padded to the longest name + 2 so a long id (`print-completion`)
   keeps a gap before its description instead of running into it.
 - **`wl tree --root <month>` / `wl focus <month>` now show tasks fuzzy-pinned at that time
-  node** (#436). A task pinned at `@2026-06` (via `scheduled_date`) hangs under its project,
+  node**. A task pinned at `@2026-06` (via `scheduled_date`) hangs under its project,
   not the month node, so the tree/focus parent_id walk missed it — which made a "what's
   already scheduled this month?" check come up empty and a duplicate get created. They now
-  surface such pins (the filtered `--tag`/`--kind` path too); #413 had fixed only day nodes.
+  surface such pins (the filtered `--tag`/`--kind` path too); an earlier fix covered only day nodes.
 - **Shell completion for default-verb group leaf args.** When a top-level command became a
   metric-style group (`log` / `sched`), its everyday args moved under the `add` subparser,
   which the fish / bash / zsh completion walk skipped — so `wl sched <id> --recur` lost its
   suggestions and `wl log <id> --date` its date completion. The generators now descend into
   a default-verb group's leaf (`_default_verb_leaf`) and emit those completions under the
   bare group name.
-- **`parent_id` cycle safety (FK-off hardening).** With foreign-key enforcement off
-  (WL#501), `parent_id` integrity isn't DB-guaranteed and the bulk `wl apply` / `wl import`
+- **`parent_id` cycle safety (FK-off hardening).** With foreign-key enforcement off, `parent_id` integrity isn't DB-guaranteed and the bulk `wl apply` / `wl import`
   update path set a parent with only an existence check (the interactive `wl reparent` had a
   cycle guard; the bulk path didn't) — a cycle would then make the ancestor/descendant
   walks loop forever and hang the CLI. The bulk path now refuses a self/descendant parent
   (parity with `reparent`), and `_collect_descendants` / `_ancestors_chain` are visited-set
   guarded so any pre-existing cycle degrades gracefully instead of hanging.
-- **`wl link` strips an outer `[[ ]]` wrapper on input (WL#462).** `[[X]]` and `X` now store
+- **`wl link` strips an outer `[[ ]]` wrapper on input.** `[[X]]` and `X` now store
   identically (no more `[[[[X]]]]` double-wrap), re-linking either form dedups via the natural
   key, and `wl unlink`/`apply -link` match regardless of wrapping. All link writes go through a
   single normalizing chokepoint (`_upsert_link`/`_delete_link`). (Dedup + `unlink` already
-  existed; this closes the last part of #462.)
+  existed; this closes the last part of that work.)
 - **`wl day` drops the redundant per-row `«planned·not-done»` hint under the default `--by
-  plan` (WL#500).** The `▸ planned` group header + the `[ ]` status marker already say it; the
+  plan`.** The `▸ planned` group header + the `[ ]` status marker already say it; the
   hint stays under `--by project`/`priority`, and the footer count is unchanged.
 
 ### Internal
@@ -217,7 +265,7 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
   `SELECT last_insert_rowid()` follow-ups — also more correct than the connection-global
   lastrowid), and 5 more single-table reads/writes moved onto `db_table`. Remaining raw SQL is
   all genuinely complex (JOIN / time-window / aggregate / OR-LIKE / conditional / dynamic).
-- **Raw-SQL 余债 cleared (WL#526):** `_get_or_make`'s 4 time-skeleton lookups (single-table
+- **Raw-SQL 余债 cleared:** `_get_or_make`'s 4 time-skeleton lookups (single-table
   `LIKE`/`=` probes) and `_node_clock_min`'s all-time clock-SUM + log-span-DISTINCT moved onto
   `db_table` (`cols=` carries the aggregate). Only the *day-scoped* aggregates (SUM/DISTINCT +
   `local_day_sql` in WHERE) stay raw — genuinely complex.

{pyworklog-0.6.0 → pyworklog-0.7.0}/DESIGN.md

@@ -117,7 +117,7 @@ The one **clean group** (no collision, so no default verb) is **`date`** (the `d
 table): `date set / ls / rm / import`, with `wl dateinfo` as the polymorphic everyday
 shortcut (sets when given a label, lists when not, `--clear` / `--import` variants).
 
-The `<entity> <verb>` reshape (WL#486) is now **complete** for every entity.
+The `<entity> <verb>` reshape is now **complete** for every entity.
 
 **B. Composite helper** — a one-step shortcut that wraps one or more primitives for
 the common path; never the *only* way to do something (the primitive stays). Status
@@ -162,6 +162,7 @@ A single `node` table carries everything; the `kind` field discriminates type; `
 - **status only applies to task / habit / meetlog**; time-hierarchy kinds (year/month/...) and project kind leave status NULL
 - Tables: `node / tag / log / metric / clock / prop / link / sched / date_meta` + derived view `v_node_path`
 - **`node → log → metric` spine** (the log-centric core): a `node` has many `log`s; a `log` (carrying a `tag` — `note`/`goal`/`summary`/`overview`/`top5`/`clock`(carrier)/… , NULL = plain note) has 0..N `metric`s. A `metric` is a structured datapoint (`tag` = what it is e.g. `glucose`/`pullups`/`checkin`; `value_num`/`value_text`/`unit`/`note`/`at`). **`tag` is the uniform classification field across all three** — node (a multi-value label set), log (its role, single-value), metric (its kind, single-value); same word, different scopes, SQL-unambiguous. A metric **must hang off a log** (`metric.log_id` NOT NULL) — so every datapoint has a log carrier; a `CHECK` requires a value (pure markers store `value_num=1`). `metric.node_id` is denormalized for join-free per-node queries (no FK; triggers keep it equal to the carrier log's node). CRUD surface: `wl metric add/ls/edit/rm` (`add` without `--on-log` creates a carrier log; a value-less marker is stored as `value_num=1`); `--metric` on `wl log`/`wl add` and `metrics` in `wl import` attach datapoints inline. Habit "done today" = a `tag=checkin` metric that day (written by `wl tick`/`wl checkin`), not "any log exists".
+- **Design rule — keep `log` thin; new per-log data goes on a `metric`, not a new log column.** The `log` table stays a small fixed shape (`node_id`/`logged_at`/`body`/`tag`). When some feature wants to attach structured data to a log event (a measurement, an id, a category, a flag), the answer is a `metric` hanging off that log — never a widened `log` row. A metric is already typed (`tag` + `value_num`/`value_text`/`unit`/`note`/`at`), queryable (`wl metric ls --tag …`), and append-only, so it carries arbitrary per-event fields without bloating every log. Example: `wl agent --record` stores the bound session id as an `agent_session` metric, not as a `log.session_id` column. This keeps the log body human-readable and the schema stable (G3).
 - **Meta fields are history-preserving typed logs**: day `goal`/`summary`, week `overview`, month `top5` are `log.tag` logs (latest = current; each edit appends), with their own `wl meta set/ls/rm` CRUD group; also written by `wl goal`/`wl recap` (today-auto) and the key-routed `wl set <node> <key>` shortcut. (`prop` is back to truly-static single-value attributes — a separate store.)
 - **`clock` is structured time tracking**: `clock(node_id, start_at, end_at, elapsed_sec)`, written by `wl start`/`stop`/`spent`/`wait` — replaces the old `CLOCK_IN`/`CLOCK_OUT` log-body convention. Durations are summed from `elapsed_sec`, not parsed from text.
 - **Two parallel trees, both hung under lifetime**:

{pyworklog-0.6.0 → pyworklog-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyworklog
-Version: 0.6.0
+Version: 0.7.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
@@ -16,12 +16,15 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Office/Business
 Classifier: Topic :: Utilities
-Requires-Python: >=3.11
+Requires-Python: >=3.9
 Requires-Dist: rich>=13
 Description-Content-Type: text/markdown
 
@@ -37,16 +40,48 @@ Description-Content-Type: text/markdown
 
 > **Changelog**: see [CHANGELOG.md](CHANGELOG.md) for a curated highlight reel of every release.
 
-SQLite-backed worklog tool with a `todo.sh`-style CLI. Models the full execution-system hierarchy in a single `node` table — lifetime / decade / year / quarter / month / week / day / project / task / habit / signal / meetlog — all sharing one id space, tree-linked via `parent_id` self-reference.
+**worklog (`wl`) is an AI-first, local-first execution-system CLI** — a structured replacement for a Markdown worklog. It models the full execution hierarchy in a single SQLite `node` table — lifetime / decade / year / quarter / month / week / day / project / task / habit / signal / meetlog — all sharing one id space, tree-linked via `parent_id` self-reference, behind a `todo.sh`-style command surface.
+
+## Why worklog?
+
+The origin: Markdown worklogs an AI kept for me grew ~50× and stopped scaling — concurrent writes clobbered, wikilinks drifted, summaries meant re-reading huge files. So I moved the structured part into a database built for an AI to drive.
+
+**AI-first** — the AI is the real user; you just glance at the terminal to confirm:
+
+- One-line commands, no interactive prompts — reliable to call from a shell.
+- `-q` brief mode + width-clipped rows → token-cheap output.
+- Plain-text output an AI reads directly; bundled [Claude Code skill](skills/worklog-cli/SKILL.md).
+
+**Local-first** — one SQLite file, transparent schema, no daemon / GUI / lock-in:
+
+- You and the AI read and write the same file — one source of truth.
+- Concurrent-write-safe → parallel AI sessions don't clobber (Markdown can't).
+- Pairs with your vault via `wl link` — structured execution in `wl`, long-form notes in Obsidian.
 
 **Design conventions: see [DESIGN.md](DESIGN.md)** — required reading before adding commands, to keep everything consistent.
 **AI collaboration: see [skills/worklog-cli/SKILL.md](skills/worklog-cli/SKILL.md)** — Claude Code skill (when / how to use `wl`, plus bulk import / apply).
-Background: structured worklog tool, built as a self-built alternative after surveying 12 candidate products (Logseq / Tana / TaskWarrior / org-mode / Anytype / Capacities / Linear etc.) and finding no off-the-shelf tool that fits all three dimensions (time hierarchy, project hierarchy, vault wikilink) without compromise.
+Background: built after surveying 12 candidate products (Logseq / Tana / TaskWarrior / org-mode / Anytype / Capacities / Linear etc.) and finding no off-the-shelf tool that fits all three dimensions (time hierarchy, project hierarchy, vault wikilink) without compromise.
+
+## Features
+
+- **One `node` table for everything** — time line (year → day) + project line (area → task) + habit / meetlog, tree-linked.
+- **Logs** — timestamped progress on any node, history-preserving.
+- **Metrics** — structured datapoints (reps, glucose, check-ins) that trend.
+- **Habits & recurrence** — check-ins + `--recur` (daily / weekly / monthly / …).
+- **Scheduling** — sched a task to a day; fuzzy words (`tomorrow`, `next-week`, `+3w`).
+- **Status machine** — TODO / DOING / LATER / WAIT / DONE / DEFERRED / CANCELED.
+- **Day / week / month views** — `wl day` / `tree` / `summary` rebuild the picture + stats.
+- **Full-text search** — `wl find`, hits highlighted.
+- **Vault link** — `wl link` to Obsidian docs (`[[wikilink]]`).
+- **Bulk import / apply** — load a whole day in one JSON or wl-diff.
+- **AI-friendly output** — `-q` brief, plain-text on capture, colors on a TTY, shell completion.
 
 ## Install
 
 ### From PyPI (recommended for users)
 
+Requires Python ≥ 3.9 (tested on 3.9–3.14).
+
 ```fish
 pipx install pyworklog          # or: uv tool install pyworklog
 wl init
@@ -76,8 +111,22 @@ Behind the scenes `make setup` runs `uv sync` to create `.venv/` from `pyproject
 
 DB location follows the [XDG Base Directory spec](https://specifications.freedesktop.org/basedir-spec/): default `$XDG_DATA_HOME/worklog/worklog.db` (i.e. `~/.local/share/worklog/worklog.db`). Override per-invocation with `wl --db PATH ...`, or globally with the `$WORKLOG_DB` env var. User config (aliases.ini) lives at `$XDG_CONFIG_HOME/worklog/aliases.ini` (default `~/.config/worklog/aliases.ini`).
 
+## Quickstart
+
+The first 30 seconds — add a task, log progress, close it, replay the day:
+
+```fish
+wl init                                   # create the DB (once)
+wl add "write the README" -k task -p A    # → prints the new id, e.g. #1
+wl log 1 "drafted the Features section"   # append progress
+wl done 1                                 # close it
+wl day                                    # today's work, regrouped + stats
+```
+
 ## Commands
 
+The fuller surface — every command also has `wl <cmd> --help`, and `wl help` browses topic docs:
+
 ```fish
 wl add "research X" -k task -p A -t work,P0 --proj dev_tooling --parent 42
 wl add "Dev tooling" -k project -p A --parent 4   # project hangs under month

{pyworklog-0.6.0 → pyworklog-0.7.0}/README.md

@@ -10,16 +10,48 @@
 
 > **Changelog**: see [CHANGELOG.md](CHANGELOG.md) for a curated highlight reel of every release.
 
-SQLite-backed worklog tool with a `todo.sh`-style CLI. Models the full execution-system hierarchy in a single `node` table — lifetime / decade / year / quarter / month / week / day / project / task / habit / signal / meetlog — all sharing one id space, tree-linked via `parent_id` self-reference.
+**worklog (`wl`) is an AI-first, local-first execution-system CLI** — a structured replacement for a Markdown worklog. It models the full execution hierarchy in a single SQLite `node` table — lifetime / decade / year / quarter / month / week / day / project / task / habit / signal / meetlog — all sharing one id space, tree-linked via `parent_id` self-reference, behind a `todo.sh`-style command surface.
+
+## Why worklog?
+
+The origin: Markdown worklogs an AI kept for me grew ~50× and stopped scaling — concurrent writes clobbered, wikilinks drifted, summaries meant re-reading huge files. So I moved the structured part into a database built for an AI to drive.
+
+**AI-first** — the AI is the real user; you just glance at the terminal to confirm:
+
+- One-line commands, no interactive prompts — reliable to call from a shell.
+- `-q` brief mode + width-clipped rows → token-cheap output.
+- Plain-text output an AI reads directly; bundled [Claude Code skill](skills/worklog-cli/SKILL.md).
+
+**Local-first** — one SQLite file, transparent schema, no daemon / GUI / lock-in:
+
+- You and the AI read and write the same file — one source of truth.
+- Concurrent-write-safe → parallel AI sessions don't clobber (Markdown can't).
+- Pairs with your vault via `wl link` — structured execution in `wl`, long-form notes in Obsidian.
 
 **Design conventions: see [DESIGN.md](DESIGN.md)** — required reading before adding commands, to keep everything consistent.
 **AI collaboration: see [skills/worklog-cli/SKILL.md](skills/worklog-cli/SKILL.md)** — Claude Code skill (when / how to use `wl`, plus bulk import / apply).
-Background: structured worklog tool, built as a self-built alternative after surveying 12 candidate products (Logseq / Tana / TaskWarrior / org-mode / Anytype / Capacities / Linear etc.) and finding no off-the-shelf tool that fits all three dimensions (time hierarchy, project hierarchy, vault wikilink) without compromise.
+Background: built after surveying 12 candidate products (Logseq / Tana / TaskWarrior / org-mode / Anytype / Capacities / Linear etc.) and finding no off-the-shelf tool that fits all three dimensions (time hierarchy, project hierarchy, vault wikilink) without compromise.
+
+## Features
+
+- **One `node` table for everything** — time line (year → day) + project line (area → task) + habit / meetlog, tree-linked.
+- **Logs** — timestamped progress on any node, history-preserving.
+- **Metrics** — structured datapoints (reps, glucose, check-ins) that trend.
+- **Habits & recurrence** — check-ins + `--recur` (daily / weekly / monthly / …).
+- **Scheduling** — sched a task to a day; fuzzy words (`tomorrow`, `next-week`, `+3w`).
+- **Status machine** — TODO / DOING / LATER / WAIT / DONE / DEFERRED / CANCELED.
+- **Day / week / month views** — `wl day` / `tree` / `summary` rebuild the picture + stats.
+- **Full-text search** — `wl find`, hits highlighted.
+- **Vault link** — `wl link` to Obsidian docs (`[[wikilink]]`).
+- **Bulk import / apply** — load a whole day in one JSON or wl-diff.
+- **AI-friendly output** — `-q` brief, plain-text on capture, colors on a TTY, shell completion.
 
 ## Install
 
 ### From PyPI (recommended for users)
 
+Requires Python ≥ 3.9 (tested on 3.9–3.14).
+
 ```fish
 pipx install pyworklog          # or: uv tool install pyworklog
 wl init
@@ -49,8 +81,22 @@ Behind the scenes `make setup` runs `uv sync` to create `.venv/` from `pyproject
 
 DB location follows the [XDG Base Directory spec](https://specifications.freedesktop.org/basedir-spec/): default `$XDG_DATA_HOME/worklog/worklog.db` (i.e. `~/.local/share/worklog/worklog.db`). Override per-invocation with `wl --db PATH ...`, or globally with the `$WORKLOG_DB` env var. User config (aliases.ini) lives at `$XDG_CONFIG_HOME/worklog/aliases.ini` (default `~/.config/worklog/aliases.ini`).
 
+## Quickstart
+
+The first 30 seconds — add a task, log progress, close it, replay the day:
+
+```fish
+wl init                                   # create the DB (once)
+wl add "write the README" -k task -p A    # → prints the new id, e.g. #1
+wl log 1 "drafted the Features section"   # append progress
+wl done 1                                 # close it
+wl day                                    # today's work, regrouped + stats
+```
+
 ## Commands
 
+The fuller surface — every command also has `wl <cmd> --help`, and `wl help` browses topic docs:
+
 ```fish
 wl add "research X" -k task -p A -t work,P0 --proj dev_tooling --parent 42
 wl add "Dev tooling" -k project -p A --parent 4   # project hangs under month

{pyworklog-0.6.0 → pyworklog-0.7.0}/README.zh.md

@@ -8,15 +8,45 @@
 [![codecov](https://codecov.io/gh/xyb/worklog/branch/main/graph/badge.svg)](https://codecov.io/gh/xyb/worklog)
 [![License: MIT](https://img.shields.io/pypi/l/pyworklog.svg)](https://github.com/xyb/worklog/blob/main/LICENSE)
 
-SQLite 后端的 worklog 工具,`todo.sh` 风格 CLI。完整执行体系层级建模在单个 `node` 表里 —— lifetime / decade / year / quarter / month / week / day / project / task / habit / signal / meetlog —— 共享同一个 id 空间,通过 `parent_id` 自引用形成树状结构。
+**worklog(`wl`)是一个 AI-first、local-first 的执行体系 CLI** —— 用来替代 Markdown 工作记录。完整执行体系层级建模在单个 SQLite `node` 表里 —— lifetime / decade / year / quarter / month / week / day / project / task / habit / signal / meetlog —— 共享同一个 id 空间,通过 `parent_id` 自引用形成树,命令风格沿用 `todo.sh`。
+
+## 为什么用 worklog?
+
+起源:AI 帮我记的 Markdown 工作记录涨了大约 50 倍后撑不住——并发写互相覆盖、wikilink 重命名就断、总结要重读大文件。于是把结构化的部分挪进一个为 AI 驱动而设计的数据库。
+
+**AI-first** —— AI 才是真正的使用者,人只在终端看一眼确认:
+
+- 命令单行、无交互问答 —— shell 里调用最不易出错。
+- `-q` brief 模式 + 按宽度截行 → 输出省 token。
+- 输出是 AI 能直接读的纯文本;自带 [Claude Code skill](skills/worklog-cli/SKILL.md)。
+
+**local-first** —— 一个 SQLite 文件、schema 透明、无常驻进程 / GUI / 锁定:
+
+- 人和 AI 读写同一个文件 —— 同一份事实。
+- 并发写安全 → 多个 AI session 并行记录不互相覆盖(Markdown 做不到)。
+- 通过 `wl link` 跟 vault 配合 —— 结构化执行进 `wl`,长文笔记留在 Obsidian。
 
 **设计约定见 [DESIGN.md](DESIGN.md)** —— 加命令前必读,保持各处一致。
 **AI 协作见 [skills/worklog-cli/SKILL.md](skills/worklog-cli/SKILL.md)** —— Claude Code skill(何时 / 如何用 `wl` + 批量 import / apply)。
-背景: 结构化 worklog 工具,在调研了 12 个候选产品(Logseq / Tana / TaskWarrior / org-mode / Anytype / Capacities / Linear 等)后没找到能同时覆盖三个维度(时间层级 / 项目层级 / vault wikilink)又无折中的现成方案,所以自建。
+背景: 在调研了 12 个候选产品(Logseq / Tana / TaskWarrior / org-mode / Anytype / Capacities / Linear 等)后没找到能同时覆盖三个维度(时间层级 / 项目层级 / vault wikilink)又无折中的现成方案,所以自建。
+
+## 特性
+
+- **一张 `node` 表装下一切** —— 时间线(year → day)+ 项目线(area → task)+ 习惯 / 会议记录,连成树。
+- **Log** —— 任意 node 上带时间戳的进展,保留历史。
+- **Metric** —— 结构化数据点(次数、血糖、打卡),能做趋势。
+- **习惯 & 循环** —— 打卡 + `--recur`(daily / weekly / monthly / …)。
+- **排期** —— 把任务排到某天;模糊时间词(`tomorrow` / `next-week` / `+3w`)。
+- **状态机** —— TODO / DOING / LATER / WAIT / DONE / DEFERRED / CANCELED。
+- **日 / 周 / 月视图** —— `wl day` / `tree` / `summary` 重建画面 + 统计。
+- **全文搜索** —— `wl find`,命中高亮。
+- **Vault 关联** —— `wl link` 到 Obsidian 文档(`[[wikilink]]`)。
+- **批量 import / apply** —— 一个 JSON 或 wl-diff 导入一整天。
+- **AI 友好输出** —— `-q` brief、捕获时纯文本、TTY 上配色、shell 补全。
 
 ## 安装
 
-需要先装 [uv](https://docs.astral.sh/uv/)(`brew install uv` 或 `pipx install uv`)。
+需要 Python ≥ 3.9(在 3.9–3.14 上测过)。先装 [uv](https://docs.astral.sh/uv/)(`brew install uv` 或 `pipx install uv`)。
 
 ```fish
 git clone https://github.com/xyb/worklog.git ~/projects/worklog
@@ -36,8 +66,22 @@ wl init
 
 数据库位置遵循 [XDG Base Directory 规范](https://specifications.freedesktop.org/basedir-spec/): 默认 `$XDG_DATA_HOME/worklog/worklog.db`(即 `~/.local/share/worklog/worklog.db`)。可以用 `wl --db PATH ...` 单次覆盖,也可以用 `$WORKLOG_DB` 环境变量全局覆盖。用户配置(aliases.ini)走 `$XDG_CONFIG_HOME/worklog/aliases.ini`(默认 `~/.config/worklog/aliases.ini`)。
 
+## 快速开始
+
+头 30 秒 —— 加任务、记进展、完成、复现当天:
+
+```fish
+wl init                                   # 建库(一次)
+wl add "写 README" -k task -p A           # → 打印新 id,如 #1
+wl log 1 "起草了 Features 段"             # 追加进展
+wl done 1                                 # 完成
+wl day                                    # 今天的工作, 重新分组 + 统计
+```
+
 ## 命令
 
+更全的命令面 —— 每条命令也有 `wl <cmd> --help`,`wl help` 浏览主题文档:
+
 ```fish
 wl add "调研 X" -k task -p A -t work,P0 --proj dev_tooling --parent 42
 wl add "Dev tooling" -k project -p A --parent 4   # 项目挂在月份下

{pyworklog-0.6.0 → pyworklog-0.7.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "pyworklog"
-version = "0.6.0"
+version = "0.7.0"
 description = "SQLite-backed worklog tool with a todo.sh-style CLI"
 readme = "README.md"
 license = "MIT"
 authors = [{ name = "Xie Yanbo" }]
-requires-python = ">=3.11"
+requires-python = ">=3.9"
 keywords = ["worklog", "cli", "sqlite", "todo", "productivity"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -15,9 +15,12 @@ classifiers = [
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Office/Business",
     "Topic :: Utilities",
 ]