farora 0.5.0__py3-none-any.whl

farora/__init__.py

@@ -0,0 +1,14 @@
+"""Farora — a local-first, plain-text task tracker."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    # `pyproject.toml`'s `[project].version` is the single source of truth. Reading it
+    # back from the installed distribution metadata is what keeps `farora --version`
+    # and the built wheel from ever disagreeing — never hardcode a number here.
+    __version__ = _version("farora")
+except PackageNotFoundError:  # pragma: no cover - source tree with nothing installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

farora/cli.py

@@ -0,0 +1,287 @@
+"""Entry point for the ``farora`` console script.
+
+Exposes three commands: bare ``farora`` (launch the TUI), ``farora doctor``
+(validate and reconcile a repo) and ``farora gc`` (purge expired tombstones).
+The remaining command bodies land with their milestones.
+
+This module is also the **composition root**: the one place that knows both that
+tasks live in a local folder and that a Textual app is going to show them. It
+builds the store adapter, injects it into the core's service, and hands that
+service to the TUI — which is why neither of those packages imports the other
+(``04-architecture.md``: ``tui -> core <- store``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from dataclasses import replace
+from pathlib import Path
+
+from . import __version__
+
+DEFAULT_REPO = "~/.farora"
+
+REPO_ENV = "FARORA_REPO"
+"""``$FARORA_REPO`` — the repo when ``--repo`` is not given (FR-X1)."""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the ``farora`` argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="farora",
+        description="A local-first, plain-text task tracker.",
+    )
+    parser.add_argument("--version", action="version", version=f"farora {__version__}")
+    _add_repo_argument(parser, default=None)
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    doctor = subparsers.add_parser(
+        "doctor",
+        help="validate and reconcile a repo",
+        description="Validate repo structure and reconcile sync conflicts.",
+    )
+    _add_repo_argument(doctor)
+    doctor.set_defaults(handler=_cmd_doctor)
+
+    gc = subparsers.add_parser(
+        "gc",
+        help="purge expired tombstones",
+        description="Purge journals of tasks deleted longer ago than the retention window.",
+    )
+    _add_repo_argument(gc)
+    gc.add_argument(
+        "--older-than",
+        metavar="DURATION",
+        help="retention window override (default: from config, 30d)",
+    )
+    gc.set_defaults(handler=_cmd_gc)
+
+    parser.set_defaults(handler=_cmd_tui)
+    return parser
+
+
+def _add_repo_argument(
+    parser: argparse.ArgumentParser, default: str | None = argparse.SUPPRESS
+) -> None:
+    """Add ``--repo`` to a parser, accepted both before and after a subcommand.
+
+    Subparsers suppress the default so that an unpassed ``--repo`` does not
+    overwrite one already parsed off the main parser.
+    """
+    parser.add_argument(
+        "--repo",
+        metavar="PATH",
+        default=default,
+        help=f"repo path (default: $FARORA_REPO, else {DEFAULT_REPO})",
+    )
+
+
+def resolve_repo(repo: str | None) -> Path:
+    """Which repo to work on: ``--repo``, else ``$FARORA_REPO``, else ``~/.farora`` (FR-X1).
+
+    The one answer, for every entry point — the TUI, ``doctor`` and ``gc`` all call
+    this and none of them reads ``$FARORA_REPO`` for itself. Everything that hangs off
+    a repo path hangs off this one: the single-writer lock, the startup check, and the
+    machine-local cache key that ``ui_state_path`` derives.
+    """
+    return Path(repo or os.environ.get(REPO_ENV) or DEFAULT_REPO).expanduser()
+
+
+def _cmd_tui(args: argparse.Namespace) -> int:
+    """Launch the TUI over a local repo — the composition root's whole job.
+
+    Imports are deferred because this is the only command that needs Textual, and
+    ``farora gc`` should not pay to import a UI it will not draw.
+    """
+    from contextlib import ExitStack, suppress
+    from functools import partial
+
+    from farora.core import FaroraError, Retention, StoreIoError, TaskService
+    from farora.doctor import light, startup_notice
+    from farora.gc import opportunistic
+    from farora.gitsync import GitSync
+    from farora.gitsync.oplog import OpLog
+    from farora.gitsync.runner import GitRunner
+    from farora.store_local import (
+        LocalTaskRepository,
+        device_id,
+        init_repo,
+        load_config,
+        repo_lock,
+        ui_state_path,
+    )
+    from farora.tui import Commands, FaroraApp, choose_spawner, viewer_status
+
+    repo = resolve_repo(args.repo)
+    with ExitStack() as stack:
+        try:
+            init_repo(repo)  # idempotent: this is also how the default repo first exists
+            repository = LocalTaskRepository(repo)
+            # One machine id, minted once: the service's actor and git tracking's fallback
+            # committer identity (A8) are the same machine, so a commit farora authors and
+            # the journal line it publishes name one and the same author.
+            actor = device_id()
+            service = TaskService(repository, actor=actor)
+            # `~/.config/farora/config.toml` is machine-local state, so reading it is
+            # the store adapter's; deciding what `e` and `v` run is the TUI's
+            # (`06-ux-and-keymap.md` §4), and how long a tombstone is kept is FR-D4's.
+            # This is the only place those facts meet — which is why `farora.tui` can
+            # own the editor without importing the thing that knows where a config
+            # file lives.
+            config = load_config()
+            commands = Commands.from_config(config)
+            retention = Retention.from_config(config)
+            # Before the check, and before the app: FR-X3's guard covers every write
+            # this process makes, and the startup check is the first of them.
+            stack.enter_context(repo_lock(repo))
+            notice = startup_notice(light(repository, service))
+        except FaroraError as exc:
+            print(f"farora: {exc}", file=sys.stderr)
+            return 1
+
+        # §5's "opportunistically on ordinary runs" — decision #2's whole scheduler.
+        #
+        # **After the check, and that ordering is load-bearing.** gc reads a tombstone
+        # as "the log's terminal entry is a delete", which is a claim about the *merged*
+        # log; `light` has just unioned in every conflict copy of every journal, so the
+        # log gc reads here is the one that has heard from the other machine.
+        #
+        # Failure is swallowed on purpose, and only here. A repo whose journals cannot
+        # be unlinked — a read-only folder, a full disk — is a repo whose tasks the user
+        # can still read and still change, and refusing to open their tracker because
+        # housekeeping did not go through would be Farora holding their work hostage to
+        # its own tidiness. It costs one keeping-things-too-long, and the next run tries
+        # again.
+        with suppress(StoreIoError):
+            opportunistic(repository, service, retention)
+        # Git tracking's composition root (technical-design §1, A14). Built here, after
+        # the lock, because the engine only ever runs while this process — the single
+        # writer — holds the repo, and torn down with the app it belongs to. The facade
+        # is handed to the app as the one thing it is: a controller answering the TUI's
+        # protocol. The app never learns it is git — only that something syncs — and it
+        # is the app's `on_mount` that starts the engine's loop as a worker so Textual
+        # owns its lifetime. A repo with no git configured makes every tick a silent
+        # no-op, so wiring this unconditionally costs an unconfigured user nothing.
+        sync = GitSync(repository.layout, service, actor, GitRunner(repo), OpLog.for_repo(repo))
+        FaroraApp(
+            service,
+            ui_state_path(repo),
+            # The capability, handed over as the one method it is
+            # (`04-architecture.md` §2): the app learns how to reach a task's file and
+            # still not that the file is in a folder.
+            body_path=repository.body_path,
+            panes=partial(choose_spawner, commands),
+            viewer=partial(viewer_status, commands),
+            notice=notice,
+            sync=sync,
+        ).run()
+    return 0
+
+
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    """Validate and reconcile a repo (FR-X4, ``05-storage-and-data-model.md`` §7).
+
+    Deliberately does **not** ``init_repo``: ``farora`` creates the repo it is asked
+    for, because a missing ``~/.farora`` on a first run is not a mistake, but a doctor
+    that created its patient would answer ``farora doctor --repo ~/typo`` by declaring
+    an empty folder healthy. Here the marker's absence is the finding.
+
+    Exits 1 when anything is left for the user, the way a linter does — what doctor
+    fixed by itself is not a failure, and what it could not is.
+    """
+    from farora.core import FaroraError, TaskService
+    from farora.doctor import check, render
+    from farora.store_local import LocalTaskRepository, device_id, repo_lock
+
+    repo = resolve_repo(args.repo)
+    try:
+        repository = LocalTaskRepository(repo)
+        service = TaskService(repository, actor=device_id())
+        with repo_lock(repo):
+            diagnosis = check(repository, service, confirm=_ask)
+    except FaroraError as exc:
+        print(f"farora: {exc}", file=sys.stderr)
+        return 1
+    print(render(diagnosis, repository.root))
+    return 1 if diagnosis.outstanding else 0
+
+
+def _ask(question: str) -> bool:
+    """§7's "after confirmation", at a terminal — and a firm no without one.
+
+    A doctor whose stdin is a pipe cannot ask, so it does not assume. The finding is
+    reported instead and the file is left alone, which is the only safe reading of
+    silence when the question is "shall I journal this task as deleted?".
+    """
+    if not sys.stdin.isatty():
+        return False
+    try:
+        return input(f"{question} [y/N] ").strip().lower() in {"y", "yes"}
+    except EOFError:
+        return False
+
+
+def _cmd_gc(args: argparse.Namespace) -> int:
+    """Purge expired tombstones on demand (FR-D4, ``05-storage-and-data-model.md`` §5).
+
+    Does not ``init_repo``, for :func:`_cmd_doctor`'s reason, and takes the repo lock for
+    :func:`_cmd_tui`'s: this removes files.
+
+    **``[gc] enabled = false`` does not stop this**, and ``--older-than`` beats the
+    config's window. The switch governs the sweep an ordinary run does on its own
+    (:func:`~farora.gc.opportunistic`); a user typing ``farora gc`` is asking, and the
+    only reading of the flag under which they could not is one where turning the
+    automatic sweep off also takes the manual one away. It is said out loud rather than
+    done quietly — see :data:`~farora.gc.DISABLED_NOTE`.
+    """
+    from farora.core import FaroraError, Retention, TaskService, parse_duration
+    from farora.gc import DISABLED_NOTE, collect, render
+    from farora.store_local import LocalTaskRepository, device_id, load_config, repo_lock
+
+    repo = resolve_repo(args.repo)
+    try:
+        retention = Retention.from_config(load_config())
+        if args.older_than is not None:
+            retention = replace(retention, window=parse_duration(args.older_than), complaint="")
+    except FaroraError as exc:
+        print(f"farora: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        # `--older-than lastweek`. An unusable window is the one thing gc must not
+        # guess at, and argparse's own exit code for a bad argument says so.
+        print(f"farora: --older-than: {exc}", file=sys.stderr)
+        return 2
+    if retention.complaint:
+        # The config's window is unreadable and nobody named one on the command line.
+        # `Retention.from_config` has already refused to invent a number; this is only
+        # where the user hears about it.
+        print(f"farora: {retention.complaint}", file=sys.stderr)
+        return 1
+    if not retention.enabled:
+        print(f"farora: {DISABLED_NOTE}", file=sys.stderr)
+
+    try:
+        repository = LocalTaskRepository(repo)
+        service = TaskService(repository, actor=device_id())
+        with repo_lock(repo):
+            sweep = collect(repository, service, window=retention.window)
+    except FaroraError as exc:
+        print(f"farora: {exc}", file=sys.stderr)
+        return 1
+    print(render(sweep, repository.root))
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse ``argv`` and dispatch. Returns the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

farora/core/__init__.py

@@ -0,0 +1,339 @@
+"""Domain core: models, operation surface, ``TaskService``, events, undo.
+
+This package is the hexagon's inside. It must not import ``farora.tui`` or
+``farora.store_local`` — the dependency direction is ``tui -> core <- store``,
+enforced by ``tests/core/test_import_boundary.py``.
+"""
+
+from farora.core.assets import rewrite_asset_links
+from farora.core.doctor import (
+    Diagnosis,
+    Finding,
+    FindingKind,
+    merge_journal_lines,
+    orphans,
+    unknown_statuses,
+)
+from farora.core.errors import (
+    HTTP_STATUS,
+    CrossProjectError,
+    CycleError,
+    ErrorCode,
+    FaroraError,
+    InvalidSlugError,
+    InvalidStatusError,
+    NotFoundError,
+    RepoLockedError,
+    SlugTakenError,
+    StaleError,
+    StatusExistsError,
+    StoreIoError,
+    error_for,
+)
+from farora.core.events import (
+    PROJECT_JOURNAL_OPS,
+    Actor,
+    ChangeKind,
+    DomainEvent,
+    FieldChange,
+    JournalEntry,
+    JournalOp,
+    RepoChange,
+    changed_fields,
+    field_payload,
+    fields_payload,
+)
+from farora.core.gc import (
+    DEFAULT_ENABLED,
+    DEFAULT_WINDOW,
+    DURATION_FORMS,
+    ENABLED_KEY,
+    GC_SECTION,
+    RETENTION_KEY,
+    Retention,
+    deleted_at,
+    expired,
+    format_duration,
+    parse_duration,
+)
+from farora.core.hashing import HASH_ALGORITHM, content_hash
+from farora.core.ids import (
+    SLUG_MAX_LENGTH,
+    SLUG_MIN_LENGTH,
+    SLUG_PATTERN,
+    TASK_ID_PATTERN,
+    OpId,
+    Slug,
+    TaskId,
+    Uid,
+    Uuid7,
+    format_task_id,
+    is_valid_slug,
+    new_op_id,
+    new_uid,
+    parse_task_id,
+    project_of,
+    validate_slug,
+)
+from farora.core.models import (
+    BUILTIN_STATUSES,
+    DEFAULT_STATUS,
+    FORMAT_VERSION,
+    SCHEMA_VERSION,
+    Name,
+    Project,
+    Rank,
+    RepoInfo,
+    Status,
+    StatusKey,
+    StatusKind,
+    Task,
+)
+from farora.core.notes import (
+    BLOCK_SEPARATOR,
+    NOTE_TIMESTAMP_FORMAT,
+    NoteLocator,
+    append_note,
+    find_note_block,
+    format_note_block,
+    remove_note_block,
+)
+from farora.core.operations import (
+    FIRST,
+    LAST,
+    OPERATION_ADAPTER,
+    ROOT,
+    After,
+    AnyOperation,
+    Before,
+    First,
+    Last,
+    Mutation,
+    Operation,
+    OperationKind,
+    Position,
+    ProjectCreateOp,
+    ProjectGetOp,
+    ProjectListOp,
+    ProjectRenameOp,
+    RepoInfoOp,
+    StatusAddOp,
+    TaskCopyOp,
+    TaskCreateOp,
+    TaskDeleteOp,
+    TaskGetOp,
+    TaskListBodiesOp,
+    TaskListOp,
+    TaskLogOp,
+    TaskMoveOp,
+    TaskNoteOp,
+    TaskReadBodyOp,
+    TaskRenameOp,
+    TaskRestoreOp,
+    TaskSetDobyOp,
+    TaskSetStatusOp,
+    TaskTransferOp,
+    TaskWriteBodyOp,
+    after,
+    before,
+    parse_operation,
+)
+from farora.core.ports import DeferredWrites, LocalFileAccess, TaskRepository
+from farora.core.ranking import (
+    MAX_RANK_LENGTH,
+    RANK_HEAL_REASON,
+    healed_ranks,
+    needs_rank_heal,
+    position_for_rank,
+    rank_between,
+    rank_for_position,
+    sort_key,
+    sort_siblings,
+)
+from farora.core.reconcile import (
+    ARBITRATED,
+    FIELD_OPS,
+    Arbitration,
+    Reconciliation,
+    arbitrate,
+    arbitrate_conflict,
+    group_edits,
+    history_of,
+    journaled,
+    last_body_hash,
+    last_known,
+    last_known_task,
+    newest,
+)
+from farora.core.service import Listener, TaskService
+from farora.core.timestamps import (
+    DueDate,
+    Timestamp,
+    format_date,
+    format_rfc3339,
+    normalize,
+    now,
+    parse_date,
+    parse_rfc3339,
+)
+from farora.core.undo import UndoEntry, UndoKind, UndoOutcome, UndoStack
+
+__all__ = [
+    "ARBITRATED",
+    "Actor",
+    "After",
+    "AnyOperation",
+    "Arbitration",
+    "BLOCK_SEPARATOR",
+    "BUILTIN_STATUSES",
+    "Before",
+    "ChangeKind",
+    "CrossProjectError",
+    "CycleError",
+    "DEFAULT_ENABLED",
+    "DEFAULT_STATUS",
+    "DEFAULT_WINDOW",
+    "DURATION_FORMS",
+    "DeferredWrites",
+    "Diagnosis",
+    "DomainEvent",
+    "DueDate",
+    "ENABLED_KEY",
+    "ErrorCode",
+    "FIELD_OPS",
+    "FIRST",
+    "FORMAT_VERSION",
+    "FaroraError",
+    "FieldChange",
+    "Finding",
+    "FindingKind",
+    "First",
+    "GC_SECTION",
+    "HASH_ALGORITHM",
+    "HTTP_STATUS",
+    "InvalidSlugError",
+    "InvalidStatusError",
+    "JournalEntry",
+    "JournalOp",
+    "LAST",
+    "Last",
+    "Listener",
+    "LocalFileAccess",
+    "MAX_RANK_LENGTH",
+    "Mutation",
+    "NOTE_TIMESTAMP_FORMAT",
+    "Name",
+    "NotFoundError",
+    "NoteLocator",
+    "OPERATION_ADAPTER",
+    "OpId",
+    "Operation",
+    "OperationKind",
+    "PROJECT_JOURNAL_OPS",
+    "Position",
+    "Project",
+    "ProjectCreateOp",
+    "ProjectGetOp",
+    "ProjectListOp",
+    "ProjectRenameOp",
+    "RANK_HEAL_REASON",
+    "RETENTION_KEY",
+    "ROOT",
+    "Rank",
+    "Reconciliation",
+    "RepoChange",
+    "RepoInfo",
+    "RepoInfoOp",
+    "RepoLockedError",
+    "Retention",
+    "SCHEMA_VERSION",
+    "SLUG_MAX_LENGTH",
+    "SLUG_MIN_LENGTH",
+    "SLUG_PATTERN",
+    "Slug",
+    "SlugTakenError",
+    "StaleError",
+    "Status",
+    "StatusAddOp",
+    "StatusExistsError",
+    "StatusKey",
+    "StatusKind",
+    "StoreIoError",
+    "TASK_ID_PATTERN",
+    "Task",
+    "TaskCopyOp",
+    "TaskCreateOp",
+    "TaskDeleteOp",
+    "TaskGetOp",
+    "TaskId",
+    "TaskListBodiesOp",
+    "TaskListOp",
+    "TaskLogOp",
+    "TaskMoveOp",
+    "TaskNoteOp",
+    "TaskReadBodyOp",
+    "TaskRenameOp",
+    "TaskRepository",
+    "TaskRestoreOp",
+    "TaskService",
+    "TaskSetDobyOp",
+    "TaskSetStatusOp",
+    "TaskTransferOp",
+    "TaskWriteBodyOp",
+    "Timestamp",
+    "Uid",
+    "UndoEntry",
+    "UndoKind",
+    "UndoOutcome",
+    "UndoStack",
+    "Uuid7",
+    "after",
+    "append_note",
+    "arbitrate",
+    "arbitrate_conflict",
+    "before",
+    "changed_fields",
+    "content_hash",
+    "deleted_at",
+    "error_for",
+    "expired",
+    "field_payload",
+    "fields_payload",
+    "find_note_block",
+    "format_date",
+    "format_duration",
+    "format_note_block",
+    "format_rfc3339",
+    "format_task_id",
+    "group_edits",
+    "healed_ranks",
+    "history_of",
+    "is_valid_slug",
+    "journaled",
+    "last_body_hash",
+    "last_known",
+    "last_known_task",
+    "merge_journal_lines",
+    "needs_rank_heal",
+    "new_op_id",
+    "new_uid",
+    "newest",
+    "normalize",
+    "now",
+    "orphans",
+    "parse_date",
+    "parse_duration",
+    "parse_operation",
+    "parse_rfc3339",
+    "parse_task_id",
+    "position_for_rank",
+    "project_of",
+    "rank_between",
+    "rank_for_position",
+    "remove_note_block",
+    "rewrite_asset_links",
+    "sort_key",
+    "sort_siblings",
+    "unknown_statuses",
+    "validate_slug",
+]