pyworklog 0.3.0__tar.gz

pyworklog-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release
+
+# Pushing a vX.Y.Z tag:
+#   1. verifies the tag matches pyproject.toml version,
+#   2. runs the test suite (release 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.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # for creating the GitHub Release
+      id-token: write   # for PyPI Trusted Publisher (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # need full history for auto-generated release notes
+
+      - name: Verify tag matches pyproject version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          proj=$(grep -m1 '^version = ' pyproject.toml | sed 's/.*"\(.*\)".*/\1/')
+          echo "git tag=$tag · pyproject=$proj"
+          if [ "$tag" != "$proj" ]; then
+            echo "::error::version mismatch — git tag must equal pyproject.toml version (which __version__ reads via importlib.metadata)"
+            exit 1
+          fi
+
+      - 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
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No `with: password:` — uses OIDC Trusted Publisher.
+        # One-time setup on PyPI: https://pypi.org/manage/account/publishing/
+        #   PyPI Project Name: pyworklog  (worklog/worklog-cli taken; hyphenated names avoided)
+        #   Owner: xyb · Repository: worklog
+        #   Workflow filename: release.yml · Environment name: (leave empty)
+
+      - name: Build commit list since previous tag
+        id: commits
+        run: |
+          prev=$(git describe --tags --abbrev=0 "${GITHUB_REF_NAME}^" 2>/dev/null || echo "")
+          {
+            if [ -n "$prev" ]; then
+              echo "## Commits since $prev"
+              echo ""
+              git log --pretty=format:'- %s (%h)' "$prev..$GITHUB_REF_NAME"
+              echo ""
+            else
+              echo "## Commits"
+              echo ""
+              git log --pretty=format:'- %s (%h)' "$GITHUB_REF_NAME"
+              echo ""
+            fi
+            echo ""
+            echo "## Install"
+            echo ""
+            echo '```'
+            echo "pip install pyworklog==${GITHUB_REF_NAME#v}"
+            echo '```'
+          } > release-body.md
+          {
+            echo 'body<<EOF'
+            cat release-body.md
+            echo 'EOF'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.commits.outputs.body }}
+          generate_release_notes: true   # keeps the auto "Full Changelog" link and any PR list
+          files: |
+            dist/*.whl
+            dist/*.tar.gz

pyworklog-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,51 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Sync deps
+        run: uv sync --all-groups
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+      - name: Smoke test CLI
+        run: |
+          export WORKLOG_DB=$(mktemp -d)/worklog.db
+          uv run wl init
+          uv run wl --version
+          uv run wl add "ci smoke task" -k task -p A
+          uv run wl log 1 "hello from CI"
+          uv run wl done 1
+          uv run wl show 1
+          uv run wl tree
+          uv run wl migrate

pyworklog-0.3.0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# ── worklog project specific ──
+*.db
+*.db-journal
+wl.py.bak
+TODO.local.md
+local/

pyworklog-0.3.0/AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+
+Primary operating guide for AI coding agents (Claude Code, Cursor, Aider, etc.) working in this repository. Keep it under ~200 lines — anything longer stops getting read in full.
+
+## Authoritative docs (read these first)
+
+- **`DESIGN.md`** is canonical for every shared convention (command style, state machine, marker symbols, time-window flags, rendering, schema, import/apply formats, color theming, scheduled time, planned/unplanned derivation, etc.). Read the relevant section before adding a command or changing a format — keeping `src/worklog/cli.py`, the tests, the completion strings, and DESIGN in sync is the project's hardest rule.
+- **`CONTRIBUTING.md`** holds the full dev setup, TDD + DRY conventions, local Makefile overrides, and release process. Do not duplicate that content here.
+- **`skills/worklog-cli/SKILL.md`** is the Claude Code skill (AI-facing usage guide: when to use `wl`, scenario→command table, bulk `import` / `apply` patterns, `-q` brief mode for token savings). Update this when usage patterns change.
+- `README.md` is the project overview + install pointer only; `tests/test_wl.py` is the de-facto contract for every command.
+
+## Common commands
+
+```fish
+make setup          # first-time: uv sync + install ~/bin/wl wrapper into project .venv
+make test           # pytest in parallel (-n auto) with the 95% cov gate from pytest.ini
+make test-v         # sequential, no cov — debug noisy output
+make test-fast      # parallel, no cov gate — quick dev loop
+make cov            # detailed term-missing coverage report
+make demo           # reset DB + populate sample tree (irreversible)
+make reset          # interactive: drop current DB + re-init
+make ship           # test then push (only pushes if green)
+```
+
+Single-test invocation:
+
+```fish
+uv run pytest tests/test_wl.py::TestApply::test_apply_delete_cascades_subtree -v --no-cov
+```
+
+Ad-hoc DB for scratch work without touching `~/.local/share/worklog/worklog.db`:
+
+```fish
+wl --db /tmp/scratch.db init
+wl --db /tmp/scratch.db add "..."
+```
+
+`wl config` prints the resolved DB path + source (`--db flag` / `$WORKLOG_DB` / XDG default) plus all env vars — start there when debugging a path/env confusion.
+
+## Architecture (the big picture)
+
+**Single-package CLI.** `src/worklog/` holds everything: `cli.py` (~5000 lines) is the implementation, `migrations/NNNN_*.sql` is the schema (one initial file at v0.3.0, more added per schema change), `__init__.py` re-exports `__version__`. No further submodule split inside `cli.py` — kept this way intentionally; reconsider only when a feature truly cannot be co-located.
+
+**One polymorphic `node` table.** The `kind` column distinguishes `lifetime / decade / year / quarter / month / week / day / area / project / task / meetlog / habit / signal`; `parent_id` self-reference builds the tree. Two parallel sub-trees hang under `lifetime`: a **responsibility line** (`area → project → task`, PARA-style) and a **time line** (`year → quarter → month → week → day`, time skeleton + metadata props). Day/week/month views are **log-driven** (`logged_at` + ancestor chain + tags), not via fixed parent-of-task — moving projects between areas does not break per-day views. Tables: `node / tag / log / prop / link / sched / date_meta` + recursive CTE view `v_node_path`.
+
+**Path resolution.** Priority: `wl --db PATH` flag → `$WORKLOG_DB` env → `$XDG_DATA_HOME/worklog/worklog.db` (default `~/.local/share/worklog/worklog.db`). Config is `$XDG_CONFIG_HOME/worklog/aliases.ini`. `_resolve_db_path(args)` is the only resolver; `cmd_config` displays which branch fired.
+
+**Subcommand dispatch.** `build_parser()` constructs the argparse tree (one `sub.add_parser(...)` block per command, with `help` + `description` + `epilog`). `HANDLERS = {"cmd": cmd_handler}` maps the parsed name to `cmd_<name>(args, con) -> None`. `main()` resolves user aliases (`~/.config/worklog/aliases.ini`), routes meta-commands (`print-completion`, `config`) that bypass `ensure_db()`, applies `--db` override, then calls the handler. Tests invoke `HANDLERS[cmd](args, con)` directly through the `cli` fixture to bypass `main()`.
+
+**Rendering pipeline.** All output goes through `out()` (rich-aware) — never bare `print()` for user-visible rows. `_c(text, style)` is the single coloring entry: when `_CONSOLE` is set, it escapes content via `rich.markup.escape` (so `[x]`, `[[doc]]`, `[#A]` aren't eaten as rich markup) and wraps with `[style]…[/style]`; when console is plain, it returns the string. **Any fragment that may contain `[ ]` must go through `_c`** — direct insertion triggers `rich.MarkupError` or silent eating. `_node_line(con, n, ...)` is the **only node renderer**; reuse it everywhere listing nodes, including new commands, to inherit highlighting + search-hit emphasis for free. `_init_console` runs once in `main()`; tests run in plain mode (no TTY).
+
+**Shell completion is generated, not hand-written.** `wl print-completion {fish,bash,zsh}` walks the argparse tree at runtime and emits a script tailored to that shell. Each shell template contains a `__wl_db_path[_bash|_zsh]` helper that queries SQLite directly for dynamic node-id / tag completions — **no Python startup**, so Tab is <50ms. When you add a subcommand or flag, completion is automatic; **but** if it takes a node id or tag, register it in `_FISH_POSITIONAL_NODE` / `_FISH_HELPERS` / `_BASH_DYN_HELPERS` so dynamic completion fires.
+
+**Coverage gate is hard (95%).** `pytest.ini` enforces `--cov-fail-under=95`; the CI runs the same. The two pragma-no-cover regions are TTY/escape-sequence probes in `_detect_bg_is_dark` and the bare `main()` entrypoint (tests bypass it).
+
+## Core principles
+
+- **TDD (Red → Green → Refactor).** Behavioral changes start with a failing test in `tests/test_wl.py` that reproduces the bug or pins the new behavior. Confirm it fails for the right reason, then write the minimum code to make it pass, then refactor. Tests stay green at every step. A PR that adds behavior without adding the test that drives it is rejected. See CONTRIBUTING.md "TDD" for the full loop.
+- **DRY (Don't Repeat Yourself).** The codebase has a small set of single-source helpers — `_status_marker`, `_node_line`, `out`/`_c`, `_resolve_window`, `_resolve_db_path`, `_project_members`, `_node_clock_min`, `_collect_descendants` (see DESIGN §12 for the full list). New code reuses them; re-implementing one of them in a fresh form is a review block. Same rule for docs: install / dev / release info is in CONTRIBUTING.md and only there — link to it, don't restate it.
+
+## Hard rules
+
+- **DESIGN.md is the source of truth.** If a convention changes (statuses, markers, time-window flag set, project↔task linkage rule, `--by` aggregation dim, theme key set, schema), update DESIGN + `src/worklog/cli.py` + tests + completion strings in the same commit. Drift between them is the failure mode this project guards against.
+- **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.
+- **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.
+
+## Local overrides + release
+
+Both processes are documented end-to-end in [CONTRIBUTING.md](CONTRIBUTING.md) — local `local/*.mk` Makefile injection and the three-anchor version-bump workflow (`__version__` in `src/worklog/cli.py` + `pyproject.toml` + git tag, all verified by `.github/workflows/release.yml`). Don't duplicate them here.

pyworklog-0.3.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to **worklog** are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures every commit; this file is the human-curated highlight reel.
+
+## [Unreleased]
+
+## [0.3.0] — 2026-06-01
+
+### Added
+- `pip install pyworklog` now works. The project ships as a proper Python package (`src/worklog/`) with a `wl` console-script entry point; `uv build` produces a wheel + sdist with `worklog/migrations/0001_initial_schema.sql` packaged in. The PyPI **distribution** name is `pyworklog` (the short names `worklog` and `worklog-cli` were already taken on PyPI, and hyphenated names like `worklog-py` were avoided); the import name and `wl` command are unchanged.
+- **SQL migrations runner** — schema is delivered as `src/worklog/migrations/NNNN_*.sql`; `PRAGMA user_version` tracks the highest applied. `ensure_db()` auto-applies pending migrations on every command. New `wl migrate` is the explicit form (and the one place that bypasses `ensure_db()` so the handler has work to do on a fresh DB).
+- **Downgrade guard** — if `user_version` is ahead of the migrations shipped with the running build, the tool aborts with an upgrade prompt instead of corrupting newer schema with stale logic.
+
+### Changed
+- `wl.py` moved to `src/worklog/cli.py`; `schema.sql` moved to `src/worklog/migrations/0001_initial_schema.sql`. Internal imports rewritten throughout; tests, CI, and the `~/bin/wl` Makefile wrapper now go through the entry-point (`.venv/bin/wl`).
+- `__version__` reads from `importlib.metadata.version("pyworklog")` — `pyproject.toml` is now the single in-repo source of truth for version, and `uv.lock` pins it deterministically. `release.yml` verifies tag against `pyproject.toml` only.
+- `--cov` target switched from `wl` to `worklog`; coverage gate stays at 95%.
+
+### Removed
+- Hand-edited `__version__` in `wl.py`. (Use `pyproject.toml`.)
+
+### Migration notes for existing users
+- The DB path is unchanged (`$WORKLOG_DB` or `$XDG_DATA_HOME/worklog/worklog.db`). Existing DBs upgrade transparently on the first command after install: `_run_migrations()` no-ops on existing tables (the bootstrap migration uses `CREATE TABLE IF NOT EXISTS`) and stamps `user_version=1`. Verified on a 311 KB production-DB backup: row counts unchanged, `PRAGMA integrity_check = ok`.
+- Re-run `make install` (or `make setup`) once so the `~/bin/wl` wrapper points at the new `.venv/bin/wl`.
+
+## [0.2.0] — 2026-05-31
+
+### Added
+- **`wl config`** command — prints resolved DB path, aliases path, XDG directories, environment, runtime info; read-only (does not create the DB just to inspect paths).
+- **`wl --db PATH`** global flag — per-invocation DB override (handy for testing or running against multiple worklogs); takes precedence over `$WORKLOG_DB` and the XDG default.
+- **XDG Base Directory spec** — DB defaults to `$XDG_DATA_HOME/worklog/worklog.db` (`~/.local/share/worklog/worklog.db`); aliases at `$XDG_CONFIG_HOME/worklog/aliases.ini`. Paths resolved lazily at call time so `pytest`'s `monkeypatch` works without reload tricks.
+- CI matrix on GitHub Actions (`ubuntu-latest` + `macos-latest` × Python 3.11 / 3.12 / 3.13) + Codecov coverage upload + status badges in README.
+- **Release workflow** — push a `v*` tag → verify version anchors agree, run the test suite, publish a GitHub Release with auto-generated `Commits since vX.Y.Z` notes.
+- **`AGENTS.md`** — vendor-neutral operating guide for AI coding agents (Claude Code, Cursor, Aider). Codifies TDD (Red-Green-Refactor) and DRY (single-source helpers) as project rules.
+- **`CONTRIBUTING.md`** — full dev setup, TDD + DRY conventions, local Makefile overrides, release process.
+
+### Changed
+- Project namespace fully renamed from `wl` to `worklog` (paths and env vars): `~/.local/share/wl/wl.db` → `~/.local/share/worklog/worklog.db`; `~/.config/wl/aliases.ini` → `~/.config/worklog/aliases.ini`; `$WL_DB` / `$WL_COLOR` / `$WL_THEME` → `$WORKLOG_*`. The CLI command stays `wl`.
+- **uv** replaces `venv` + `pip` + `requirements*.txt`. `pyproject.toml` (PEP 621) + `dependency-groups` (PEP 735) + `uv.lock` is the dependency single-source. `make setup` runs `uv sync` and installs the `~/bin/wl` wrapper.
+- `_setup_aliases` test fixture now also clears `XDG_CONFIG_HOME` / `XDG_DATA_HOME` — CI runners preset these and otherwise leak into tests.
+
+### Removed
+- `requirements.txt` / `requirements-dev.txt` — replaced by `pyproject.toml` + `uv.lock`.
+- Pre-XDG path fallbacks (`~/.worklog/wl.db`) — v0.1.0 was the only release that wrote there.
+
+## [0.1.0] — 2026-05-31
+
+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).
+- Bilingual project documentation (English + Chinese for README / DESIGN / SKILL).
+- MIT License.
+
+[Unreleased]: https://github.com/xyb/worklog/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/xyb/worklog/compare/v0.2.0...v0.3.0
+
+[0.2.0]: https://github.com/xyb/worklog/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/xyb/worklog/releases/tag/v0.1.0

pyworklog-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Contributing to worklog
+
+Thanks for considering a contribution! This guide covers the local setup, the development loop, and the two coding principles every change is held to: **TDD** and **DRY**.
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) — install via `brew install uv` or `pipx install uv`.
+- Python ≥ 3.11. `uv` handles the interpreter — no system Python juggling.
+
+## Quick start
+
+```fish
+git clone https://github.com/xyb/worklog.git ~/projects/worklog
+cd ~/projects/worklog
+make setup       # uv sync (creates .venv) + installs ~/bin/wl wrapper
+make test        # run the full suite (parallel, 95% cov gate)
+```
+
+`make setup` does two things: `uv sync --all-groups` materializes `.venv/` from `pyproject.toml` + `uv.lock`, and `make install` writes `~/bin/wl` pointing into that venv. From there, every command (`uv run pytest …`, `make test`, etc.) uses the same locked deps.
+
+## Day-to-day development loop
+
+```fish
+make test          # parallel, cov, 95% gate  — pre-commit baseline
+make test-fast     # parallel, no cov, no gate — quick iteration
+make test-v        # sequential, verbose, no cov — debug a single failure
+
+# single test by node id
+uv run pytest tests/test_wl.py::TestApply::test_apply_delete_cascades_subtree -v --no-cov
+
+# coverage gate already lives in pytest.ini (--cov-fail-under=95); `make cov`
+# just re-runs `make test` with term-missing output for inspection.
+make cov
+```
+
+Run `wl` against a throwaway DB without touching `~/.local/share/worklog/worklog.db`:
+
+```fish
+wl --db /tmp/scratch.db init
+wl --db /tmp/scratch.db add "experiment"
+```
+
+`wl config` shows which DB is currently resolved (helpful when an env / flag mix is confusing).
+
+## Architecture
+
+`DESIGN.md` is canonical for every shared convention — command style, state machine, marker symbols, time-window flags, render pipeline, schema, `import` / `apply` formats, theme keys, scheduled-time resolution, planned/unplanned derivation. Read the relevant section before adding a command or changing a format. If your change touches a convention, the same commit must update **DESIGN.md + `src/worklog/cli.py` + `tests/test_wl.py` + completion strings together** — drift between them is the failure mode this project guards against.
+
+`AGENTS.md` is the operating guide for AI coding agents (Claude Code, Cursor, Aider). Skim it once even if you code by hand; it concentrates the hard-rules into one page.
+
+## TDD: red → green → refactor
+
+Every change touching behavior follows the [Red-Green-Refactor cycle](https://brennanbrown.github.io/notes/programming/python-tdd/):
+
+1. **Red** — add a failing test in `tests/test_wl.py` first. Run it; confirm it fails for the reason you expect (not an import error). A test that never fails is not a test.
+2. **Green** — write the minimum production code to make that test pass. Resist the urge to also fix neighboring code; one cycle, one concern.
+3. **Refactor** — clean up. Extract helpers, remove duplication, rename. Tests still green at every step.
+
+Bug fixes follow the same path: write a regression test that reproduces the bug first, then fix.
+
+Tests don't ship without docstrings explaining what behavior they pin down (see existing `TestXDGPaths`, `TestConfig` for the style). One `Test<Command>` class per command. Cover happy path + boundaries (missing id, empty DB, illegal flag values) — the boundaries are where DESIGN drift surfaces first.
+
+## DRY: there is exactly one of each
+
+The codebase has a small set of single-source helpers; new code must reuse them, never re-implement. The full list lives in DESIGN §12, but the load-bearing ones:
+
+- `_status_marker(status)` — status → `[ ]/[x]/[/]/...` marker. Never hard-code the marker elsewhere.
+- `_node_line(con, n, ...)` — the **only** node renderer. Any place listing nodes reuses it and inherits highlighting + search emphasis for free. Hand-rolling a node line is rejected in review.
+- `out()` / `_c(text, style)` — the single output pipe. Bare `print()` for renderable content is rejected; any fragment that might contain `[ ]` must go through `_c` so `rich.markup` doesn't eat it.
+- `_resolve_window(args)` — time-window flag resolution. Commands must not parse `--since` / `--until` / `--week` / `--month` themselves.
+- `_resolve_db_path(args)` — DB path resolution (`--db` flag > `$WORKLOG_DB` > XDG default). Mirrored by `__wl_db_path[_bash|_zsh]` helpers in the generated shell completion — keep them in sync.
+
+Same rule for documentation: install / dev / release info lives here, not duplicated in README. Sections in README that need this content link to it instead of restating it.
+
+## Local Makefile overrides
+
+The Makefile loads any `local/*.mk` files at the end via `-include local/*.mk`. The `local/` directory is gitignored, so site-specific variables, private remotes, or extra targets go there without touching the shipped Makefile. Missing is fine — make won't complain.
+
+Example `local/private.mk`:
+
+```makefile
+GITEA_REMOTE := git@your-private-host:user/worklog.git
+
+push-gitea:        ## push current branch to private remote
+	@$(GIT) -c commit.gpgsign=false push $(GITEA_REMOTE) $$($(GIT) branch --show-current)
+```
+
+After saving, `make help` lists `push-gitea` alongside the built-in targets.
+
+## Release process
+
+Version has a **single** in-repo source: `version = "X.Y.Z"` in `pyproject.toml`. `__version__` in `src/worklog/cli.py` reads it via `importlib.metadata.version("worklog")` — never edit it by hand. The git tag `vX.Y.Z` must match the pyproject version; the release workflow enforces that.
+
+The `Release` workflow (`.github/workflows/release.yml`) is triggered by pushing a `v*` tag. It verifies tag == pyproject version, re-runs the test suite, then calls `softprops/action-gh-release@v2` to publish a GitHub Release with auto-generated notes (commits since the previous tag).
+
+To cut a release:
+
+```fish
+# 1. bump version in pyproject.toml only
+# 2. refresh the lock entry so uv.lock pins the new version
+uv lock --upgrade-package worklog
+# 3. commit + tag + push
+git commit -am "chore: bump version to X.Y.Z"
+git tag vX.Y.Z
+git push origin main
+git push origin vX.Y.Z
+```
+
+The workflow fails the release if any of the three version anchors disagree, so a typo can't ship.
+
+## Pull requests
+
+- Branch from `main`. PRs target `main`.
+- Each PR moves the test count up: a refactor adds no tests but keeps coverage ≥95%; a feature/fix adds the test that exercises it.
+- Run `make test` locally before pushing. CI runs the same parallel pytest + 95% gate across ubuntu + macos × Python 3.11/3.12/3.13.
+- DESIGN.md / AGENTS.md drift is the most common review block — when in doubt, update them in the same PR.