taskledger 0.1.0__py3-none-any.whl

taskledger/storage/__init__.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from taskledger.storage.init import ensure_project_exists, init_project_state
+from taskledger.storage.paths import resolve_project_paths, resolve_taskledger_root
+from taskledger.storage.project_config import (
+    DEFAULT_PROJECT_TOML,
+    load_project_config_overrides,
+    merge_project_config,
+)
+from taskledger.storage.repos import (
+    add_repo,
+    clear_default_execution_repo,
+    load_repos,
+    remove_repo,
+    resolve_repo,
+    resolve_repo_root,
+    save_repos,
+    set_default_execution_repo,
+    set_repo_role,
+)
+
+__all__ = [
+    "DEFAULT_PROJECT_TOML",
+    "add_repo",
+    "clear_default_execution_repo",
+    "ensure_project_exists",
+    "init_project_state",
+    "load_project_config_overrides",
+    "load_repos",
+    "merge_project_config",
+    "remove_repo",
+    "resolve_project_paths",
+    "resolve_repo",
+    "resolve_repo_root",
+    "resolve_taskledger_root",
+    "save_repos",
+    "set_default_execution_repo",
+    "set_repo_role",
+]

taskledger/storage/atomic.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from taskledger.errors import LaunchError
+
+
+def atomic_write_text(path: Path, contents: str) -> None:
+    temp_path: Path | None = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=path.parent,
+            delete=False,
+        ) as handle:
+            handle.write(contents)
+            handle.flush()
+            os.fsync(handle.fileno())
+            temp_path = Path(handle.name)
+        os.replace(temp_path, path)
+        _fsync_directory(path.parent)
+    except OSError as exc:
+        if temp_path is not None and temp_path.exists():
+            temp_path.unlink(missing_ok=True)
+        raise LaunchError(f"Failed to atomically write {path}: {exc}") from exc
+
+
+def atomic_create_text(path: Path, contents: str) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError as exc:
+        raise LaunchError(f"Lock already exists: {path}") from exc
+    except OSError as exc:
+        raise LaunchError(f"Failed to create {path}: {exc}") from exc
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(contents)
+            handle.flush()
+            os.fsync(handle.fileno())
+    except OSError as exc:
+        raise LaunchError(f"Failed to write {path}: {exc}") from exc
+    _fsync_directory(path.parent)
+
+
+def _fsync_directory(path: Path) -> None:
+    if os.name != "posix":
+        return
+    directory_fd = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(directory_fd)
+    finally:
+        os.close(directory_fd)

