git-worklog 1.6.0__py3-none-any.whl

git_worklog/cli/view.py

@@ -0,0 +1,218 @@
+"""``git-worklog view`` — the worklog as one page in a browser.
+
+Read-only, like ``validate``: nothing in the repository or its worklog is
+written. The page is derived from the day files every time
+(:mod:`git_worklog.viewer`) and lands outside the repository, in
+``~/.git-worklog/view/``, under a name fixed per worklog -- so re-running the
+command and reloading the tab is how the page refreshes. The file is
+owner-only because it embeds the whole worklog, quotes from the source
+included.
+
+Git is asked, read-only, about the commits the worklog cites, so a hash on the
+page opens its commit. The repository asked is the directory the worklog sits
+in -- the same one the page is named for -- not the cwd, which with ``--dir``
+may be another project altogether.
+
+``--serve`` keeps the command running as a local server
+(:mod:`git_worklog.viewserver`) instead of writing a file, which is what lets
+the page show diffs. The JSON still comes first and whole: ``run`` binds the
+port and opens the browser, the answer is printed, and only then does
+``after_emit`` start answering requests, until it is interrupted.
+
+Opening a browser is best effort and can never cost the JSON contract. Python's
+``webbrowser`` starts some browsers as child processes that inherit stdout, so
+for the length of the call stdout points at stderr. And on Linux with no
+display, ``webbrowser`` falls back to terminal browsers (lynx, w3m) whenever
+``TERM`` is set -- which an agent's shell sets -- and runs them in the
+foreground, where they would sit waiting for keys nobody will press. There the
+page is written and the browser is not started; the answer says so and exits 0,
+because the page is what the command promised.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import sys
+import webbrowser
+from pathlib import Path
+
+from git_worklog import markers as wm
+from git_worklog import paths, viewer, viewserver, writer
+
+NOTE = ("The page embeds the whole worklog, quotes from the source included, and "
+        "is written owner-only. Share it only where the source may be read.")
+SERVE_NOTE = ("Serving on 127.0.0.1 until interrupted (Ctrl+C). The page shows "
+              "diffs, which are source code. The URL holds this run's access "
+              "token: it stays in the browser's history and in this output, "
+              "and stops working when the server does.")
+
+
+def _default_output(worklog_dir: str) -> str:
+    """One stable file per worklog: named for its project, keyed by its path.
+
+    The project is the directory holding the worklog, not the cwd: the skill runs
+    every command from its own directory, which would name every page after it.
+    """
+    real = os.path.realpath(worklog_dir)
+    project = re.sub(r"[^A-Za-z0-9._-]+", "-", os.path.basename(os.path.dirname(real)))
+    project = project.strip("-.") or "worklog"
+    digest = hashlib.sha256(real.encode("utf-8")).hexdigest()[:8]
+    return os.path.join(paths.view_dir(), f"{project}-{digest}.html")
+
+
+def _inside(path: str, directory: str) -> bool:
+    path, directory = os.path.realpath(path), os.path.realpath(directory)
+    try:
+        return os.path.commonpath([path, directory]) == directory
+    except ValueError:      # different drives on Windows
+        return False
+
+
+def _open_quietly(url: str) -> "str | None":
+    """Open ``url`` in a browser. None when it opened, else why it did not."""
+    if sys.platform.startswith("linux") and not any(
+            os.environ.get(v) for v in ("DISPLAY", "WAYLAND_DISPLAY", "BROWSER")):
+        return "there is no display to open a browser on"
+    sys.stdout.flush()
+    saved = os.dup(1)
+    try:
+        os.dup2(2, 1)
+        opened = webbrowser.open(url)
+    finally:
+        os.dup2(saved, 1)
+        os.close(saved)
+    return None if opened else "no browser could be started"
+
+
+def run(args) -> "tuple[dict, int]":
+    repo = args.repo or "."
+    worklog_dir = args.dir or os.path.join(repo, wm.WORKLOG_DIRNAME)
+    target = os.path.abspath(worklog_dir)
+
+    if not os.path.isdir(worklog_dir):
+        return {"ok": False, "worklog_dir": target, "errors": [{
+            "code": "NOT_FOUND", "message": f"{target} does not exist.",
+            "target": target}]}, 2
+    # The page may go anywhere but into the worklog it shows:
+    # `--output .git-worklog/index.md` would replace the index with HTML.
+    if args.output and _inside(args.output, worklog_dir):
+        out = os.path.abspath(args.output)
+        return {"ok": False, "worklog_dir": target, "errors": [{
+            "code": "OUTPUT_INSIDE_WORKLOG",
+            "message": f"{out} is inside the worklog directory {target}; "
+                       "view never writes there.",
+            "target": out}]}, 2
+
+    # Where the worklog lives, which is where its commits are.
+    repo_dir = os.path.dirname(os.path.realpath(worklog_dir))
+    if getattr(args, "serve", False):
+        return _serve(args, worklog_dir, target, repo_dir)
+
+    try:
+        page, info = viewer.build(worklog_dir, repo=repo_dir)
+        if args.output:
+            out = os.path.abspath(args.output)
+        else:
+            # Created first, owner-only: atomic_write would create it too, but
+            # with default permissions, and this directory holds private text.
+            paths.ensure_dir(paths.view_dir())
+            out = _default_output(worklog_dir)
+        writer.atomic_write(out, page, lambda _text: None, prefix=".rw-view-")
+    except OSError as exc:
+        return {"ok": False, "worklog_dir": target, "errors": [{
+            "code": "IO_ERROR", "message": str(exc)}]}, 2
+
+    url = Path(out).as_uri()
+    warnings = list(info["warnings"])
+    opened = _open(args, url, f"The page was written, but {{}}. Open {out}.", out, warnings)
+    return {
+        "ok": True,
+        "worklog_dir": target,
+        "layout": info["layout"],
+        "output": out,
+        "url": url,
+        "opened": opened,
+        "day_count": info["day_count"],
+        "commit_count": info["commit_count"],
+        "range": info["range"],
+        "warnings": warnings,
+        "note": NOTE,
+    }, 0
+
+
+def _open(args, url: str, message: str, target: str, warnings: list) -> bool:
+    """Open ``url`` unless told not to; a browser that will not start is a warning."""
+    if args.no_open:
+        return False
+    reason = _open_quietly(url)
+    if reason:
+        warnings.append({"code": "BROWSER_NOT_OPENED",
+                         "message": message.format(reason), "target": target})
+    return reason is None
+
+
+def _serve(args, worklog_dir: str, target: str, repo_dir: str) -> "tuple[dict, int]":
+    """Bind, build once and answer; :func:`after_emit` does the serving."""
+    server = None
+    try:
+        server = viewserver.Server(worklog_dir, repo_dir)
+        _page, info = server.page()
+    except OSError as exc:
+        if server is not None:
+            server.server_close()
+        return {"ok": False, "worklog_dir": target, "errors": [{
+            "code": "IO_ERROR", "message": str(exc)}]}, 2
+    args.server = server
+    url = server.url
+    warnings = list(info["warnings"])
+    # The socket is already listening, so a browser that is quicker than
+    # after_emit just waits in the backlog.
+    opened = _open(args, url, f"The page is being served, but {{}}. Open {url}.", url,
+                   warnings)
+    return {
+        "ok": True,
+        "worklog_dir": target,
+        "layout": info["layout"],
+        "output": None,
+        "url": url,
+        "serving": True,
+        "opened": opened,
+        "day_count": info["day_count"],
+        "commit_count": info["commit_count"],
+        "range": info["range"],
+        "warnings": warnings,
+        "note": SERVE_NOTE,
+    }, 0
+
+
+def after_emit(args, payload: dict, code: int) -> int:
+    """Serve until interrupted, once the answer is out."""
+    server = getattr(args, "server", None)
+    if server is None:
+        return code
+    # A pipe is block-buffered: unflushed, the reader would wait for a URL that
+    # is only printed when the server stops.
+    sys.stdout.flush()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 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", []))
+    head = f"git-worklog view — {p['day_count']} day file(s)"
+    if p["range"]:
+        head += f", {p['range']['from']} → {p['range']['to']}"
+    lines = [head, f"  {p['output'] or 'serving ' + p['url']}",
+             "  opened in your browser" if p["opened"] else f"  open: {p['url']}"]
+    if p.get("serving"):
+        lines.append("  press Ctrl+C to stop")
+    lines.extend(f"  warning: {w['message']}" for w in p["warnings"])
+    return "\n".join(lines) + "\n"

git_worklog/config.py

@@ -0,0 +1,79 @@
+"""Reading ``.git-worklog/config.json`` (roadmap §4.4, §6.2.7).
+
+Until the language contract there was no reader at all: ``markers.render_config``
+wrote the file on first apply and only ``schema_version`` was ever read back, by
+``doctor`` and ``validate``, to check the layout was not from the future. This
+module is the first code to treat config as *settings* rather than as a version
+stamp.
+
+Two facts about the file shape everything here:
+
+``ensure_data_dir`` never rewrites an existing config. Every worklog created
+since the ``.git-worklog/`` layout landed already carries ``"language": "auto"``
+and ``"index_language": "auto"``, written by builds that ignored both. So
+``"auto"`` on disk cannot be read as a choice — it is indistinguishable from a
+file the user has never opened, and means exactly "nobody has decided".
+
+The file is the user's. A malformed config is reported by ``doctor`` and
+``validate``, which exist for that; it does not entitle this module to rewrite
+it, and an unreadable one degrades to "no preference" rather than stopping a
+run — losing a config override is a smaller failure than refusing to write a
+worklog at all.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from git_worklog import markers as wm
+from git_worklog.language import AUTO
+
+
+def load(worklog_dir: str) -> dict:
+    """The config object, or ``{}`` when absent, unreadable or malformed."""
+    path = wm.config_path(worklog_dir)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError, UnicodeDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _setting(config: dict, key: str) -> "str | None":
+    """A configured string, or None for absent/``auto``/wrong-typed."""
+    value = config.get(key)
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    if not value or value.lower() == AUTO:
+        return None
+    return value
+
+
+def language(config: dict) -> "str | None":
+    """The project's content-language override, if it set one (§6.2.7)."""
+    return _setting(config, "language")
+
+
+def index_language(config: dict) -> "str | None":
+    """The project's fixed index language, if it set one (§6.2.12).
+
+    ``auto`` here does not mean "no index language" — it means the index keeps
+    whichever language it was first built in, which is recorded in the index
+    file itself rather than written back here.
+    """
+    return _setting(config, "index_language")
+
+
+def timezone(config: dict) -> "str | None":
+    """The project's timezone override, if it set one."""
+    return _setting(config, "timezone")
+
+
+def find(repo: str = ".", worklog_dir: "str | None" = None) -> dict:
+    """Load the config for a repository, honouring an explicit ``--dir``."""
+    if worklog_dir is None:
+        worklog_dir = os.path.join(repo, wm.WORKLOG_DIRNAME)
+    return load(worklog_dir)

