dsh-task-ledger 0.0.101 → 0.0.103

package/skill/scripts/ledgerkit/shell/runner.py

@@ -1,232 +0,0 @@
-"""七步的执行顺序：唯一创建记账本、唯一决定退出码、唯一统一回滚的地方。
-
-七步：绑记账本 → 取最新 → 自举 → 调动作 → 打印 → 提交 → 推送。
-（仓库定位在更前面，见 `run` 开头。）
-
-- `already_done` **不**跳过提交与推送（写没写只看记账本）。
-- 记账本为空 ⇒ 提交与推送都跳过（没脏文件就没得提交）。
-- **唯一不回滚的失败分支是 `BrokenPipeError`**：文件已经写完，照常提交推送。
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-from pathlib import Path
-from typing import Any
-
-from .. import notices
-from ..actions import registry
-from ..actions.atom import atom
-from ..actions.guard import current_identity
-from ..core.ids import make_id
-from ..core.paths import to_repo_rel
-from ..core.time import now, to_utc
-from ..errors import (
-    BUSINESS,
-    INTERRUPTED,
-    OK,
-    UNEXPECTED,
-    Fail,
-)
-from ..store import dirty
-from ..store.atomic import snapshot
-from . import render
-from .gitops import GitRepo
-from .presync import presync_scope
-
-
-def run(command: str, args: argparse.Namespace) -> int:
-    """跑一条命令，返回退出码。"""
-    log = dirty.WriteLog()
-    try:
-        with dirty.bound(log):
-            return _run(command, args, log)
-    except Fail as exc:
-        if log.commit_started:
-            # 提交阶段才失败：数据已落盘，回滚 = 吃掉刚写的台账（2026-10-24 修）
-            render.fail_message(exc)
-            return BUSINESS
-        log.rollback_presync()
-        log.discard_created()
-        render.fail_message(exc)
-        return BUSINESS
-    except BrokenPipeError:
-        # 唯一不回滚的分支：文件已写，按记账本照常提交推送
-        _finalize(command, args, log, broken=True)
-        return OK
-    except KeyboardInterrupt:
-        if log.commit_started:
-            return INTERRUPTED
-        log.rollback_presync()
-        log.discard_created()
-        return INTERRUPTED
-    except Exception as exc:  # noqa: BLE001 —— 兜底：任何未预期异常都要留下可诊断信息
-        if log.commit_started:
-            render.fail_message(exc, title="未预期错误")
-            return UNEXPECTED
-        log.rollback_presync()
-        log.discard_created()
-        render.fail_message(exc, title="未预期错误")
-        return UNEXPECTED
-
-
-def _run(command: str, args: argparse.Namespace, log: dirty.WriteLog) -> int:
-    spec = registry.spec_of(command)
-    repo = _repo_of(args)
-    me = current_identity(repo)
-    no_sync = bool(getattr(args, "no_sync", False))
-    as_json = bool(getattr(args, "json", False))
-
-    git = GitRepo(repo)
-    syncing = not no_sync
-    if syncing:
-        # 中间态是**全局前提**，必须早于下面任何读台账的动作（`_params` 的 `new` 快照、
-        # `presync_scope` 的锁集都要读台账）：冲突标记下的台账不是合法 JSON，读它就抛
-        # 「未预期错误」（退出码 3），而文档要的是「仓库处于中间态」这句人话。
-        git.check_repo_state()
-
-    params = _params(command, args, repo, me, spec)
-
-    # 只读：不建 GitRepo、不进事务、不提交
-    if spec.readonly:
-        value = spec.func(repo, me, **params)
-        # 先自报读的是哪个台账：`--repo` 指错目录时输出会变成一片「没有任务」，不带这一行
-        # 就完全看不出读错了地方。`--count-only` 也出 JSON，同样不打（2026-10-25 改）
-        render.repo_banner(
-            repo, machine=as_json or bool(getattr(args, "count_only", False))
-        )
-        _render(spec, value, args, as_json=as_json)
-        if getattr(value, "problems", ()):
-            return BUSINESS  # validate 有 problems ⇒ 退出码 1（§六）
-        return OK
-
-    boot_scope, act_scope = presync_scope(repo, me, spec.lock_action or command, params)
-
-    if syncing:
-        git.guard_before_write(boot_scope | act_scope)
-        for path, before in git.sync_down(boot_scope | act_scope):
-            log.record_presync(path, before)
-
-    # 自举会登记自己（改 owners.json、缺文件时建池与分片）。它碰过的文件按「命令前的字节」
-    # 记进记账本：成功时照常提交（登记必须进仓），失败时由 rollback_presync 一起还回去 ——
-    # 否则一条失败的命令会把台账留在「已写未提交」，下一条写命令被写前 guard 拦死
-    # （架构文档 §三.5 正是要避免这个）。登记是幂等的，还回去下次再登记，没有损失。
-    for rel in boot_scope.files:
-        log.record_presync(repo / to_repo_rel(rel), snapshot(repo / to_repo_rel(rel)))
-    with atom(repo, *boot_scope.files):
-        me = registry.bootstrap_func()(repo, me)
-
-    with atom(repo, *act_scope.files):
-        value = spec.func(repo, me, **params)
-
-    _render(spec, value, args, as_json=as_json)
-    _finalize(command, args, log, message=getattr(value, "message", None))
-    return OK
-
-
-def _finalize(
-    command: str,
-    args: argparse.Namespace,
-    log: dirty.WriteLog,
-    *,
-    message: str | None = None,
-    broken: bool = False,
-) -> None:
-    """提交 + 推送：要不要做只看记账本（与 `already_done` 无关，只有 `--no-sync` 才整段跳过）。"""
-    if broken:
-        try:
-            sys.stdout.close()
-        except Exception:  # noqa: BLE001, S110  # 关 stdout 本就无信息可记
-            pass
-    if getattr(args, "no_sync", False):
-        if getattr(args, "no_sync", False) and log.has_writes():
-            # 以前这条路径一个字都不打，「已写未提交」就此静默腐烂
-            notices.note(
-                "提示：--no-sync 本次只写了本地文件、未签入 git（也未推送）。\n"
-                "  处理：确认后自行 git add ledger && git commit && git push；"
-                "留着不提交的话，下一条写命令会被「本地有未提交的台账改动」拦住。"
-            )
-        log.clear()
-        return
-    if not log.has_writes():
-        log.clear()
-        return
-    repo = _repo_of(args)
-    git = GitRepo(repo)
-    if not git.is_git_repo():
-        # 没有 git 也能用：台账照写，只不做同步（2026-10-24 用户拍板）。
-        # 以前这里直接 git add，非 git 目录下必失败 ⇒ 整条命令退 1，台账像没写。
-        notices.note(
-            "提示：当前目录不是 git 仓库，台账只写了本地文件（未提交、未推送）。\n"
-            "  处理：想纳入版本管理就 git init；否则继续本地写也行 —— "
-            "多人各写各的，后写覆盖先写。"
-        )
-        log.clear()
-        return
-    log.commit_started = True
-    message = message or f"chore(ledger): {command}"
-    git.commit(log.commit_set(), message)
-    git.push()
-    log.clear()
-
-
-def _render(spec: registry.ActionSpec, value, args, *, as_json: bool) -> None:
-    func = getattr(render, spec.render)
-    if spec.render in ("list_view", "history_view"):
-        func(value, getattr(args, "q", None), as_json=as_json)
-    else:
-        func(value, as_json=as_json)
-
-
-def _params(
-    command: str, args: argparse.Namespace, repo: Path, me, spec: registry.ActionSpec
-) -> dict[str, Any]:
-    """按 `spec.params` 从 args 里挑；**不许把整个 args 透传进业务层**。"""
-    out: dict[str, Any] = {}
-    for key in spec.params:
-        out[key] = getattr(args, key, None)
-    if command == "new":
-        created = out.get("created") or now()
-        if getattr(args, "created", None):
-            created = to_utc(args.created, field="--created")
-        out["created"] = created
-        if not out.get("tid"):
-            out["tid"] = make_id(
-                out.get("title") or "", _task_snapshot(repo, me), created
-            )
-        out["tags"] = tuple(out.get("tags") or ())
-    if command == "close":
-        out["finished"] = (
-            to_utc(args.finished, field="--finished")
-            if getattr(args, "finished", None)
-            else now()
-        )
-        out["tags"] = tuple(out.get("tags") or ())
-    return out
-
-
-def _task_snapshot(repo: Path, me) -> dict[str, Any]:
-    """建任务查重要用的在办任务快照（**锁外**只读，只用于生成不撞的号）。"""
-    from ..core.paths import POOL_REL, shard_rel
-    from ..store.task_store import TaskStore
-
-    tasks: dict[str, Any] = {}
-    tasks.update(TaskStore(repo, POOL_REL).all())
-    tasks.update(TaskStore(repo, shard_rel(me.uuid)).all())
-    return tasks
-
-
-def _repo_of(args: argparse.Namespace) -> Path:
-    """工作区根：`cli.main` 已经解析好挂在 `args.repo` 上（定位只做一次）。
-
-    直接调 runner（测试 / 内嵌调用）时没挂过 ⇒ 现解一次，规则与 cli 一致。
-    """
-    repo = getattr(args, "repo", None)
-    if repo:
-        from ..core.roots import as_root  # 门 2 兜底：绕过 cli 直调 runner 也不收错位根
-
-        return as_root(repo, source="--repo")
-    from .cli import resolve_repo  # 延迟导入：cli 在模块层 import runner
-
-    return resolve_repo(None)

package/skill/scripts/ledgerkit/store/atomic.py

@@ -1,130 +0,0 @@
-"""怎么安全地写一个文件：唯一写盘出口。
-
-进门规则：不打印、不跑 git、不判断 owner/status、不自己加锁。
-写完顺手通知 `dirty` 记一笔（那是记账本唯一被写的地方之一）。
-"""
-
-from __future__ import annotations
-
-import hashlib
-import os
-import stat
-import tempfile
-from pathlib import Path
-
-from ..errors import Fail
-from . import dirty
-
-
-def ensure_dir(path: Path) -> None:
-    """建目录（`mkdir -p` 语义）。**全仓唯一建目录的地方**，写文件不替人建父目录。"""
-    try:
-        path.mkdir(parents=True, exist_ok=True)
-    except OSError as exc:
-        raise Fail(f"建目录 {path} 失败：{exc}") from exc
-
-
-def write_text_atomic(path: Path, text: str, *, track: bool = True) -> None:
-    """原子写文本：同目录临时文件 → 写 → fsync → 继承权限 → replace → fsync 父目录。
-
-    `track=False` 只给 `restore`（复原世界）与外壳两条受控通道用 —— 那三处都不是业务改动。
-    两个属性必须保住：mkstemp 建的是 0600，直接 replace 会把 644 降成 600；
-    符号链接一律拒绝，否则 replace 会把链接替换成普通文件。
-    """
-    fd = None
-    tmp: Path | None = None
-    existed = False
-    try:
-        # 不替调用方建父目录：建目录只有 ensure_dir 一处，业务层要自己先 ensure_dir
-        if not path.parent.exists():
-            raise Fail(
-                f"写 {path} 失败：父目录 {path.parent} 不存在（建目录要显式调 ensure_dir）。"
-            )
-        if path.is_symlink():
-            raise Fail(f"拒绝写入 {path}：它是符号链接，写入会把它替换成普通文件")
-        try:
-            mode = stat.S_IMODE(path.stat().st_mode)
-            existed = True
-        except OSError:
-            mode = 0o644  # 新文件：与 git 默认对齐
-        fd, tmp_name = tempfile.mkstemp(
-            dir=str(path.parent), prefix=path.name + ".", suffix=".tmp"
-        )
-        tmp = Path(tmp_name)
-        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
-            fd = None  # 所有权已交给文件对象
-            fh.write(text)
-            fh.flush()
-            os.fsync(fh.fileno())
-        os.chmod(tmp, mode)
-        os.replace(tmp, path)
-        _fsync_dir(path.parent)
-        tmp = None
-    except OSError as exc:
-        raise Fail(
-            f"写 {path} 失败：{exc}\n"
-            "  处理：确认该路径可写、磁盘没满，然后重跑这条命令（文件是整份替换，不会写坏）。"
-        ) from exc
-    finally:
-        if fd is not None:
-            try:
-                os.close(fd)
-            except OSError:
-                pass
-        if tmp is not None and tmp.exists():
-            try:
-                tmp.unlink()
-            except OSError:
-                pass
-    dirty.current().record(path, track=track, created=not existed)
-
-
-def _fsync_dir(dirpath: Path) -> None:
-    """刷父目录：掉电时 rename 的目录项可能丢，只刷文件是不够的。"""
-    try:
-        fd = os.open(str(dirpath), os.O_RDONLY)
-    except OSError:
-        return
-    try:
-        os.fsync(fd)
-    except OSError:
-        pass
-    finally:
-        os.close(fd)
-
-
-def fingerprint(path: Path) -> str | None:
-    """文件内容 sha256，用来判「我读完以后别人动过没有」。
-
-    三种返回值互不相等：正常 → sha256 串；不存在 → None；读不了 → `"unreadable"`。
-    """
-    try:
-        data = path.read_bytes()
-    except FileNotFoundError:
-        return None
-    except OSError:
-        return "unreadable"
-    return hashlib.sha256(data).hexdigest()
-
-
-def snapshot(path: Path) -> bytes | None:
-    """写之前把原文留一份字节；原本不存在返回 None。"""
-    try:
-        return path.read_bytes()
-    except FileNotFoundError:
-        return None
-    except OSError as exc:
-        raise Fail(f"读 {path} 失败：{exc}") from exc
-
-
-def restore(path: Path, before: bytes | None) -> None:
-    """按字节还原：`None` 表示原本不存在 ⇒ 删掉。恢复本身不进记账本（`track=False`）。"""
-    if before is None:
-        try:
-            path.unlink()
-        except FileNotFoundError:
-            return
-        except OSError as exc:
-            raise Fail(f"撤销 {path} 失败：{exc}") from exc
-        return
-    write_text_atomic(path, before.decode("utf-8"), track=False)

package/skill/scripts/ledgerkit/store/dirty.py

@@ -1,108 +0,0 @@
-"""记账本：这一轮到底动了哪些文件。**提交集合只看它**，不看 `Result.changed`。
-
-三类记录各有各的用途：
-- `changed`：业务改动，最后要提交；
-- `created`：本次新建的文件，失败时要删掉（不能留下孤儿）；
-- `presync`：取最新时刷过的文件（连"刷之前"的字节一起）——它们**反而必须**一起提交，
-  否则拉下来的新内容留在工作树里，下一条写命令会被写前 guard 拦死。
-
-只返回清单、不打印（打印归外壳，否则 dirty 要 import shell，依赖反向）。
-"""
-
-from __future__ import annotations
-
-import contextlib
-from collections.abc import Iterator
-from dataclasses import dataclass, field
-from pathlib import Path
-
-
-@dataclass
-class WriteLog:
-    changed: list[Path] = field(default_factory=list)
-    created: list[Path] = field(default_factory=list)
-    presync: list[tuple[Path, bytes | None]] = field(default_factory=list)
-    # 进入提交阶段（_finalize 开始 git add/commit）后置位：此时台账数据已落盘，
-    # 失败 / 中断都不许回滚或删除 —— 那会吃掉刚写的台账（2026-10-24 修）。
-    commit_started: bool = False
-
-    def record(self, path: Path, *, track: bool = True, created: bool = False) -> None:
-        """记一次写。`track=False`（复原 / 外壳刷盘）不进改动集合。"""
-        if created and path not in self.created:
-            self.created.append(path)
-        if track and path not in self.changed:
-            self.changed.append(path)
-
-    def record_presync(self, path: Path, before: bytes | None) -> None:
-        """记「取最新刷过这个文件」+ 刷之前的字节（失败时按它恢复）。"""
-        for i, (known, _) in enumerate(self.presync):
-            if known == path:
-                self.presync[i] = (path, before)
-                return
-        self.presync.append((path, before))
-
-    def commit_set(self) -> list[Path]:
-        """最后要提交的文件：本次改动 + 取最新刷过的（去重保序）。"""
-        out: list[Path] = []
-        for path in [*self.changed, *(p for p, _ in self.presync)]:
-            if path not in out:
-                out.append(path)
-        return out
-
-    def has_writes(self) -> bool:
-        return bool(self.changed or self.presync)
-
-    def rollback_presync(self) -> list[Path]:
-        """按备份把「被取最新覆盖掉」的内容恢复回去（刷之前不存在 ⇒ 删掉）。"""
-        from .atomic import write_text_atomic
-
-        done: list[Path] = []
-        for path, before in reversed(self.presync):
-            if before is None:
-                try:
-                    path.unlink()
-                except FileNotFoundError:
-                    pass
-            else:
-                write_text_atomic(path, before.decode("utf-8"), track=False)
-            done.append(path)
-        self.presync = []
-        return done
-
-    def discard_created(self) -> list[Path]:
-        """删掉本次新建的文件（失败收尾用）。"""
-        done: list[Path] = []
-        for path in self.created:
-            try:
-                path.unlink()
-            except FileNotFoundError:
-                pass
-            done.append(path)
-        self.created = []
-        return done
-
-    def clear(self) -> None:
-        """成功路径收尾：全部清零。"""
-        self.changed = []
-        self.created = []
-        self.presync = []
-
-
-_CURRENT: WriteLog = WriteLog()
-
-
-def current() -> WriteLog:
-    """当前这一轮的记账本（没绑定时给一个空账本）。"""
-    return _CURRENT
-
-
-@contextlib.contextmanager
-def bound(log: WriteLog) -> Iterator[None]:
-    """绑定这一轮的记账本（生产只在 runner 里绑一次；测试用）。"""
-    global _CURRENT
-    saved = _CURRENT
-    _CURRENT = log
-    try:
-        yield
-    finally:
-        _CURRENT = saved

package/skill/scripts/ledgerkit/store/history_store.py

@@ -1,134 +0,0 @@
-"""已结案 `history/<年月>.md`：列全部文件、读一篇、算「追加一行后的新全文」、判重、落盘。
-
-「算」和「落」是两个方法 —— 结案要控顺序（历史 → 封卷 → 删分片），落盘时机由业务层定。
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-from ..core import history_md
-from ..core.paths import HISTORY_DIR, to_repo_rel
-from .atomic import write_text_atomic
-
-HIT = "hit"
-MISS = "miss"
-UNDECIDABLE = "undecidable"
-
-
-class HistoryStore:
-    def __init__(self, repo: Path):
-        self.repo = Path(repo)
-
-    # ---- 读 ----
-
-    def sources(self) -> list[Path]:
-        """按月的 `history/*.md`（按文件名排序）。"""
-        base = self.repo / to_repo_rel(HISTORY_DIR)
-        return sorted(base.glob("*.md")) if base.is_dir() else []
-
-    def month_key(self, path: Path) -> str:
-        """按月文件的 `YYYYMM`。"""
-        stem = Path(path).stem
-        return stem if len(stem) == 6 and stem.isdigit() else ""
-
-    def read(self, path: Path) -> str:
-        try:
-            return path.read_text(encoding="utf-8-sig")
-        except FileNotFoundError:
-            return ""
-        except OSError as exc:
-            raise ValueError(f"读 {path} 失败：{exc}") from exc
-
-    # ---- 判重 ----
-
-    def has_log(
-        self,
-        path: Path,
-        *,
-        log_name: str | None,
-        created: str | None,
-        title: str | None,
-    ) -> str:
-        """这个月的历史里已经有这条了吗？三态：`hit` / `miss` / `undecidable`。
-
-        有末列就比**文件名**（不比整条路径）。末列为空的行改按「创建时间 + 标题」两列比
-        —— 那种行在调用方给不出 `created` / `title` 时判不了，明说 `undecidable`，不拿 miss 冒充。
-        """
-        records, _ = history_md.parse_history(self.read(path))
-        undecidable = False
-        for row in records:
-            worklog = (row.get("worklog") or "").strip()
-            if log_name and worklog:
-                if Path(worklog).name == Path(log_name).name:
-                    return HIT
-                continue
-            if log_name is None and worklog:
-                # 历史行里有链接，但这次判不出对应的是哪篇文档（任务的过程文档丢了 / 被移走）：
-                # 判不了就明说。拿 miss 冒充会再追加一行 ⇒ 同一条任务两条结案记录。
-                undecidable = True
-                continue
-            if not worklog:
-                if created and title:
-                    if row.get("created") == created and row.get("title") == title:
-                        return HIT
-                else:
-                    undecidable = True
-        return UNDECIDABLE if undecidable else MISS
-
-    # ---- 算 ----
-
-    def append_row(self, path: Path, row: dict[str, Any]) -> dict[str, Any]:
-        """算出「追加这一行后的新全文」，**不落盘**。返回 `text` / `duplicate`。"""
-        original = self.read(path)
-        duplicate = (
-            self.has_log(
-                path,
-                log_name=_name_of(row.get("worklog")),
-                created=row.get("created"),
-                title=row.get("title"),
-            )
-            == HIT
-        )
-        text = original if original.strip() else _fresh_table()
-        line = history_md.history_line(
-            row.get("finished") or "",
-            row.get("created"),
-            row.get("title") or "",
-            row.get("owner"),
-            row.get("summary") or "",
-            row.get("worklog"),
-            category=row.get("category"),
-            tags=row.get("tags"),
-            creator=row.get("creator"),
-            owner_name=row.get("owner_name"),
-            creator_name=row.get("creator_name"),
-        )
-        return {"text": _append_line(text, line), "duplicate": duplicate}
-
-    # ---- 写 ----
-
-    def write(self, path: Path, text: str) -> None:
-        """历史表唯一的写回口：只用于「结案追加」的结果落盘。"""
-        write_text_atomic(path, text)
-
-
-def _name_of(worklog: str | None) -> str | None:
-    return Path(worklog).name if worklog else None
-
-
-def _fresh_table() -> str:
-    """当月第一次结案：按十一列表头起表（表头的真源只有 `history_md` 一处）。"""
-    return (
-        f"{history_md.HISTORY_TITLE}\n\n"
-        f"{history_md.HISTORY_HEADER}\n{history_md.HISTORY_SEP}\n"
-    )
-
-
-def _append_line(text: str, line: str) -> str:
-    body = text.rstrip("\n")
-    if body and not body.splitlines()[-1].strip().startswith("|"):
-        # 表前有散文：补一个空行，别把表头贴上去
-        return body + "\n\n" + line
-    return body + "\n" + line