git-worklog 1.6.0__py3-none-any.whl

git_worklog/mdhtml.py

@@ -0,0 +1,266 @@
+"""Worklog Markdown to HTML, safe by construction (``git-worklog view``).
+
+A day file is Markdown an LLM wrote after reading the repository, plus whatever
+a human put in its MANUAL region. Either can hold text shaped like HTML: a
+worklog that describes an XSS fix quotes ``<script>``, and a repository can
+carry text written to steer the model that summarised it. A general Markdown
+library passes inline HTML through by design. This renderer is built the other
+way round: **nothing the input says is ever emitted as markup.** Every
+character is escaped first, and the only tags in the output are the ones this
+module adds itself.
+
+It supports what the worklog format actually uses (worklog-format.md §3): ATX
+headings, paragraphs, bullet and ordered lists nested by indentation, fenced
+code, inline code, ``**bold**``, ``*italic*`` and http(s) links. Anything else
+-- tables, block quotes, footnotes, raw HTML -- is shown as the text it is, line
+breaks kept. That is the safe way to be incomplete: an unsupported construct
+reads a little plainer, it never runs.
+
+Commit hashes become badges, because a worklog is mostly read to get from a
+sentence to the commit behind it: a ``<button>`` the page's script opens the
+commit from -- or copies to the clipboard, when Git did not know the hash -- or
+a plain ``<span>`` inside something that is itself a link. A
+token counts when it mixes digits and letters, or when it is written as the
+format's own commit reference, ``<hash> (<author>)`` (worklog-format.md §3). The
+first rule keeps numbers and all-hex words ("defaced") plain; the second catches
+the hashes that happen to be all digits, four of 91 in this repository's own
+worklog.
+
+Two omissions are deliberate:
+
+- ``_underscore_`` emphasis. Worklogs name identifiers such as
+  REPO_WORKLOG_ANTHROPIC_MODEL outside backticks, and reading their underscores
+  as emphasis would mangle exactly the names a reader searches for.
+- Links other than http(s) and the worklog's own day files. ``javascript:`` and
+  ``data:`` are the obvious ones, but ``//host`` matters too: on a ``file://``
+  page it resolves to ``file://host/``, which Windows opens as a network share.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+
+_FENCE_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
+_HEADING_RE = re.compile(r"^ {0,3}(#{1,6})\s+(.*?)(?:\s+#+)?\s*$")
+_LIST_RE = re.compile(r"^( *)([-*+]|\d{1,9}[.)])(?:\s+(.*))?$")
+_HR_RE = re.compile(r"^ {0,3}([-*_])(?:\s*\1){2,}\s*$")
+# A whole-line HTML comment -- in a day file, a GIT_WORKLOG marker. It is
+# structure, not text: dropped, and it ends the paragraph it interrupts, so a
+# summary bracketed by SUMMARY markers never runs into the line after them.
+COMMENT_RE = re.compile(r"^\s*<!--.*-->\s*$")
+
+_CODE_RE = re.compile(r"(`+)(.+?)\1")
+_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^()\s]*)(?:\s+\"[^\"]*\")?\)")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^()\s]*)(?:\s+\"[^\"]*\")?\)")
+_AUTOLINK_RE = re.compile(r"<(https?://[^\s<>]+)>", re.IGNORECASE)
+_STRONG_RE = re.compile(r"\*\*(?=\S)(.+?)(?<=\S)\*\*")
+_EM_RE = re.compile(r"(?<!\*)\*(?=[^\s*])([^*]+?)(?<=[^\s*])\*(?!\*)")
+_DAY_LINK_RE = re.compile(r"^(?:\.{1,2}/)*(?:days/)?(\d{4}-\d{2}-\d{2})\.md$")
+# 7-40 lowercase hex characters not glued to a path, an identifier or a colour.
+# ASCII boundaries rather than \b, which treats CJK as word characters and would
+# miss a hash written directly against Chinese text.
+HASH_RE = re.compile(r"(?<![0-9A-Za-z_./#-])[0-9a-f]{7,40}(?![0-9A-Za-z_-])")
+_AUTHOR_AFTER_RE = re.compile(r"\s*[(（][^()（）\n]{1,80}[)）]")
+# Placeholders are NUL-delimited, and NUL is stripped from every input first,
+# so text can never forge one.
+_SLOT_RE = re.compile("\x00(\\d+)\x00")
+
+_EXTERNAL = ' rel="noopener noreferrer" target="_blank"'
+
+
+def _clean(text: str) -> str:
+    return (text.replace("\x00", "").replace("\r\n", "\n").replace("\r", "\n")
+            .expandtabs(4))
+
+
+def _href(target: str, dates) -> "str | None":
+    """Where a link may point, or None to keep only its text."""
+    t = target.strip()
+    low = t.lower()
+    if low.startswith("http://") or low.startswith("https://"):
+        return t
+    m = _DAY_LINK_RE.match(t)
+    if m and m.group(1) in dates:
+        return "#d-" + m.group(1)
+    return None
+
+
+def inline(text: str, *, dates=frozenset(), links: bool = True) -> str:
+    """One line of Markdown as HTML.
+
+    ``dates`` are the day files a relative ``<date>.md`` link may be rewritten
+    to. ``links=False`` keeps link text and drops the link, for places that are
+    themselves inside a link; commit hashes there are badges that do nothing.
+    """
+    slots: "list[str]" = []
+
+    def slot(fragment: str) -> str:
+        slots.append(fragment)
+        return f"\x00{len(slots) - 1}\x00"
+
+    def code(m):
+        return slot("<code>" + html.escape(m.group(2), quote=False) + "</code>")
+
+    def image(m):
+        return slot(html.escape(m.group(1), quote=False))
+
+    def link(m):
+        label = _emphasis(html.escape(m.group(1), quote=False))
+        href = _href(m.group(2), dates) if links else None
+        if href is None:
+            return slot(label)
+        extra = "" if href.startswith("#") else _EXTERNAL
+        return slot(f'<a href="{html.escape(href)}"{extra}>{label}</a>')
+
+    def autolink(m):
+        shown = html.escape(m.group(1), quote=False)
+        if not links:
+            return slot(shown)
+        return slot(f'<a href="{html.escape(m.group(1))}"{_EXTERNAL}>{shown}</a>')
+
+    def commit(m):
+        token = m.group(0)
+        mixed = any(c.isdigit() for c in token) and any(c.isalpha() for c in token)
+        if not mixed and not _AUTHOR_AFTER_RE.match(m.string, m.end()):
+            return token            # a number, or a word such as "defaced"
+        if not links:
+            return slot(f'<span class="hash">{token}</span>')
+        return slot(f'<button type="button" class="hash" data-hash="{token}" '
+                    f'title="Copy {token}">{token}</button>')
+
+    text = _CODE_RE.sub(code, _clean(text))
+    text = _IMAGE_RE.sub(image, text)
+    text = _LINK_RE.sub(link, text)
+    text = _AUTOLINK_RE.sub(autolink, text)
+    text = HASH_RE.sub(commit, text)   # last: never inside code, a link or its URL
+    text = _emphasis(html.escape(text, quote=False))
+    # A link label can hold a code span, so a slot can hold a slot.
+    while _SLOT_RE.search(text):
+        text = _SLOT_RE.sub(lambda m: slots[int(m.group(1))], text)
+    return text
+
+
+def _emphasis(escaped: str) -> str:
+    escaped = _STRONG_RE.sub(r"<strong>\1</strong>", escaped)
+    return _EM_RE.sub(r"<em>\1</em>", escaped)
+
+
+def _indent(line: str) -> int:
+    return len(line) - len(line.lstrip(" "))
+
+
+def _fenced(lines: "list[str]", i: int, opener: str, indent: int,
+            out: "list[str]") -> int:
+    """Emit the fenced block opening at ``lines[i]``; return the next index."""
+    close = re.compile(r"^\s*" + re.escape(opener[0]) + "{" + str(len(opener)) + r",}\s*$")
+    body = []
+    i += 1
+    while i < len(lines) and not close.match(lines[i]):
+        line = lines[i]
+        body.append(line[min(indent, _indent(line)):])
+        i += 1
+    out.append("<pre><code>" + html.escape("\n".join(body), quote=False)
+               + "</code></pre>")
+    return i + 1   # past the closing fence -- or the end, if it never closed
+
+
+def _list(lines: "list[str]", i: int, out: "list[str]", dates) -> int:
+    """Emit the list starting at ``lines[i]``; return the next index."""
+    base = _indent(lines[i])
+    ordered = _LIST_RE.match(lines[i]).group(2)[0].isdigit()
+    items: "list[dict]" = []
+    n = len(lines)
+    while i < n:
+        line = lines[i]
+        if not line.strip():
+            # A blank line ends the list unless the list, or its last item,
+            # carries on after it.
+            j = i + 1
+            while j < n and not lines[j].strip():
+                j += 1
+            if j < n and items and (_indent(lines[j]) > base or (
+                    _indent(lines[j]) == base and _LIST_RE.match(lines[j]))):
+                i = j
+                continue
+            break
+        if COMMENT_RE.match(line):
+            break
+        ind = _indent(line)
+        m = _LIST_RE.match(line)
+        if m and ind == base:
+            items.append({"text": [m.group(3) or ""], "children": []})
+            i += 1
+        elif m and ind > base and items:
+            i = _list(lines, i, items[-1]["children"], dates)
+        elif ind > base and items:
+            fence = _FENCE_RE.match(line.strip())
+            if fence:
+                i = _fenced(lines, i, fence.group(1), ind, items[-1]["children"])
+            else:
+                items[-1]["text"].append(line.strip())
+                i += 1
+        else:
+            break
+    tag = "ol" if ordered else "ul"
+    parts = [f"<{tag}>"]
+    for item in items:
+        # An item that opens with bold text is a labelled field -- the shape of
+        # every work-item bullet (`- **label：** value`). Marked here, by
+        # structure, so the page can style the label without knowing its words.
+        opener = '<li class="kv">' if item["text"][0].startswith("**") else "<li>"
+        text = "<br>\n".join(inline(t, dates=dates) for t in item["text"])
+        parts.append(opener + text + "".join(item["children"]) + "</li>")
+    parts.append(f"</{tag}>")
+    out.append("\n".join(parts))
+    return i
+
+
+def render(md: str, *, dates=frozenset(), min_heading: int = 4) -> str:
+    """A block of Markdown as HTML.
+
+    Headings are clamped to at least ``min_heading``, because this text always
+    sits inside a page that already has its own h1-h3.
+    """
+    lines = _clean(md).split("\n")
+    out: "list[str]" = []
+    para: "list[str]" = []
+
+    def flush():
+        if para:
+            out.append("<p>" + "<br>\n".join(inline(p, dates=dates) for p in para)
+                       + "</p>")
+            para.clear()
+
+    i, n = 0, len(lines)
+    while i < n:
+        line = lines[i]
+        fence = _FENCE_RE.match(line)
+        if fence:
+            flush()
+            i = _fenced(lines, i, fence.group(1), _indent(line), out)
+            continue
+        if not line.strip() or COMMENT_RE.match(line):
+            flush()
+            i += 1
+            continue
+        heading = _HEADING_RE.match(line)
+        if heading:
+            flush()
+            level = min(6, max(min_heading, len(heading.group(1))))
+            out.append(f"<h{level}>{inline(heading.group(2), dates=dates)}</h{level}>")
+            i += 1
+            continue
+        if _HR_RE.match(line):
+            flush()
+            out.append("<hr>")
+            i += 1
+            continue
+        if _LIST_RE.match(line):
+            flush()
+            i = _list(lines, i, out, dates)
+            continue
+        para.append(line.strip())
+        i += 1
+    flush()
+    return "\n".join(out)

git_worklog/migrate.py

@@ -0,0 +1,305 @@
+"""One-time migration of a legacy worklog into the ``.git-worklog/`` layout.
+
+Two legacy shapes are migrated, because the worklog has moved twice:
+
+**Single file** (``from_file``, pre-v0.2) — every day lived in one
+``docs/PROJECT_WORKLOG.md`` delimited by ``REPO_WORKLOG:ENTRIES`` and per-date
+``START/END`` markers. Each date is split into its own day file, preserving that
+date's GENERATED and MANUAL text.
+
+**Flat directory** (``from_dir``, v0.2–v0.5) — ``PROJECT_WORKLOG/<date>.md``
+with the index alongside. Day files move to ``.git-worklog/days/<date>.md`` and
+their markers are re-tagged ``REPO_WORKLOG`` → ``GIT_WORKLOG``. Nothing else in
+a day file changes: the title, meta blockquote, GENERATED prose and MANUAL notes
+are copied byte for byte, so a migration never rewrites a worklog's content or
+its language. The index is rebuilt (its links must now point into ``days/``)
+with its MANUAL region preserved.
+
+With neither given the source is auto-detected, directory first.
+
+It is **never** invoked by normal runs — only explicitly. Dry-run is the default.
+It never deletes the source, and never overwrites a day file that already exists
+(those are left for the user to reconcile). If the legacy markers are corrupt, it
+refuses to migrate rather than guess.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+
+from git_worklog import markers as wm
+from git_worklog import writer
+
+DEFAULT_LEGACY = os.path.join("docs", "PROJECT_WORKLOG.md")
+DEFAULT_LEGACY_DIR = wm.LEGACY_WORKLOG_DIRNAME
+DEFAULT_DIR = wm.WORKLOG_DIRNAME
+
+_LEGACY_MARKER_RE = re.compile(
+    rf"^<!--\s*{wm.LEGACY_PREFIX}:(\d{{4}}-\d{{2}}-\d{{2}}):(GENERATED|MANUAL):(START|END)\s*-->$"
+)
+_ENTRIES_RE = re.compile(rf"^<!--\s*{wm.LEGACY_PREFIX}:ENTRIES:(START|END)\s*-->$")
+
+
+class MigrateError(ValueError):
+    """A migration that must not proceed, carrying the wire code.
+
+    Mirrors :class:`git_worklog.dates.DateError` and
+    :class:`git_worklog.analysis.AnalysisError`.
+    """
+
+    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 _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def parse_legacy(text: str) -> "dict[str, dict[str, str]]":
+    """Extract ``{date: {"generated": ..., "manual": ...}}`` from the legacy file.
+
+    Raises ValueError with a reason when the markers are unbalanced, so a corrupt
+    legacy file is refused rather than half-migrated.
+    """
+    lines = text.splitlines(keepends=True)
+    has_entries = any(_ENTRIES_RE.match(ln.strip()) for ln in lines)
+    if not has_entries:
+        raise ValueError("no REPO_WORKLOG:ENTRIES markers found")
+
+    # Collect marker positions per date.
+    marks: "dict[str, dict[str, int]]" = {}
+    order: "list[str]" = []
+    for idx, raw in enumerate(lines):
+        m = _LEGACY_MARKER_RE.match(raw.strip())
+        if not m:
+            continue
+        date, region, edge = m.group(1), m.group(2), m.group(3)
+        key = f"{region}_{edge}"
+        slot = marks.setdefault(date, {})
+        if key in slot:
+            raise ValueError(f"duplicate {region}:{edge} marker for {date}")
+        slot[key] = idx
+        if date not in order:
+            order.append(date)
+
+    result: "dict[str, dict[str, str]]" = {}
+    for date in order:
+        slot = marks[date]
+        for need in ("GENERATED_START", "GENERATED_END", "MANUAL_START", "MANUAL_END"):
+            if need not in slot:
+                raise ValueError(f"missing {need} marker for {date}")
+        gs, ge = slot["GENERATED_START"], slot["GENERATED_END"]
+        ms, me = slot["MANUAL_START"], slot["MANUAL_END"]
+        if not (gs < ge and ms < me):
+            raise ValueError(f"markers out of order for {date}")
+        result[date] = {
+            "generated": "".join(lines[gs + 1:ge]),
+            "manual": "".join(lines[ms + 1:me]),
+        }
+    return result
+
+
+def _read_utf8(path: str, what: str) -> str:
+    with open(path, "rb") as fh:
+        raw = fh.read()
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise MigrateError("NON_UTF8", f"{what} is not valid UTF-8: {exc}", target=path)
+
+
+def resolve_source(from_dir: "str | None", from_file: "str | None") -> "tuple[str, str]":
+    """Decide what we are migrating from. Returns ``(kind, path)``."""
+    if from_dir and from_file:
+        raise MigrateError("AMBIGUOUS_SOURCE",
+                           "Pass only one of --from-dir / --from-file; they are "
+                           "different legacy shapes.")
+    if from_dir:
+        return "dir", from_dir
+    if from_file:
+        return "file", from_file
+    # Auto-detect: the flat directory is the newer legacy shape, so prefer it.
+    if wm.detect_layout(DEFAULT_LEGACY_DIR) == wm.LAYOUT_LEGACY:
+        return "dir", DEFAULT_LEGACY_DIR
+    if os.path.exists(DEFAULT_LEGACY):
+        return "file", DEFAULT_LEGACY
+    raise MigrateError("LEGACY_NOT_FOUND",
+                       f"No legacy worklog found: neither {DEFAULT_LEGACY_DIR}/ (flat "
+                       f"directory) nor {DEFAULT_LEGACY} (single file). Pass "
+                       "--from-dir or --from-file.")
+
+
+def _plan_from_file(legacy_path: str, worklog_dir: str,
+                    tz: "str | None") -> "tuple[list, list, dict]":
+    text = _read_utf8(legacy_path, "Legacy worklog")
+    try:
+        parsed = parse_legacy(text)
+    except ValueError as exc:
+        raise MigrateError("LEGACY_CORRUPT",
+                           f"Legacy worklog markers are corrupt; refusing to migrate: {exc}",
+                           target=legacy_path)
+    if not parsed:
+        raise MigrateError("LEGACY_EMPTY", "Legacy worklog has no date blocks to migrate.",
+                           target=legacy_path)
+
+    planned: "list[dict]" = []
+    to_write: "list[tuple[str, str]]" = []
+    summaries: "dict[str, str]" = {}
+    for date in sorted(parsed, reverse=True):
+        gen, manual = parsed[date]["generated"], parsed[date]["manual"]
+        if wm.contains_marker_line(gen):
+            raise MigrateError("LEGACY_CONTAINS_MARKER",
+                               f"Legacy GENERATED content for {date} contains a marker "
+                               "line; refusing to migrate rather than produce a corrupt "
+                               "day file.", date=date)
+        summaries[date] = wm.summarise_generated(gen)
+        path = wm.day_path(worklog_dir, date, wm.LAYOUT_CURRENT)
+        if os.path.exists(path):
+            planned.append({"date": date, "path": path, "action": "skip-exists"})
+            continue
+        planned.append({"date": date, "path": path, "action": "create"})
+        to_write.append((path, wm.build_day_file(date, gen, manual, timezone=tz)))
+    return planned, to_write, summaries
+
+
+def _plan_from_dir(src_dir: str, worklog_dir: str) -> "tuple[list, list, dict]":
+    """Plan a flat-directory migration: move day files and re-tag their markers.
+
+    Day content is copied verbatim apart from the marker prefix, so the original
+    header metadata (branch, HEAD, timezone) and the prose survive untouched.
+    ``timezone`` is deliberately ignored here: each day file already records
+    the timezone it was written under, and rewriting it would falsify history.
+    """
+    if os.path.abspath(src_dir) == os.path.abspath(worklog_dir):
+        raise MigrateError("SOURCE_IS_TARGET",
+                           f"--from-dir and --dir are the same directory ({src_dir}); "
+                           "nothing to migrate.")
+    layout = wm.detect_layout(src_dir)
+    if layout != wm.LAYOUT_LEGACY:
+        raise MigrateError("SOURCE_NOT_LEGACY",
+                           f"{src_dir} does not hold a flat legacy worklog (no <date>.md "
+                           f"files at its root). Detected layout: {layout}.", target=src_dir)
+
+    planned: "list[dict]" = []
+    to_write: "list[tuple[str, str]]" = []
+    summaries: "dict[str, str]" = {}
+    for date in sorted(wm.list_day_dates(src_dir, layout), reverse=True):
+        src = wm.day_path(src_dir, date, layout)
+        text = _read_utf8(src, f"Day file {date}.md")
+        retagged, _ = wm.retag_markers(text)
+        try:
+            day = wm.parse_day(retagged, date)
+        except wm.WorklogFormatError as exc:
+            raise MigrateError("DAY_FILE_CORRUPT",
+                               f"Day file {date}.md has corrupt/missing markers; refusing "
+                               "to migrate rather than guess a repair.",
+                               target=src, issues=exc.issues)
+        summaries[date] = wm.summarise_generated(day.generated)
+        dst = wm.day_path(worklog_dir, date, wm.LAYOUT_CURRENT)
+        if os.path.exists(dst):
+            planned.append({"date": date, "path": dst, "action": "skip-exists"})
+            continue
+        planned.append({"date": date, "path": dst, "action": "create", "source": src})
+        to_write.append((dst, retagged))
+    if not to_write and not planned:
+        raise MigrateError("LEGACY_EMPTY", f"{src_dir} has no day files to migrate.",
+                           target=src_dir)
+    return planned, to_write, summaries
+
+
+def _source_index_manual(kind: str, src: str, worklog_dir: str) -> "str | None":
+    """The MANUAL region to carry into the new index.
+
+    The target's own index wins if it exists; otherwise a flat source's index
+    donates its MANUAL so hand-written navigation notes survive the move.
+    """
+    target_index = wm.index_path(worklog_dir)
+    for path, why in ((target_index, "An existing index.md"),
+                      (wm.index_path(src) if kind == "dir" else None, "The source index.md")):
+        if not path or not os.path.exists(path):
+            continue
+        try:
+            return wm.parse_index(_read_utf8(path, "index.md")).manual
+        except wm.WorklogFormatError as exc:
+            raise MigrateError("INDEX_CORRUPT_MARKERS",
+                               f"{why} has corrupt markers; refusing to migrate rather "
+                               f"than discard its MANUAL region: {exc}", target=path)
+    return None
+
+
+def run(from_dir: "str | None" = None, from_file: "str | None" = None,
+        dir: "str | None" = None, timezone: "str | None" = None,
+        apply: bool = False) -> dict:
+    """Plan (and optionally write) the migration. Raises MigrateError."""
+    kind, source = resolve_source(from_dir, from_file)
+    worklog_dir = dir or DEFAULT_DIR
+    if not os.path.exists(source):
+        raise MigrateError("LEGACY_NOT_FOUND", f"Legacy worklog not found: {source}",
+                           target=source)
+
+    if kind == "dir":
+        planned, to_write, summaries = _plan_from_dir(source, worklog_dir)
+    else:
+        planned, to_write, summaries = _plan_from_file(source, worklog_dir, timezone)
+
+    # Preview the rebuilt index over all migrated dates (existing + to-create).
+    index_path = wm.index_path(worklog_dir)
+    existing_manual = _source_index_manual(kind, source, worklog_dir)
+    rows = [(d, summaries[d]) for d in sorted(summaries, reverse=True)]
+    index_content = wm.render_index(rows, existing_manual, wm.LAYOUT_CURRENT)
+
+    common = {
+        "source": source,
+        "source_kind": kind,
+        "legacy_path": source,   # retained for callers written against the old key
+        "worklog_dir": worklog_dir,
+        "index_path": index_path,
+        "planned_changes": planned,
+        "dates": [d for d, _ in rows],
+        "index_preview_sha256": _sha256(index_content),
+    }
+
+    if not apply:
+        return {"ok": True, "mode": "dry-run", **common,
+                "index_preview": index_content,
+                "config_preview": wm.render_config(timezone),
+                "note": ("No files have been modified. The source is never deleted; "
+                         "existing day files are never overwritten.")}
+
+    # Write the new day files (and index) atomically; on any failure remove the
+    # files we created so a partial migration is never left behind.
+    created: "list[str]" = []
+    try:
+        for path, content in to_write:
+            writer.atomic_write(
+                path, content,
+                lambda t, d=os.path.basename(path)[:-3]: wm.parse_day(t, d),
+                prefix=".rw-mig-")
+            created.append(path)
+        writer.atomic_write(index_path, index_content, wm.parse_index,
+                            prefix=".rw-mig-")
+        created.extend(wm.ensure_data_dir(worklog_dir, timezone))
+    except Exception as exc:
+        for path in created:
+            try:
+                os.unlink(path)
+            except OSError:
+                pass
+        raise MigrateError("MIGRATION_FAILED",
+                           f"Migration failed and created files were rolled back: {exc}",
+                           worklog_dir=worklog_dir)
+
+    return {"ok": True, "mode": "apply", **common,
+            "created_dates": [os.path.basename(p)[:-3] for p, _ in to_write],
+            "note": (f"Migration written to {worklog_dir}/. The source ({source}) was NOT "
+                     "deleted — review the result, then remove it yourself if you are "
+                     "satisfied. No git add / commit / push was performed.")}

