taskledger 0.1.0__py3-none-any.whl

taskledger/storage/meta.py

@@ -0,0 +1,103 @@
+"""Read and write .taskledger/storage.yaml workspace metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from taskledger.domain.states import (
+    TASKLEDGER_RECORD_SCHEMA_VERSION,
+    TASKLEDGER_STORAGE_LAYOUT_VERSION,
+)
+from taskledger.errors import LaunchError
+from taskledger.storage.atomic import atomic_write_text
+from taskledger.storage.paths import resolve_taskledger_root
+from taskledger.timeutils import utc_now_iso
+
+
+@dataclass(slots=True, frozen=True)
+class StorageMeta:
+    storage_layout_version: int = TASKLEDGER_STORAGE_LAYOUT_VERSION
+    record_schema_version: int = TASKLEDGER_RECORD_SCHEMA_VERSION
+    created_with_taskledger: str = ""
+    created_at: str = field(default_factory=utc_now_iso)
+    last_migrated_with_taskledger: str | None = None
+    last_migrated_at: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "storage_layout_version": self.storage_layout_version,
+            "record_schema_version": self.record_schema_version,
+            "created_with_taskledger": self.created_with_taskledger,
+            "created_at": self.created_at,
+            "last_migrated_with_taskledger": self.last_migrated_with_taskledger,
+            "last_migrated_at": self.last_migrated_at,
+        }
+
+
+def _storage_yaml_path(workspace_root: Path) -> Path:
+    return resolve_taskledger_root(workspace_root) / "storage.yaml"
+
+
+def read_storage_meta(workspace_root: Path) -> StorageMeta | None:
+    path = _storage_yaml_path(workspace_root)
+    if not path.exists():
+        return None
+    try:
+        payload = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise LaunchError(f"Invalid storage.yaml: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise LaunchError("Invalid storage.yaml: expected mapping.")
+    return StorageMeta(
+        storage_layout_version=_int_field(payload, "storage_layout_version"),
+        record_schema_version=_int_field(payload, "record_schema_version"),
+        created_with_taskledger=_str_field(payload, "created_with_taskledger"),
+        created_at=_str_field(payload, "created_at"),
+        last_migrated_with_taskledger=_optional_str(
+            payload, "last_migrated_with_taskledger"
+        ),
+        last_migrated_at=_optional_str(payload, "last_migrated_at"),
+    )
+
+
+def write_storage_meta(workspace_root: Path, meta: StorageMeta) -> StorageMeta:
+    path = _storage_yaml_path(workspace_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(path, yaml.safe_dump(meta.to_dict(), sort_keys=False))
+    return meta
+
+
+def require_storage_meta(workspace_root: Path) -> StorageMeta:
+    meta = read_storage_meta(workspace_root)
+    if meta is None:
+        raise LaunchError(
+            "Missing storage.yaml. Run 'taskledger init' or 'taskledger migrate apply'."
+        )
+    if meta.storage_layout_version > TASKLEDGER_STORAGE_LAYOUT_VERSION:
+        raise LaunchError(
+            f"Storage layout version {meta.storage_layout_version} is newer than "
+            f"supported {TASKLEDGER_STORAGE_LAYOUT_VERSION}. Upgrade taskledger."
+        )
+    return meta
+
+
+def _int_field(payload: dict[str, object], key: str) -> int:
+    value = payload.get(key)
+    if not isinstance(value, int):
+        raise LaunchError(f"Missing or invalid '{key}' in storage.yaml.")
+    return value
+
+
+def _str_field(payload: dict[str, object], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str):
+        raise LaunchError(f"Missing or invalid '{key}' in storage.yaml.")
+    return value
+
+
+def _optional_str(payload: dict[str, object], key: str) -> str | None:
+    value = payload.get(key)
+    return value if isinstance(value, str) else None

taskledger/storage/migrations.py

@@ -0,0 +1,207 @@
+"""Migration framework for taskledger storage layout and record schema changes."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from taskledger.domain.states import TASKLEDGER_STORAGE_LAYOUT_VERSION
+from taskledger.errors import LaunchError
+
+Record = dict[str, Any]
+MigrationFunc = Callable[[Path], None]
+RecordMigrationFunc = Callable[[Record], Record]
+
+
+@dataclass(frozen=True)
+class LayoutMigration:
+    from_version: int
+    to_version: int
+    name: str
+    apply: MigrationFunc
+
+
+@dataclass(frozen=True)
+class RecordMigration:
+    object_type: str
+    from_schema_version: int
+    to_schema_version: int
+    name: str
+    apply: RecordMigrationFunc
+
+
+@dataclass(frozen=True)
+class MigrationNeeded:
+    path: Path
+    object_type: str
+    current_version: int
+    target_version: int
+
+
+@dataclass(frozen=True)
+class MigrationScanIssue:
+    path: Path
+    object_type: str
+    message: str
+
+
+LAYOUT_MIGRATIONS: tuple[LayoutMigration, ...] = ()
+
+RECORD_MIGRATIONS: tuple[RecordMigration, ...] = ()
+
+
+def required_layout_migrations(current: int, target: int) -> list[LayoutMigration]:
+    migrations: list[LayoutMigration] = []
+    version = current
+    while version < target:
+        match = next(
+            (
+                migration
+                for migration in LAYOUT_MIGRATIONS
+                if migration.from_version == version
+            ),
+            None,
+        )
+        if match is None:
+            raise LaunchError(
+                f"No migration path from storage layout {version} to {version + 1}."
+            )
+        migrations.append(match)
+        version = match.to_version
+    return migrations
+
+
+def scan_records_for_migration(
+    workspace_root: Path,
+) -> list[MigrationNeeded]:
+    needed, _issues = inspect_records_for_migration(workspace_root)
+    return needed
+
+
+def inspect_records_for_migration(
+    workspace_root: Path,
+) -> tuple[list[MigrationNeeded], list[MigrationScanIssue]]:
+    """Scan all durable records for pending schema migrations.
+
+    Returns records whose schema_version is below the current target and any
+    malformed Markdown/frontmatter records encountered during the scan.
+    """
+    from taskledger.storage.task_store import resolve_v2_paths
+
+    paths = resolve_v2_paths(workspace_root)
+    needed: list[MigrationNeeded] = []
+    issues: list[MigrationScanIssue] = []
+    if not paths.tasks_dir.exists():
+        return needed, issues
+
+    for task_dir in sorted(paths.tasks_dir.glob("task-*")):
+        if not task_dir.is_dir():
+            continue
+        _scan_dir(task_dir / "plans", "plan", needed, issues)
+        _scan_dir(task_dir / "questions", "question", needed, issues)
+        _scan_dir(task_dir / "runs", "run", needed, issues)
+        _scan_dir(task_dir / "changes", "change", needed, issues)
+        _scan_dir(task_dir / "todos", "todo", needed, issues)
+        _scan_dir(task_dir / "links", "link", needed, issues)
+        _scan_dir(task_dir / "requirements", "requirement", needed, issues)
+        _scan_dir(task_dir / "handoffs", "handoff", needed, issues)
+
+        task_md = task_dir / "task.md"
+        if task_md.exists():
+            _scan_file(task_md, "task", needed, issues)
+
+    return needed, issues
+
+
+def apply_layout_migrations(
+    workspace_root: Path,
+    current_version: int,
+    dry_run: bool = False,
+) -> list[str]:
+    """Apply layout migrations from current_version
+    to TASKLEDGER_STORAGE_LAYOUT_VERSION.
+
+    Returns list of migration names that were applied (or would be applied in dry_run).
+    """
+    from taskledger.storage.meta import read_storage_meta, write_storage_meta
+
+    migrations = required_layout_migrations(
+        current_version, TASKLEDGER_STORAGE_LAYOUT_VERSION
+    )
+    applied: list[str] = []
+    for migration in migrations:
+        if not dry_run:
+            migration.apply(workspace_root)
+        applied.append(migration.name)
+
+    if not dry_run and applied:
+        meta = read_storage_meta(workspace_root)
+        if meta is not None:
+            try:
+                from taskledger._version import __version__ as tl_version
+            except ImportError:
+                tl_version = "unknown"
+            from taskledger.timeutils import utc_now_iso
+
+            updated = type(meta)(
+                storage_layout_version=TASKLEDGER_STORAGE_LAYOUT_VERSION,
+                record_schema_version=meta.record_schema_version,
+                created_with_taskledger=meta.created_with_taskledger,
+                created_at=meta.created_at,
+                last_migrated_with_taskledger=tl_version,
+                last_migrated_at=utc_now_iso(),
+            )
+            write_storage_meta(workspace_root, updated)
+
+    return applied
+
+
+def _scan_dir(
+    directory: Path,
+    object_type: str,
+    needed: list[MigrationNeeded],
+    issues: list[MigrationScanIssue],
+) -> None:
+    if not directory.exists():
+        return
+    for md_file in sorted(directory.glob("*.md")):
+        _scan_file(md_file, object_type, needed, issues)
+
+
+def _scan_file(
+    path: Path,
+    default_object_type: str,
+    needed: list[MigrationNeeded],
+    issues: list[MigrationScanIssue],
+) -> None:
+    from taskledger.storage.frontmatter import read_markdown_front_matter
+
+    try:
+        metadata, _ = read_markdown_front_matter(path)
+    except Exception as exc:
+        issues.append(
+            MigrationScanIssue(
+                path=path,
+                object_type=default_object_type,
+                message=f"Cannot parse {default_object_type} record {path}: {exc}",
+            )
+        )
+        return
+    version = metadata.get("schema_version")
+    if not isinstance(version, int):
+        return
+    if version < 1:
+        return  # Legacy/unversioned, not a migration candidate
+    from taskledger.domain.states import TASKLEDGER_SCHEMA_VERSION
+
+    if version < TASKLEDGER_SCHEMA_VERSION:
+        needed.append(
+            MigrationNeeded(
+                path=path,
+                object_type=str(metadata.get("object_type", default_object_type)),
+                current_version=version,
+                target_version=TASKLEDGER_SCHEMA_VERSION,
+            )
+        )

