secondbrain-py 0.2.1__py3-none-any.whl

brain/todo.py

@@ -0,0 +1,124 @@
+"""Parser for ``- [ ]`` / ``- [x]`` Markdown action-item lines.
+
+Standalone so it can be unit-tested without a DB. The CLI calls
+:func:`parse_action_items` on each ``krisp_action_items`` doc body fetched
+in one SELECT (see :mod:`brain.cli` `todo` command).
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal
+
+import psycopg
+
+# Match leading whitespace, ``-`` or ``*``, whitespace, ``[ ]`` or ``[x]``
+# (case-insensitive), whitespace, rest-of-line. Anchored with ``^`` +
+# ``re.MULTILINE`` so we walk every body line in one pass.
+_TASK_RE = re.compile(
+    r"^\s*[-*]\s*\[([ xX])\]\s*(.+?)\s*$",
+    re.MULTILINE,
+)
+
+
+@dataclass(frozen=True)
+class ActionItem:
+    """One parsed action-item line.
+
+    ``state`` is ``"open"`` for ``[ ]`` and ``"done"`` for ``[x]`` (case-
+    insensitive). ``text`` is the rest-of-line content after the checkbox,
+    stripped of trailing whitespace.
+    """
+
+    state: Literal["open", "done"]
+    text: str
+
+
+def parse_action_items(body: str) -> list[ActionItem]:
+    """Return one :class:`ActionItem` per recognized task line.
+
+    Lines without the ``[ ]`` / ``[x]`` pattern are ignored — comments,
+    headers, the trailing ``Parent meeting:`` wikilink. The parser is
+    Markdown-aware enough to handle leading whitespace + ``-`` / ``*``
+    bullets but does NOT support nested checkboxes (a future wave can add
+    nesting if the action-items shape grows). Pure function; the CLI feeds
+    in pre-fetched bodies.
+    """
+    out: list[ActionItem] = []
+    for m in _TASK_RE.finditer(body):
+        ch = m.group(1)
+        state: Literal["open", "done"] = "done" if ch.lower() == "x" else "open"
+        out.append(ActionItem(state=state, text=m.group(2)))
+    return out
+
+
+@dataclass(frozen=True)
+class TodoRow:
+    """One flat row returned by :func:`iter_action_item_docs`.
+
+    Carries the parent document context (id, title, ingested_at) alongside
+    the parsed action item so the CLI ``brain todo`` view can render a flat
+    table without re-joining at print time.
+    """
+
+    document_id: str
+    document_title: str
+    ingested_at: datetime | None
+    state: Literal["open", "done"]
+    text: str
+
+
+def iter_action_item_docs(
+    conn: psycopg.Connection[Any],
+    *,
+    source_kind: str | None = None,
+    since_days: int | None = None,
+    include_closed: bool = False,
+) -> Iterator[TodoRow]:
+    """Yield one :class:`TodoRow` per parsed item across the corpus.
+
+    Walks ``documents WHERE content_type='krisp_action_items'`` (optionally
+    filtered by source / recency), parses each body line by line, and
+    yields the parsed items in document-recency order. The caller decides
+    whether to render a table or emit JSON.
+
+    Filters:
+
+    - ``source_kind`` — restricts to docs whose joined ``sources.kind``
+      matches (today only ``"krisp"`` is meaningful, but the parameter
+      stays open for future source kinds emitting the same content_type).
+    - ``since_days`` — restricts to docs ingested in the last N days.
+    - ``include_closed`` — when False (default), drop ``[x]`` items from
+      the stream; when True, both states are returned.
+    """
+    sql = (
+        "SELECT d.id::text, d.title, d.content, d.ingested_at, s.kind "
+        "FROM documents d LEFT JOIN sources s ON s.id = d.source_id "
+        "WHERE d.content_type = 'krisp_action_items'"
+    )
+    params: list[Any] = []
+    if source_kind is not None:
+        sql += " AND s.kind = %s"
+        params.append(source_kind)
+    if since_days is not None:
+        sql += " AND d.ingested_at >= NOW() - (%s * INTERVAL '1 day')"
+        params.append(since_days)
+    sql += " ORDER BY d.ingested_at DESC"
+    rows = conn.execute(sql, params).fetchall()
+    for r in rows:
+        doc_id = str(r[0])
+        title = str(r[1])
+        body = str(r[2] or "")
+        ingested_at = r[3]
+        for item in parse_action_items(body):
+            if item.state == "done" and not include_closed:
+                continue
+            yield TodoRow(
+                document_id=doc_id,
+                document_title=title,
+                ingested_at=ingested_at,
+                state=item.state,
+                text=item.text,
+            )

brain/uninstall.py

@@ -0,0 +1,185 @@
+"""brain uninstall — removes launchd plists, $BRAIN_HOME runtime state, and optionally the vault.
+
+Does NOT remove the pipx installation itself; a CLI cannot safely uninstall
+its own running process.  After running this command, the user should manually
+run `pipx uninstall secondbrain-py`.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+from ._compose import compose_cmd
+from .config import DEFAULT_VAULT_PATH, _brain_home_root
+
+# Files / dirs inside $BRAIN_HOME that are safe to remove even when --remove-db
+# is NOT set (i.e. everything except the data/ subtree).
+_BRAIN_HOME_SAFE_REMOVES = (
+    ".env",
+    ".shims",
+    "Caddyfile",
+    "docker-compose.yml",
+    "bin",
+    "logs",
+    "build",
+)
+
+
+def _step(label: str) -> None:
+    typer.echo(f"  {label}")
+
+
+def _ok(label: str) -> None:
+    typer.secho(f"  [ok]     {label}", fg="green")
+
+
+def _skipped(label: str) -> None:
+    typer.echo(f"  [skipped] {label}")
+
+
+def run_uninstall(
+    *,
+    yes: bool = False,
+    remove_db: bool = False,
+    remove_vault: bool = False,
+    brain_home: Path | None = None,
+    vault_path: Path | None = None,
+    _launchd_uninstall: object | None = None,
+) -> None:
+    """Core uninstall logic — separated from the Typer command for testability.
+
+    Parameters
+    ----------
+    yes:
+        Skip the interactive confirmation prompt.
+    remove_db:
+        Also remove ``$BRAIN_HOME/data/postgres/`` (requires extra typed
+        confirmation regardless of ``yes``).
+    remove_vault:
+        Also remove the vault directory.
+    brain_home:
+        Override the resolved ``$BRAIN_HOME`` path (for tests).
+    vault_path:
+        Override the resolved ``$BRAIN_VAULT_PATH`` path (for tests).
+    _launchd_uninstall:
+        Dependency-injected callable that replaces ``brain.bin.launchd.uninstall_main``
+        (for tests that don't want real launchctl calls).
+    """
+    home = brain_home if brain_home is not None else _brain_home_root()
+    vault = vault_path if vault_path is not None else DEFAULT_VAULT_PATH
+
+    # -----------------------------------------------------------------------
+    # 1. Print summary of what will be removed.
+    # -----------------------------------------------------------------------
+    typer.echo("")
+    typer.echo("🧠 brain uninstall")
+    typer.echo("")
+    typer.echo("The following will be removed:")
+    typer.echo("  • launchd plists (macOS only)")
+    typer.echo("  • Docker compose containers / networks (brain project)")
+    for name in _BRAIN_HOME_SAFE_REMOVES:
+        p = home / name
+        if p.exists():
+            typer.echo(f"  • {p}")
+    if remove_db:
+        typer.echo(f"  • {home / 'data' / 'postgres'}  ← ALL DATABASE DATA")
+    if remove_vault:
+        typer.echo(f"  • {vault}  ← YOUR NOTES")
+    typer.echo("")
+
+    # -----------------------------------------------------------------------
+    # 2. Interactive confirmation (unless --yes).
+    # -----------------------------------------------------------------------
+    if not yes:
+        typer.confirm("Proceed?", default=False, abort=True)
+
+    # -----------------------------------------------------------------------
+    # 3. Extra typed confirmation for --remove-db (NEVER bypassed by --yes).
+    # -----------------------------------------------------------------------
+    if remove_db:
+        typer.echo("")
+        typer.echo("WARNING: --remove-db will permanently delete all ingested documents.")
+        answer = typer.prompt('Type "yes, delete my data" to confirm')
+        if answer != "yes, delete my data":
+            typer.secho("Aborted — database data was NOT removed.", fg="yellow")
+            raise typer.Abort()
+
+    # -----------------------------------------------------------------------
+    # 4. Uninstall launchd (macOS only).
+    # -----------------------------------------------------------------------
+    if sys.platform == "darwin":
+        _step("Uninstalling launchd plists …")
+        try:
+            if _launchd_uninstall is not None:
+                _launchd_uninstall()  # type: ignore[operator]
+            else:
+                from .bin.launchd import uninstall_main
+                uninstall_main()
+            _ok("launchd plists removed")
+        except Exception as exc:  # noqa: BLE001
+            typer.secho(f"  [warn]   launchd uninstall: {exc}", fg="yellow")
+    else:
+        _skipped("launchd (not macOS)")
+
+    # -----------------------------------------------------------------------
+    # 5. Stop Docker compose (fail-silent — user may have stopped it already).
+    # -----------------------------------------------------------------------
+    _step("Stopping Docker compose …")
+    try:
+        subprocess.run(
+            compose_cmd("down", brain_home=home),
+            check=False,
+            capture_output=True,
+            timeout=30,
+        )
+        _ok("docker compose down")
+    except Exception as exc:  # noqa: BLE001
+        typer.secho(f"  [warn]   docker compose down: {exc}", fg="yellow")
+
+    # -----------------------------------------------------------------------
+    # 6. Remove safe $BRAIN_HOME entries.
+    # -----------------------------------------------------------------------
+    _step(f"Removing $BRAIN_HOME runtime files from {home} …")
+    for name in _BRAIN_HOME_SAFE_REMOVES:
+        p = home / name
+        if p.is_dir():
+            shutil.rmtree(p, ignore_errors=True)
+            _ok(f"removed dir  {p}")
+        elif p.is_file():
+            p.unlink(missing_ok=True)
+            _ok(f"removed file {p}")
+
+    # -----------------------------------------------------------------------
+    # 7. Optionally remove the database data directory.
+    # -----------------------------------------------------------------------
+    if remove_db:
+        pg_dir = home / "data" / "postgres"
+        if pg_dir.exists():
+            shutil.rmtree(pg_dir)
+            _ok(f"removed database {pg_dir}")
+        else:
+            _skipped(f"data/postgres not found at {pg_dir}")
+
+    # -----------------------------------------------------------------------
+    # 8. Optionally remove the vault.
+    # -----------------------------------------------------------------------
+    if remove_vault:
+        if vault.exists():
+            shutil.rmtree(vault)
+            _ok(f"removed vault {vault}")
+        else:
+            _skipped(f"vault not found at {vault}")
+    else:
+        _skipped(f"vault kept at {vault}  (pass --remove-vault to delete)")
+
+    # -----------------------------------------------------------------------
+    # 9. Final hint.
+    # -----------------------------------------------------------------------
+    typer.echo("")
+    typer.secho("Done. To complete removal, run:", fg="cyan")
+    typer.secho("  pipx uninstall secondbrain-py", bold=True)
+    typer.echo("")

