git-worklog 1.6.0__py3-none-any.whl

git_worklog/analysis/worktree.py

@@ -0,0 +1,114 @@
+"""Inspect the Git working tree for uncommitted changes.
+
+Only used when ``include_uncommitted`` is on. It classifies changes into
+staged / unstaged / untracked, flags binary and submodule entries, and computes
+a stable working-tree fingerprint the preview state uses to detect drift between
+dry-run and apply.
+
+Uncommitted content may only ever be attributed to *today*: this module does not
+guess historical dates from filesystem mtimes, because a file's mtime says when
+it was last written, not when the work happened.
+
+The git helpers and diff parser come from :mod:`~git_worklog.analysis.history`.
+They were duplicated here while these were two standalone scripts that had to stay
+individually portable; now that both ship in the package that rationale is gone,
+so this module imports them rather than carrying its own copy (#20).
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from git_worklog.analysis import AnalysisError
+# The git helpers and diff parser live in history. They were duplicated here only
+# while these two modules were standalone scripts that had to stay individually
+# portable (#20); now that both ship in the package, that rationale is gone.
+# history's `_parse_raw` returns a fuller entry — it also needs old/new mode and
+# sha for submodule and mode-change detection — and `_diff_files` below reads the
+# subset it needs, so sharing the parser leaves this module's output unchanged.
+# GitError is now the one class, so a working-tree git failure surfaces as
+# GIT_ERROR through the same CLI catch as every other Git call.
+from git_worklog.analysis.history import (  # noqa: F401
+    GitError, _git, _git_ok, _parse_numstat, _parse_raw,
+)
+
+
+def _diff_files(repo: str, cached: bool) -> "list[dict]":
+    base = ["diff", "-M", "-C", "-z"]
+    if cached:
+        base.append("--cached")
+    raw = _parse_raw(_git(repo, [*base, "--raw"]))
+    nums = _parse_numstat(_git(repo, [*base, "--numstat"]))
+    files = []
+    for idx, entry in enumerate(raw):
+        add, dele = nums[idx] if idx < len(nums) else ("-", "-")
+        is_binary = add == "-" and dele == "-"
+        files.append({
+            "status": entry["status"],
+            "path": entry["path"],
+            "old_path": entry["old_path"],
+            "similarity": entry["similarity"],
+            "additions": None if is_binary else int(add or 0),
+            "deletions": None if is_binary else int(dele or 0),
+            "is_binary": is_binary,
+            "is_submodule": entry["is_submodule"],
+        })
+    return files
+
+
+def _untracked(repo: str) -> "list[dict]":
+    out = _git(repo, ["ls-files", "--others", "--exclude-standard", "-z"])
+    paths = [p for p in out.split("\x00") if p]
+    result = []
+    for path in paths:
+        # Sniff for a NUL byte in the first 8 KB, the same heuristic Git uses.
+        try:
+            with open(f"{repo}/{path}", "rb") as fh:
+                is_binary = b"\x00" in fh.read(8000)
+        except OSError:
+            is_binary = False
+        result.append({"status": "A", "path": path, "is_binary": is_binary})
+    return result
+
+
+def _fingerprint(repo: str) -> str:
+    h = hashlib.sha256()
+    h.update(_git(repo, ["status", "--porcelain=v2", "-z"], binary=True))
+    h.update(b"\x00STAGED\x00")
+    h.update(_git(repo, ["diff", "--cached"], binary=True))
+    h.update(b"\x00UNSTAGED\x00")
+    h.update(_git(repo, ["diff"], binary=True))
+    h.update(b"\x00UNTRACKED\x00")
+    for entry in _untracked(repo):
+        h.update(entry["path"].encode("utf-8", "replace"))
+        try:
+            with open(f"{repo}/{entry['path']}", "rb") as fh:
+                h.update(fh.read())
+        except OSError:
+            pass
+        h.update(b"\x00")
+    return h.hexdigest()
+
+
+def inspect(repo: str) -> dict:
+    """Everything uncommitted in ``repo``, plus a fingerprint of that state."""
+    if not _git_ok(repo, ["rev-parse", "--is-inside-work-tree"]):
+        raise AnalysisError("NOT_A_GIT_REPO",
+                            "The target directory is not inside a Git repository.",
+                            path=repo)
+    staged = _diff_files(repo, cached=True)
+    unstaged = _diff_files(repo, cached=False)
+    untracked = _untracked(repo)
+    return {
+        "ok": True,
+        "staged": staged,
+        "unstaged": unstaged,
+        "untracked": untracked,
+        "counts": {
+            "staged": len(staged),
+            "unstaged": len(unstaged),
+            "untracked": len(untracked),
+        },
+        "has_uncommitted": bool(staged or unstaged or untracked),
+        "worktree_fingerprint": _fingerprint(repo),
+    }

git_worklog/cli/__init__.py

@@ -0,0 +1,414 @@
+"""The ``git-worklog`` command.
+
+``version``, ``doctor`` and ``validate`` came first (roadmap §12.1): the things
+you want *before* trusting anything else, none of which need the analysis
+pipeline. ``analyze prepare``/``collect`` (§7) then bracket the pipeline — they
+decide what must be analysed and check what came back, while the analysis itself
+stays with the hosting agent's LLM. The CLI does not replace it and needs no
+model API key (§6.1). ``preview`` and ``apply`` (§10) close the loop: the first
+turns a collected run plus the agent's prose into a frozen payload, the second
+writes that payload and takes no other input. ``coverage`` and ``refs`` serve
+report mode's two questions — "is there an analysis behind these dates?" and
+"which commits is this version actually made of?" — and ``migrate`` (§2.4) moves
+a legacy worklog into the current layout. ``view`` is for reading what all of
+that produced: the worklog as one self-contained page in a browser, read-only.
+
+Every subcommand prints one JSON object to stdout, matching the scripts'
+contract, so the same parsing works everywhere. ``--text`` switches to a
+human-readable rendering for terminal use.
+
+Exit codes:
+    0  ok
+    1  ran fine, but the answer is "no" (doctor found a problem, validate failed)
+    2  the command itself could not run
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from git_worklog import __version__, language
+from git_worklog import markers as wm
+
+
+def _emit(payload: dict, as_text: bool, render) -> None:
+    if as_text:
+        sys.stdout.write(render(payload))
+    else:
+        json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="git-worklog",
+        description="Engineering worklogs from real Git history and code.",
+    )
+    p.add_argument("--version", action="version", version=f"git-worklog {__version__}")
+    p.add_argument("--text", action="store_true",
+                   help="Human-readable output instead of JSON.")
+    p.add_argument("--interface-language", default=None, metavar="TAG",
+                   help="Language for this command's own messages (BCP 47). "
+                        "English only for now; anything else is reported and "
+                        "falls back. Separate from the worklog's content "
+                        "language, which these commands do not set.")
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+
+    sub.add_parser("version", help="Report the CLI, layout and schema versions.")
+
+    d = sub.add_parser("doctor", help="Check that this environment can run the tool.")
+    d.add_argument("--repo", default=".", help="Repository to check (default: cwd).")
+    d.add_argument("--dir", help="Worklog directory (default: <repo>/.git-worklog).")
+
+    v = sub.add_parser("validate", help="Validate a worklog directory.")
+    v.add_argument("--repo", default=".", help="Repository to check (default: cwd).")
+    v.add_argument("--dir", help="Worklog directory (default: <repo>/.git-worklog).")
+
+    a = sub.add_parser("analyze", help="Prepare per-day analysis tasks, and collect them back.")
+    asub = a.add_subparsers(dest="analyze_command", metavar="<prepare|collect>",
+                            required=True)
+
+    prep = asub.add_parser("prepare", help="Mint a run and write one manifest per day.")
+    prep.add_argument("shortcut", nargs="?", metavar="SHORTCUT",
+                      help="Date shortcut: NNd (last N days, e.g. 7d) or a bare "
+                           "YYYY-MM-DD. Alternative to the flags below.")
+    prep.add_argument("--date", metavar="DATE", help="A single day (YYYY-MM-DD).")
+    prep.add_argument("--days", type=int, metavar="N",
+                      help="The last N calendar days, including today.")
+    prep.add_argument("--from", metavar="DATE",
+                      help="First day to analyse (YYYY-MM-DD, inclusive). Needs --to.")
+    prep.add_argument("--to", metavar="DATE",
+                      help="Last day to analyse (YYYY-MM-DD, inclusive). Needs --from.")
+    prep.add_argument("--timezone", metavar="TZ",
+                      help="IANA timezone deciding where each day starts. Detected "
+                           "from the environment when omitted; the run reports "
+                           "which zone it used and where that came from.")
+    prep.add_argument("--today", metavar="DATE",
+                      help="Override today's date (YYYY-MM-DD) for deterministic "
+                           "runs. Affects NNd/--days and where uncommitted work lands.")
+    prep.add_argument("--repo", default=".", help="Repository to read (default: cwd).")
+    prep.add_argument("--dir", help="Worklog directory, read for its config.json "
+                                    f"language setting (default: ./{wm.WORKLOG_DIRNAME}).")
+    prep.add_argument("--run-dir", help="Override the run directory (default: "
+                                        "~/.git-worklog/analysis/<run_id>).")
+    prep.add_argument("--date-field", choices=["committer", "author"],
+                      default="committer",
+                      help="Which date decides day attribution (default: committer).")
+    prep.add_argument("--worklog-dir", default=wm.WORKLOG_DIRNAME,
+                      help="Worklog output directory; commits touching only this "
+                           "directory are excluded as self-referential.")
+    prep.add_argument("--include-uncommitted", action="store_true",
+                      help="Also hand the subagent the working tree's uncommitted "
+                           "changes. They are attributed to today and to no other "
+                           "day; if today is outside --from/--to they are left out "
+                           "and the run says so.")
+    prep.add_argument("--host", metavar="KEY",
+                      help="Detected agent host (anthropic / openai / google). "
+                           "Resolves the subagent model from the packaged config, "
+                           "honouring $GIT_WORKLOG_<HOST>_MODEL and --model. The "
+                           "host is never guessed: unknown or unconfigured is an "
+                           "error, not a fallback to the first provider.")
+    prep.add_argument("--model", default="",
+                      help="Explicit model id, the highest-precedence override. "
+                           "Needs --host.")
+    prep.add_argument("--escalate", action="store_true",
+                      help="Use the host's escalation_model_id. Opt-in only, after "
+                           "the user approves an escalation re-run. Needs --host.")
+    prep.add_argument("--provider", default=None,
+                      help="Subagent provider key, stated rather than resolved "
+                           "(default: anthropic). Use --host instead unless you "
+                           "already hold the model object.")
+    prep.add_argument("--model-json", default="",
+                      help="Structured model object (JSON: {display_name, "
+                           "model_id[, reasoning_effort]}). Goes with --provider.")
+    prep.add_argument("--language", default="auto",
+                      help="Content language for the worklog as a BCP 47 tag "
+                           "(zh-TW, en, ja), or 'auto' to fall through to project "
+                           "config and GIT_WORKLOG_LANGUAGE. Resolved once and "
+                           "stamped on every manifest in the run.")
+    prep.add_argument("--language-source", default=None,
+                      help="Where --language came from, so the manifest records "
+                           "why and not just what: user-request, agent-host, "
+                           "conversation, cli-argument, project-config, "
+                           "environment, system-locale, fallback.")
+
+    coll = asub.add_parser("collect", help="Read and validate a prepared run's results.")
+    coll.add_argument("--run-id", help="The run to collect (from `analyze prepare`).")
+    coll.add_argument("--run-dir", help="The run directory, if it is not "
+                                        "~/.git-worklog/analysis/<run-id>.")
+    coll.add_argument("--repo", default=".",
+                      help="Repository the evidence cites. Every entry is checked "
+                           "against the tree of the commit it names — not the "
+                           "checkout, which holds everything changed since.")
+
+    pv = sub.add_parser("preview", help="Freeze what an apply would write.")
+    pv.add_argument("--run-id", help="The collected run to preview (from "
+                                     "`analyze prepare`).")
+    pv.add_argument("--run-dir", help="The run directory, if it is not "
+                                      "~/.git-worklog/analysis/<run-id>.")
+    pv.add_argument("--repo", default=".", help="Repository to read (default: cwd).")
+    pv.add_argument("--dir", help=f"Worklog directory (default: <repo>/{wm.WORKLOG_DIRNAME}).")
+    pv.add_argument("--input", help="Rendered day files as JSON, or '-' / omit "
+                                    "for stdin: {\"entries\": {\"<date>\": "
+                                    "{\"generated_markdown\": \"...\"}}}.")
+    # Defaulted by the engine, not here: reading the real default would mean
+    # importing git_worklog.preview (and the writer, and Git) on every run,
+    # including `version`, which this parser is built for too.
+    pv.add_argument("--ttl-seconds", type=int, default=None,
+                    help="How long the preview stays applicable (default: 24h).")
+    pv.add_argument("--show", metavar="PREVIEW_ID",
+                    help="Print a stored preview instead of creating one.")
+    pv.add_argument("--check", action="store_true",
+                    help="With --show, also re-read the repository and worklog "
+                         "to report whether the preview is still applicable.")
+    pv.add_argument("--cancel", metavar="PREVIEW_ID",
+                    help="Retire a preview instead of creating one.")
+    pv.add_argument("--now", help="Override current time (ISO 8601) for "
+                                  "deterministic runs.")
+
+    ap = sub.add_parser("apply", help="Write a preview's stored payload.")
+    ap.add_argument("--preview-id", required=True,
+                    help="The preview to apply. This is the only input: the "
+                         "content comes from the record, never from the caller.")
+    ap.add_argument("--now", help="Override current time (ISO 8601) for "
+                                  "deterministic runs.")
+
+    cov = sub.add_parser("coverage",
+                         help="Which dates have a worklog behind them (report mode).")
+    # Two ways in, because report mode has two scopes: a date scope is a range,
+    # a ref scope is whatever days a tag's commits landed on — an arbitrary set.
+    cov.add_argument("shortcut", nargs="?", metavar="SHORTCUT",
+                     help="Date shortcut: NNd or a bare YYYY-MM-DD.")
+    cov.add_argument("--date", metavar="DATE", help="A single day (YYYY-MM-DD).")
+    cov.add_argument("--days", type=int, metavar="N",
+                     help="The last N calendar days, including today.")
+    cov.add_argument("--from", metavar="DATE", help="Range start (inclusive).")
+    cov.add_argument("--to", metavar="DATE", help="Range end (inclusive).")
+    cov.add_argument("--dates", metavar="LIST",
+                     help="Exact days as a comma-separated list, e.g. "
+                          "2026-07-01,2026-07-02. For a ref scope, whose dates "
+                          "are a set with gaps rather than a span.")
+    cov.add_argument("--today", metavar="DATE",
+                     help="Override today's date for deterministic runs.")
+    # Defaulted by the engine, not here: naming the number would mean importing
+    # analysis.coverage (and history, and Git) to build a parser that `version`
+    # also uses. Same reason as --ttl-seconds below.
+    cov.add_argument("--max-days", type=int, default=None,
+                     help="Maximum span in calendar days (default: 90). Higher "
+                          "than generation's 30: report mode reads day files and "
+                          "spawns no subagents, so the cost that cap bounds is "
+                          "not at stake.")
+    cov.add_argument("--repo", default=".", help="Repository to read (default: cwd).")
+    cov.add_argument("--dir", default=wm.WORKLOG_DIRNAME,
+                     help="Worklog directory, absolute or relative to the repo "
+                          f"root (default: {wm.WORKLOG_DIRNAME}).")
+    cov.add_argument("--timezone", default=None,
+                     help="IANA timezone deciding each day's bounds. Detected "
+                          "from the environment when omitted; with --dates it "
+                          "defaults to UTC.")
+    cov.add_argument("--date-field", choices=["committer", "author"],
+                     default="committer",
+                     help="Which date decides day attribution (default: committer).")
+    cov.add_argument("--worklog-dir", default=None,
+                     help="Repo-relative worklog path whose commits count as "
+                          "self-referential and are excluded from the counts.")
+
+    rf = sub.add_parser("refs",
+                        help="Resolve a tag into its commit set (report mode).")
+    rf.add_argument("--tag", help="Tag to report on; its predecessor is found "
+                                  "automatically.")
+    rf.add_argument("--from-ref", help="Explicit range start, exclusive (any ref).")
+    rf.add_argument("--to-ref", help="Explicit range end, inclusive (any ref).")
+    rf.add_argument("--list-tags", action="store_true",
+                    help="List the repository's tags, newest-first.")
+    rf.add_argument("--repo", default=".", help="Repository to read (default: cwd).")
+    rf.add_argument("--timezone", default="UTC",
+                    help="IANA timezone deciding each commit's calendar day "
+                         "(default: UTC).")
+    rf.add_argument("--date-field", choices=["committer", "author"],
+                    default="committer",
+                    help="Which date decides day attribution (default: committer).")
+
+    rp = sub.add_parser("report",
+                        help="Settle a report's scope, coverage and language "
+                             "before it is written (report mode).")
+    # The same two scopes as `coverage`, for the same reason, plus the ref flags
+    # of `refs`: this is the one call that needs both halves at once, because
+    # reconciling a tag's commits against the day files is impossible with
+    # either alone.
+    rp.add_argument("shortcut", nargs="?", metavar="SHORTCUT",
+                    help="Date shortcut: NNd or a bare YYYY-MM-DD.")
+    rp.add_argument("--date", metavar="DATE", help="A single day (YYYY-MM-DD).")
+    rp.add_argument("--days", type=int, metavar="N",
+                    help="The last N calendar days, including today.")
+    rp.add_argument("--from", metavar="DATE", help="Range start (inclusive).")
+    rp.add_argument("--to", metavar="DATE", help="Range end (inclusive).")
+    rp.add_argument("--tag", help="Report on a tag; its predecessor is found "
+                                  "automatically. The commit set is the scope, "
+                                  "not the dates it spans.")
+    rp.add_argument("--from-ref", help="Explicit range start, exclusive (any ref).")
+    rp.add_argument("--to-ref", help="Explicit range end, inclusive (any ref).")
+    rp.add_argument("--language", default="auto",
+                    help="Language to write the report in, as a BCP 47 tag. "
+                         "Independent of the language the day files are written "
+                         "in: zh-TW worklogs can produce an English release "
+                         "report (default: auto).")
+    rp.add_argument("--language-source", default=None,
+                    help="Where --language came from, so the payload records "
+                         "whether a user asked or a default applied.")
+    rp.add_argument("--today", metavar="DATE",
+                    help="Override today's date for deterministic runs.")
+    rp.add_argument("--max-days", type=int, default=None,
+                    help="Maximum span in calendar days (default: 90), as "
+                         "`coverage`. Date scope only.")
+    rp.add_argument("--repo", default=".", help="Repository to read (default: cwd).")
+    rp.add_argument("--dir", default=wm.WORKLOG_DIRNAME,
+                    help="Worklog directory, absolute or relative to the repo "
+                         f"root (default: {wm.WORKLOG_DIRNAME}).")
+    rp.add_argument("--timezone", default=None,
+                    help="IANA timezone deciding each day's bounds. Detected "
+                         "from the environment when omitted; for a ref scope it "
+                         "defaults to UTC.")
+    rp.add_argument("--date-field", choices=["committer", "author"],
+                    default="committer",
+                    help="Which date decides day attribution (default: committer).")
+    rp.add_argument("--worklog-dir", default=None,
+                    help="Repo-relative worklog path whose commits count as "
+                         "self-referential and are excluded from the counts.")
+
+    mg = sub.add_parser("migrate",
+                        help="Move a legacy worklog into .git-worklog/ (dry-run "
+                             "by default).")
+    mg.add_argument("--from-dir", dest="from_dir",
+                    help="Flat legacy worklog directory (v0.2-v0.5).")
+    mg.add_argument("--from-file", dest="from_file",
+                    help="Single-file legacy worklog (pre-v0.2).")
+    mg.add_argument("--dir", help=f"Target worklog directory (default: "
+                                  f"{wm.WORKLOG_DIRNAME}).")
+    mg.add_argument("--timezone",
+                    help="Timezone recorded in config.json, and in each day file's "
+                         "header when migrating from a single file. Ignored for "
+                         "--from-dir, whose day files already record their own.")
+    mg.add_argument("--apply", action="store_true",
+                    help="Write the migration. Without this the run is a dry-run.")
+
+    ri = sub.add_parser("reindex",
+                        help="Rebuild index.md from the day files (dry-run by "
+                             "default). The repair for INDEX_WRITE_FAILED.")
+    ri.add_argument("--dir", help=f"Worklog directory (default: "
+                                  f"{wm.WORKLOG_DIRNAME}).")
+    ri.add_argument("--language", default=None,
+                    help="Language for the index, used only when it does not "
+                         "exist yet. An index that already has one keeps it.")
+    ri.add_argument("--apply", action="store_true",
+                    help="Write index.md. Without this the run is a dry-run.")
+
+    md = sub.add_parser("models",
+                        help="Show the user's subagent model table "
+                             "(~/.git-worklog/provider_models.json), or change "
+                             "one host's models in it (dry-run by default).")
+    md.add_argument("--host", help="The host whose models to change: "
+                                   "anthropic | openai | google.")
+    md.add_argument("--model", help="The host's default subagent model id.")
+    md.add_argument("--display-name", dest="display_name",
+                    help="Human label for --model (default: the model id).")
+    md.add_argument("--reasoning-effort", dest="reasoning_effort",
+                    help="Reasoning effort for --model (openai).")
+    md.add_argument("--escalation-model", dest="escalation_model",
+                    help="The host's escalation model id.")
+    md.add_argument("--escalation-reasoning-effort", dest="escalation_reasoning_effort",
+                    help="Reasoning effort for --escalation-model (openai).")
+    md.add_argument("--apply", action="store_true",
+                    help="Write the change. Without this the run is a dry-run.")
+
+    vw = sub.add_parser("view",
+                        help="Show the worklog as one HTML page in a browser "
+                             "(read-only).")
+    vw.add_argument("--repo", default=".", help="Repository to show (default: cwd).")
+    vw.add_argument("--dir", help=f"Worklog directory (default: <repo>/{wm.WORKLOG_DIRNAME}).")
+    where = vw.add_mutually_exclusive_group()
+    where.add_argument("--output", metavar="FILE",
+                       help="Where to write the page (default: ~/.git-worklog/view/"
+                            "<project>-<hash>.html, the same file every run). "
+                            "Refused inside the worklog directory.")
+    where.add_argument("--serve", action="store_true",
+                       help="Serve the page on 127.0.0.1 instead of writing it, "
+                            "so that it can show each commit's diff. Runs until "
+                            "interrupted (Ctrl+C).")
+    vw.add_argument("--no-open", action="store_true",
+                    help="Write the page without opening a browser.")
+    return p
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    # Imported lazily so `git-worklog version` stays fast and cannot be broken
+    # by an unrelated subcommand's import. Spelled out rather than defaulted:
+    # argparse already rejects an unknown command, so a name reaching here with
+    # no module is a wiring mistake, and it should say so instead of quietly
+    # running whichever subcommand happened to be the fallback.
+    if args.command == "version":
+        from git_worklog.cli import version as cmd
+    elif args.command == "doctor":
+        from git_worklog.cli import doctor as cmd
+    elif args.command == "validate":
+        from git_worklog.cli import validate as cmd
+    elif args.command == "analyze":
+        from git_worklog.cli import analyze as cmd
+    elif args.command == "preview":
+        from git_worklog.cli import preview as cmd
+    elif args.command == "apply":
+        from git_worklog.cli import apply as cmd
+    elif args.command == "coverage":
+        from git_worklog.cli import coverage as cmd
+    elif args.command == "refs":
+        from git_worklog.cli import refs as cmd
+    elif args.command == "report":
+        from git_worklog.cli import report as cmd
+    elif args.command == "migrate":
+        from git_worklog.cli import migrate as cmd
+    elif args.command == "reindex":
+        from git_worklog.cli import reindex as cmd
+    elif args.command == "models":
+        from git_worklog.cli import models as cmd
+    elif args.command == "view":
+        from git_worklog.cli import view as cmd
+    else:
+        raise AssertionError(f"no module wired for command {args.command!r}")
+
+    # §6.2.13 keeps interface language and content language apart. Phase one
+    # ships English messages only -- which the roadmap allows -- but an
+    # unsupported request is answered rather than ignored: silence would look
+    # like it worked.
+    try:
+        interface = language.resolve_interface(args.interface_language)
+    except language.LanguageError as exc:
+        _emit({"ok": False, "errors": [{"code": exc.code, "message": exc.message}]},
+              args.text, lambda p: f"error: {exc.message}\n")
+        return 2
+
+    try:
+        payload, code = cmd.run(args)
+    except Exception as exc:  # never let a traceback replace the JSON contract
+        _emit({"ok": False, "errors": [{
+            "code": "UNEXPECTED_ERROR",
+            "message": f"{type(exc).__name__}: {exc}",
+        }]}, args.text, lambda p: f"error: {exc}\n")
+        return 2
+
+    if interface.warnings:
+        payload.setdefault("warnings", []).extend(interface.warnings)
+    payload.setdefault("interface_language", interface.resolved)
+
+    _emit(payload, args.text, cmd.render_text)
+    # `view --serve` answers first and then stays: the one command that outlives
+    # its own output.
+    after = getattr(cmd, "after_emit", None)
+    return after(args, payload, code) if after else code