taskledger/storage/common.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+from hashlib import sha256
+from pathlib import Path
+
+from taskledger.errors import LaunchError
+from taskledger.storage.paths import ProjectPaths
+
+
+def load_json_array(path: Path, label: str) -> list[dict[str, object]]:
+    if not path.exists():
+        return []
+    text = read_text(path).strip()
+    if not text:
+        return []
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise LaunchError(f"Invalid {label} {path}: {exc}") from exc
+    if not isinstance(data, list):
+        raise LaunchError(f"Invalid {label} {path}: expected a JSON array.")
+    return [item for item in data if isinstance(item, dict)]
+
+
+def load_json_object(path: Path, label: str) -> dict[str, object]:
+    text = read_text(path).strip()
+    if not text:
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise LaunchError(f"Invalid {label} {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise LaunchError(f"Invalid {label} {path}: expected a JSON object.")
+    return data
+
+
+def write_json(path: Path, payload: object) -> None:
+    write_text(path, json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+
+def write_text(path: Path, contents: str) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(contents, encoding="utf-8")
+    except OSError as exc:
+        raise LaunchError(f"Failed to write {path}: {exc}") from exc
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise LaunchError(f"Failed to read {path}: {exc}") from exc
+
+
+def relative_to_project(paths: ProjectPaths, target: Path) -> str:
+    return str(target.relative_to(paths.project_dir))
+
+
+def relative_to_workspace(paths: ProjectPaths, target: Path) -> str:
+    try:
+        return str(target.relative_to(paths.workspace_root))
+    except ValueError:
+        return str(target)
+
+
+def summarize_text(text: str) -> str | None:
+    stripped = " ".join(text.split())
+    if not stripped:
+        return None
+    if len(stripped) <= 80:
+        return stripped
+    return stripped[:77] + "..."
+
+
+def content_hash(text: str) -> str | None:
+    if not text:
+        return None
+    return sha256(text.encode("utf-8")).hexdigest()
+
+
+def merge_text(current: str, incoming: str, *, prepend: bool) -> str:
+    if not current:
+        return incoming
+    if not incoming:
+        return current
+    combined = [incoming, current] if prepend else [current, incoming]
+    return "\n\n".join(part.rstrip("\n") for part in combined if part)

taskledger/storage/events.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from taskledger.domain.models import TaskEvent
+from taskledger.errors import LaunchError
+
+
+def append_event(events_dir: Path, event: TaskEvent) -> Path:
+    path = event_log_path(events_dir, event.ts)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event.to_dict(), sort_keys=True) + "\n")
+    except OSError as exc:
+        raise LaunchError(f"Failed to append event {path}: {exc}") from exc
+    return path
+
+
+def load_events(events_dir: Path) -> list[TaskEvent]:
+    if not events_dir.exists():
+        return []
+    events: list[TaskEvent] = []
+    seen_ids: set[str] = set()
+    for path in sorted(events_dir.glob("*.ndjson")):
+        try:
+            for line in path.read_text(encoding="utf-8").splitlines():
+                if not line.strip():
+                    continue
+                payload = json.loads(line)
+                if isinstance(payload, dict):
+                    event = TaskEvent.from_dict(payload)
+                    if event.event_id in seen_ids:
+                        raise LaunchError(
+                            f"Duplicate event id detected: {event.event_id}"
+                        )
+                    seen_ids.add(event.event_id)
+                    events.append(event)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise LaunchError(f"Failed to read event log {path}: {exc}") from exc
+    return sorted(events, key=lambda item: (item.ts, item.event_id))
+
+
+def load_recent_events(
+    events_dir: Path,
+    *,
+    task_id: str | None = None,
+    limit: int = 50,
+) -> list[TaskEvent]:
+    if limit <= 0 or not events_dir.exists():
+        return []
+    matches: list[TaskEvent] = []
+    for path in sorted(events_dir.glob("*.ndjson"), reverse=True):
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError as exc:
+            raise LaunchError(f"Failed to read event log {path}: {exc}") from exc
+        for line in reversed(lines):
+            if not line.strip():
+                continue
+            try:
+                payload = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise LaunchError(f"Failed to read event log {path}: {exc}") from exc
+            if not isinstance(payload, dict):
+                continue
+            event = TaskEvent.from_dict(payload)
+            if task_id is not None and event.task_id != task_id:
+                continue
+            matches.append(event)
+            if len(matches) >= limit:
+                return list(reversed(matches))
+    return list(reversed(matches))
+
+
+def next_event_id(events_dir: Path, timestamp: str) -> str:
+    sequence = len(load_events(events_dir)) + 1
+    normalized = (
+        timestamp.replace(":", "")
+        .replace("-", "")
+        .replace("+00:00", "Z")
+        .replace(".", "")
+    )
+    return f"evt-{normalized}-{sequence:06d}"
+
+
+def event_log_path(events_dir: Path, timestamp: str) -> Path:
+    return events_dir / f"{timestamp[:10]}.ndjson"
+
+
+__all__ = [
+    "append_event",
+    "event_log_path",
+    "load_events",
+    "load_recent_events",
+    "next_event_id",
+]