git_worklog/paths.py

@@ -0,0 +1,85 @@
+"""User-level state directory resolution.
+
+Previews and analysis results are deliberately kept **outside** the target
+repository — they are working state, not project content, and committing them
+would pollute the very history the tool reads. They live under
+``~/.git-worklog/`` (roadmap §5), overridable with ``GIT_WORKLOG_HOME`` so a
+test, a sandbox, or a shared CI runner can point somewhere else.
+
+``GIT_WORKLOG_HOME`` is a new variable, not a rename: there was never a
+``REPO_WORKLOG_HOME``. The paths were hard-coded, which is why they moved here.
+"""
+
+from __future__ import annotations
+
+import os
+
+HOME_ENV = "GIT_WORKLOG_HOME"
+HOME_DIRNAME = ".git-worklog"
+
+# Where state lived before v0.7. Nothing is migrated automatically: previews
+# expire in 24h and analysis files are diagnostic leftovers, so a stale copy is
+# noise rather than loss. `doctor` points it out; deleting it is the user's call.
+LEGACY_HOME_DIRNAME = ".repo_worklog"
+
+PREVIEWS_SUBDIR = "previews"
+ANALYSIS_SUBDIR = "analysis"
+# Apply locks live here (roadmap §5). They are transient by nature -- a lock
+# outliving its process is a bug to detect, not state to keep -- so they sit in
+# tmp/ rather than earning a directory of their own.
+TMP_SUBDIR = "tmp"
+# Pages written by `git-worklog view`. Derived from a worklog on every run, so
+# deleting them loses nothing: the next `view` writes them again.
+VIEW_SUBDIR = "view"
+
+# The user's own copy of the subagent model table. Seeded from the shipped one
+# the first time a model is resolved and never rewritten after that, so a new
+# model id is an edit to this file rather than a release of the tool.
+MODELS_FILENAME = "provider_models.json"
+
+# Owner-only: these files quote source code and diffs from private repositories.
+DIR_MODE = 0o700
+
+
+def home() -> str:
+    """The user-level state directory. ``GIT_WORKLOG_HOME`` wins when set."""
+    override = os.environ.get(HOME_ENV)
+    if override:
+        return os.path.abspath(os.path.expanduser(override))
+    return os.path.join(os.path.expanduser("~"), HOME_DIRNAME)
+
+
+def legacy_home() -> str:
+    """The pre-v0.7 state directory, whether or not it exists."""
+    return os.path.join(os.path.expanduser("~"), LEGACY_HOME_DIRNAME)
+
+
+def previews_dir() -> str:
+    return os.path.join(home(), PREVIEWS_SUBDIR)
+
+
+def analysis_dir() -> str:
+    return os.path.join(home(), ANALYSIS_SUBDIR)
+
+
+def tmp_dir() -> str:
+    return os.path.join(home(), TMP_SUBDIR)
+
+
+def view_dir() -> str:
+    return os.path.join(home(), VIEW_SUBDIR)
+
+
+def models_path() -> str:
+    return os.path.join(home(), MODELS_FILENAME)
+
+
+def ensure_dir(path: str) -> str:
+    """Create ``path`` (and parents) owner-only, and return it.
+
+    The mode is applied on creation only; an existing directory is left as the
+    user set it. On filesystems without POSIX permissions the mode is ignored,
+    which is why this is a best-effort hardening rather than a guarantee.
+    """
+    os.makedirs(path, mode=DIR_MODE, exist_ok=True)
+    return path