weektag 0.0.1__tar.gz

weektag-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+      - name: Test
+        run: uv run pytest -q

weektag-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC), no API tokens (ADR 0010)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

weektag-0.0.1/.gitignore

@@ -0,0 +1,218 @@
+# 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

weektag-0.0.1/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+**weektag** — a CLI-first, tag-based time tracker (command name: `tt`) distributed on PyPI as `weektag`. Its differentiator is agent-readability: the data files must be directly readable by humans, `jq`, and coding agents with no preprocessing.
+
+Implementation lives in `src/weektag/` (`cli.py` typer commands → `ops.py` operations → `storage.py` JSONL I/O, plus `timeutil.py`, `ulid.py`, `report.py`, `export.py`). Tests in `tests/` pin the current time by monkeypatching `timeutil.now_local` (see `conftest.py` fixtures `data_dir` / `freeze_now`) so results don't depend on the machine timezone.
+
+## Design source of truth: docs/adr/
+
+`docs/adr/latest/` (Japanese) is the **single canonical source** for all design decisions. Read the relevant ADRs before implementing or reviewing anything, and resolve design questions against them.
+
+ADR rules: new decisions get a new sequential number in `latest/`; numbers are never reused or renumbered. To change a decision, move the old ADR to `archive/{NNNN}/` and write a new one under a new number. Each ADR has four sections: ステータス / コンテキスト / 決定 / 結果.
+
+## Architecture (decided in ADRs 0001–0010)
+
+**Recording model (0002):** start/stop interval records only. At most **one running task** — `start` while another runs auto-stops it. A running task is simply a record with no `stop` key; there is no separate state file. `add`/`edit`/`rm`/`cancel` provide after-the-fact correction.
+
+**Storage (0003):** weekly JSONL files are the **only source of truth** — no index, no DB, no hidden state. Location: `~/.local/share/weektag/events/` (XDG), overridable via `WEEKTAG_DATA_DIR`. Files are named by ISO 8601 week (`2026-W27.jsonl`), weeks start **Monday (unchangeable)**. A record belongs to the week of its **start time**; week-spanning records are not split. Writes go through temp file + atomic `os.replace`. Hand-editing by users/agents is officially supported. The running task is found by scanning recent week files for a record lacking `stop`.
+
+**Record schema (0004):** one JSON object per line:
+```json
+{"id":"01JZK3AB","start":"2026-07-06T09:00:00+09:00","stop":"2026-07-06T10:30:00+09:00","tags":["writing","client-a"],"note":"ブログ下書き"}
+```
+- Times are **local time + UTC offset** (ISO 8601) — never normalize to UTC. Week membership is judged by local date.
+- `id` is a self-implemented sortable **mini-ULID** (timestamp + randomness); commands accept prefix matches.
+- Tags are positional args (`tt start writing client-a`); a quoted `'#tag'` is accepted with `#` stripped. Note goes via `-m`.
+
+**v1 command set (0005):** `start`, `stop`, `status`, `resume`, `add`, `edit`, `rm`, `cancel`, `log`, `report`, `export`. Explicitly **out of scope for v1**: goals/targets, focus timer, timeline UI, plan.
+
+**report vs export (0006):** `report` is a per-tag summary table for the terminal (multi-tag events count their full duration under *each* tag, so the tag column can exceed the total row, which is computed from real event time). `export` emits row-level data, default **TSV**, columns `date/start/stop/hours/tags/note`. Hours are **decimal** (1.50), unrounded unless `--round`. All output is **plain text — no rich formatting anywhere**. No clipboard integration (pipe to clip.exe/pbcopy instead).
+
+**Daily preset (0007):** `tt export --daily [--date 7/6]` emits exactly 3 TSV columns (summary / AM hours / PM hours), **no header by default**, aggregated per (tag-set + note) per day, split mechanically at noon (`--noon` to change), pro-rated across the boundary. Summary = note if present, else space-joined tags.
+
+**Naming (0008):** PyPI/import/repo name `weektag`, console command `tt` via `[project.scripts] tt = "weektag.cli:main"`.
+
+## Stack & constraints (0009)
+
+- **typer** is the only runtime dependency (bundled rich/shellingham included, but rich decoration is unused).
+- Python **3.11+**.
+- Shell completion is a v1 requirement, including **dynamic tag completion** (candidates gathered from recent week files via typer autocompletion callbacks).
+- Current time: `datetime.now().astimezone()` (works on Windows without tzdata).
+- No config file in v1 — env var + flags only.
+
+## Development (0010)
+
+- **src layout** (`src/weektag/`), **hatchling** backend, everything in `pyproject.toml`.
+- Tooling: **uv** (env/lock), **ruff** (lint + format), **pytest + freezegun** (deterministic time-based tests). Dev deps separated from runtime deps.
+- This checkout lives under OneDrive, which breaks uv's default hardlinking — run uv with `UV_LINK_MODE=copy` (e.g. `UV_LINK_MODE=copy uv sync`).
+- Commands:
+  - `uv sync` — set up environment
+  - `uv run pytest` — run tests; single test: `uv run pytest tests/test_x.py::test_name`
+  - `uv run ruff check .` / `uv run ruff format .`
+  - `uv run tt ...` — run the CLI locally
+- CI: GitHub Actions matrix ubuntu/macos/windows × Python 3.11–3.13 on every push/PR.
+- Publishing: PyPI **Trusted Publishing** (OIDC) triggered by pushing a git tag. No API tokens.
+- License MIT. README in English with a `README.ja.md` alongside.
+
+## Testing focus
+
+Bugs are expected to concentrate in time handling — write freezegun-pinned tests for: ISO week boundaries, the W53 ISO-week-year mismatch (e.g. 2027-01-01 belongs to `2026-W53.jsonl`), noon splitting/pro-rating, timezone offsets, and midnight-spanning events. Windows behavior (paths, `os.replace` atomicity, console output) is verified in CI, not locally.

