task-ledger 1.3.0 → 1.3.1

package/scripts/ledgerkit/core/time.py

@@ -0,0 +1,102 @@
+"""时间：本地墙钟 ↔ UTC 的换算、格式化、排序键。
+
+进门规则：不读文件、不写文件、不打印；只依赖 errors。
+所有**存盘**时间都是 UTC（`YYYY-MM-DD HH:MM:SS`，不带偏移量）；
+所有**人话显示**都过 `fmt_local`；`--json` 原样吐 UTC。
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+
+from ..errors import Fail
+
+_UTC = UTC
+
+TIME_RE = re.compile(r"\d{4}-\d{2}-\d{2} \d{2}:\d{2}(?::\d{2})?\Z")
+_TIME_IN_RE = re.compile(
+    r"(\d{4})-(\d{1,2})-(\d{1,2})(?: +(\d{1,2}):(\d{1,2})(?::(\d{1,2}))?)?\Z"
+)
+
+
+def now() -> str:
+    """当前时刻（UTC，到秒）。"""
+    return datetime.now(_UTC).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def normalize_time(
+    value: str | datetime,
+    *,
+    field: str = "时间",
+    tid: str | None = None,
+    date_only_ref: str | None = None,
+) -> str:
+    """把「正确但不完整」的写法归一化到 `YYYY-MM-DD HH:MM:SS`。
+
+    接受 `YYYY-MM-DD`、`YYYY-MM-DD HH:MM`、`YYYY-MM-DD HH:MM:SS`，容忍 `/` 与 `T`。
+    `date_only_ref`：只给了日期时用这个时刻顶替（`--until` 想含整天传 `23:59:59`）。
+    """
+    where = f"{tid}: " if tid else ""
+    if isinstance(value, datetime):
+        return value.strftime("%Y-%m-%d %H:%M:%S")
+    if not isinstance(value, str) or not value.strip():
+        raise Fail(f"{where}{field} 要是一个时间字符串，收到 {value!r}")
+    s = " ".join(
+        value.strip().replace("/", "-").replace("T", " ").replace("t", " ").split()
+    )
+    m = _TIME_IN_RE.fullmatch(s)
+    if not m:
+        raise Fail(
+            f"{where}{field} 时间格式不对：{value!r}"
+            "（可用 YYYY-MM-DD、YYYY-MM-DD HH:MM、YYYY-MM-DD HH:MM:SS）"
+        )
+    y, mo, d, hh, mm, ss = m.groups()
+    if date_only_ref is not None and hh is None:
+        out = f"{int(y):04d}-{int(mo):02d}-{int(d):02d} {date_only_ref}"
+    else:
+        out = (
+            f"{int(y):04d}-{int(mo):02d}-{int(d):02d} "
+            f"{int(hh or 0):02d}:{int(mm or 0):02d}:{int(ss or 0):02d}"
+        )
+    try:
+        datetime.strptime(out, "%Y-%m-%d %H:%M:%S")
+    except ValueError as exc:
+        raise Fail(f"{where}{field} 不是真实时间：{value!r}（{exc}）") from exc
+    return out
+
+
+def to_utc(
+    value: str,
+    *,
+    field: str,
+    tid: str | None = None,
+    date_only_ref: str | None = None,
+) -> str:
+    """用户按本地墙钟给的时间 → 存盘用的 UTC 串。只由外壳调用。"""
+    wall = normalize_time(value, field=field, tid=tid, date_only_ref=date_only_ref)
+    naive = datetime.strptime(wall, "%Y-%m-%d %H:%M:%S")
+    return naive.astimezone(_UTC).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def fmt_local(stamp: object) -> str:
+    """存盘的 UTC → 查看者本地时间，只用于人看的输出。
+
+    存量老数据（2026-10-22 前写的是写入者本地时间、无标记）无法区分，
+    按 UTC 转会显示偏后若干小时 —— 这是已知例外，不在脚本里猜。
+    """
+    key = time_key(stamp)
+    if key is None:
+        return "" if stamp is None else str(stamp)
+    try:
+        dt = datetime.strptime(key, "%Y-%m-%d %H:%M:%S").replace(tzinfo=_UTC)
+    except ValueError:
+        return str(stamp)
+    return dt.astimezone().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def time_key(value: object) -> str | None:
+    """已存时间（可能只到分）→ 秒精度串，用于比较/排序；不合法返回 None。"""
+    if not isinstance(value, str) or not TIME_RE.fullmatch(value):
+        return None
+    return value if len(value) == 19 else value + ":00"

package/scripts/ledgerkit/core/worklog_md.py

@@ -0,0 +1,232 @@
+"""过程文档的文本操作：给一段文字，返回新文字。不读文件、不写文件。
+
+模板的**读取**归 `store/WorklogStore.template()`，这里只做字符串替换。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from itertools import takewhile
+
+from ..errors import Fail
+from .labels import label_line, parse_label_line
+from .time import fmt_local, normalize_time
+
+EXEC_HEAD = "## 执行记录"
+EXEC_HINT = (
+    "<!-- 本节由脚本维护：new / claim / set / release / log / close 自动追加，请勿手改。\n"
+    '     补记用 progress.py log --id <任务号> --note "一句话"。 -->'
+)
+FROZEN_MARK = "✅ 完成封卷"
+FROZEN_RE = re.compile(r"^>\s*" + FROZEN_MARK, re.MULTILINE)
+CREATED_RE = re.compile(r"^\s*>\s*\*\*创建\*\*")
+# 头部「创建」行：`> **创建**：2026-10-06 00:00（@某人）` —— 创建时间与发起人两个来源。
+CREATED_AT_RE = re.compile(
+    r"^\s*>\s*\*\*创建\*\*\s*[：:]\s*"
+    r"(\d{4}-\d{2}-\d{2}(?: +\d{1,2}:\d{1,2}(?::\d{1,2})?)?)"
+)
+CREATOR_RE = re.compile(r"^\s*>\s*\*\*创建\*\*\s*[：:].*?（@(.+?)）")
+
+_HEAD_RE = re.compile(r"\A(.*?)(?=^## |\Z)", re.DOTALL | re.MULTILINE)
+
+
+#: 过程文档应有的六节，顺序即模板顺序（真源是 `assets/worklog.md`）。
+WORKLOG_SECTIONS = ("背景", "待办", "下一步", "过程", "结论", "执行记录")
+#: 判「格式坏」只要求前五节；「执行记录」由脚本维护，老文档没有、写入时会补，缺了只提示。
+REQUIRED_SECTIONS = WORKLOG_SECTIONS[:5]
+
+
+def section_heads(text: str) -> list[str]:
+    """文档里的二级标题（`## 背景` → `背景`），按出现顺序。"""
+    return [
+        line[3:].strip() for line in (text or "").splitlines() if line.startswith("## ")
+    ]
+
+
+def _head_lines(lines: list[str]) -> list[str]:
+    """第一个二级标题之前的行（头部引用块）。"""
+    return list(takewhile(lambda line: not line.startswith("## "), lines))
+
+
+def format_problems(text: str) -> list[str]:
+    """过程文档的**格式**问题：只看骨架结构，不看内容、不判业务。空列表 = 没问题。
+
+    五项：第一行是标题 / 头部「创建」行有时间 / 创建行有发起人 / 前五节齐全 / 前五节顺序对。
+    结案封卷、分类标签、正文写得怎么样都不在这里判（那是内容与业务）。
+    """
+    problems: list[str] = []
+    body = (text or "").lstrip("\ufeff")
+    lines = body.splitlines()
+    if not lines or not lines[0].startswith("# "):
+        problems.append("第一行不是标题（应为 `# <任务号>：<标题>`）")
+    head = _head_lines(lines)
+    if not any(CREATED_AT_RE.match(line) for line in head):
+        problems.append(
+            "头部缺「创建」时间行（应为 `> **创建**：YYYY-MM-DD HH:MM（@某人）`）"
+        )
+    elif not any(CREATOR_RE.match(line) for line in head):
+        problems.append("头部「创建」行缺发起人（应为 `…（@某人）`）")
+    heads = section_heads(body)
+    missing = [s for s in REQUIRED_SECTIONS if s not in heads]
+    if missing:
+        problems.append("缺节：" + "、".join(f"`## {s}`" for s in missing))
+    else:
+        # 按「首次出现」去重再比顺序：老文档里同一节重复出现很常见（编辑残留），
+        # 那不影响读写（脚本按锚点定位），只作提示，不判错。
+        order: list[str] = []
+        for head in heads:
+            if head in REQUIRED_SECTIONS and head not in order:
+                order.append(head)
+        if order != list(REQUIRED_SECTIONS):
+            problems.append(
+                "节的顺序不对：应为 "
+                + " → ".join(f"`## {s}`" for s in REQUIRED_SECTIONS)
+            )
+    return problems
+
+
+def duplicated_sections(text: str) -> list[str]:
+    """重复出现的节标题（老文档编辑残留；不影响读写，只作提示）。"""
+    heads = section_heads(text)
+    return [s for s in REQUIRED_SECTIONS if heads.count(s) > 1]
+
+
+def lacks_exec_section(text: str) -> bool:
+    """缺「执行记录」节（老文档没有；只提示，脚本写入时会自动补上这一节）。"""
+    return WORKLOG_SECTIONS[-1] not in section_heads(text)
+
+
+def is_skeleton(text: str) -> bool:
+    """是不是骨架（正文还没填）：前五节里没有任何实质内容。"""
+    body = _sections_body(text)
+    if not body.strip():
+        return True
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("<!--", "-->", ">")):
+            continue
+        if stripped.startswith("#"):
+            continue
+        if stripped in {"-", "—"}:
+            continue
+        return False
+    return True
+
+
+def _sections_body(text: str) -> str:
+    """去掉「执行记录」节之后剩下的正文。"""
+    idx = text.find(f"\n{EXEC_HEAD}")
+    return text[:idx] if idx >= 0 else text
+
+
+def render_worklog(
+    *,
+    tid: str,
+    title: str,
+    created: str,
+    creator: str,
+    category: str | None = None,
+    tags: Iterable[str] | None = None,
+    template: str,
+) -> str:
+    """把模板套成一篇过程文档（`<id>` / `<title>` / `<created>` / `<creator>` 四个占位符）。"""
+    text = (
+        template.replace("<id>", tid)
+        .replace("<title>", title or "")
+        .replace("<created>", created or "")
+        .replace("<creator>", creator or "")
+    )
+    meta = label_line(category, tags)
+    if not meta:
+        return text
+    return "\n".join(_insert_after_head(text.splitlines(), meta)) + "\n"
+
+
+def _insert_after_head(lines: list[str], line: str) -> list[str]:
+    """把一行插到「创建」行之后（头部引用块内）；找不到创建行就插标题后。"""
+    at = next((i for i, ln in enumerate(lines) if CREATED_RE.match(ln)), None)
+    if at is None:
+        at = 1 if lines and lines[0].startswith("# ") else 0
+    lines.insert(at + 1, line)
+    return lines
+
+
+def exec_line(when: str, who: str | None, kind: str, note: str) -> str:
+    """一条执行记录：`- 本地时刻 · 类型 · @某人 · 说明`。
+
+    时刻是**给人读的日志行**，所以在这里转成查看者本地时间（调用方一律传 UTC，
+    别在外面先转一遍）。类型取动作名（new / claim / set / release / log / close）。
+    """
+    head = f"- {fmt_local(when)} · {kind}"
+    tail = f" · @{who} · {note}" if who else f" · {note}"
+    return head + tail
+
+
+def append_exec_log(text: str, line: str) -> str:
+    """把一条记录追加到「执行记录」节末尾；老文档没有这一节就先补一节。"""
+    if f"\n{EXEC_HEAD}" in text or text.startswith(EXEC_HEAD):
+        return text.rstrip("\n") + "\n" + line + "\n"
+    block = f"\n{EXEC_HEAD}\n\n{EXEC_HINT}\n{line}\n"
+    return text.rstrip("\n") + "\n" + block
+
+
+def has_frozen_line(text: str) -> bool:
+    """这篇文档封卷了没有（认标记行）。"""
+    return bool(FROZEN_RE.search(text or ""))
+
+
+def stamp_frozen(text: str, finished: str, who: str | None = "") -> str:
+    """封卷：在头部打标记行（`finished` 传 UTC，这里转本地给人看）。"""
+    mark = f"> {FROZEN_MARK}：{fmt_local(finished)}"
+    if who:
+        mark += f"（@{who}）"
+    if FROZEN_RE.search(text or ""):
+        return text
+    return "\n".join(_insert_after_head(text.splitlines(), mark)) + "\n"
+
+
+def rewrite_label_line(
+    text: str, category: str | None, tags: Iterable[str] | None
+) -> str:
+    """改写头部的分类 / 标签行：有就地替换，没有就插到创建行后。"""
+    line = label_line(category, tags)
+    lines = text.splitlines()
+    for i, ln in enumerate(lines):
+        if ln.startswith("## "):
+            break
+        if "**分类**" in ln or "**标签**" in ln:
+            if line:
+                lines[i] = line
+            else:
+                del lines[i]
+            return "\n".join(lines) + "\n"
+    if not line:
+        return text
+    return "\n".join(_insert_after_head(lines, line)) + "\n"
+
+
+def head_meta(text: str) -> tuple[str | None, tuple[str, ...]]:
+    """过程文档头部的分类与标签（供历史回链与标签统计共用）。"""
+    return parse_label_line(text)
+
+
+def head_created(text: str) -> str | None:
+    """头部「创建」行的时间（原样返回，不转时区）；读不到返回 None。"""
+    for line in text.splitlines():
+        m = CREATED_AT_RE.match(line)
+        if m:
+            try:
+                return normalize_time(m.group(1), field="创建")
+            except Fail:
+                return None
+    return None
+
+
+def head_creator(text: str) -> str | None:
+    """头部「创建」行括号里的发起人（裸标识，不带 @）；读不到返回 None。"""
+    for line in text.splitlines():
+        m = CREATOR_RE.match(line)
+        if m and m.group(1).strip():
+            return m.group(1).strip()
+    return None

