task-ledger 1.3.0 → 1.3.1

package/scripts/ledgerkit/actions/registry.py

@@ -0,0 +1,82 @@
+"""动作名册：命令写法 → `ActionSpec`。只有 `shell/cli.py` 与 `shell/runner.py` 会 import 它。
+
+**渲染函数只存名字**，不 import `shell/render.py` —— 否则 actions → shell 的依赖就反了；
+由 runner 用 `getattr(render, spec.render)` 取到函数。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from ..errors import Fail
+from . import (
+    bootstrap,
+    claim,
+    close_task,
+    list_tasks,
+    log_progress,
+    new_task,
+    query_history,
+    set_task,
+    show_task,
+    validate,
+)
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    func: Callable  # (repo, me, **params) -> Result | 视图对象
+    render: str  # 渲染函数**名**；runner 用 getattr 取
+    readonly: bool = False
+    lock_action: str = ""  # 交给 lock_scope 的动作名；默认同命令名
+    params: tuple[str, ...] = field(default=())  # 从参数里挑哪些键传给 func
+
+
+ACTIONS: dict[str, ActionSpec] = {
+    "new": ActionSpec(
+        new_task.new_task,
+        "result",
+        params=("title", "tid", "created", "category", "tags", "mine"),
+    ),
+    "claim": ActionSpec(claim.claim, "result", params=("tid",)),
+    "set": ActionSpec(
+        set_task.set_task,
+        "result",
+        params=("tid", "owner"),
+        lock_action="set",
+    ),
+    "log": ActionSpec(log_progress.log_progress, "result", params=("tid", "note")),
+    "close": ActionSpec(
+        close_task.close_task,
+        "result",
+        params=("tid", "summary", "finished", "category", "tags"),
+    ),
+    "list": ActionSpec(
+        list_tasks.list_tasks, "list_view", readonly=True, params=("q",)
+    ),
+    "show": ActionSpec(
+        show_task.show_task, "show_view", readonly=True, params=("tid",)
+    ),
+    "history": ActionSpec(
+        query_history.query_history, "history_view", readonly=True, params=("q",)
+    ),
+    "validate": ActionSpec(
+        validate.validate, "validate_view", readonly=True, params=("deep",)
+    ),
+}
+
+READONLY = tuple(name for name, spec in ACTIONS.items() if spec.readonly)
+
+
+def spec_of(command: str) -> ActionSpec:
+    """按命令写法取名册项；不在名册里就是用法错（业务错，退 1 人话）。"""
+    spec = ACTIONS.get(command)
+    if spec is None:
+        raise Fail(f"未知命令：{command}")
+    return spec
+
+
+def bootstrap_func():
+    """自举不是名册里的命令（runner 单独调），这里只给它的入口，避免 shell 直接 import 动作。"""
+    return bootstrap.bootstrap

package/scripts/ledgerkit/actions/release.py

@@ -0,0 +1,51 @@
+"""释放：写回公共池，再删我分片那行，再记一笔。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..core.paths import POOL_REL, shard_rel
+from ..core.time import now
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .result import Result, rel
+
+
+def release(repo: Path, me: Identity, tid: str) -> Result:
+    """写序：写回池（已有同号就不覆盖）→ 删我分片那行 → 过程文档记一笔。"""
+    pool = TaskStore(repo, POOL_REL)
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    task = mine.get(tid)  # 锁内重读
+    if task is None:
+        if pool.get(tid) is not None:
+            return Result(
+                already_done=True,
+                where=rel(repo, pool.path),
+                notices=(f"任务 {tid} 已经在公共池里，无需重复释放。",),
+            )
+        raise Fail(f"任务 {tid} 不在我的分片里，也没在公共池里。")
+
+    back = dict(task)
+    back["owner"] = None
+    back["status"] = "open"
+    back["updated"] = now()
+    if pool.get(tid) is None:
+        pool.put(tid, back)
+    mine.drop(tid)
+
+    logs = WorklogStore(repo)
+    path = logs.find(tid, back.get("worklog"))
+    note = None
+    if path is None:
+        note = f"任务 {tid} 已退回公共池，但过程文档没找到，跳过执行记录。"
+    else:
+        logs.append_exec(path, exec_line(now(), me.email, "release", "释放回公共池"))
+    return Result(
+        changed=("owner", "status", "updated"),
+        where=rel(repo, pool.path),
+        message=f"释放 {tid}：{back.get('title') or ''}".strip(),
+        notices=(note,) if note else (),
+    )

package/scripts/ledgerkit/actions/result.py