taskledger/storage/paths.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from taskledger.storage.project_config import load_project_config_document
+
+CANONICAL_PROJECT_CONFIG_FILENAME = "taskledger.toml"
+PROJECT_CONFIG_FILENAMES = (".taskledger.toml", CANONICAL_PROJECT_CONFIG_FILENAME)
+DEFAULT_TASKLEDGER_DIR_NAME = ".taskledger"
+LEGACY_PROJECT_CONFIG_FILENAME = "project.toml"
+
+
+@dataclass(slots=True, frozen=True)
+class ProjectLocator:
+    workspace_root: Path
+    config_path: Path
+    taskledger_dir: Path
+    source: Literal["explicit", "dotfile", "toml", "legacy", "default"]
+
+
+@dataclass(slots=True, frozen=True)
+class ProjectPaths:
+    workspace_root: Path
+    project_dir: Path
+    taskledger_dir: Path
+    config_path: Path
+    repos_dir: Path
+    repo_index_path: Path
+
+
+def resolve_taskledger_root(workspace_root: Path) -> Path:
+    return load_project_locator(workspace_root).taskledger_dir
+
+
+def resolve_project_paths(workspace_root: Path) -> ProjectPaths:
+    locator = load_project_locator(workspace_root)
+    return project_paths_for_root(
+        locator.workspace_root,
+        locator.taskledger_dir,
+        config_path=locator.config_path,
+    )
+
+
+def discover_workspace_root(start: Path) -> Path:
+    return load_project_locator(start).workspace_root
+
+
+def find_project_config(start: Path) -> Path | None:
+    for current in _search_roots(start):
+        for filename in PROJECT_CONFIG_FILENAMES:
+            candidate = current / filename
+            if candidate.exists():
+                return candidate
+    return None
+
+
+def load_project_locator(
+    start: Path,
+    *,
+    taskledger_dir_override: Path | None = None,
+    config_filename: str = CANONICAL_PROJECT_CONFIG_FILENAME,
+) -> ProjectLocator:
+    start_path = start.expanduser().resolve()
+    config_path = find_project_config(start_path)
+    if config_path is not None:
+        workspace_root = config_path.parent
+        taskledger_dir = (
+            _resolve_path(taskledger_dir_override, workspace_root=workspace_root)
+            if taskledger_dir_override is not None
+            else _taskledger_dir_from_config(config_path, workspace_root=workspace_root)
+        )
+        return ProjectLocator(
+            workspace_root=workspace_root,
+            config_path=config_path,
+            taskledger_dir=taskledger_dir,
+            source=(
+                "explicit"
+                if taskledger_dir_override is not None
+                else "dotfile"
+                if config_path.name.startswith(".")
+                else "toml"
+            ),
+        )
+
+    legacy_workspace_root = _find_legacy_workspace_root(start_path)
+    if legacy_workspace_root is not None:
+        legacy_config_path = (
+            legacy_workspace_root
+            / DEFAULT_TASKLEDGER_DIR_NAME
+            / LEGACY_PROJECT_CONFIG_FILENAME
+        )
+        workspace_root = legacy_workspace_root
+        return ProjectLocator(
+            workspace_root=workspace_root,
+            config_path=(
+                legacy_config_path
+                if legacy_config_path.exists()
+                else workspace_root / config_filename
+            ),
+            taskledger_dir=(
+                _resolve_path(taskledger_dir_override, workspace_root=workspace_root)
+                if taskledger_dir_override is not None
+                else workspace_root / DEFAULT_TASKLEDGER_DIR_NAME
+            ),
+            source="explicit" if taskledger_dir_override is not None else "legacy",
+        )
+
+    workspace_root = start_path
+    return ProjectLocator(
+        workspace_root=workspace_root,
+        config_path=workspace_root / config_filename,
+        taskledger_dir=(
+            _resolve_path(taskledger_dir_override, workspace_root=workspace_root)
+            if taskledger_dir_override is not None
+            else workspace_root / DEFAULT_TASKLEDGER_DIR_NAME
+        ),
+        source="explicit" if taskledger_dir_override is not None else "default",
+    )
+
+
+def project_paths_for_root(
+    workspace_root: Path,
+    project_dir: Path,
+    *,
+    config_path: Path | None = None,
+) -> ProjectPaths:
+    indexes_dir = project_dir / "indexes"
+    return ProjectPaths(
+        workspace_root=workspace_root,
+        project_dir=project_dir,
+        taskledger_dir=project_dir,
+        config_path=config_path or workspace_root / CANONICAL_PROJECT_CONFIG_FILENAME,
+        repos_dir=project_dir / "repos",
+        repo_index_path=indexes_dir / "repos.json",
+    )
+
+
+def _search_roots(start: Path) -> tuple[Path, ...]:
+    current = start if start.is_dir() else start.parent
+    return (current, *current.parents)
+
+
+def _find_legacy_workspace_root(start: Path) -> Path | None:
+    for current in _search_roots(start):
+        if (current / DEFAULT_TASKLEDGER_DIR_NAME / "storage.yaml").exists():
+            return current
+    return None
+
+
+def _taskledger_dir_from_config(config_path: Path, *, workspace_root: Path) -> Path:
+    document = load_project_config_document(config_path)
+    raw_value = document.get("taskledger_dir")
+    if not isinstance(raw_value, str) or not raw_value.strip():
+        return workspace_root / DEFAULT_TASKLEDGER_DIR_NAME
+    return _resolve_path(raw_value, workspace_root=workspace_root)
+
+
+def _resolve_path(value: str | Path, *, workspace_root: Path) -> Path:
+    raw_value = os.path.expandvars(os.fspath(value))
+    path = Path(raw_value).expanduser()
+    if not path.is_absolute():
+        path = workspace_root / path
+    return path.resolve()