taskledger/storage/frontmatter.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+from taskledger.errors import LaunchError
+from taskledger.storage.common import read_text as _read_text
+from taskledger.storage.common import write_text as _write_text
+
+_FRONT_MATTER_PATTERN = re.compile(r"^---\n(?P<meta>.*?)\n---(?:\n|$)", re.DOTALL)
+MARKDOWN_FILE_VERSION = "v1"
+
+
+def read_markdown_front_matter(path: Path) -> tuple[dict[str, object], str]:
+    text = normalize_front_matter_newlines(_read_text(path))
+    match = _FRONT_MATTER_PATTERN.match(text)
+    if match is None:
+        raise LaunchError(
+            f"Invalid front matter document {path}: expected leading YAML front matter."
+        )
+    metadata_text = match.group("meta")
+    try:
+        raw_metadata = yaml.safe_load(metadata_text)
+    except yaml.YAMLError as exc:
+        raise LaunchError(f"Invalid YAML front matter in {path}: {exc}") from exc
+    if raw_metadata is None:
+        metadata: dict[str, object] = {}
+    elif isinstance(raw_metadata, dict):
+        metadata = raw_metadata
+    else:
+        raise LaunchError(f"Invalid YAML front matter in {path}: expected a mapping.")
+    body = text[match.end() :]
+    return metadata, body
+
+
+def write_markdown_front_matter(
+    path: Path,
+    metadata: dict[str, object],
+    body: str,
+) -> None:
+    normalized_body = normalize_front_matter_newlines(body)
+    yaml_text = yaml.safe_dump(metadata, sort_keys=False, allow_unicode=True)
+    yaml_text = normalize_front_matter_newlines(yaml_text)
+    contents = f"---\n{yaml_text}---\n{normalized_body}"
+    _write_text(path, contents)
+
+
+def iter_markdown_files(directory: Path) -> list[Path]:
+    if not directory.exists():
+        return []
+    return sorted(path for path in directory.glob("*.md") if path.is_file())
+
+
+def normalize_front_matter_newlines(text: str) -> str:
+    return text.replace("\r\n", "\n").replace("\r", "\n")

taskledger/storage/indexes.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from taskledger.storage.common import write_json
+from taskledger.storage.task_store import (
+    V2Paths,
+    list_introductions,
+    list_tasks,
+    load_active_locks,
+    load_requirements,
+)
+
+
+def rebuild_v2_indexes(paths: V2Paths) -> dict[str, int]:
+    tasks = list_tasks(paths.workspace_root)
+    introductions = list_introductions(paths.workspace_root)
+    locks = load_active_locks(paths.workspace_root)
+    dependencies = [
+        {
+            "task_id": task.id,
+            "requirements": [
+                item.task_id
+                for item in load_requirements(
+                    paths.workspace_root, task.id
+                ).requirements
+            ],
+        }
+        for task in tasks
+    ]
+    write_json(
+        paths.introductions_index_path,
+        [
+            {"id": intro.id, "slug": intro.slug, "title": intro.title}
+            for intro in introductions
+        ],
+    )
+    write_json(paths.active_locks_index_path, [lock.to_dict() for lock in locks])
+    write_json(paths.dependencies_index_path, dependencies)
+    return {
+        "introductions": len(introductions),
+        "locks": len(locks),
+        "dependencies": len(dependencies),
+    }

