weektag 0.0.1__py3-none-any.whl

weektag/cli.py

@@ -0,0 +1,262 @@
+"""tt — the weektag command line interface (ADR 0005, 0008, 0009).
+
+Output is plain text only: safe for pipes, agents, and Excel paste.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import sys
+from typing import Annotated
+
+import typer
+
+from . import export as export_mod
+from . import ops, report, storage, timeutil
+from .ops import WeektagError
+
+app = typer.Typer(
+    name="tt",
+    help="Tag-based time tracker with agent-readable weekly JSONL storage.",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+
+def complete_tag(incomplete: str) -> list[str]:
+    """Dynamic tag completion from recent week files (ADR 0009)."""
+    return [t for t in ops.collect_recent_tags() if t.startswith(incomplete)]
+
+
+def _fail(message: str) -> None:
+    typer.echo(f"error: {message}", err=True)
+    raise typer.Exit(1)
+
+
+def _hhmm(iso: str) -> str:
+    return dt.datetime.fromisoformat(iso).strftime("%H:%M")
+
+
+def _summary(rec: dict) -> str:
+    # ASCII separators only: Windows consoles may use narrow codepages (cp932)
+    tags = " ".join(rec.get("tags", []))
+    note = rec.get("note", "")
+    return f'{tags} "{note}"' if note else tags
+
+
+def _echo_stopped(rec: dict) -> None:
+    hours = timeutil.fmt_hours(storage.duration_hours(rec))
+    typer.echo(f"stopped {_summary(rec)} ({hours} h)")
+
+
+TagsArg = Annotated[
+    list[str], typer.Argument(help="tags (no '#' needed)", autocompletion=complete_tag)
+]
+NoteOpt = Annotated[str, typer.Option("-m", "--note", help="free-form note")]
+AtOpt = Annotated[str | None, typer.Option("--at", help="time like 9:00 (today)")]
+WeekOpt = Annotated[str | None, typer.Option("--week", help="ISO week like 2026-W27")]
+LastOpt = Annotated[bool, typer.Option("--last", help="previous week")]
+
+
+def _resolve_week(week: str | None, last: bool) -> str:
+    today = timeutil.now_local().date()
+    if week is not None:
+        return timeutil.parse_week(week)
+    if last:
+        return timeutil.last_week_key(today)
+    return timeutil.week_key(today)
+
+
+@app.command()
+def start(tags: TagsArg, note: NoteOpt = "", at: AtOpt = None) -> None:
+    """Start a task (auto-stops a running one)."""
+    try:
+        rec, stopped = ops.start(tags, note=note, at=at)
+    except (WeektagError, ValueError) as e:
+        _fail(str(e))
+    if stopped is not None:
+        _echo_stopped(stopped)
+    typer.echo(f"started {_summary(rec)} at {_hhmm(rec['start'])} [{rec['id']}]")
+
+
+@app.command()
+def stop(at: AtOpt = None) -> None:
+    """Stop the running task."""
+    try:
+        rec = ops.stop(at=at)
+    except (WeektagError, ValueError) as e:
+        _fail(str(e))
+    _echo_stopped(rec)
+
+
+@app.command()
+def status() -> None:
+    """Show the running task and elapsed time."""
+    running = ops.find_running()
+    if running is None:
+        typer.echo("no task is running")
+        return
+    _, rec = running
+    elapsed = (timeutil.now_local() - storage.start_dt(rec)).total_seconds() / 3600
+    typer.echo(
+        f"running: {_summary(rec)} "
+        f"(started {_hhmm(rec['start'])}, {timeutil.fmt_hours(elapsed)} h elapsed) [{rec['id']}]"
+    )
+
+
+@app.command()
+def resume() -> None:
+    """Restart the previous task with the same tags and note."""
+    try:
+        rec = ops.resume()
+    except WeektagError as e:
+        _fail(str(e))
+    typer.echo(f"resumed {_summary(rec)} at {_hhmm(rec['start'])} [{rec['id']}]")
+
+
+@app.command()
+def add(
+    range_: Annotated[str, typer.Argument(metavar="RANGE", help="interval like 9:00-10:30")],
+    tags: TagsArg,
+    note: NoteOpt = "",
+) -> None:
+    """Add a past interval (today)."""
+    try:
+        rec = ops.add(range_, tags, note=note)
+    except (WeektagError, ValueError) as e:
+        _fail(str(e))
+    hours = timeutil.fmt_hours(storage.duration_hours(rec))
+    typer.echo(
+        f"added {_summary(rec)} {_hhmm(rec['start'])}-{_hhmm(rec['stop'])} "
+        f"({hours} h) [{rec['id']}]"
+    )
+
+
+@app.command()
+def edit(
+    id_prefix: Annotated[str, typer.Argument(metavar="ID", help="record id (prefix ok)")],
+    start_: Annotated[
+        str | None, typer.Option("--start", help="new start (14:00 or 2026-07-06T14:00)")
+    ] = None,
+    stop_: Annotated[
+        str | None, typer.Option("--stop", help="new stop (14:00 or 2026-07-06T14:00)")
+    ] = None,
+    tags: Annotated[
+        str | None, typer.Option("--tags", help="replacement tags, space/comma separated")
+    ] = None,
+    note: Annotated[str | None, typer.Option("-m", "--note", help="replacement note")] = None,
+) -> None:
+    """Edit a record by id prefix."""
+    tag_list = tags.replace(",", " ").split() if tags is not None else None
+    try:
+        rec = ops.edit(id_prefix, start=start_, stop=stop_, tags=tag_list, note=note)
+    except WeektagError as e:
+        _fail(str(e))
+    typer.echo(f"edited [{rec['id']}] {_summary(rec)}")
+
+
+@app.command()
+def rm(
+    id_prefix: Annotated[str, typer.Argument(metavar="ID", help="record id (prefix ok)")],
+) -> None:
+    """Delete a record by id prefix."""
+    try:
+        rec = ops.remove(id_prefix)
+    except WeektagError as e:
+        _fail(str(e))
+    typer.echo(f"removed [{rec['id']}] {_summary(rec)}")
+
+
+@app.command()
+def cancel() -> None:
+    """Discard the running task without recording it."""
+    try:
+        rec = ops.cancel()
+    except WeektagError as e:
+        _fail(str(e))
+    typer.echo(f"cancelled {_summary(rec)} (started {_hhmm(rec['start'])})")
+
+
+@app.command()
+def log(week: WeekOpt = None, last: LastOpt = False) -> None:
+    """Raw log with ids (the entry point for edit)."""
+    try:
+        key = _resolve_week(week, last)
+    except ValueError as e:
+        _fail(str(e))
+    for rec in ops.log_records(key):
+        start_ = storage.start_dt(rec)
+        stop_ = storage.stop_dt(rec)
+        if stop_ is None:
+            span, hours = f"{start_:%H:%M}-...", ""
+        else:
+            span = f"{start_:%H:%M}-{stop_:%H:%M}"
+            hours = timeutil.fmt_hours(storage.duration_hours(rec))
+        typer.echo(
+            f"{rec['id']}  {start_.date().isoformat()}  {span:>12}  {hours:>6}  {_summary(rec)}"
+        )
+
+
+@app.command("report")
+def report_cmd(week: WeekOpt = None, last: LastOpt = False) -> None:
+    """Per-tag summary for a week (default: this week)."""
+    try:
+        key = _resolve_week(week, last)
+    except ValueError as e:
+        _fail(str(e))
+    typer.echo(report.render(key), nl=False)
+
+
+@app.command("export")
+def export_cmd(
+    week: WeekOpt = None,
+    last: LastOpt = False,
+    fmt: Annotated[str, typer.Option("--format", help="tsv or csv")] = "tsv",
+    output: Annotated[str | None, typer.Option("-o", "--output", help="write to file")] = None,
+    header: Annotated[
+        bool | None,
+        typer.Option("--header/--no-header", help="default: on for week export, off for --daily"),
+    ] = None,
+    daily: Annotated[bool, typer.Option("--daily", help="3-column daily report preset")] = False,
+    date: Annotated[str | None, typer.Option("--date", help="daily target like 7/6")] = None,
+    noon: Annotated[str, typer.Option("--noon", help="AM/PM boundary")] = "12:00",
+    round_: Annotated[
+        float | None, typer.Option("--round", help="round hours to this increment, e.g. 0.25")
+    ] = None,
+) -> None:
+    """Row-level TSV/CSV export, or the daily preset with --daily (ADR 0006, 0007)."""
+    if fmt not in ("tsv", "csv"):
+        _fail(f"unknown format {fmt!r} (expected tsv or csv)")
+    today = timeutil.now_local().date()
+    try:
+        if daily:
+            target = timeutil.parse_date(date, today) if date else today
+            rows = export_mod.daily_rows(
+                target, noon=timeutil.parse_time(noon), round_increment=round_
+            )
+            header_row = export_mod.DAILY_HEADER if header else None
+        else:
+            key = _resolve_week(week, last)
+            rows = export_mod.week_rows(key, round_increment=round_)
+            header_row = export_mod.WEEK_HEADER if header is None or header else None
+    except ValueError as e:
+        _fail(str(e))
+    content = export_mod.render(rows, header=header_row, fmt=fmt)
+    if output:
+        with open(output, "w", encoding="utf-8", newline="\n") as f:
+            f.write(content)
+        typer.echo(f"wrote {len(rows)} rows to {output}")
+    else:
+        typer.echo(content, nl=False)
+
+
+def main() -> None:
+    # never crash on notes the console codepage can't render
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="replace")
+    app()
+
+
+if __name__ == "__main__":
+    main()

weektag/export.py

@@ -0,0 +1,95 @@
+"""tt export — row-level TSV/CSV output and the daily preset (ADR 0006, 0007)."""
+
+from __future__ import annotations
+
+import csv
+import datetime as dt
+import io
+
+from . import storage, timeutil
+
+WEEK_HEADER = ["date", "start", "stop", "hours", "tags", "note"]
+DAILY_HEADER = ["summary", "am", "pm"]
+
+
+def _fmt(hours: float, round_increment: float | None) -> str:
+    return timeutil.fmt_hours(timeutil.round_to(hours, round_increment))
+
+
+def week_rows(week: str, round_increment: float | None = None) -> list[list[str]]:
+    rows = []
+    records = sorted(storage.read_week(week), key=lambda r: (r["start"], r["id"]))
+    for rec in records:
+        if storage.is_running(rec):
+            continue
+        start = storage.start_dt(rec)
+        stop = storage.stop_dt(rec)
+        rows.append(
+            [
+                start.date().isoformat(),
+                start.strftime("%H:%M"),
+                stop.strftime("%H:%M"),
+                _fmt(storage.duration_hours(rec), round_increment),
+                " ".join(rec.get("tags", [])),
+                rec.get("note", ""),
+            ]
+        )
+    return rows
+
+
+def daily_rows(
+    date: dt.date,
+    noon: dt.time = dt.time(12, 0),
+    round_increment: float | None = None,
+) -> list[list[str]]:
+    """3-column daily preset: summary / AM / PM (ADR 0007).
+
+    Rows aggregate by (tag set + note); events are clipped to the target
+    date and split mechanically at the noon boundary.
+    """
+    day_start = timeutil.local_dt(date, dt.time(0, 0))
+    day_end = timeutil.local_dt(date + dt.timedelta(days=1), dt.time(0, 0))
+    noon_dt = timeutil.local_dt(date, noon)
+
+    def overlap(a0: dt.datetime, a1: dt.datetime, b0: dt.datetime, b1: dt.datetime) -> float:
+        lo, hi = max(a0, b0), min(a1, b1)
+        return max((hi - lo).total_seconds(), 0) / 3600
+
+    # a day-spanning event may live in the previous week's file (ADR 0003)
+    weeks = {timeutil.week_key(date), timeutil.week_key(date - dt.timedelta(days=7))}
+    groups: dict[tuple, dict] = {}
+    for week in sorted(weeks):
+        for rec in storage.read_week(week):
+            if storage.is_running(rec):
+                continue
+            start, stop = storage.start_dt(rec), storage.stop_dt(rec)
+            if stop <= day_start or start >= day_end:
+                continue
+            key = (tuple(sorted(rec.get("tags", []))), rec.get("note", ""))
+            group = groups.setdefault(
+                key, {"am": 0.0, "pm": 0.0, "first": start, "tags": rec.get("tags", [])}
+            )
+            group["am"] += overlap(start, stop, day_start, noon_dt)
+            group["pm"] += overlap(start, stop, noon_dt, day_end)
+            if start < group["first"]:
+                group["first"] = start
+                group["tags"] = rec.get("tags", [])
+
+    rows = []
+    for (_, note), group in sorted(groups.items(), key=lambda kv: kv[1]["first"]):
+        summary = note or " ".join(group["tags"])
+        cells = []
+        for hours in (group["am"], group["pm"]):
+            rounded = timeutil.round_to(hours, round_increment)
+            cells.append(timeutil.fmt_hours(rounded) if rounded > 0 else "")
+        rows.append([summary, *cells])
+    return rows
+
+
+def render(rows: list[list[str]], header: list[str] | None = None, fmt: str = "tsv") -> str:
+    all_rows = ([header] if header else []) + rows
+    if fmt == "csv":
+        buf = io.StringIO()
+        csv.writer(buf, lineterminator="\n").writerows(all_rows)
+        return buf.getvalue()
+    return "".join("\t".join(cell.replace("\t", " ") for cell in row) + "\n" for row in all_rows)

weektag/ops.py

@@ -0,0 +1,203 @@
+"""Recording operations (ADR 0002, 0005).
+
+At most one running task at a time; a running task is a record without a
+`stop` key. Everything is read-modify-write against the weekly JSONL files.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+
+from . import storage, timeutil
+from .ulid import mini_ulid
+
+# ADR 0003: the running task is found by scanning recent week files.
+RECENT_SCAN_WEEKS = 4
+
+
+class WeektagError(Exception):
+    """User-facing error; the CLI prints the message and exits non-zero."""
+
+
+def _iso(d: dt.datetime) -> str:
+    return d.isoformat(timespec="seconds")
+
+
+def clean_tags(tags: list[str]) -> list[str]:
+    """Strip a quoted leading '#' (ADR 0004) and drop empties."""
+    cleaned = [t.lstrip("#").strip() for t in tags]
+    return [t for t in cleaned if t]
+
+
+def find_running() -> tuple[str, dict] | None:
+    today = timeutil.now_local().date()
+    candidates = []
+    for key in timeutil.recent_week_keys(today, RECENT_SCAN_WEEKS):
+        for rec in storage.read_week(key):
+            if storage.is_running(rec):
+                candidates.append((key, rec))
+    if not candidates:
+        return None
+    return max(candidates, key=lambda kr: kr[1]["start"])
+
+
+def _resolve_at(at: str | None) -> dt.datetime:
+    now = timeutil.now_local()
+    if at is None:
+        return now
+    return timeutil.at_time(now.date(), at)
+
+
+def _complete(key: str, rec: dict, stop: dt.datetime) -> dict:
+    start = storage.start_dt(rec)
+    if stop <= start:
+        raise WeektagError(
+            f"stop time {_iso(stop)} is not after start {_iso(start)} (record {rec['id']})"
+        )
+    records = storage.read_week(key)
+    for r in records:
+        if r["id"] == rec["id"]:
+            r["stop"] = _iso(stop)
+            rec = r
+            break
+    storage.write_week(key, records)
+    return rec
+
+
+def start(tags: list[str], note: str = "", at: str | None = None) -> tuple[dict, dict | None]:
+    tags = clean_tags(tags)
+    if not tags:
+        raise WeektagError("at least one tag is required")
+    start_time = _resolve_at(at)
+    stopped = None
+    running = find_running()
+    if running is not None:
+        stopped = _complete(running[0], running[1], start_time)
+    rec = {"id": mini_ulid(start_time), "start": _iso(start_time), "tags": tags, "note": note}
+    storage.append_record(rec)
+    return rec, stopped
+
+
+def stop(at: str | None = None) -> dict:
+    running = find_running()
+    if running is None:
+        raise WeektagError("no task is running")
+    return _complete(running[0], running[1], _resolve_at(at))
+
+
+def cancel() -> dict:
+    running = find_running()
+    if running is None:
+        raise WeektagError("no task is running")
+    key, rec = running
+    storage.write_week(key, [r for r in storage.read_week(key) if r["id"] != rec["id"]])
+    return rec
+
+
+def resume() -> dict:
+    if find_running() is not None:
+        raise WeektagError("a task is already running (stop it first)")
+    today = timeutil.now_local().date()
+    completed = []
+    for key in timeutil.recent_week_keys(today, RECENT_SCAN_WEEKS):
+        completed.extend(r for r in storage.read_week(key) if not storage.is_running(r))
+    if not completed:
+        raise WeektagError("no previous task to resume")
+    last = max(completed, key=lambda r: r["stop"])
+    rec, _ = start(list(last["tags"]), note=last.get("note", ""))
+    return rec
+
+
+def add(range_str: str, tags: list[str], note: str = "") -> dict:
+    tags = clean_tags(tags)
+    if not tags:
+        raise WeektagError("at least one tag is required")
+    today = timeutil.now_local().date()
+    try:
+        start_time, stop_time = timeutil.parse_range(range_str, today)
+    except ValueError as e:
+        raise WeektagError(str(e)) from None
+    rec = {
+        "id": mini_ulid(start_time),
+        "start": _iso(start_time),
+        "stop": _iso(stop_time),
+        "tags": tags,
+        "note": note,
+    }
+    storage.append_record(rec)
+    return rec
+
+
+def find_by_prefix(prefix: str) -> tuple[str, dict]:
+    prefix = prefix.strip().upper()
+    if not prefix:
+        raise WeektagError("empty id")
+    matches = [
+        (key, rec)
+        for key in storage.all_week_keys()
+        for rec in storage.read_week(key)
+        if rec["id"].upper().startswith(prefix)
+    ]
+    if not matches:
+        raise WeektagError(f"no record matching id {prefix!r}")
+    if len(matches) > 1:
+        ids = ", ".join(rec["id"] for _, rec in matches)
+        raise WeektagError(f"id {prefix!r} is ambiguous: {ids}")
+    return matches[0]
+
+
+def edit(
+    prefix: str,
+    start: str | None = None,
+    stop: str | None = None,
+    tags: list[str] | None = None,
+    note: str | None = None,
+) -> dict:
+    key, rec = find_by_prefix(prefix)
+    old_start = storage.start_dt(rec)
+    try:
+        if start is not None:
+            rec["start"] = _iso(timeutil.parse_datetime_arg(start, old_start.date()))
+        if stop is not None:
+            fallback = storage.stop_dt(rec) or storage.start_dt(rec)
+            rec["stop"] = _iso(timeutil.parse_datetime_arg(stop, fallback.date()))
+    except ValueError as e:
+        raise WeektagError(str(e)) from None
+    if tags is not None:
+        cleaned = clean_tags(tags)
+        if not cleaned:
+            raise WeektagError("at least one tag is required")
+        rec["tags"] = cleaned
+    if note is not None:
+        rec["note"] = note
+    new_stop = storage.stop_dt(rec)
+    if new_stop is not None and new_stop <= storage.start_dt(rec):
+        raise WeektagError("stop time must be after start time")
+    new_key = storage.record_week_key(rec)
+    remaining = [r for r in storage.read_week(key) if r["id"] != rec["id"]]
+    if new_key == key:
+        storage.write_week(key, remaining + [rec])
+    else:
+        storage.write_week(key, remaining)
+        storage.append_record(rec)
+    return rec
+
+
+def remove(prefix: str) -> dict:
+    key, rec = find_by_prefix(prefix)
+    storage.write_week(key, [r for r in storage.read_week(key) if r["id"] != rec["id"]])
+    return rec
+
+
+def log_records(week: str) -> list[dict]:
+    return sorted(storage.read_week(week), key=lambda r: (r["start"], r["id"]))
+
+
+def collect_recent_tags() -> list[str]:
+    """Tag candidates for shell completion (ADR 0009)."""
+    today = timeutil.now_local().date()
+    tags: set[str] = set()
+    for key in timeutil.recent_week_keys(today, RECENT_SCAN_WEEKS):
+        for rec in storage.read_week(key):
+            tags.update(rec.get("tags", []))
+    return sorted(tags)