git_worklog/data/provider_models.json

@@ -0,0 +1,34 @@
+{
+  "_comment": "Subagent model selection per host — SINGLE SOURCE OF TRUTH. The skill selects the provider it is currently running under and passes that provider's model_id to every spawned day / code-analysis subagent. Defaults prioritise cost efficiency for bounded, per-day repository analysis. Do NOT silently replace these models with more expensive ones. Resolved by git_worklog/providers.py (`git-worklog analyze prepare --host <key>`); mirrored (human-facing) in references/provider-models.md. It lives inside the package, not in a sibling config/ directory, because only git_worklog* is packaged — from outside, an installed CLI could not read it.",
+  "providers": {
+    "anthropic": {
+      "display_name": "Claude Haiku 4.5",
+      "model_id": "claude-haiku-4-5",
+      "escalation_model_id": "claude-sonnet-5-5"
+    },
+    "openai": {
+      "display_name": "GPT-6 Luna",
+      "model_id": "gpt-6-luna",
+      "reasoning_effort": "low",
+      "escalation_model_id": "gpt-6.1-sol",
+      "escalation_reasoning_effort": "medium"
+    },
+    "google": {
+      "display_name": "Gemini 3.8 Flash",
+      "model_id": "gemini-3.8-flash",
+      "escalation_model_id": "gemini-3.1-pro-preview"
+    }
+  },
+  "model_unavailable_policy": "halt-and-ask",
+  "escalation_policy": {
+    "automatic": false,
+    "suggest_when": [
+      "analysis_incomplete",
+      "confidence_unknown",
+      "conflicting_evidence",
+      "merge_result_unresolved",
+      "revert_final_state_unclear",
+      "required_code_context_unreadable"
+    ]
+  }
+}