taskledger/storage/init.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from taskledger.errors import LaunchError
+from taskledger.storage.common import write_text
+from taskledger.storage.meta import StorageMeta, write_storage_meta
+from taskledger.storage.paths import (
+    CANONICAL_PROJECT_CONFIG_FILENAME,
+    ProjectPaths,
+    load_project_locator,
+    project_paths_for_root,
+)
+from taskledger.storage.project_config import render_default_taskledger_toml
+
+
+def _storage_yaml_path(workspace_root: Path) -> Path:
+    return load_project_locator(workspace_root).taskledger_dir / "storage.yaml"
+
+
+def init_project_state(
+    workspace_root: Path,
+    *,
+    taskledger_dir: Path | None = None,
+    config_filename: str = CANONICAL_PROJECT_CONFIG_FILENAME,
+) -> tuple[ProjectPaths, list[str]]:
+    existing = load_project_locator(workspace_root, config_filename=config_filename)
+    requested = load_project_locator(
+        workspace_root,
+        taskledger_dir_override=taskledger_dir,
+        config_filename=config_filename,
+    )
+    if (
+        taskledger_dir is not None
+        and existing.config_path.exists()
+        and existing.taskledger_dir != requested.taskledger_dir
+    ):
+        raise LaunchError(
+            "Existing taskledger config points to "
+            f"{existing.taskledger_dir}. Refusing to reinitialize with "
+            f"{requested.taskledger_dir}."
+        )
+    if (
+        taskledger_dir is not None
+        and existing.source == "legacy"
+        and not existing.config_path.exists()
+    ):
+        raise LaunchError(
+            "Legacy workspaces cannot change taskledger_dir through init without "
+            "an explicit migration."
+        )
+    paths = project_paths_for_root(
+        requested.workspace_root,
+        requested.taskledger_dir,
+        config_path=requested.config_path,
+    )
+    created: list[str] = []
+    for directory in (
+        paths.taskledger_dir,
+        paths.taskledger_dir / "intros",
+        paths.taskledger_dir / "tasks",
+        paths.taskledger_dir / "events",
+        paths.taskledger_dir / "indexes",
+    ):
+        if directory.exists():
+            continue
+        directory.mkdir(parents=True, exist_ok=True)
+        created.append(str(directory))
+    config_spec: list[tuple[Path, str]] = []
+    if _should_write_root_config(existing, paths):
+        taskledger_dir_value = _taskledger_dir_setting(
+            taskledger_dir or Path(".taskledger")
+        )
+        config_spec = [
+            (
+                paths.config_path,
+                render_default_taskledger_toml(taskledger_dir=taskledger_dir_value),
+            )
+        ]
+    for path, contents in (
+        *config_spec,
+        (paths.repo_index_path, "[]\n"),
+        (paths.taskledger_dir / "indexes" / "active_locks.json", "[]\n"),
+        (paths.taskledger_dir / "indexes" / "dependencies.json", "[]\n"),
+        (paths.taskledger_dir / "indexes" / "introductions.json", "[]\n"),
+    ):
+        if path.exists():
+            continue
+        write_text(path, contents)
+        created.append(str(path))
+    # Write storage.yaml
+    storage_path = paths.taskledger_dir / "storage.yaml"
+    if not storage_path.exists():
+        try:
+            from taskledger._version import __version__ as tl_version
+        except ImportError:
+            tl_version = "0.1.0"
+        meta = StorageMeta(created_with_taskledger=tl_version)
+        write_storage_meta(paths.workspace_root, meta)
+        created.append(str(storage_path))
+    return paths, created
+
+
+def ensure_project_exists(workspace_root: Path) -> ProjectPaths:
+    locator = load_project_locator(workspace_root)
+    paths = project_paths_for_root(
+        locator.workspace_root,
+        locator.taskledger_dir,
+        config_path=locator.config_path,
+    )
+    _reject_legacy_item_memory_indexes(paths)
+    missing = [
+        path
+        for path in (
+            paths.taskledger_dir / "tasks",
+            paths.taskledger_dir / "intros",
+            paths.taskledger_dir / "events",
+            paths.taskledger_dir / "indexes",
+        )
+        if not path.exists()
+    ]
+    if missing:
+        raise LaunchError(
+            "Project state is not initialized. Run 'taskledger init' first."
+        )
+    _ensure_additive_project_files(paths)
+    return paths
+
+
+def _ensure_additive_project_files(paths: ProjectPaths) -> None:
+    for directory in (
+        paths.taskledger_dir,
+        paths.taskledger_dir / "intros",
+        paths.taskledger_dir / "tasks",
+        paths.taskledger_dir / "events",
+        paths.taskledger_dir / "indexes",
+    ):
+        if directory.exists():
+            continue
+        try:
+            directory.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise LaunchError(f"Failed to create {directory}: {exc}") from exc
+    for path in (
+        paths.repo_index_path,
+        paths.taskledger_dir / "indexes" / "active_locks.json",
+        paths.taskledger_dir / "indexes" / "dependencies.json",
+        paths.taskledger_dir / "indexes" / "introductions.json",
+    ):
+        if path.exists():
+            continue
+        write_text(path, "[]\n")
+
+
+def _reject_legacy_item_memory_indexes(paths: ProjectPaths) -> None:
+    legacy_item_index = paths.taskledger_dir / "items" / "index.json"
+    legacy_memory_index = paths.taskledger_dir / "memories" / "index.json"
+    if legacy_item_index.exists():
+        raise LaunchError(
+            "Legacy item JSON storage is unsupported after this refactor: "
+            f"remove {legacy_item_index}."
+        )
+    if legacy_memory_index.exists():
+        raise LaunchError(
+            "Legacy memory JSON storage is unsupported after this refactor: "
+            f"remove {legacy_memory_index}."
+        )
+
+
+def _should_write_root_config(
+    locator: object,
+    paths: ProjectPaths,
+) -> bool:
+    if paths.config_path.exists():
+        return False
+    source = getattr(locator, "source", "")
+    return source not in {"legacy"}
+
+
+def _taskledger_dir_setting(taskledger_dir: Path) -> str:
+    if not taskledger_dir.is_absolute():
+        return taskledger_dir.as_posix()
+    if taskledger_dir.exists():
+        resolved = taskledger_dir
+    else:
+        resolved = taskledger_dir.resolve()
+    return str(resolved)