weektag/report.py

@@ -0,0 +1,46 @@
+"""tt report — per-tag summary table for the terminal (ADR 0006).
+
+Plain text only. A multi-tag event counts its full duration under each of
+its tags, so the tag column may sum to more than the total row, which is
+computed from real event time.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from collections import defaultdict
+
+from . import storage, timeutil
+
+
+def _completed(week: str) -> list[dict]:
+    return [r for r in storage.read_week(week) if not storage.is_running(r)]
+
+
+def tag_totals(week: str) -> list[tuple[str, float]]:
+    totals: dict[str, float] = defaultdict(float)
+    for rec in _completed(week):
+        hours = storage.duration_hours(rec)
+        for tag in rec.get("tags", []):
+            totals[tag] += hours
+    return sorted(totals.items(), key=lambda kv: (-kv[1], kv[0]))
+
+
+def total_hours(week: str) -> float:
+    return sum(storage.duration_hours(r) for r in _completed(week))
+
+
+def render(week: str) -> str:
+    totals = tag_totals(week)
+    monday = timeutil.week_monday(week)
+    sunday = monday + dt.timedelta(days=6)
+    title = f"{week} ({monday.isoformat()} - {sunday.isoformat()})"
+    if not totals:
+        return f"{title}\nno records\n"
+    width = max(len(tag) for tag, _ in totals + [("total", 0.0)])
+    lines = [title]
+    for tag, hours in totals:
+        lines.append(f"{tag:<{width}}  {timeutil.fmt_hours(hours):>7}")
+    lines.append("-" * (width + 9))
+    lines.append(f"{'total':<{width}}  {timeutil.fmt_hours(total_hours(week)):>7}")
+    return "\n".join(lines) + "\n"

weektag/storage.py

@@ -0,0 +1,116 @@
+"""Weekly JSONL storage — the only source of truth (ADR 0003).
+
+No index, no DB, no hidden state. Writes are temp-file + atomic os.replace.
+Files are hand-editable by users and agents.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime as dt
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+
+from . import timeutil
+
+_WEEK_FILE_RE = re.compile(r"^(\d{4}-W\d{2})\.jsonl$")
+
+# JSON keys in canonical order (ADR 0004 schema)
+_KEY_ORDER = ["id", "start", "stop", "tags", "note"]
+
+
+def data_dir() -> Path:
+    env = os.environ.get("WEEKTAG_DATA_DIR")
+    if env:
+        return Path(env)
+    xdg = os.environ.get("XDG_DATA_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".local" / "share"
+    return base / "weektag" / "events"
+
+
+def week_path(key: str) -> Path:
+    return data_dir() / f"{key}.jsonl"
+
+
+def read_week(key: str) -> list[dict]:
+    path = week_path(key)
+    if not path.exists():
+        return []
+    records = []
+    with path.open(encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                records.append(json.loads(line))
+    return records
+
+
+def _dump(record: dict) -> str:
+    ordered = {k: record[k] for k in _KEY_ORDER if k in record}
+    ordered.update({k: v for k, v in record.items() if k not in _KEY_ORDER})
+    return json.dumps(ordered, ensure_ascii=False, separators=(",", ":"))
+
+
+def write_week(key: str, records: list[dict]) -> None:
+    path = week_path(key)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    records = sorted(records, key=lambda r: (r["start"], r["id"]))
+    content = "".join(_dump(r) + "\n" for r in records)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
+            f.write(content)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+def record_week_key(record: dict) -> str:
+    """A record belongs to the week of its start's local date (ADR 0003)."""
+    return timeutil.week_key(start_dt(record))
+
+
+def append_record(record: dict) -> str:
+    key = record_week_key(record)
+    records = read_week(key)
+    records.append(record)
+    write_week(key, records)
+    return key
+
+
+def all_week_keys() -> list[str]:
+    d = data_dir()
+    if not d.exists():
+        return []
+    keys = []
+    for entry in d.iterdir():
+        m = _WEEK_FILE_RE.match(entry.name)
+        if m:
+            keys.append(m.group(1))
+    return sorted(keys)
+
+
+def start_dt(record: dict) -> dt.datetime:
+    return dt.datetime.fromisoformat(record["start"])
+
+
+def stop_dt(record: dict) -> dt.datetime | None:
+    if "stop" not in record:
+        return None
+    return dt.datetime.fromisoformat(record["stop"])
+
+
+def is_running(record: dict) -> bool:
+    return "stop" not in record
+
+
+def duration_hours(record: dict) -> float:
+    stop = stop_dt(record)
+    if stop is None:
+        raise ValueError(f"record {record['id']} is still running")
+    return (stop - start_dt(record)).total_seconds() / 3600

weektag/timeutil.py

@@ -0,0 +1,117 @@
+"""ISO-week and local-time helpers (ADR 0003, 0004).
+
+All times are local + UTC offset; week membership is judged on the local
+date. Weeks are ISO 8601, Monday-start (fixed, see ADR 0003).
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+
+_WEEK_RE = re.compile(r"^(\d{4})-[Ww](\d{1,2})$")
+_TIME_RE = re.compile(r"^(\d{1,2}):(\d{2})$")
+_MD_RE = re.compile(r"^(\d{1,2})/(\d{1,2})$")
+
+
+def now_local() -> dt.datetime:
+    """Current local time with UTC offset, no tzdata needed (ADR 0009)."""
+    return dt.datetime.now().astimezone()
+
+
+def week_key(d: dt.date | dt.datetime) -> str:
+    if isinstance(d, dt.datetime):
+        d = d.date()
+    year, week, _ = d.isocalendar()
+    return f"{year}-W{week:02d}"
+
+
+def parse_week(s: str) -> str:
+    m = _WEEK_RE.match(s.strip())
+    if not m:
+        raise ValueError(f"invalid week (expected like 2026-W27): {s!r}")
+    year, week = int(m.group(1)), int(m.group(2))
+    if not 1 <= week <= 53:
+        raise ValueError(f"invalid week number: {s!r}")
+    return f"{year}-W{week:02d}"
+
+
+def week_monday(key: str) -> dt.date:
+    year, week = parse_week(key).split("-W")
+    return dt.date.fromisocalendar(int(year), int(week), 1)
+
+
+def last_week_key(today: dt.date) -> str:
+    return week_key(today - dt.timedelta(days=7))
+
+
+def recent_week_keys(today: dt.date, n: int) -> list[str]:
+    return [week_key(today - dt.timedelta(weeks=i)) for i in range(n)]
+
+
+def parse_time(s: str) -> dt.time:
+    m = _TIME_RE.match(s.strip())
+    if not m:
+        raise ValueError(f"invalid time (expected like 9:00): {s!r}")
+    hour, minute = int(m.group(1)), int(m.group(2))
+    if hour > 23 or minute > 59:
+        raise ValueError(f"invalid time: {s!r}")
+    return dt.time(hour, minute)
+
+
+def local_dt(date: dt.date, time: dt.time) -> dt.datetime:
+    """Combine into an aware datetime carrying the local offset for that date."""
+    return dt.datetime.combine(date, time).astimezone()
+
+
+def at_time(date: dt.date, s: str) -> dt.datetime:
+    return local_dt(date, parse_time(s))
+
+
+def parse_range(s: str, date: dt.date) -> tuple[dt.datetime, dt.datetime]:
+    parts = s.split("-")
+    if len(parts) != 2:
+        raise ValueError(f"invalid range (expected like 9:00-10:30): {s!r}")
+    start = at_time(date, parts[0])
+    stop = at_time(date, parts[1])
+    if stop <= start:  # overnight range rolls the stop to the next day
+        stop = local_dt(date + dt.timedelta(days=1), parse_time(parts[1]))
+    return start, stop
+
+
+def parse_date(s: str, today: dt.date) -> dt.date:
+    s = s.strip()
+    m = _MD_RE.match(s)
+    if m:
+        return dt.date(today.year, int(m.group(1)), int(m.group(2)))
+    try:
+        return dt.date.fromisoformat(s)
+    except ValueError:
+        raise ValueError(f"invalid date (expected like 7/6 or 2026-07-06): {s!r}") from None
+
+
+def parse_datetime_arg(s: str, fallback_date: dt.date) -> dt.datetime:
+    """For edit: accept a bare time (uses the record's date) or a full ISO datetime."""
+    s = s.strip()
+    if _TIME_RE.match(s):
+        return at_time(fallback_date, s)
+    try:
+        parsed = dt.datetime.fromisoformat(s)
+    except ValueError:
+        raise ValueError(
+            f"invalid datetime (expected like 14:00 or 2026-07-06T14:00): {s!r}"
+        ) from None
+    if parsed.tzinfo is None:
+        parsed = parsed.astimezone()
+    return parsed
+
+
+def fmt_hours(hours: float) -> str:
+    """Decimal hours, two places, no other rounding (ADR 0006)."""
+    return f"{hours:.2f}"
+
+
+def round_to(hours: float, increment: float | None) -> float:
+    if not increment:
+        return hours
+    return round(hours / increment) * increment

weektag/ulid.py

@@ -0,0 +1,33 @@
+"""Mini-ULID: 8-char time-sortable id (ADR 0004).
+
+Layout: 6 Crockford-base32 chars of seconds since 2020-01-01 UTC (sortable
+until 2054), followed by 2 random chars. Second-level precision is enough
+for a single-user CLI; prefix matching is the primary lookup.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import secrets
+
+CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_EPOCH = dt.datetime(2020, 1, 1, tzinfo=dt.UTC)
+_TS_CHARS = 6
+_RAND_CHARS = 2
+
+
+def _encode(value: int, width: int) -> str:
+    chars = []
+    for _ in range(width):
+        chars.append(CROCKFORD[value & 0x1F])
+        value >>= 5
+    return "".join(reversed(chars))
+
+
+def mini_ulid(now: dt.datetime | None = None) -> str:
+    if now is None:
+        now = dt.datetime.now().astimezone()
+    seconds = int((now - _EPOCH).total_seconds())
+    rand = secrets.randbelow(32**_RAND_CHARS)
+    return _encode(seconds, _TS_CHARS) + _encode(rand, _RAND_CHARS)

weektag-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+weektag/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+weektag/cli.py,sha256=HxrRC8B-TvUtrqaufJO55d_9p22y8gfbfUzk8k4WWOA,8577
+weektag/export.py,sha256=lM-qHJqGM0-s0MNVCm3zTAFN4gS-GyEtqM4eJb-hGOA,3595
+weektag/ops.py,sha256=pYMMHynwtN0krPCWyT8qeFODnVT14t-Zc3629S966-I,6491
+weektag/report.py,sha256=OmS20eVAmSywyoGAJsUsqBLi5JWr-smpU5cdZTrRsQA,1543
+weektag/storage.py,sha256=RvEHEu8L5ZrjkKNchsYleZHFPbHNzF_-Q3F6NRRmVN8,3132
+weektag/timeutil.py,sha256=Nl9cdvoYgHfEsz5--e9tc0-OrmXI2jntqyDHiPPZiYw,3643
+weektag/ulid.py,sha256=67SgE7vhfYKRtCqyNfN1MjaK_oqBFwxhUTb90pC-iX0,942
+weektag-0.0.1.dist-info/METADATA,sha256=DffROOygj7yG3upa7__13gyysz0BcRwdBHzOpFxdI1w,4597
+weektag-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+weektag-0.0.1.dist-info/entry_points.txt,sha256=sYFaBM6iAFTeajOX6qFG5EvW4SeFe9wtJO5acY9EEYs,40
+weektag-0.0.1.dist-info/licenses/LICENSE,sha256=0nZQ5Ko8OQuVIhGmVT8PODxVlHmHLsDZpMjbTxu96Rc,1089
+weektag-0.0.1.dist-info/RECORD,,

weektag-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

weektag-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tt = weektag.cli:main

weektag-0.0.1.dist-info/licenses/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.