git_worklog/dates.py

@@ -0,0 +1,237 @@
+"""Resolve Git Worklog date parameters into a canonical per-day range.
+
+This is the deterministic date contract (roadmap §6.1): natural language is
+normalised into standard parameters by the model *before* anything here runs, so
+this module never interprets free text. It only accepts the canonical parameters
+(``date`` / ``days`` / ``from_`` / ``to``) plus the ``NNd`` / bare-date
+shortcuts.
+
+The logic lives in the package rather than in ``scripts/`` because only
+``git_worklog*`` is packaged: an installed CLI has no ``scripts/`` directory to
+shell out to, so anything the CLI needs has to be importable, and the two front
+ends must not drift apart.
+
+The per-day boundary uses a half-open interval ``[local 00:00, next 00:00)`` so
+that millisecond precision and DST transitions never create gaps or overlaps.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import date as date_cls, datetime, timedelta
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+# Default span cap. It exists to bound per-day subagent cost, so it governs
+# worklog generation and backfill. Report mode only reads day files already on
+# disk and spawns no subagents, so it overrides this with its own max_days.
+MAX_DAYS = 30
+
+_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_SHORTCUT_DAYS_RE = re.compile(r"^(\d+)d$")
+
+
+class DateError(ValueError):
+    """A date parameter that cannot be honoured, carrying the wire code.
+
+    Mirrors :class:`git_worklog.language.LanguageError` and
+    :class:`git_worklog.analysis.AnalysisError`: the callers are thin shells (a
+    script and, later, a CLI subcommand) that both owe the user one JSON object
+    with a stable ``code``, so the code belongs on the exception rather than
+    being re-derived from the message at each call site.
+    """
+
+    def __init__(self, code: str, message: str, **extra):
+        self.code = code
+        self.message = message
+        self.extra = extra
+        super().__init__(message)
+
+    def as_error(self) -> dict:
+        """The error dict as it goes on the wire."""
+        return {"code": self.code, "message": self.message, **self.extra}
+
+
+def detect_timezone(override: "str | None") -> "tuple[ZoneInfo, str, str]":
+    """Resolve the timezone following the documented priority order.
+
+    Returns ``(tzinfo, iana_name, source)``. ``source`` records where the value
+    came from so the dry-run summary can be transparent about it.
+    """
+    if override:
+        try:
+            return ZoneInfo(override), override, "explicit"
+        except ZoneInfoNotFoundError:
+            raise DateError("INVALID_TIMEZONE",
+                            f"Unknown IANA timezone: {override!r}.")
+
+    tz_env = os.environ.get("TZ")
+    if tz_env:
+        try:
+            return ZoneInfo(tz_env), tz_env, "env:TZ"
+        except ZoneInfoNotFoundError:
+            pass
+
+    localtime = "/etc/localtime"
+    if os.path.islink(localtime):
+        target = os.path.realpath(localtime)
+        marker = "/zoneinfo/"
+        if marker in target:
+            name = target.split(marker, 1)[1]
+            try:
+                return ZoneInfo(name), name, "system:/etc/localtime"
+            except ZoneInfoNotFoundError:
+                pass
+
+    # Last resort: a fixed offset with no IANA name. The orchestrator should
+    # surface this and, per the contract, may ask the user to specify one.
+    local = datetime.now().astimezone().tzinfo
+    name = getattr(local, "key", None) or (local.tzname(None) if local else "UTC") or "UTC"
+    return local, name, "system-offset"
+
+
+def _parse_iso_date(value: str, field: str) -> date_cls:
+    if not _DATE_RE.match(value):
+        raise DateError("INVALID_DATE",
+                        f"{field} must be formatted as YYYY-MM-DD (got {value!r}).",
+                        field=field, value=value)
+    try:
+        return date_cls.fromisoformat(value)
+    except ValueError:
+        raise DateError("INVALID_DATE",
+                        f"{field} is not a real calendar date: {value!r}.",
+                        field=field, value=value)
+
+
+def day_window(d: "date_cls | str", tz: ZoneInfo) -> "tuple[datetime, datetime]":
+    """The half-open ``[local 00:00, next 00:00)`` window for one calendar day.
+
+    This is the day boundary the whole tool agrees on: what a day file covers,
+    what a Day Subagent is asked about, and what report mode counts commits in
+    all have to be the same window, or a commit falls through the crack between
+    two of them.
+    """
+    if isinstance(d, str):
+        d = datetime.fromisoformat(d).date()
+    start = datetime(d.year, d.month, d.day, tzinfo=tz)
+    # timedelta arithmetic operates on wall-clock time and keeps the tzinfo, so
+    # the offset is recomputed for the next local midnight even across DST.
+    return start, start + timedelta(days=1)
+
+
+def _day_bounds(d: date_cls, tz: ZoneInfo) -> dict:
+    start, end = day_window(d, tz)
+    return {
+        "date": d.isoformat(),
+        "start": start.isoformat(),
+        "end": end.isoformat(),
+    }
+
+
+def absorb_shortcut(token: "str | None", date: "str | None",
+                    days: "int | None") -> "tuple[str | None, int | None]":
+    """Fold a positional shortcut token into the canonical ``(date, days)``.
+
+    Returns the pair unchanged when there is no token. A shortcut that collides
+    with the flag it would set is an error rather than an override: the user
+    said the same thing twice and the two may disagree.
+    """
+    if token is None:
+        return date, days
+    m = _SHORTCUT_DAYS_RE.match(token)
+    if m:
+        if days is not None:
+            raise DateError("ARG_CONFLICT",
+                            f"Shortcut {token!r} conflicts with --days.")
+        return date, int(m.group(1))
+    if _DATE_RE.match(token):
+        if date is not None:
+            raise DateError("ARG_CONFLICT",
+                            f"Shortcut {token!r} conflicts with --date.")
+        return token, days
+    raise DateError("UNKNOWN_SHORTCUT",
+                    f"Unrecognised shortcut {token!r}; expected NNd or YYYY-MM-DD.",
+                    value=token)
+
+
+def resolve(date: "str | None" = None, days: "int | None" = None,
+            from_: "str | None" = None, to: "str | None" = None,
+            include_uncommitted: bool = False, timezone: "str | None" = None,
+            today: "str | None" = None, max_days: "int | None" = None) -> dict:
+    """Resolve the canonical parameters into per-day boundaries.
+
+    Raises :class:`DateError` on any validation failure.
+    """
+    tz, tz_name, tz_source = detect_timezone(timezone)
+    # Explicit None check: `or MAX_DAYS` would treat max_days=0 as unset and
+    # silently restore the default instead of rejecting it.
+    if max_days is None:
+        max_days = MAX_DAYS
+    if max_days < 1:
+        raise DateError("BAD_MAX_DAYS",
+                        f"max-days must be at least 1 (got {max_days}).",
+                        max_days=max_days)
+
+    today_date = _parse_iso_date(today, "today") if today else datetime.now(tz).date()
+
+    has_date = date is not None
+    has_days = days is not None
+    has_from = from_ is not None
+    has_to = to is not None
+    has_range = has_from or has_to
+
+    # Mutual exclusivity: date / days / (from+to) are three separate modes.
+    active = sum([has_date, has_days, has_range])
+    if active == 0:
+        raise DateError("NO_DATE_SPEC",
+                        "No date parameter given. Provide date, days, or from+to.")
+    if active > 1:
+        raise DateError("ARG_CONFLICT",
+                        "date, days and from/to are mutually exclusive; supply exactly one mode.",
+                        provided={"date": date, "days": days,
+                                  "from": from_, "to": to})
+
+    common = {
+        "ok": True,
+        "timezone": tz_name,
+        "timezone_source": tz_source,
+        "include_uncommitted": bool(include_uncommitted),
+        "today": today_date.isoformat(),
+        "max_days": max_days,
+        "errors": [],
+    }
+
+    if has_date:
+        d = _parse_iso_date(date, "date")
+        return {**common, "mode": "date", "days_count": 1,
+                "dates": [_day_bounds(d, tz)]}
+
+    if has_days:
+        if not isinstance(days, int) or days < 1 or days > max_days:
+            raise DateError("DAYS_OUT_OF_RANGE",
+                            f"days must be an integer between 1 and {max_days} (got {days}).",
+                            requested_days=days, max_days=max_days)
+        start_day = today_date - timedelta(days=days - 1)
+        dates = [_day_bounds(start_day + timedelta(days=i), tz) for i in range(days)]
+        return {**common, "mode": "days", "days_count": days, "dates": dates}
+
+    # range mode
+    if has_from and not has_to:
+        raise DateError("FROM_WITHOUT_TO", "from must be accompanied by to.")
+    if has_to and not has_from:
+        raise DateError("TO_WITHOUT_FROM",
+                        "to must not be used on its own; provide from as well.")
+
+    d_from = _parse_iso_date(from_, "from")
+    d_to = _parse_iso_date(to, "to")
+    if d_from > d_to:
+        raise DateError("FROM_AFTER_TO",
+                        f"from ({d_from}) must not be later than to ({d_to}).")
+    total = (d_to - d_from).days + 1
+    if total > max_days:
+        raise DateError("TOO_MANY_DAYS",
+                        f"The requested range spans {total} days, exceeding the "
+                        f"{max_days}-day limit. Narrow the range to {max_days} days or fewer.",
+                        requested_days=total, max_days=max_days)
+    dates = [_day_bounds(d_from + timedelta(days=i), tz) for i in range(total)]
+    return {**common, "mode": "range", "days_count": total, "dates": dates}