brain/vault/__init__.py

@@ -0,0 +1,115 @@
+"""Vault model — `.md` files on disk are the source of truth for vault notes.
+
+Phase 1 ships :func:`init_vault` (one-shot directory + template scaffold) and
+:func:`export_vault` (DB → vault dump). Later phases add sync, link parsing,
+authoring commands, and a Quartz renderer on top of the same module layout.
+"""
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .link_rewrite import rewrite_vault_links, rewrite_wiki_links
+from .templates import (
+    CAPTURE_README,
+    DAILY_TEMPLATE,
+    INGESTED_README,
+    NOTE_TEMPLATE,
+    VAULT_README,
+)
+
+__all__ = [
+    "CAPTURE_README",
+    "DAILY_TEMPLATE",
+    "INGESTED_README",
+    "NOTE_TEMPLATE",
+    "VAULT_README",
+    "VAULT_SUBDIRS",
+    "VAULT_TEMPLATE_FILES",
+    "VaultInitSummary",
+    "create_vault_note",
+    "init_vault",
+    "rewrite_vault_links",
+    "rewrite_wiki_links",
+]
+
+# Subdirectories created (or ensured) by ``brain vault init``. Order is
+# preserved in the summary so output stays deterministic across runs.
+VAULT_SUBDIRS: tuple[str, ...] = (
+    "_templates",
+    "_attachments",
+    "_ingested",
+    "_ingested/krisp",
+    "_ingested/slack",
+    "_ingested/gmail",
+    "_ingested/manual",
+    "capture",
+    "daily",
+)
+
+# (relative path, content) pairs written if the file does not already exist.
+# Tuple-of-tuples (not dict) so iteration order is part of the contract.
+VAULT_TEMPLATE_FILES: tuple[tuple[str, str], ...] = (
+    ("_templates/daily.md", DAILY_TEMPLATE),
+    ("_templates/note.md", NOTE_TEMPLATE),
+    ("_ingested/README.md", INGESTED_README),
+    ("capture/README.md", CAPTURE_README),
+    ("README.md", VAULT_README),
+)
+
+
+@dataclass
+class VaultInitSummary:
+    """What ``init_vault`` actually did, for the CLI to print.
+
+    ``created_dirs`` lists subdirs that didn't exist before this call;
+    ``existing_dirs`` lists ones that did. ``written_files`` and
+    ``preserved_files`` are the analogous lists for templates: a template
+    is only ever written when absent (we never overwrite user edits).
+    """
+
+    vault_path: Path
+    created_dirs: list[str] = field(default_factory=list)
+    existing_dirs: list[str] = field(default_factory=list)
+    written_files: list[str] = field(default_factory=list)
+    preserved_files: list[str] = field(default_factory=list)
+
+
+def init_vault(vault_path: Path) -> VaultInitSummary:
+    """Create / ensure the vault folder structure and default templates.
+
+    Idempotent — safe to re-run. Never overwrites existing files; user edits
+    to ``_templates/*.md`` or ``README.md`` survive every subsequent
+    ``brain vault init`` call.
+
+    Creates the vault root if absent. Creates each subdir under
+    :data:`VAULT_SUBDIRS` with ``mkdir -p`` semantics (no error if present).
+    Writes each template in :data:`VAULT_TEMPLATE_FILES` only if its target
+    path does not yet exist.
+    """
+    summary = VaultInitSummary(vault_path=vault_path)
+    vault_path.mkdir(parents=True, exist_ok=True)
+
+    for relative in VAULT_SUBDIRS:
+        target = vault_path / relative
+        if target.is_dir():
+            summary.existing_dirs.append(relative)
+        else:
+            target.mkdir(parents=True, exist_ok=True)
+            summary.created_dirs.append(relative)
+
+    for relative, content in VAULT_TEMPLATE_FILES:
+        target = vault_path / relative
+        if target.exists():
+            summary.preserved_files.append(relative)
+        else:
+            target.write_text(content, encoding="utf-8")
+            summary.written_files.append(relative)
+
+    return summary
+
+
+# Imported at the BOTTOM on purpose: ``note_builder`` pulls in (lazily) the
+# ingest pipeline, and ``brain.ingest`` imports ``brain.vault.export``, which
+# does ``from . import init_vault``. Re-exporting here only after ``init_vault``
+# is defined keeps that re-entrant import resolvable instead of hitting a
+# partially-initialized package. See note_builder's module docstring.
+from .note_builder import create_vault_note  # noqa: E402

