task-recorder-cui 1.0.0__py3-none-any.whl

task_recorder_cui/__init__.py

@@ -0,0 +1,3 @@
+"""task-recorder-cui: 時間記録のためのCUIツール。"""
+
+__version__ = "1.0.0"

task_recorder_cui/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m task_recorder_cui` 用エントリ。"""
+
+from task_recorder_cui.cli import main
+
+raise SystemExit(main())

task_recorder_cui/cli.py

@@ -0,0 +1,162 @@
+"""argparse ベースの CLI エントリポイント。
+
+本モジュールはサブコマンドの受け口 (parser) と main ディスパッチャを持つ。
+記録系 (start/stop/now/add)、参照系 (today/week/month/range/all)、カテゴリ管理
+(cat ...) は commands/ 配下の実装に dispatch する。インタラクティブメニューは
+`menu.run()` に dispatch する。
+"""
+
+import argparse
+
+from task_recorder_cui import __version__
+from task_recorder_cui.commands import add as add_cmd
+from task_recorder_cui.commands import all as all_cmd
+from task_recorder_cui.commands import cat as cat_cmd
+from task_recorder_cui.commands import month as month_cmd
+from task_recorder_cui.commands import now as now_cmd
+from task_recorder_cui.commands import range as range_cmd
+from task_recorder_cui.commands import start as start_cmd
+from task_recorder_cui.commands import stop as stop_cmd
+from task_recorder_cui.commands import today as today_cmd
+from task_recorder_cui.commands import week as week_cmd
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """tsk の引数パーサを構築する。
+
+    Returns:
+        サブコマンドを含む設定済み ArgumentParser。
+
+    """
+    parser = argparse.ArgumentParser(
+        prog="tsk",
+        description="日々の時間の使い方を記録して、週平均・月平均で可視化するCUIツール",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"tsk {__version__}",
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    # --- 記録系 ---
+    p_start = sub.add_parser("start", help="新しいセッションを開始")
+    p_start.add_argument("category_key", help="カテゴリキー (例: game, study, dev)")
+    p_start.add_argument("description", nargs="?", default=None, help="活動内容 (任意)")
+
+    sub.add_parser("stop", help="記録中のセッションを終了")
+
+    p_add = sub.add_parser("add", help="事後に手動で追加")
+    p_add.add_argument("category_key", help="カテゴリキー")
+    p_add.add_argument("minutes", type=int, help="記録する分数")
+    p_add.add_argument("description", nargs="?", default=None, help="活動内容 (任意)")
+
+    sub.add_parser("now", help="記録中のセッションを表示")
+
+    # --- 参照系 ---
+    sub.add_parser("today", help="今日の記録一覧")
+    p_week = sub.add_parser("week", help="直近7日 (default) または今週 (--calendar)")
+    p_week.add_argument(
+        "--calendar",
+        action="store_true",
+        help="月曜〜今日の今週集計にする",
+    )
+    p_month = sub.add_parser("month", help="直近30日 (default) または今月 (--calendar)")
+    p_month.add_argument(
+        "--calendar",
+        action="store_true",
+        help="今月1日〜今日の集計にする",
+    )
+    p_range = sub.add_parser("range", help="任意期間の集計")
+    p_range.add_argument("--from", dest="from_date", required=True, help="開始日 YYYY-MM-DD")
+    p_range.add_argument(
+        "--to", dest="to_date", required=True, help="終了日 YYYY-MM-DD (inclusive)"
+    )
+    sub.add_parser("all", help="全累計")
+
+    # --- カテゴリ管理 ---
+    p_cat = sub.add_parser("cat", help="カテゴリ管理")
+    cat_sub = p_cat.add_subparsers(dest="cat_action", metavar="<action>", required=True)
+
+    p_cat_list = cat_sub.add_parser("list", help="カテゴリ一覧")
+    list_filter = p_cat_list.add_mutually_exclusive_group()
+    list_filter.add_argument(
+        "--active", action="store_true", help="archived でないカテゴリだけ表示"
+    )
+    list_filter.add_argument("--archived", action="store_true", help="archived のカテゴリだけ表示")
+
+    p_cat_add = cat_sub.add_parser(
+        "add", help="カテゴリを追加 (archived同名があれば復帰+表示名上書き)"
+    )
+    p_cat_add.add_argument("key", help="新しいカテゴリキー")
+    p_cat_add.add_argument("display_name", help="表示名")
+    p_cat_remove = cat_sub.add_parser("remove", help="カテゴリをアーカイブ")
+    p_cat_remove.add_argument("key", help="アーカイブするカテゴリキー")
+    p_cat_restore = cat_sub.add_parser("restore", help="アーカイブから復帰")
+    p_cat_restore.add_argument("key", help="復帰させるカテゴリキー")
+    p_cat_rename = cat_sub.add_parser("rename", help="表示名を変更")
+    p_cat_rename.add_argument("key", help="変更するカテゴリキー")
+    p_cat_rename.add_argument("new_display_name", help="新しい表示名")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI エントリポイント。
+
+    Args:
+        argv: 引数リスト。Noneの場合は sys.argv[1:] が使われる。
+
+    Returns:
+        終了コード (0: 成功)。
+
+    Raises:
+        SystemExit: --help / --version 表示時、または usage error 時に
+            argparse が送出する。正常終了は code=0、usage error は code=2。
+
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        from task_recorder_cui.menu import run as menu_run
+
+        return menu_run()
+
+    # --- 記録系 (Phase 3) ---
+    if args.command == "start":
+        return start_cmd.run(args.category_key, args.description)
+    if args.command == "stop":
+        return stop_cmd.run()
+    if args.command == "now":
+        return now_cmd.run()
+    if args.command == "add":
+        return add_cmd.run(args.category_key, args.minutes, args.description)
+
+    # --- 参照系 (Phase 4) ---
+    if args.command == "today":
+        return today_cmd.run()
+    if args.command == "week":
+        return week_cmd.run(calendar=args.calendar)
+    if args.command == "month":
+        return month_cmd.run(calendar=args.calendar)
+    if args.command == "range":
+        return range_cmd.run(args.from_date, args.to_date)
+    if args.command == "all":
+        return all_cmd.run()
+
+    # --- カテゴリ管理 (Phase 5) ---
+    if args.command == "cat":
+        if args.cat_action == "list":
+            return cat_cmd.list_categories(active_only=args.active, archived_only=args.archived)
+        if args.cat_action == "add":
+            return cat_cmd.add_category(args.key, args.display_name)
+        if args.cat_action == "remove":
+            return cat_cmd.remove_category(args.key)
+        if args.cat_action == "restore":
+            return cat_cmd.restore_category(args.key)
+        if args.cat_action == "rename":
+            return cat_cmd.rename_category(args.key, args.new_display_name)
+
+    return 0

task_recorder_cui/commands/_summary.py

@@ -0,0 +1,246 @@
+"""集計系コマンド (today/week/month/range/all) の共通ロジック。
+
+SQLite からレコードを取得し、ローカル日付でグルーピングして日別×カテゴリの
+集計を行う。表示は rich.Table を使って CJK 幅のズレを吸収する。
+
+仕様:
+- 日付境界はシステムのローカルタイムゾーンにおける 00:00〜翌00:00
+- 日またぎレコードは started_at の日に計上 (分割しない)
+- 記録中セッションは started_at が期間内のとき、現在時刻までの経過分を計上
+- display_name は常に現在の categories テーブルから引く (rename 即時反映)
+"""
+
+import sqlite3
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import UTC, date, datetime, time, timedelta
+
+from rich.box import SIMPLE
+from rich.markup import escape
+from rich.table import Table
+
+from task_recorder_cui.io import print_line, print_table
+from task_recorder_cui.repo import find_active_record, row_to_record
+from task_recorder_cui.utils.time import format_duration, now_utc, to_iso
+
+WEEKDAY_EN: list[str] = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+
+
+@dataclass(frozen=True)
+class DayTotal:
+    """1日分のカテゴリ別集計。
+
+    Attributes:
+        local_date: 対象のローカル日付。
+        per_category_minutes: カテゴリkey → 分数。
+        total_minutes: 全カテゴリ合計分。
+
+    """
+
+    local_date: date
+    per_category_minutes: dict[str, int]
+    total_minutes: int
+
+
+@dataclass(frozen=True)
+class PeriodSummary:
+    """期間全体の集計結果。
+
+    Attributes:
+        start_local: 集計期間の開始日 (inclusive)。
+        end_local: 集計期間の終了日 (inclusive)。
+        days: レコードがあった日の DayTotal リスト (昇順)。
+        per_category_minutes: カテゴリkey → 期間内分数合計。
+        total_minutes: 全カテゴリの期間内合計分。
+        display_names: カテゴリkey → display_name (現在の値)。
+        active_partial_minutes: 記録中セッションから計上された分数 (0 なら含まない)。
+
+    """
+
+    start_local: date
+    end_local: date
+    days: list[DayTotal]
+    per_category_minutes: dict[str, int]
+    total_minutes: int
+    display_names: dict[str, str]
+    active_partial_minutes: int
+
+
+def today_local() -> date:
+    """システムのローカルタイムゾーンにおける今日の日付を返す。"""
+    return datetime.now().astimezone().date()
+
+
+def _to_local_date(dt: datetime) -> date:
+    """tz付き datetime をローカル日付に変換する。"""
+    return dt.astimezone().date()
+
+
+def period_bounds_utc(start_local_date: date, end_local_date: date) -> tuple[datetime, datetime]:
+    """ローカル日付範囲を UTC の半開区間 [start_utc, end_next_utc) に変換。"""
+    start_utc = datetime.combine(start_local_date, time.min).astimezone().astimezone(UTC)
+    end_next_utc = (
+        datetime.combine(end_local_date + timedelta(days=1), time.min).astimezone().astimezone(UTC)
+    )
+    return start_utc, end_next_utc
+
+
+def aggregate_period(
+    conn: sqlite3.Connection,
+    start_local_date: date,
+    end_local_date: date,
+    *,
+    include_active: bool = True,
+) -> PeriodSummary:
+    """指定ローカル日付区間 [start, end] の集計を返す (両端inclusive)。
+
+    Args:
+        conn: DB接続。
+        start_local_date: 集計開始日 (local)。
+        end_local_date: 集計終了日 (local, inclusive)。
+        include_active: 記録中セッションを期間に含めるか。
+
+    Returns:
+        PeriodSummary。レコードが1件もなければ days=[]。
+
+    """
+    start_utc, end_next_utc = period_bounds_utc(start_local_date, end_local_date)
+
+    rows = conn.execute(
+        "SELECT * FROM records WHERE started_at >= ? AND started_at < ? ORDER BY started_at",
+        (to_iso(start_utc), to_iso(end_next_utc)),
+    ).fetchall()
+    records = [row_to_record(r) for r in rows]
+
+    if include_active:
+        active = find_active_record(conn)
+        if (
+            active is not None
+            and start_utc <= active.started_at < end_next_utc
+            and all(r.id != active.id for r in records)
+        ):
+            records.append(active)
+
+    now = now_utc()
+    day_buckets: dict[date, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+    per_category: dict[str, int] = defaultdict(int)
+    active_partial_minutes = 0
+
+    for rec in records:
+        local_d = _to_local_date(rec.started_at)
+        if rec.duration_minutes is not None:
+            minutes = rec.duration_minutes
+        else:
+            minutes = max(0, int((now - rec.started_at).total_seconds() / 60))
+            active_partial_minutes += minutes
+        day_buckets[local_d][rec.category_key] += minutes
+        per_category[rec.category_key] += minutes
+
+    days = [
+        DayTotal(
+            local_date=d,
+            per_category_minutes=dict(buckets),
+            total_minutes=sum(buckets.values()),
+        )
+        for d, buckets in sorted(day_buckets.items())
+    ]
+
+    category_keys = list(per_category.keys())
+    display_names: dict[str, str] = {}
+    if category_keys:
+        placeholders = ",".join("?" for _ in category_keys)
+        category_rows = conn.execute(
+            f"SELECT key, display_name FROM categories WHERE key IN ({placeholders})",
+            category_keys,
+        ).fetchall()
+        display_names = {row["key"]: row["display_name"] for row in category_rows}
+    for key in category_keys:
+        display_names.setdefault(key, key)
+
+    return PeriodSummary(
+        start_local=start_local_date,
+        end_local=end_local_date,
+        days=days,
+        per_category_minutes=dict(per_category),
+        total_minutes=sum(per_category.values()),
+        display_names=display_names,
+        active_partial_minutes=active_partial_minutes,
+    )
+
+
+def _sorted_category_keys(summary: PeriodSummary) -> list[str]:
+    """合計分数の降順でカテゴリキーを並べる (同点は key 昇順)。"""
+    return sorted(
+        summary.per_category_minutes.keys(),
+        key=lambda k: (-summary.per_category_minutes[k], k),
+    )
+
+
+def render_breakdown_table(summary: PeriodSummary, title: str) -> Table:
+    """日別×カテゴリの内訳テーブルを組み立てる。
+
+    Args:
+        summary: 集計結果。
+        title: テーブルタイトル。
+
+    Returns:
+        そのまま print_table() に渡せる Table。
+
+    """
+    keys = _sorted_category_keys(summary)
+    table = Table(title=title, box=SIMPLE, show_edge=True, pad_edge=False)
+    table.add_column("日付", justify="left", no_wrap=True)
+    for key in keys:
+        table.add_column(escape(summary.display_names.get(key, key)), justify="right")
+    table.add_column("合計", justify="right", style="bold")
+
+    for day in summary.days:
+        weekday = WEEKDAY_EN[day.local_date.weekday()]
+        date_cell = f"{day.local_date.strftime('%m-%d')} {weekday}"
+        row = [date_cell]
+        for key in keys:
+            minutes = day.per_category_minutes.get(key, 0)
+            row.append(format_duration(minutes) if minutes > 0 else "")
+        row.append(format_duration(day.total_minutes))
+        table.add_row(*row)
+
+    return table
+
+
+def render_category_totals(summary: PeriodSummary, *, with_daily_avg: bool = False) -> None:
+    """カテゴリ別合計 (降順) を表示する。
+
+    Args:
+        summary: 集計結果。
+        with_daily_avg: True のとき "/ 日平均 1h30m" を付記する (week/month/range用)。
+
+    """
+    total = summary.total_minutes
+    if not summary.per_category_minutes:
+        print_line("記録なし")
+        return
+
+    day_count = (summary.end_local - summary.start_local).days + 1
+    keys = _sorted_category_keys(summary)
+
+    grid = Table.grid(padding=(0, 1))
+    grid.add_column()  # label:
+    grid.add_column(justify="right")  # duration
+    grid.add_column()  # percentage
+    if with_daily_avg:
+        grid.add_column()  # daily avg
+
+    for key in keys:
+        minutes = summary.per_category_minutes[key]
+        name = summary.display_names.get(key, key)
+        pct = round(minutes * 100 / total) if total > 0 else 0
+        label = f"{escape(name)}:"
+        duration = format_duration(minutes)
+        percent = f"({pct}%)"
+        if with_daily_avg:
+            avg = minutes // day_count if day_count > 0 else 0
+            grid.add_row(label, duration, percent, f"/ 日平均 {format_duration(avg)}")
+        else:
+            grid.add_row(label, duration, percent)
+
+    print_table(grid)

task_recorder_cui/commands/add.py

@@ -0,0 +1,63 @@
+"""tsk add: 事後に手動で時間記録を追加する。"""
+
+from datetime import timedelta
+
+from rich.markup import escape
+
+from task_recorder_cui.db import open_db
+from task_recorder_cui.io import print_error, print_line
+from task_recorder_cui.repo import find_category, insert_record
+from task_recorder_cui.utils.time import format_duration, now_utc
+
+
+def run(category_key: str, minutes: int, description: str | None) -> int:
+    """started_at = 現在 - minutes, ended_at = 現在 として1レコードを挿入する。
+
+    Args:
+        category_key: 対象カテゴリのkey。
+        minutes: 記録する分数 (1以上の整数)。
+        description: 活動内容 (任意)。
+
+    Returns:
+        0: 追加成功 / 1: 未登録カテゴリ、または不正な minutes。
+
+    """
+    if minutes <= 0:
+        print_error(f"minutes は1以上である必要があります: {minutes}")
+        return 1
+
+    with open_db() as conn:
+        category = find_category(conn, category_key)
+        if category is None:
+            print_error(
+                f"カテゴリ '{category_key}' が存在しません。`tsk cat list` で一覧を確認してください"
+            )
+            return 1
+        if category.archived:
+            print_error(
+                f"カテゴリ '{category_key}' はアーカイブ済みです。 "
+                f"`tsk cat restore {category_key}` または "
+                f"`tsk cat add {category_key} <display_name>` で復帰させてください"
+            )
+            return 1
+        ended_at = now_utc()
+        started_at = ended_at - timedelta(minutes=minutes)
+        with conn:
+            insert_record(
+                conn,
+                category_key=category_key,
+                description=description,
+                started_at=started_at,
+                ended_at=ended_at,
+                duration_minutes=minutes,
+            )
+        display_name = category.display_name
+
+    started_hm = started_at.astimezone().strftime("%H:%M")
+    ended_hm = ended_at.astimezone().strftime("%H:%M")
+    detail = f" {escape(description)}" if description else ""
+    print_line(
+        f"追加: [{escape(display_name)}]{detail}"
+        f" ({started_hm}-{ended_hm}, {format_duration(minutes)})"
+    )
+    return 0

task_recorder_cui/commands/all.py

@@ -0,0 +1,37 @@
+"""tsk all: 全累計。"""
+
+from datetime import date
+
+from task_recorder_cui.commands._summary import (
+    aggregate_period,
+    render_category_totals,
+    today_local,
+)
+from task_recorder_cui.db import open_db
+from task_recorder_cui.io import print_line
+from task_recorder_cui.utils.time import format_duration, from_iso
+
+
+def run() -> int:
+    """最古の記録日から今日までの全累計を表示する (日別内訳は出さない)。
+
+    Returns:
+        常に 0。
+
+    """
+    today = today_local()
+
+    with open_db() as conn:
+        row = conn.execute("SELECT MIN(started_at) AS earliest FROM records").fetchone()
+        if row is None or row["earliest"] is None:
+            print_line("全累計")
+            print_line("記録なし")
+            return 0
+        start: date = from_iso(row["earliest"]).astimezone().date()
+        summary = aggregate_period(conn, start, today)
+
+    title = f"全累計 ({start.isoformat()} 以降)"
+    print_line(title)
+    print_line(f"合計: {format_duration(summary.total_minutes)}")
+    render_category_totals(summary, with_daily_avg=True)
+    return 0

task_recorder_cui/commands/cat.py

@@ -0,0 +1,172 @@
+"""tsk cat サブコマンド群 (list/add/remove/restore/rename)。
+
+各関数は cli.py から `args.cat_action` に応じて呼び出される。
+"""
+
+from rich.box import SIMPLE
+from rich.markup import escape
+from rich.table import Table
+
+from task_recorder_cui.db import open_db
+from task_recorder_cui.io import print_error, print_line, print_table
+from task_recorder_cui.repo import (
+    find_category,
+    insert_category,
+    list_all_categories,
+    update_category_archived,
+    update_category_display_name,
+)
+from task_recorder_cui.utils.validate import validate_category_key
+
+
+def list_categories(*, active_only: bool = False, archived_only: bool = False) -> int:
+    """カテゴリ一覧を表示する。
+
+    Args:
+        active_only: True なら archived=0 のみ表示。
+        archived_only: True なら archived=1 のみ表示。
+
+    Returns:
+        常に 0。
+
+    """
+    with open_db() as conn:
+        categories = list_all_categories(conn, active_only=active_only, archived_only=archived_only)
+
+    if not categories:
+        if archived_only:
+            print_line("archived カテゴリはありません")
+        elif active_only:
+            print_line("active カテゴリはありません")
+        else:
+            print_line("カテゴリがありません")
+        return 0
+
+    table = Table(title="カテゴリ", box=SIMPLE, show_edge=True, pad_edge=False)
+    table.add_column("key", style="bold")
+    table.add_column("表示名")
+    table.add_column("archived", justify="center")
+    for cat in categories:
+        table.add_row(escape(cat.key), escape(cat.display_name), "✓" if cat.archived else "")
+    print_table(table)
+    return 0
+
+
+def add_category(key: str, display_name: str) -> int:
+    """カテゴリを新規追加する。
+
+    同じ key が archived 状態で既に存在する場合は、archived=0 に戻し、
+    display_name を今回指定された値に更新する (実質 restore + rename)。
+    active 状態で存在する場合は重複エラー。
+
+    Args:
+        key: 新しいカテゴリキー (ASCII 英小文字+数字+_)。
+        display_name: 表示名。
+
+    Returns:
+        0: 追加または再有効化成功 / 1: 不正key、空 display_name、重複。
+
+    """
+    try:
+        validate_category_key(key)
+    except ValueError as exc:
+        print_error(str(exc))
+        return 1
+    if not display_name:
+        print_error("display_name は空にできません")
+        return 1
+
+    with open_db() as conn:
+        existing = find_category(conn, key)
+        if existing is not None:
+            if not existing.archived:
+                print_error(
+                    f"カテゴリ '{key}' は既に存在します (display_name='{existing.display_name}')"
+                )
+                return 1
+            with conn:
+                update_category_archived(conn, key, archived=False)
+                update_category_display_name(conn, key, display_name)
+            print_line(
+                f"再有効化: {key} → '{escape(display_name)}' "
+                "(以前 archived だったカテゴリを復帰、display_name を上書き)"
+            )
+            return 0
+
+        with conn:
+            insert_category(conn, key, display_name)
+    print_line(f"追加: {key} → '{escape(display_name)}'")
+    return 0
+
+
+def remove_category(key: str) -> int:
+    """カテゴリを archived にする (物理削除はしない)。
+
+    Args:
+        key: 対象カテゴリキー。
+
+    Returns:
+        0: 成功、または既に archived (no-op) / 1: 未存在。
+
+    """
+    with open_db() as conn:
+        existing = find_category(conn, key)
+        if existing is None:
+            print_error(f"カテゴリ '{key}' が存在しません")
+            return 1
+        if existing.archived:
+            print_line(f"'{key}' は既にアーカイブ済みです")
+            return 0
+        with conn:
+            update_category_archived(conn, key, archived=True)
+    print_line(f"アーカイブ: {key} ('{escape(existing.display_name)}')")
+    return 0
+
+
+def restore_category(key: str) -> int:
+    """archived カテゴリを active に戻す。display_name は維持する。
+
+    Args:
+        key: 対象カテゴリキー。
+
+    Returns:
+        0: 成功、または既に active (no-op) / 1: 未存在。
+
+    """
+    with open_db() as conn:
+        existing = find_category(conn, key)
+        if existing is None:
+            print_error(f"カテゴリ '{key}' が存在しません")
+            return 1
+        if not existing.archived:
+            print_line(f"'{key}' は既に有効です")
+            return 0
+        with conn:
+            update_category_archived(conn, key, archived=False)
+    print_line(f"復帰: {key} ('{escape(existing.display_name)}')")
+    return 0
+
+
+def rename_category(key: str, new_display_name: str) -> int:
+    """display_name のみを変更する。key は不変 (履歴保持のため)。
+
+    Args:
+        key: 対象カテゴリキー。
+        new_display_name: 新しい表示名。
+
+    Returns:
+        0: 成功 / 1: 未存在、空 display_name。
+
+    """
+    if not new_display_name:
+        print_error("新しい display_name は空にできません")
+        return 1
+    with open_db() as conn:
+        existing = find_category(conn, key)
+        if existing is None:
+            print_error(f"カテゴリ '{key}' が存在しません")
+            return 1
+        with conn:
+            update_category_display_name(conn, key, new_display_name)
+    print_line(f"変更: {key} '{escape(existing.display_name)}' → '{escape(new_display_name)}'")
+    return 0