package/scripts/ledgerkit/env.py

@@ -0,0 +1,93 @@
+"""唯一允许去问 git「我现在是谁」的地方。
+
+只**读**配置（`GIT_COMMITTER_IDENT` / `config user.email` / `config user.name`），
+不 pull、不 commit、不 push —— 那不算 git 操作，算环境。
+兜底身份这件事本身只 `notices.note("提示：…")`，不打印。
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import re
+import socket
+import subprocess
+from pathlib import Path
+
+from . import notices
+from .core.identity import Identity, normalize
+
+_IDENT_RE = re.compile(r"<([^>]*)>")
+
+
+def _git(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", *args], capture_output=True, text=True, check=False)
+
+
+def git_value(repo: Path | None, *args: str) -> str | None:
+    """读一个 git 配置值；cwd 给定时按那个仓库判（--repo 未必是当前目录）。
+
+    没装 git 二进制不算故障：当「读不到」处理，走兜底身份（2026-10-24：
+    以前直接 FileNotFoundError 崩，没 git 的机器连台账都建不起来）。
+    """
+    base = ("git", "-C", str(repo)) if repo is not None else ("git",)
+    try:
+        proc = subprocess.run(
+            [*base, *args], capture_output=True, text=True, check=False
+        )
+    except FileNotFoundError:
+        return None
+    if proc.returncode == 0 and proc.stdout.strip():
+        return proc.stdout.strip()
+    return None
+
+
+def git_email(repo: Path | None) -> str | None:
+    """GIT_COMMITTER_IDENT 优先，退回 user.email。"""
+    ident = git_value(repo, "var", "GIT_COMMITTER_IDENT")
+    if ident:
+        m = _IDENT_RE.search(ident)
+        if m and m.group(1).strip():
+            return m.group(1).strip()
+    return git_value(repo, "config", "user.email")
+
+
+def git_name(repo: Path | None) -> str | None:
+    ident = git_value(repo, "var", "GIT_COMMITTER_IDENT")
+    if ident:
+        head = ident.split("<", 1)[0].strip()
+        if head:
+            return head
+    return git_value(repo, "config", "user.name")
+
+
+def fallback_identity() -> str:
+    """不在 git 仓库里时的兜底链：系统用户名 → getpass → 主机名 → 字面 default。"""
+    for key in ("USER", "LOGNAME"):
+        value = os.environ.get(key, "").strip()
+        if value:
+            return value
+    try:
+        name = getpass.getuser().strip()
+    except Exception:  # noqa: BLE001 —— 拿不到用户名是正常分支，不该炸
+        name = ""
+    if name:
+        return name
+    try:
+        host = socket.gethostname().strip()
+    except OSError:
+        host = ""
+    return host or "default"
+
+
+def current(repo: Path | None = None) -> Identity:
+    """当前操作者。邮箱与名字取不到都给兜底，并留一条提示（不打印）。"""
+    email = git_email(repo)
+    if not email:
+        email = fallback_identity()
+        notices.note(
+            f"提示：读不到 git 身份（user.email），本次按兜底身份 {email!r} 记账；"
+            "配好 git config user.email 再跑，任务才会记到正确的名下。"
+        )
+    name = git_name(repo) or email
+    return Identity(email=normalize(email), name=name.strip(), aliases=())

package/scripts/ledgerkit/errors.py

@@ -0,0 +1,15 @@
+"""只放两样东西：业务错误 `Fail`，以及退出码数字。
+
+任何层都可以 import 它；它自己谁也不 import。
+"""
+
+
+class Fail(Exception):
+    """业务错误：抛出即中止，由外壳接住转成「错误：…」并返回对应退出码。"""
+
+
+OK = 0
+BUSINESS = 1  # 业务错：任务不存在、不是你的、参数不合法
+USAGE = 2  # 用法错：argparse 自己会退出，这里留给外壳显式用
+UNEXPECTED = 3  # 未预期异常
+INTERRUPTED = 130  # Ctrl-C / SIGINT

package/scripts/ledgerkit/notices.py

@@ -0,0 +1,28 @@
+"""进程级提示收集器：只收文本，永不打印。
+
+各层都能往里放（数据层读盘时的版本告警、env 的兜底身份、业务层的兜底提示），
+最后由 shell/render.py 一次性打到 stderr。同一句只收一次。
+"""
+
+_seen: set[str] = set()
+_items: list[str] = []
+
+
+def note(text: str) -> None:
+    """收一条提示；重复的同一句自动忽略。"""
+    line = (text or "").strip()
+    if not line or line in _seen:
+        return
+    _seen.add(line)
+    _items.append(line)
+
+
+def warnings() -> tuple[str, ...]:
+    """取当前全部提示（只有 render.py 与 runner.py 能调）。"""
+    return tuple(_items)
+
+
+def clear() -> None:
+    """清空（只有 render.py 与 runner.py 能调）。"""
+    _seen.clear()
+    _items.clear()