brain/vault/_atomic.py

@@ -0,0 +1,25 @@
+"""Atomic file-write helper shared by every body-rewriter under ``vault/``."""
+import os
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` atomically (sibling tempfile + ``os.replace``).
+
+    The temp file is a sibling of ``path`` (same parent directory) so the
+    rename never crosses a filesystem boundary — ``os.replace`` is atomic
+    on POSIX in that case (it's ``rename(2)`` underneath). A crash between
+    the write and the rename leaves the original file intact.
+
+    On any failure during the write or rename, the temp file is removed so
+    we don't leave stray ``*.tmp`` siblings cluttering the vault. Tempfile
+    cleanup uses ``unlink(missing_ok=True)`` because the failure may have
+    happened before the file was created.
+    """
+    tmp = path.with_name(f"{path.name}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8")
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise

brain/vault/daily_index.py

@@ -0,0 +1,228 @@
+"""Auto-generate ``<vault>/daily/index.md`` from the dailies on disk.
+
+Phase 4.1 of the Wiki UX Overhaul. The home note's "Daily notes" door
+points at ``daily/`` — Quartz resolves a folder reference to
+``daily/index`` if and only if a markdown file exists at that path.
+Without :func:`regenerate_daily_index`, the door is a 404.
+
+Contract:
+
+* Walks ``<vault>/daily/<YYYY>/<YYYY-MM-DD>.md`` recursively (any depth
+  is tolerated, but the brain CLI only writes year-folder children) and
+  collects every ``.md`` file whose stem matches ``YYYY-MM-DD``.
+  ``index.md`` itself is excluded so a re-run of the regen doesn't
+  feed itself.
+* Sorted reverse-chronological by filename. The filename is the
+  canonical truth (matches the slug Quartz emits, matches what the
+  user expects to see) — frontmatter ``date`` would be a second
+  truth-source that could drift.
+* Body = ``- [[YYYY-MM-DD]]`` per line, newest first. Wiki-link form
+  uses the bare date stem so Quartz's ``markdownLinkResolution:
+  shortest`` resolves to the right path under ``daily/<YYYY>/``
+  without the regen having to know about year folders.
+* Frontmatter: ``id`` and ``created`` are preserved across re-runs
+  (read from the existing file when present); ``updated`` is bumped
+  only when the body changed; ``autogenerated: true`` flags the
+  file as a brain-managed artifact users shouldn't hand-edit.
+* Idempotent: when the body matches what's already on disk, the file
+  is left untouched (no ``updated`` churn, no atomic write). A test
+  asserts byte-identical output across two consecutive regens.
+* Empty case: when no daily notes exist, the function does NOT write
+  ``index.md``. Combined with the home-page hide-if-empty
+  transformer this gives a coherent "no dailies → no door" UX. A
+  pre-existing ``index.md`` is left in place — deleting it would
+  surprise users who hand-curated the file before running the regen.
+
+The atomic write uses :func:`brain.vault._atomic.atomic_write_text`
+so a crash mid-write can never leave a half-written index visible to
+Quartz's watcher.
+"""
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+import yaml
+
+from ._atomic import atomic_write_text
+from .frontmatter import dump_frontmatter, parse_frontmatter
+from .paths import strip_md_extension
+
+# Filename stem of a daily note: ``YYYY-MM-DD``. Anchored on both ends
+# so a stray ``2026-04-29-rough-thoughts.md`` (a manually-named note
+# under ``daily/``) doesn't get hoisted into the index.
+_DAILY_STEM_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+_INDEX_FILENAME = "index.md"
+
+
+def _list_daily_notes(daily_dir: Path) -> list[Path]:
+    """Return every ``YYYY-MM-DD.md`` daily note under ``daily_dir``.
+
+    Recursive — the brain CLI nests daily notes under
+    ``daily/<YYYY>/`` but a user who's flattened the structure
+    (or never year-folded their pre-2026 notes) is also supported. The
+    filename ``index.md`` is excluded so a stale auto-generated index
+    can't recursively feed itself.
+
+    Returns the empty list when ``daily_dir`` doesn't exist (the brain
+    vault scaffolds it via ``init_vault`` but a user pointing at an
+    unmanaged folder might not have one yet).
+    """
+    if not daily_dir.is_dir():
+        return []
+    out: list[Path] = []
+    for path in daily_dir.rglob("*.md"):
+        if path.name == _INDEX_FILENAME:
+            continue
+        if not path.is_file():
+            continue
+        if _DAILY_STEM_RE.match(path.stem):
+            out.append(path)
+    return out
+
+
+def _build_index_body(daily_paths: list[Path], *, vault_path: Path) -> str:
+    """Return the body text for ``daily/index.md`` from ``daily_paths``.
+
+    Reverse-chronological by filename stem (``YYYY-MM-DD`` lex-sorts
+    correctly as date order). Each line is a path-form-aliased wiki
+    link — ``[[daily/<year>/<stem>|<stem>]]`` — matching the canonical
+    shape that :func:`brain.vault.link_rewrite.rewrite_wiki_links`
+    produces for resolved vault links.
+
+    Why path-form, not bare stem? Earlier prototype used
+    ``[[<stem>]]`` and relied on Quartz's ``markdownLinkResolution:
+    shortest`` to resolve the date-shaped target. That worked at the
+    Quartz level, but the post-write ``brain vault sync`` ran the link
+    rewriter over the body and replaced every bare stem with the path-
+    form alias. The next ``brain daily`` invocation then saw a body
+    mismatch (regen wanted bare stem, disk had path form), triggered
+    a rewrite, and bumped ``updated:`` — losing idempotency and
+    sending the watcher into a rebuild loop on every invocation.
+    Emitting the path-form here makes the regen output already
+    canonical, so the sync step is a no-op and consecutive runs
+    leave the file byte-identical.
+
+    The body opens with a ``# Daily notes`` heading and a one-line
+    preamble — Quartz uses the heading as the page title and the
+    preamble as the breadcrumb-friendly first paragraph. A trailing
+    newline closes the file in the conventional Unix way.
+    """
+    # Sort by stem desc — but keep the resolved path alongside so the
+    # path-form alias can be emitted without a second filesystem walk.
+    rels: list[tuple[str, str]] = []
+    for p in daily_paths:
+        try:
+            rel = p.resolve().relative_to(vault_path.resolve())
+        except ValueError:
+            # Defensive: ``rglob`` shouldn't surface a path outside
+            # ``daily_dir``, but a symlinked vault could in theory.
+            # Skip rather than crash.
+            continue
+        # POSIX form so the wiki link round-trips on Windows too. Strip
+        # ``.md`` to match what the link rewriter emits — shared helper
+        # in :mod:`brain.vault.paths` so the homepage / people / daily
+        # renderers cannot drift on the canonical link-target shape.
+        rels.append((p.stem, strip_md_extension(rel.as_posix())))
+    rels.sort(key=lambda t: t[0], reverse=True)
+
+    lines = [
+        "# Daily notes",
+        "",
+        (
+            "All daily notes, newest first. "
+            "This page is auto-generated — run `brain daily` to refresh it."
+        ),
+        "",
+    ]
+    for stem, posix in rels:
+        lines.append(f"- [[{posix}|{stem}]]")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _read_existing_metadata(target: Path) -> tuple[str | None, str | None, str | None]:
+    """Return ``(id, created, body)`` from an existing index.md, or ``None``s.
+
+    Used to preserve ``id`` and ``created`` across re-runs (so the
+    auto-generated row keeps a stable DB identity even when the body
+    changes), and to short-circuit the rewrite when the body hasn't
+    changed (so the on-disk file stays byte-identical and the watcher
+    doesn't fire a needless rebuild).
+
+    Failure modes — missing file, malformed YAML, structurally invalid
+    frontmatter — return ``(None, None, None)`` so the caller treats
+    the situation as "regenerate from scratch." This is safe: a
+    corrupt index re-emerges with a fresh id; the user can always
+    rebind it via ``brain edit`` if they had hand-edits worth saving
+    (auto-generated files explicitly carry ``autogenerated: true`` to
+    discourage that workflow).
+    """
+    if not target.is_file():
+        return (None, None, None)
+    try:
+        text = target.read_text(encoding="utf-8")
+    except OSError:
+        return (None, None, None)
+    try:
+        fields, body = parse_frontmatter(text)
+    except (ValueError, yaml.YAMLError):
+        return (None, None, None)
+    raw_id = fields.get("id")
+    raw_created = fields.get("created")
+    return (
+        raw_id if isinstance(raw_id, str) else None,
+        raw_created if isinstance(raw_created, str) else None,
+        body,
+    )
+
+
+def regenerate_daily_index(vault_path: Path) -> bool:
+    """Regenerate ``<vault>/daily/index.md`` from the dailies on disk.
+
+    Returns ``True`` if the file was written (or rewritten), ``False``
+    if the regen was a no-op (body unchanged, or no dailies to index).
+
+    Atomic — a crash mid-write leaves the previous ``index.md`` (if
+    any) intact. Idempotent — two consecutive calls against an
+    unchanged ``daily/`` produce a byte-identical file on disk.
+
+    Empty case: no daily notes ⇒ no write. A pre-existing
+    ``index.md`` is left in place rather than deleted; the user's
+    hand-curated file (if any) survives. The home-page hide-if-empty
+    transformer is the layer that reflects "no dailies" in the UI.
+    """
+    daily_dir = vault_path / "daily"
+    target = daily_dir / _INDEX_FILENAME
+
+    daily_paths = _list_daily_notes(daily_dir)
+    if not daily_paths:
+        return False
+
+    body = _build_index_body(daily_paths, vault_path=vault_path)
+
+    existing_id, existing_created, existing_body = _read_existing_metadata(target)
+    if existing_body is not None and existing_body == body:
+        # No content drift — skip rewrite to keep the file byte-identical
+        # and the watcher quiet.
+        return False
+
+    now_iso = datetime.now(UTC).isoformat(timespec="seconds")
+    doc_id = existing_id if existing_id else str(uuid.uuid4())
+    created = existing_created if existing_created else now_iso
+    fields: dict[str, object] = {
+        "id": doc_id,
+        "title": "Daily notes",
+        "created": created,
+        "updated": now_iso,
+        "tags": ["daily", "index"],
+        "kind": "vault",
+        "content_type": "note",
+        "autogenerated": True,
+    }
+    target.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(target, dump_frontmatter(fields, body))
+    return True