@@ -0,0 +1,88 @@
+"""动作的返回值长什么样。字段名是**公开契约**，插件看板直接读，外壳不许重新算。
+
+写动作返回 `Result`，只读动作返回各自的视图对象（不再套一层统一的壳）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+def rel(repo: Path, path: Path) -> str:
+    """绝对路径 → 相对 repo 的字符串（输出给人 / 给界面的一律这个基准）。"""
+    try:
+        return str(Path(path).resolve().relative_to(Path(repo).resolve()))
+    except ValueError:
+        return str(path)
+
+
+@dataclass(frozen=True)
+class WorklogView:
+    """「这条任务的过程文档要怎么显示」。"""
+
+    path: str | None = None  # 相对 repo
+    text: str | None = None  # 全文；读不到时为 None
+    error: str | None = None  # 读不到的原因（缺失 / 读不了），给人看
+
+
+@dataclass(frozen=True)
+class Result:
+    """写动作的返回。"""
+
+    changed: tuple[str, ...] = ()  # 改了哪些**字段名**（不是文件名、不是任务号）
+    where: str | None = None  # 主要落在哪个文件（**相对 repo**）
+    already_done: bool = False  # 重跑发现已经做过 ⇒ 退出码仍是 0
+    message: str | None = None  # git 提交说明；None ⇒ 外壳用默认模板
+    worklog: WorklogView | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+    notices: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TaskRow:
+    """人话表格的一行（9 字段投影）。`--json` 吐的是 `rows`（原样任务对象），不是它。"""
+
+    tid: str
+    title: str
+    status: str
+    owner: str | None = None  # 显示名
+    created: str | None = None
+    started: str | None = None
+    category: str | None = None
+    tags: tuple[str, ...] = ()
+    where: str | None = None  # 所在文件（相对 repo）
+
+
+@dataclass(frozen=True)
+class ListResult:
+    rows: dict[str, dict[str, Any]] = field(default_factory=dict)  # tid → 原样任务对象
+    table: tuple[TaskRow, ...] = ()
+    notices: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ShowResult:
+    task: dict[str, Any] = field(default_factory=dict)
+    worklog: WorklogView | None = None
+    others: tuple[str, ...] = ()  # 同一个任务号还出现在哪些文件里
+    notices: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class HistoryResult:
+    count: int = 0
+    filters: dict[str, Any] = field(default_factory=dict)  # 回显生效的筛选
+    records: tuple[dict[str, Any], ...] = ()
+    warnings: tuple[str, ...] = ()
+    capped: bool = False
+
+
+@dataclass(frozen=True)
+class ValidationReport:
+    problems: tuple[str, ...] = ()  # 只有它影响退出码
+    notices: tuple[str, ...] = ()  # 只提示，不改退出码
+    checked_files: int = 0
+    total_tasks: int = 0
+    deep: bool = False  # 本次是深度检查（--deep）还是默认浅度

package/scripts/ledgerkit/actions/set_task.py

@@ -0,0 +1,43 @@
+"""改归属的入口：只看 `--owner`，决定走哪个动作，**自己不加锁、不改任何文件**。
+
+它是全树唯一的跨动作引用点（import `release` / `handoff` / `claim`）。
+
+任务状态只随命令语义变（认领 → 进行中、释放 → 待认领、结案 → 历史），
+**没有单独的「改状态」入口**：`--status` 于 2026-10-23 删除 —— 全仓没有任何
+产品调用方（看板只有 claim / release / close 三个写路由），且它能制造
+「归我名下、状态却还是待认领」的坏状态（看板上显示成没人认领）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity, is_me
+from ..core.paths import shard_rel
+from ..errors import Fail
+from ..store.task_store import TaskStore
+from . import claim as claim_mod
+from . import handoff as handoff_mod
+from . import release as release_mod
+from .result import Result, rel
+
+
+def set_task(repo: Path, me: Identity, tid: str, *, owner: str | None) -> Result:
+    """路由：空串 = 释放；别人 = 交接；自己 = 已认领则空转、没认领先认领。"""
+    if owner is None:
+        raise Fail(
+            "set 必须带 --owner：空串 = 释放回公共池；对方身份 = 交接（预留通道，agent 不用）。"
+        )
+    target = owner.strip()
+    if not target:
+        return release_mod.release(repo, me, tid)
+    if not is_me(me, target):
+        return handoff_mod.handoff(repo, me, tid, to=target)
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    if mine.get(tid) is not None:
+        return Result(
+            already_done=True,
+            where=rel(repo, mine.path),
+            notices=(f"任务 {tid} 已经在你名下，无需操作。",),
+        )
+    return claim_mod.claim(repo, me, tid)

package/scripts/ledgerkit/actions/show_task.py