weektag-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takehiro M.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

weektag-0.0.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: weektag
+Version: 0.0.1
+Summary: Tag-based CLI time tracker with agent-readable weekly JSONL storage
+Project-URL: Repository, https://github.com/takeknock/weektag
+Author: takeknock
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,jsonl,tags,time-tracking
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# weektag
+
+Tag-based CLI time tracker with agent-readable weekly JSONL storage.
+
+[日本語版 README](README.ja.md)
+
+`weektag` records what you work on as start/stop intervals with flat tags, stores them
+as plain JSONL files split by ISO week, and turns them into weekly reports or
+TSV/CSV you can paste straight into Excel. The files are the whole database:
+`cat`, `grep`, `jq`, and coding agents (Claude Code etc.) can read them with no
+preprocessing — and hand-editing them is officially supported.
+
+```console
+$ tt start writing client-a -m "blog draft"
+started writing client-a "blog draft" at 09:00 [KZ3M2A7Q]
+
+$ tt status
+running: writing client-a "blog draft" (started 09:00, 1.50 h elapsed) [KZ3M2A7Q]
+
+$ tt stop
+stopped writing client-a "blog draft" (1.50 h)
+```
+
+## Install
+
+```console
+pipx install weektag    # or: uv tool install weektag
+```
+
+The installed command is `tt` (the package name `tt` was taken on PyPI).
+Requires Python 3.11+.
+
+## Commands
+
+```
+tt start <tags...> [-m NOTE] [--at 9:00]   # start (auto-stops a running task)
+tt stop [--at 10:30]                       # stop
+tt status                                  # running task + elapsed time
+tt resume                                  # restart previous task (same tags/note)
+tt add 9:00-10:30 <tags...> [-m NOTE]      # add a past interval
+tt edit <id-prefix> [--start] [--stop] [--tags] [-m]
+tt rm <id-prefix>                          # delete a record
+tt cancel                                  # discard the running task
+tt log [--week 2026-W27]                   # raw log with ids (entry point for edit)
+tt report [--week 2026-W27 | --last]       # per-tag weekly summary
+tt export [--format csv] [-o FILE] [--no-header]
+tt export --daily [--date 7/6] [--noon 13:00] [--round 0.25] [--header]
+```
+
+Only one task runs at a time: `tt start` while another task is running stops it
+first. Forgot to start or stop? `add` / `edit` / `rm` fix the record afterwards.
+
+Shell completion (bash / zsh / fish), including dynamic tag completion from your
+recent records:
+
+```console
+tt --install-completion
+```
+
+## Data format
+
+One JSON object per line, one file per ISO week (Monday start), in
+`~/.local/share/weektag/events/` (override with `WEEKTAG_DATA_DIR`;
+`XDG_DATA_HOME` is honored):
+
+```json
+{"id":"KZ3M2A7Q","start":"2026-07-06T09:00:00+09:00","stop":"2026-07-06T10:30:00+09:00","tags":["writing","client-a"],"note":"blog draft"}
+```
+
+- A running task is simply a record without a `stop` key.
+- Times are local time with UTC offset; week membership follows the local date
+  of `start`. Week-spanning records are not split.
+- The week files are the only source of truth — no hidden state, no index, no
+  database. Edit them by hand or with an agent whenever you like.
+
+### Note on ISO week years
+
+Files use ISO 8601 week numbering, which can differ from the calendar year at
+year boundaries: a record on 2027-01-01 lives in `2026-W53.jsonl`. Commands
+resolve this correctly; it only matters when you browse the files by hand.
+
+## Excel workflow
+
+`tt export` prints TSV rows (`date start stop hours tags note`) with decimal
+hours (`1.50`), so a paste into Excel splits into columns and `SUM` just works.
+
+`tt export --daily` is a preset for daily-report sheets: exactly three columns
+(summary / AM hours / PM hours), aggregated per (tag set + note), split at noon
+(`--noon` to change), no header by default so you can append to an existing
+table day after day. There is no clipboard integration — pipe instead:
+
+```console
+tt export --daily | clip        # Windows
+tt export --daily | pbcopy      # macOS
+tt export --daily | xclip -sel c
+```
+
+## Command name collision
+
+The `tt-time-tracker` package also installs a `tt` command. pipx / uv isolate
+the environments, so only the PATH entry can collide. If you use both, rename
+one with a shell alias, e.g. `alias wt=tt`.
+
+## Development
+
+```console
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+MIT license.

weektag-0.0.1/README.ja.md

@@ -0,0 +1,111 @@
+# weektag
+
+タグ式のCLIタイムトラッカー。記録はエージェント可読な週別JSONLに保存。
+
+[English README](README.md)
+
+`weektag` は作業を start/stop の区間としてフラットなタグ付きで記録し、ISO週ごとの
+プレーンな JSONL ファイルに保存します。週次レポートや、Excel にそのまま貼れる
+TSV/CSV に変換できます。ファイルがデータベースのすべてであり、`cat` / `grep` /
+`jq`、そして Claude Code などのコーディングエージェントが前処理なしで読めます。
+手編集も正式サポートです。
+
+```console
+$ tt start writing client-a -m "ブログ下書き"
+started writing client-a "ブログ下書き" at 09:00 [KZ3M2A7Q]
+
+$ tt status
+running: writing client-a "ブログ下書き" (started 09:00, 1.50 h elapsed) [KZ3M2A7Q]
+
+$ tt stop
+stopped writing client-a "ブログ下書き" (1.50 h)
+```
+
+## インストール
+
+```console
+pipx install weektag    # または: uv tool install weektag
+```
+
+インストールされるコマンドは `tt` です（PyPI の `tt` は取得済みのため配布名は
+`weektag`）。Python 3.11 以上が必要です。
+
+## コマンド
+
+```
+tt start <tags...> [-m メモ] [--at 9:00]   # 開始（実行中があれば自動stop）
+tt stop [--at 10:30]                       # 停止
+tt status                                  # 実行中タスクと経過時間
+tt resume                                  # 直前タスクを同タグ・同メモで再開
+tt add 9:00-10:30 <tags...> [-m メモ]      # 後追いの区間追加
+tt edit <id前方一致> [--start] [--stop] [--tags] [-m]
+tt rm <id前方一致>                         # 削除
+tt cancel                                  # 実行中を記録せず破棄
+tt log [--week 2026-W27]                   # id付き生ログ（editの入口）
+tt report [--week 2026-W27 | --last]       # タグ別の週次集計
+tt export [--format csv] [-o FILE] [--no-header]
+tt export --daily [--date 7/6] [--noon 13:00] [--round 0.25] [--header]
+```
+
+同時に実行できるタスクは常に1本だけです。実行中に `tt start` すると前のタスクを
+止めてから開始します。打ち忘れ・止め忘れは `add` / `edit` / `rm` で後から直せます。
+
+シェル補完（bash / zsh / fish）。直近の記録からのタグ動的補完つき：
+
+```console
+tt --install-completion
+```
+
+## データ形式
+
+1行=1 JSONオブジェクト、1ファイル=1 ISO週（月曜始まり）。保存先は
+`~/.local/share/weektag/events/`（`WEEKTAG_DATA_DIR` で変更可、
+`XDG_DATA_HOME` にも対応）：
+
+```json
+{"id":"KZ3M2A7Q","start":"2026-07-06T09:00:00+09:00","stop":"2026-07-06T10:30:00+09:00","tags":["writing","client-a"],"note":"ブログ下書き"}
+```
+
+- 実行中タスクは `stop` キーを持たないレコードです。
+- 時刻はローカル時刻＋UTCオフセット。週の帰属は `start` のローカル日付で決まり、
+  週を跨ぐレコードも分割しません。
+- 週ファイルが唯一の真実です。隠れた状態ファイル・インデックス・DBはありません。
+  手やエージェントでいつでも編集できます。
+
+### ISO週年についての注意
+
+ファイル名は ISO 8601 週番号なので、年末年始で暦年とズレることがあります。
+例：2027-01-01 のレコードは `2026-W53.jsonl` に入ります。コマンドは正しく
+解決するので、手でファイルを探すときだけ気にしてください。
+
+## Excel との連携
+
+`tt export` は十進時間（`1.50`）の TSV（`date start stop hours tags note`）を
+出力するので、Excel に貼ると列が自動で分かれ、SUM がそのまま効きます。
+
+`tt export --daily` は日報転記用プリセットです：3列だけ（概要 / 午前実績 /
+午後実績）、その日の「タグ集合＋メモ」ごとに集約、正午で機械分割（`--noon` で
+変更可）、既存の表に日々貼るためヘッダーは既定で出しません。予定列は出力しない
+ので、右端の予定列を上書きしません。クリップボード連携は内蔵せず、パイプで：
+
+```console
+tt export --daily | clip        # Windows
+tt export --daily | pbcopy      # macOS
+tt export --daily | xclip -sel c
+```
+
+## コマンド名の衝突
+
+`tt-time-tracker` パッケージも `tt` コマンドをインストールします。pipx / uv では
+環境自体は隔離され、PATH 上でのみ衝突します。両方使う場合はシェルエイリアスで
+どちらかを改名してください（例：`alias wt=tt`）。
+
+## 開発
+
+```console
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+MIT ライセンス。