git-worklog 1.6.0__py3-none-any.whl

git_worklog/cli/doctor.py

@@ -0,0 +1,348 @@
+"""``git-worklog doctor`` — can this environment actually run the tool?
+
+Each check reports ``ok`` / ``warn`` / ``fail`` with the value it observed, so a
+failure names the thing that is wrong rather than the thing that broke later.
+``fail`` means a real run would not work; ``warn`` means it would work but
+something is worth knowing (a shallow clone limits history, a legacy layout
+needs migrating).
+
+The roadmap's §12.1 list is covered in full, language and index_language
+included. A green check must never imply coverage it does not have, so anything
+this command cannot check says so rather than being silently omitted.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+from git_worklog import config, language
+from git_worklog import markers as wm
+from git_worklog import paths, providers
+
+# git log --since-as-filter, which the collector relies on, landed in 2.37.
+MIN_GIT = (2, 37)
+MIN_PYTHON = (3, 9)
+
+
+def _check(name: str, status: str, detail: str, **extra) -> dict:
+    return {"check": name, "status": status, "detail": detail, **extra}
+
+
+def _git(repo: str, *args: str) -> "tuple[int, str]":
+    try:
+        p = subprocess.run(["git", "-C", repo, *args],
+                           capture_output=True, text=True)
+        return p.returncode, (p.stdout or p.stderr).strip()
+    except OSError as exc:
+        return 127, str(exc)
+
+
+def _check_python() -> dict:
+    v = sys.version_info[:3]
+    got = ".".join(str(x) for x in v)
+    if v[:2] < MIN_PYTHON:
+        return _check("python", "fail",
+                      f"Python {got} is below the {'.'.join(str(x) for x in MIN_PYTHON)} floor.",
+                      value=got)
+    return _check("python", "ok", f"Python {got}.", value=got)
+
+
+def _check_git_version() -> dict:
+    if not shutil.which("git"):
+        return _check("git", "fail", "git was not found on PATH.", value=None)
+    code, out = _git(".", "--version")
+    m = re.search(r"(\d+)\.(\d+)(?:\.(\d+))?", out or "")
+    if code != 0 or not m:
+        return _check("git", "fail", f"Could not read the git version: {out}", value=None)
+    got = tuple(int(g) for g in m.groups(default="0"))
+    text = ".".join(str(x) for x in got)
+    if got[:2] < MIN_GIT:
+        return _check("git", "fail",
+                      f"git {text} is below {'.'.join(str(x) for x in MIN_GIT)}; "
+                      "`git log --since-as-filter` is unavailable.", value=text)
+    return _check("git", "ok", f"git {text}.", value=text)
+
+
+def _check_repo(repo: str) -> "tuple[dict, bool]":
+    code, out = _git(repo, "rev-parse", "--is-inside-work-tree")
+    if code != 0 or out != "true":
+        return _check("repository", "fail",
+                      f"{os.path.abspath(repo)} is not inside a Git work tree.",
+                      value=os.path.abspath(repo)), False
+    return _check("repository", "ok", f"{os.path.abspath(repo)} is a Git work tree.",
+                  value=os.path.abspath(repo)), True
+
+
+def _check_shallow(repo: str) -> dict:
+    code, out = _git(repo, "rev-parse", "--is-shallow-repository")
+    if code != 0:
+        return _check("shallow_clone", "warn", "Could not determine clone depth.")
+    if out == "true":
+        # Not a failure: a shallow clone works, it just cannot see far back, and
+        # a day whose commits were truncated away would look empty rather than
+        # wrong. Better said out loud than discovered in a worklog.
+        return _check("shallow_clone", "warn",
+                      "Shallow clone: history is truncated, so older days may "
+                      "appear to have no commits. `git fetch --unshallow` to fix.",
+                      value=True)
+    return _check("shallow_clone", "ok", "Full clone.", value=False)
+
+
+def _check_worktree(repo: str) -> dict:
+    code, out = _git(repo, "status", "--porcelain")
+    if code != 0:
+        return _check("worktree", "warn", "Could not read the working tree status.")
+    n = len([ln for ln in out.splitlines() if ln.strip()])
+    if n:
+        return _check("worktree", "ok",
+                      f"{n} uncommitted change(s). Analysis covers them only when "
+                      "explicitly asked (include_uncommitted).", value=n)
+    return _check("worktree", "ok", "Clean.", value=0)
+
+
+def _check_worklog_dir(worklog_dir: str) -> dict:
+    if not os.path.isdir(worklog_dir):
+        return _check("worklog_dir", "ok",
+                      f"{worklog_dir} does not exist yet; it is created on first apply.",
+                      value=None)
+    layout = wm.detect_layout(worklog_dir)
+    days = len(wm.list_day_dates(worklog_dir, layout))
+    if layout == wm.LAYOUT_LEGACY:
+        return _check("worklog_dir", "warn",
+                      f"{worklog_dir} uses the pre-v0.6 flat layout ({days} day file(s) "
+                      "at its root). It can be read but not written; run "
+                      "migrate_legacy_worklog.py --from-dir to convert it.",
+                      value=layout, day_count=days)
+    return _check("worklog_dir", "ok",
+                  f"{worklog_dir}: {layout} layout, {days} day file(s).",
+                  value=layout, day_count=days)
+
+
+def _check_config(worklog_dir: str) -> dict:
+    path = wm.config_path(worklog_dir)
+    if not os.path.exists(path):
+        return _check("config", "ok",
+                      "No config.json yet; it is written on first apply.", value=None)
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            cfg = json.load(fh)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        return _check("config", "fail", f"config.json is unreadable: {exc}", value=path)
+    if not isinstance(cfg, dict):
+        return _check("config", "fail", "config.json must contain an object.", value=path)
+    got = cfg.get("schema_version")
+    if got is None:
+        return _check("config", "warn", "config.json has no schema_version.", value=path)
+    if got > wm.LAYOUT_VERSION:
+        return _check("config", "fail",
+                      f"config.json declares schema_version {got}, newer than this "
+                      f"build understands ({wm.LAYOUT_VERSION}). Upgrade git-worklog.",
+                      value=got)
+    return _check("config", "ok", f"config.json: schema_version {got}.", value=got)
+
+
+def _check_language(worklog_dir: str) -> dict:
+    """Whether config's language setting is one this build can honour.
+
+    A bad tag here is worth surfacing now rather than at the point a run dies
+    on it: config.json is edited by hand, and the failure it causes otherwise
+    appears in the middle of an analysis with the diff already collected.
+    """
+    cfg = config.load(worklog_dir)
+    raw = cfg.get("language")
+    if raw is None:
+        return _check("language", "ok",
+                      "No language set; it resolves per run.", value=None)
+    if isinstance(raw, str) and raw.strip().lower() == language.AUTO:
+        return _check("language", "ok",
+                      "language: auto — resolved per run from the request, the "
+                      "environment or English.", value="auto")
+    try:
+        tag = language.normalize(raw)
+    except language.LanguageError as exc:
+        return _check("language", "fail",
+                      f"config.json language: {exc.message}", value=raw)
+    return _check("language", "ok", f"language: {tag}.", value=tag)
+
+
+def _check_index_language(worklog_dir: str) -> dict:
+    """What the index is written in, and whether that is pinned or inherited."""
+    cfg = config.load(worklog_dir)
+    raw = cfg.get("index_language")
+    pinned = None
+    if isinstance(raw, str) and raw.strip() and raw.strip().lower() != language.AUTO:
+        try:
+            pinned = language.normalize(raw)
+        except language.LanguageError as exc:
+            return _check("index_language", "fail",
+                          f"config.json index_language: {exc.message}", value=raw)
+
+    index_path = wm.index_path(worklog_dir)
+    stamped = None
+    if os.path.exists(index_path):
+        try:
+            with open(index_path, "r", encoding="utf-8") as fh:
+                stamped = wm.index_language_of(fh.read())
+        except (OSError, UnicodeDecodeError):
+            stamped = None  # the index's own check owns reporting this
+
+    if pinned:
+        detail = f"index_language: {pinned} (pinned by config)."
+        if stamped and stamped != pinned:
+            detail += (f" The index on disk is {stamped} and will be rebuilt in "
+                       f"{pinned}.")
+        return _check("index_language", "ok", detail, value=pinned)
+    if stamped:
+        return _check("index_language", "ok",
+                      f"index_language: {stamped} (fixed when the index was "
+                      f"first built).", value=stamped)
+    return _check("index_language", "ok",
+                  "index_language: auto — the first build decides.", value="auto")
+
+
+def _check_version_file(worklog_dir: str) -> dict:
+    path = wm.version_path(worklog_dir)
+    if not os.path.exists(path):
+        return _check("layout_version", "ok",
+                      "No VERSION yet; it is written on first apply.", value=None)
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            raw = fh.read().strip()
+        got = int(raw)
+    except (OSError, ValueError) as exc:
+        return _check("layout_version", "fail", f"VERSION is unreadable: {exc}", value=path)
+    if got > wm.LAYOUT_VERSION:
+        return _check("layout_version", "fail",
+                      f"The worklog declares layout version {got}, newer than this "
+                      f"build understands ({wm.LAYOUT_VERSION}). Upgrade git-worklog.",
+                      value=got)
+    return _check("layout_version", "ok", f"Layout version {got}.", value=got)
+
+
+def _check_state_dir() -> dict:
+    home = paths.home()
+    if not os.path.isdir(home):
+        return _check("state_dir", "ok",
+                      f"{home} does not exist yet; it is created on first preview.",
+                      value=home)
+    if not os.access(home, os.W_OK | os.X_OK):
+        return _check("state_dir", "fail",
+                      f"{home} is not writable; previews cannot be recorded.", value=home)
+    mode = os.stat(home).st_mode & 0o777
+    if os.name == "posix" and mode & 0o077:
+        # These files quote source and diffs from private repositories.
+        return _check("state_dir", "warn",
+                      f"{home} is mode {mode:03o}; it holds code excerpts, so 700 is "
+                      "advisable.", value=home, mode=f"{mode:03o}")
+    return _check("state_dir", "ok", f"{home} is writable.", value=home,
+                  mode=f"{mode:03o}")
+
+
+def _check_legacy_state_dir() -> dict:
+    legacy = paths.legacy_home()
+    if os.path.isdir(legacy) and os.path.abspath(legacy) != os.path.abspath(paths.home()):
+        return _check("legacy_state_dir", "warn",
+                      f"{legacy} is left over from before v0.7. Nothing reads it now — "
+                      "previews there have long expired. Delete it when convenient.",
+                      value=legacy)
+    return _check("legacy_state_dir", "ok", "No leftover state directory.", value=None)
+
+
+def _check_provider_models() -> dict:
+    """The user's model table against the defaults this version ships.
+
+    Differing is not a fault -- editing that file is how a model is changed --
+    so it is a warning that names each difference: the same list serves someone
+    who edited on purpose and someone whose copy an upgrade has left behind.
+    """
+    path = paths.models_path()
+    if not os.path.exists(path):
+        return _check("provider_models", "ok",
+                      f"{path} does not exist yet; it is created from the shipped "
+                      "defaults the first time a model is resolved. Those may be "
+                      "older than what your host offers: `git-worklog models` sets "
+                      "the current ones.", value=path)
+    try:
+        user = providers.load_config(path)
+    except providers.ProviderError as exc:
+        return _check("provider_models", "fail",
+                      f"{exc.message} Fix it, or delete it to start again from the "
+                      "shipped defaults.", value=path)
+    differ = providers.differences(user, providers.load_config())
+    if not differ:
+        return _check("provider_models", "ok",
+                      f"{path} matches the shipped defaults.", value=path)
+    listed = "; ".join(f"{d['provider']}.{d['field']}: yours {d['yours']!r}, "
+                       f"shipped {d['shipped']!r}" for d in differ)
+    return _check("provider_models", "warn",
+                  f"{path} differs from the shipped defaults ({listed}). Your file "
+                  "is the one used; edit it if these are not the models you want.",
+                  value=path, differences=differ)
+
+
+def _check_skill_compat() -> dict:
+    from git_worklog.cli.version import SKILL_COMPAT_VERSION
+    skill_md = os.path.join(os.path.dirname(os.path.dirname(
+        os.path.dirname(os.path.abspath(__file__)))), "SKILL.md")
+    if not os.path.exists(skill_md):
+        # A pip-only install has no skill body; that is a valid way to use the CLI.
+        return _check("skill_compat", "ok",
+                      "No SKILL.md alongside the package (CLI-only install).",
+                      value=None)
+    return _check("skill_compat", "ok",
+                  f"Skill body found; compat version {SKILL_COMPAT_VERSION}.",
+                  value=SKILL_COMPAT_VERSION)
+
+
+def run(args) -> "tuple[dict, int]":
+    repo = args.repo or "."
+    worklog_dir = args.dir or os.path.join(repo, wm.WORKLOG_DIRNAME)
+
+    checks = [_check_python(), _check_git_version()]
+    repo_check, in_repo = _check_repo(repo)
+    checks.append(repo_check)
+    if in_repo:
+        checks.append(_check_shallow(repo))
+        checks.append(_check_worktree(repo))
+    checks.append(_check_worklog_dir(worklog_dir))
+    checks.append(_check_version_file(worklog_dir))
+    checks.append(_check_config(worklog_dir))
+    checks.append(_check_state_dir())
+    checks.append(_check_legacy_state_dir())
+    checks.append(_check_provider_models())
+    checks.append(_check_skill_compat())
+    checks.append(_check_language(worklog_dir))
+    checks.append(_check_index_language(worklog_dir))
+
+    failed = [c for c in checks if c["status"] == "fail"]
+    warned = [c for c in checks if c["status"] == "warn"]
+    return {
+        "ok": not failed,
+        "repo": os.path.abspath(repo),
+        "worklog_dir": os.path.abspath(worklog_dir),
+        "checks": checks,
+        "failed": [c["check"] for c in failed],
+        "warnings": [c["check"] for c in warned],
+    }, (1 if failed else 0)
+
+
+_GLYPH = {"ok": "✓", "warn": "!", "fail": "✗", "skipped": "-"}
+
+
+def render_text(p: dict) -> str:
+    lines = [f"git-worklog doctor — {p['repo']}", ""]
+    for c in p["checks"]:
+        lines.append(f"  {_GLYPH.get(c['status'], '?')} {c['check']:<18} {c['detail']}")
+    lines.append("")
+    if p["failed"]:
+        lines.append(f"FAILED: {', '.join(p['failed'])}")
+    elif p["warnings"]:
+        lines.append(f"OK, with warnings: {', '.join(p['warnings'])}")
+    else:
+        lines.append("All checks passed.")
+    return "\n".join(lines) + "\n"

git_worklog/cli/migrate.py

@@ -0,0 +1,43 @@
+"""``git-worklog migrate`` — move a legacy worklog into ``.git-worklog/``.
+
+On the CLI surface since roadmap §2.4, and never part of a normal run: it is
+invoked explicitly or not at all. Dry-run is the default, which is why ``--apply``
+exists rather than a ``--dry-run`` flag — the safe direction is the one you get
+by not thinking about it.
+
+It never deletes the source and never overwrites a day file that already exists.
+Corrupt legacy markers end the run rather than produce a half-migrated worklog:
+the engine (:mod:`git_worklog.migrate`) refuses instead of guessing a repair.
+"""
+
+from __future__ import annotations
+
+from git_worklog import migrate as engine
+
+
+def run(args) -> "tuple[dict, int]":
+    try:
+        return engine.run(from_dir=args.from_dir, from_file=args.from_file,
+                          dir=args.dir, timezone=args.timezone,
+                          apply=args.apply), 0
+    except engine.MigrateError as exc:
+        return {"ok": False, "errors": [exc.as_error()]}, 2
+
+
+def render_text(p: dict) -> str:
+    if not p.get("ok"):
+        return "".join(f"error: {e['message']}\n" for e in p.get("errors", []))
+
+    lines = [f"git-worklog migrate — {p['mode']}\n"]
+    lines.append(f"  source : {p['source']}  ({p['source_kind']})\n")
+    lines.append(f"  target : {p['worklog_dir']}\n\n")
+
+    for change in p["planned_changes"]:
+        mark = "+" if change["action"] == "create" else "="
+        note = "" if change["action"] == "create" else "  (exists, left alone)"
+        lines.append(f"  {mark} {change['date']}{note}\n")
+    if not p["planned_changes"]:
+        lines.append("  nothing to migrate\n")
+
+    lines.append(f"\n{p['note']}\n")
+    return "".join(lines)

git_worklog/cli/models.py

@@ -0,0 +1,112 @@
+"""``git-worklog models`` — read or change the user's subagent model table.
+
+The table is ``~/.git-worklog/provider_models.json``
+(:mod:`git_worklog.providers`): the user's file, seeded from the shipped
+defaults and never rewritten behind their back. This command is the same edit
+they could make by hand, for when the one making it is a coding agent that
+knows which models its own host currently offers -- so a new model does not
+wait for a release of this tool.
+
+With no ``--host`` it only reports: where the file is, what each host resolves
+to, and where that differs from the shipped defaults. With ``--host`` and at
+least one field it shows the change, and writes it only with ``--apply`` --
+dry-run first, like every other command here that writes. It changes the one
+host it is given and leaves every other key of the file as it found it.
+
+It does not check that a model id exists. Only the host can say that, at
+dispatch time, and an id it rejects still halts the run and asks
+(``model_unavailable_policy``); nothing is substituted.
+"""
+
+from __future__ import annotations
+
+import os
+
+from git_worklog import paths, providers
+
+# argparse destination -> the table's field.
+FIELDS = (
+    ("model", "model_id"),
+    ("display_name", "display_name"),
+    ("reasoning_effort", "reasoning_effort"),
+    ("escalation_model", "escalation_model_id"),
+    ("escalation_reasoning_effort", "escalation_reasoning_effort"),
+)
+
+
+NOT_CREATED = ("The file does not exist yet, so these are the defaults shipped with "
+               "this version and may be older than the models the host offers now. "
+               "Set the current ones with --host <host> --model <id> --apply.")
+
+
+def _fail(code: str, message: str, **extra) -> "tuple[dict, int]":
+    return {"ok": False, "errors": [{"code": code, "message": message, **extra}]}, 2
+
+
+def run(args) -> "tuple[dict, int]":
+    path = paths.models_path()
+    exists = os.path.exists(path)
+    try:
+        shipped = providers.load_config()
+        current = providers.load_config(path) if exists else providers.seed()
+    except providers.ProviderError as exc:
+        return {"ok": False, "errors": [exc.as_error()]}, 2
+
+    changes = {field: getattr(args, dest) for dest, field in FIELDS if getattr(args, dest)}
+    common = {"ok": True, "path": path, "exists": exists}
+    if not args.host:
+        if changes or args.apply:
+            return _fail("ARG_CONFLICT", "--host says whose model to change; "
+                                         "without it this command only reports.")
+        return {**common, "mode": "show", "providers": current["providers"],
+                "differences": providers.differences(current, shipped),
+                **({} if exists else {"note": NOT_CREATED})}, 0
+    if args.host not in providers.VALID_HOSTS:
+        return _fail("UNKNOWN_HOST", f"Unknown host '{args.host}'.",
+                     requested_host=args.host, valid_hosts=list(providers.VALID_HOSTS))
+    if not changes:
+        return _fail("ARG_CONFLICT", "Nothing to change: pass --model, "
+                                     "--escalation-model or another field.")
+
+    before = dict(current["providers"].get(args.host) or {})
+    # A new default model under the old model's name would be a label that lies.
+    if "model_id" in changes and "display_name" not in changes \
+            and changes["model_id"] != before.get("model_id"):
+        changes["display_name"] = changes["model_id"]
+    after = dict(before, **changes)
+    changed = sorted(f for f in after if after[f] != before.get(f))
+    payload = {**common, "host": args.host, "before": before, "after": after,
+               "changed": changed}
+    if not args.apply:
+        return {**payload, "mode": "dry-run",
+                "note": "Nothing was written. Re-run with --apply to write it."}, 0
+    if changed or not exists:
+        updated = dict(current, providers=dict(current["providers"], **{args.host: after}))
+        try:
+            providers.write_user_config(updated)
+        except OSError as exc:
+            return _fail("IO_ERROR", f"{path} could not be written: {exc}", target=path)
+    return {**payload, "mode": "apply", "exists": True}, 0
+
+
+def render_text(p: dict) -> str:
+    if not p.get("ok"):
+        return "".join(f"error: {e['message']}\n" for e in p.get("errors", []))
+    lines = [f"git-worklog models — {p['path']}"
+             + ("" if p["exists"] else " (not created yet; shipped defaults shown)")]
+    if p["mode"] == "show":
+        for host, entry in p["providers"].items():
+            lines.append(f"  {host}: {entry.get('model_id')}"
+                         f"  (escalation: {entry.get('escalation_model_id')})")
+        lines.extend(f"  differs from shipped — {d['provider']}.{d['field']}: "
+                     f"yours {d['yours']!r}, shipped {d['shipped']!r}"
+                     for d in p["differences"])
+        return "\n".join(lines) + "\n"
+    for field in p["changed"]:
+        lines.append(f"  {p['host']}.{field}: {p['before'].get(field)!r} -> "
+                     f"{p['after'][field]!r}")
+    if not p["changed"]:
+        lines.append(f"  {p['host']}: already set; nothing to change")
+    lines.append("  written" if p["mode"] == "apply"
+                 else "  dry-run: nothing written (re-run with --apply)")
+    return "\n".join(lines) + "\n"

git_worklog/cli/preview.py

@@ -0,0 +1,124 @@
+"""``git-worklog preview`` — freeze what apply will write (roadmap §10.2).
+
+Takes a collected run and the day prose the agent's LLM wrote for it, computes
+every target file's final text, and stores the lot as one immutable record. What
+comes back is a summary and a ``preview_id``; the bytes are on disk, not in the
+conversation, and :mod:`git_worklog.cli.apply` writes them from there.
+
+``--show`` and ``--cancel`` share this command because they act on the thing it
+made. Creation is the bare form, matching §10.2, because it is the one on the
+hot path — a skill runs it every time and reads the other two almost never.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from git_worklog import preview as pv
+from git_worklog import writer
+from git_worklog.analysis import AnalysisError
+from git_worklog.analysis import results as ar
+
+
+def _load_entries(path: "str | None") -> dict:
+    # Reading a TTY here would hang waiting for a human who was never asked to
+    # type a worklog. The same guard rebuild_worklog_index.py needs.
+    if path is None and sys.stdin.isatty():
+        return {}
+    raw = (open(path, "r", encoding="utf-8").read()
+           if path and path != "-" else sys.stdin.read())
+    if not raw.strip():
+        return {}
+    payload = json.loads(raw)
+    entries = payload.get("entries")
+    if not isinstance(entries, dict):
+        raise pv.PreviewError(
+            "NO_ENTRIES",
+            "Pass the rendered day files as {\"entries\": {\"<date>\": "
+            "{\"generated_markdown\": \"...\"}}} on stdin or via --input.")
+    return entries
+
+
+def _run_dir_for(args) -> str:
+    if args.run_dir:
+        return args.run_dir
+    if not args.run_id:
+        raise AnalysisError("NO_RUN",
+                            "Pass --run-id (from `analyze prepare`) or --run-dir.")
+    return os.path.join(ar.analysis_dir(), args.run_id)
+
+
+def _create(args) -> "tuple[dict, int]":
+    entries = _load_entries(args.input)
+    record = pv.build(
+        run_dir=_run_dir_for(args), entries=entries, repo=args.repo,
+        worklog_dir=args.dir, ttl_seconds=args.ttl_seconds,
+        now=pv.now_utc(args.now),
+    )
+    state_path = pv.save(record)
+    payload = pv.public(record)
+    payload.update({"ok": True, "state_path": state_path})
+    # The full text of every file, returned once so the caller can show the user
+    # what they are approving. Apply never asks for it again.
+    payload["previews"] = {d["date"]: d["content"] for d in record["payload"]["days"]}
+    payload["index_preview"] = record["payload"]["index"]["content"]
+    return payload, 0
+
+
+def _show(args) -> "tuple[dict, int]":
+    record = pv.load(args.show)
+    verdict = pv.evaluate(record, pv.snapshot(record) if args.check else None,
+                          pv.now_utc(args.now))
+    payload = pv.public(record)
+    payload.update({"ok": True, **verdict})
+    return payload, (0 if verdict["applicable"] or not args.check else 1)
+
+
+def _cancel(args) -> "tuple[dict, int]":
+    record = pv.cancel(pv.load(args.cancel), pv.now_utc(args.now))
+    payload = pv.public(record)
+    payload.update({"ok": True})
+    return payload, 0
+
+
+def run(args) -> "tuple[dict, int]":
+    try:
+        if args.show:
+            return _show(args)
+        if args.cancel:
+            return _cancel(args)
+        return _create(args)
+    except (pv.PreviewError, writer.WriterError, AnalysisError) as exc:
+        return {"ok": False, "errors": [
+            {"code": exc.code, "message": exc.message, **exc.extra}]}, 2
+    except json.JSONDecodeError as exc:
+        return {"ok": False, "errors": [
+            {"code": "IO_ERROR", "message": f"Entries are not valid JSON: {exc}"}]}, 2
+
+
+def render_text(p: dict) -> str:
+    if not p.get("ok"):
+        return "".join(f"error: {e['message']}\n" for e in p.get("errors", []))
+
+    lines = [f"preview {p['preview_id']}  ({p.get('state', pv.PREVIEWED)})\n"]
+    lang = p.get("language") or {}
+    if lang.get("resolved"):
+        lines.append(f"  language : {lang['resolved']} (via {lang.get('source')})\n")
+    lines.append(f"  expires  : {p['expires_at']}\n")
+    if p.get("reason"):
+        lines.append(f"  reason   : {p['reason']}\n")
+    lines.append("\n")
+    for f in p.get("files", []):
+        lines.append(f"  {f['action']:9} {f['path']}\n")
+    if p.get("not_written"):
+        lines.append(f"\n  analysed but not written: {', '.join(p['not_written'])}\n")
+    for w in p.get("warnings", []):
+        lines.append(f"  warning: {w.get('message', w)}\n")
+    for m in p.get("mismatches", []):
+        lines.append(f"  changed: {m['field']}\n")
+    if p.get("state_path"):
+        lines.append("\nNo files have been modified. Apply with "
+                     f"`git-worklog apply --preview-id {p['preview_id']}`.\n")
+    return "".join(lines)