@@ -0,0 +1,27 @@
+"""只读：看一条任务（池 + 索引登记的全部分片都扫，别人的也要能看）。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..store.worklog_store import WorklogStore
+from .guard import load_task
+from .result import ShowResult, WorklogView, rel
+
+
+def show_task(repo: Path, me: Identity, tid: str) -> ShowResult:
+    task, where = load_task(repo, tid)
+    logs = WorklogStore(repo)
+    path = logs.find(tid, task.get("worklog"))
+    if path is None:
+        view = WorklogView(
+            path=None, text=None, error="这条任务没有过程文档（或文档已不在原处）。"
+        )
+    else:
+        view = WorklogView(path=rel(repo, path), text=logs.read(path), error=None)
+    return ShowResult(
+        task=task,
+        worklog=view,
+        others=tuple(rel(repo, p) for p in where),
+    )

package/scripts/ledgerkit/actions/validate.py

@@ -0,0 +1,224 @@
+"""只读：台账体检。两档：默认浅度只查格式，`--deep` 才读全部历史与过程文档正文。
+
+浅度（默认）：池 + 各分片的字段格式、索引与文件对不对得上、**当月**历史、每篇过程文档的模板格式。
+深度（`--deep`）：历史不止当月（全部月份），过程文档再判骨架（正文填了没）。
+
+只查格式，不查业务（该谁结案、逾期与否都不管）；也不查「同一任务号落在多个文件」——
+读侧只显示一次（`show` 会点名）、写侧已有防护，撞上了不关体检的事（2026-10-24 用户拍板）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core import history_md
+from ..core.identity import Identity
+from ..core.labels import STATUSES
+from ..core.paths import LEGACY_HISTORY_REL, OWNERS_REL, POOL_REL, to_repo_rel
+from ..core.time import now
+from ..core.worklog_md import (
+    duplicated_sections,
+    format_problems,
+    is_skeleton,
+    lacks_exec_section,
+)
+from ..store.history_store import HistoryStore
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .guard import owner_of, status_of
+from .result import ValidationReport, rel
+
+
+def _read_tasks(repo: Path, store: TaskStore, problems: list[str]) -> dict:
+    """读一个任务文件；撞上**程序自留**的冲突标记 ⇒ 记一条 problem 继续。
+
+    推送被拒后 rebase 给 JSON 留的 `<<<<<<<` 是程序自己产的坏数据，validate
+    要能指出来（退 1 给清单），而不是整条命令退 3（2026-10-24 修）。
+    其余读错误（用户手改坏）不在此列，照旧抛出。
+    """
+    try:
+        return store.all()
+    except ValueError:
+        text = store.path.read_text(encoding="utf-8", errors="replace")
+        if "<<<<<<<" in text:
+            problems.append(
+                f"{rel(repo, store.path)} 带着冲突标记"
+                "（推送被拒后 rebase 没解完）：先解决冲突，再跑 validate。"
+            )
+            return {}
+        raise
+
+
+def _check_task_files(
+    repo: Path, index: OwnersIndex, problems: list[str]
+) -> tuple[int, int]:
+    """池 + 各分片的字段格式（owner / status / 分片归属）；返回 (查了几个文件, 几条任务)。"""
+    checked = 0
+    total = 0
+
+    pool = TaskStore(repo, POOL_REL)
+    if pool.path.exists():
+        checked += 1
+        for tid, task in _read_tasks(repo, pool, problems).items():
+            total += 1
+            if owner_of(task):
+                problems.append(
+                    f"公共池里的 {tid} 带着 owner（池里的行必须无人认领）。"
+                )
+            if task.get("status") not in STATUSES:
+                problems.append(f"公共池里的 {tid} 状态 {task.get('status')!r} 非法。")
+
+    for key, path in index.shards().items():
+        if not path.exists():
+            problems.append(f"索引登记了 {key}，但分片文件 {path.name} 不存在。")
+            continue
+        checked += 1
+        store = TaskStore(repo, Path(path).relative_to(repo / "ledger"))
+        for tid, task in _read_tasks(repo, store, problems).items():
+            total += 1
+            owner = owner_of(task)
+            if not owner:
+                problems.append(f"分片 {key} 里的 {tid} 没有 owner。")
+            elif owner != key:
+                problems.append(
+                    f"分片 {key} 里的 {tid} 的 owner 是 {owner}（分片主人与分区键不一致）。"
+                )
+            status = status_of(task)
+            if status not in STATUSES:
+                problems.append(f"分片 {key} 里的 {tid} 状态 {status!r} 非法。")
+
+    return checked, total
+
+
+def _check_orphan_shards(index: OwnersIndex, problems: list[str]) -> None:
+    """目录里有、索引没登记的分片（全仓唯一扫目录的地方）。"""
+    registered = {p.name for p in index.shards().values()}
+    for path in index.disk_shards():
+        if path.name not in registered:
+            problems.append(
+                f"owners/ 里的 {path.name} 没有在索引里登记（对它人等于不存在）。"
+            )
+
+
+def _history_paths(store: HistoryStore, *, deep: bool) -> list[Path]:
+    """要读的历史文件：浅度只读当月那个月文件（存量平铺文件不读），深度读全部。"""
+    sources = store.sources()
+    if deep:
+        return sources
+    month = now()[0:4] + now()[5:7]
+    return [p for p in sources if store.month_key(p) == month]
+
+
+def _check_history(
+    repo: Path,
+    paths: list[Path],
+    open_docs: set[str],
+    store: HistoryStore,
+    notices: list[str],
+) -> int:
+    """历史文件的格式与对账：解析警告、行尾文档链接对得上在办任务没。"""
+    checked = 0
+    for path in paths:
+        checked += 1
+        rows, warns = history_md.parse_history(store.read(path))
+        notices.extend(f"{rel(repo, path)}：{w}" for w in warns)
+        for row in rows:
+            name = Path(row.get("worklog") or "").name
+            if name and name in open_docs:
+                notices.append(
+                    f"历史里有「{row.get('title') or name}」的结案行，"
+                    "但它还挂在在办台账里。"
+                )
+    return checked
+
+
+def _check_worklog(
+    repo: Path,
+    logs: WorklogStore,
+    problems: list[str],
+    notices: list[str],
+    *,
+    deep: bool,
+) -> int:
+    """每篇过程文档：模板格式（浅度就查）+ 空骨架判定（只有 `--deep` 才判）。
+
+    一趟读完两件事都做 —— 格式要看全文找节标题，骨架吃同一份文本，别为此读第二遍。
+    """
+    checked = 0
+    for path in logs.all():
+        checked += 1
+        try:
+            text = logs.read(path)
+        except ValueError:
+            continue
+        if not text:
+            continue
+        where = rel(repo, path)
+        problems.extend(f"{where} 格式：{line}" for line in format_problems(text))
+        if lacks_exec_section(text):
+            notices.append(
+                f"{where} 没有「执行记录」节（老文档；写一条记录会自动补上）。"
+            )
+        dup = duplicated_sections(text)
+        if dup:
+            notices.append(
+                f"{where} 有重复的节：{'、'.join(f'`## {s}`' for s in dup)}。"
+            )
+        if deep and is_skeleton(text):
+            notices.append(f"{where} 还是骨架（正文没填）。")
+    return checked
+
+
+def validate(repo: Path, me: Identity, deep: bool = False) -> ValidationReport:
+    problems: list[str] = []
+    notices: list[str] = []
+    checked = 0
+    total = 0
+
+    index = OwnersIndex(repo)
+    history = HistoryStore(repo)
+    logs = WorklogStore(repo)
+
+    files, tasks = _check_task_files(repo, index, problems)
+    checked += files
+    total += tasks
+    _check_orphan_shards(index, problems)
+
+    checked += _check_history(
+        repo,
+        _history_paths(history, deep=deep),
+        _open_worklog_names(repo, index),
+        history,
+        notices,
+    )
+    checked += _check_worklog(repo, logs, problems, notices, deep=deep)
+
+    legacy = repo / to_repo_rel(LEGACY_HISTORY_REL)
+    if legacy.exists():
+        notices.append(f"存量平铺文件 {rel(repo, legacy)} 只读兼容，不会重写。")
+    if not (repo / to_repo_rel(OWNERS_REL)).exists():
+        notices.append("还没有 owners.json（索引）：跑一条写命令会自动建。")
+
+    return ValidationReport(
+        problems=tuple(problems),
+        notices=tuple(notices),
+        checked_files=checked,
+        total_tasks=total,
+        deep=deep,
+    )
+
+
+def _open_worklog_names(repo: Path, index: OwnersIndex) -> set[str]:
+    """在办任务的过程文档**文件名**集合（池 + 全部分片）：历史行按它对账。"""
+    stores = [TaskStore(repo, POOL_REL)]
+    for path in index.shards().values():
+        if path.exists():
+            stores.append(TaskStore(repo, Path(path).relative_to(repo / "ledger")))
+    out: set[str] = set()
+    for store in stores:
+        for task in store.all().values():
+            name = Path((task.get("worklog") or "").strip()).name
+            if name:
+                out.add(name)
+    return out