taskledger/storage/locks.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from taskledger.domain.models import TaskLock
+from taskledger.errors import LaunchError
+from taskledger.storage.atomic import atomic_create_text, atomic_write_text
+from taskledger.storage.common import read_text
+
+
+def write_lock(path: Path, lock: TaskLock) -> None:
+    atomic_create_text(
+        path,
+        yaml.safe_dump(lock.to_dict(), sort_keys=False, allow_unicode=True),
+    )
+
+
+def update_lock(path: Path, lock: TaskLock) -> None:
+    """Update an existing lock, or create if it doesn't exist."""
+    atomic_write_text(
+        path,
+        yaml.safe_dump(lock.to_dict(), sort_keys=False, allow_unicode=True),
+    )
+
+
+def read_lock(path: Path) -> TaskLock | None:
+    if not path.exists():
+        return None
+    try:
+        payload = yaml.safe_load(read_text(path))
+    except yaml.YAMLError as exc:
+        raise LaunchError(f"Invalid lock file {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise LaunchError(f"Invalid lock file {path}: expected mapping.")
+    return TaskLock.from_dict(payload)
+
+
+def remove_lock(path: Path) -> None:
+    if not path.exists():
+        return
+    try:
+        path.unlink()
+    except OSError as exc:
+        raise LaunchError(f"Failed to remove lock {path}: {exc}") from exc
+
+
+def lock_is_expired(lock: TaskLock, *, now: datetime | None = None) -> bool:
+    if lock.expires_at is None:
+        return False
+    try:
+        expires_at = datetime.fromisoformat(lock.expires_at)
+    except ValueError as exc:
+        raise LaunchError(
+            f"Invalid lock expiration on {lock.task_id} "
+            f"({lock.lock_id}): {lock.expires_at}"
+        ) from exc
+    reference = now or datetime.now(timezone.utc)
+    return expires_at < reference
+
+
+def lock_status(lock: TaskLock | None) -> dict[str, object]:
+    if lock is None:
+        return {
+            "active": False,
+            "expired": False,
+            "holder": None,
+            "stage": None,
+            "run_id": None,
+            "created_at": None,
+            "expires_at": None,
+        }
+    return {
+        "active": True,
+        "expired": lock_is_expired(lock),
+        "holder": lock.holder.to_dict(),
+        "stage": lock.stage,
+        "run_id": lock.run_id,
+        "created_at": lock.created_at,
+        "expires_at": lock.expires_at,
+    }