task-notes 0.1.0__py3-none-any.whl

task_notes/cli.py

@@ -0,0 +1,568 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import select
+import sys
+from dataclasses import dataclass
+
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.table import Table
+from rich.text import Text
+from rich.tree import Tree
+
+from .core import (
+    ProjectExistsError,
+    ProjectSummary,
+    ProjectStore,
+    SelectorError,
+    TaskDocument,
+    TaskError,
+    TaskNode,
+    TaskNotFoundError,
+    iter_selectors,
+    slugify,
+)
+
+
+DEFAULT_TASKS_DIRNAME = ".task-notes"
+
+
+@dataclass(slots=True)
+class _TaskRow:
+    selector: str
+    text: str
+    done: bool
+    depth: int
+
+
+def default_tasks_dir() -> Path:
+    return Path.home() / DEFAULT_TASKS_DIRNAME
+
+
+def normalize_tasks_dir(path: Path) -> Path:
+    return path.expanduser().resolve()
+
+
+def validate_tasks_dir(path: Path, allow_external: bool) -> None:
+    if allow_external:
+        return
+    safe_root = normalize_tasks_dir(default_tasks_dir())
+    if path != safe_root:
+        raise TaskError(
+            f"external tasks dir is blocked: {path}. "
+            "Use --unsafe-external-dir to allow non-default directories."
+        )
+
+
+def _render_ls(projects: list[ProjectSummary]) -> None:
+    console = Console()
+    if not projects:
+        console.print("[dim]No projects yet.[/dim]")
+        return
+
+    table = Table(
+        show_header=True,
+        header_style="bold cyan",
+        box=None,
+        pad_edge=False,
+    )
+    table.add_column("#", style="dim", no_wrap=True, justify="right")
+    table.add_column("Project", style="bold", no_wrap=True)
+    table.add_column("Progress", justify="right", no_wrap=True)
+    table.add_column("Path", overflow="fold")
+
+    for index, item in enumerate(projects, start=1):
+        progress_style = "green" if item.total > 0 and item.done == item.total else "yellow"
+        table.add_row(
+            f"{index}.",
+            item.name,
+            Text(f"{item.done}/{item.total}", style=progress_style),
+            str(item.path),
+        )
+
+    console.print(table)
+
+
+def _render_show(document: TaskDocument) -> None:
+    console = Console()
+    done, total = document.progress
+    title = Text()
+    title.append(document.title, style="bold")
+    title.append(f"  {done}/{total} done", style="dim")
+
+    root = Tree(title, guide_style="bright_black")
+    if not document.nodes:
+        root.add(Text("[ ] no tasks", style="dim"))
+    else:
+        for index, node in enumerate(document.nodes, start=1):
+            _add_tree_node(root, node, str(index))
+
+    console.print(root)
+
+
+def _add_tree_node(parent: Tree, node: TaskNode, selector: str) -> None:
+    label = Text()
+    label.append(f"{selector} ", style="cyan")
+    if node.done:
+        label.append("[x] ", style="green")
+        label.append(node.text, style="green")
+    else:
+        label.append("[ ] ", style="yellow")
+        label.append(node.text)
+
+    branch = parent.add(label)
+    for index, child in enumerate(node.children, start=1):
+        _add_tree_node(branch, child, f"{selector}.{index}")
+
+
+def _interactive_edit(store: ProjectStore, project: str) -> tuple[str | None, str | None]:
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        raise TaskError("interactive edit requires a TTY terminal")
+
+    document = store.load_project(project)
+    rows = _task_rows(document)
+    if not rows:
+        raise TaskError("project has no tasks to edit")
+
+    selected = _pick_task_row(rows, project)
+    if selected is None:
+        return None, None
+
+    prompt = f"Edit {selected.selector}"
+    updated = Prompt.ask(prompt, default=selected.text)
+    return selected.selector, updated
+
+
+def _task_rows(document: TaskDocument) -> list[_TaskRow]:
+    rows: list[_TaskRow] = []
+    for selector, node in iter_selectors(document.nodes):
+        rows.append(
+            _TaskRow(
+                selector=selector,
+                text=node.text,
+                done=node.done,
+                depth=selector.count("."),
+            )
+        )
+    return rows
+
+
+def _pick_task_row(rows: list[_TaskRow], project: str) -> _TaskRow | None:
+    console = Console()
+    cursor = 0
+    selected_index: int | None = None
+
+    while True:
+        _render_edit_picker(console, rows, project, cursor, selected_index)
+        key = _read_key()
+
+        if key in {"up"}:
+            cursor = max(0, cursor - 1)
+        elif key in {"down"}:
+            cursor = min(len(rows) - 1, cursor + 1)
+        elif key == "space":
+            selected_index = cursor
+        elif key == "enter":
+            if selected_index is None:
+                selected_index = cursor
+            return rows[selected_index]
+        elif key in {"q", "escape"}:
+            return None
+
+
+def _render_edit_picker(
+    console: Console,
+    rows: list[_TaskRow],
+    project: str,
+    cursor: int,
+    selected_index: int | None,
+) -> None:
+    console.clear()
+    console.print(f"[bold]Edit project:[/bold] {project}")
+    console.print("[dim]Use ↑/↓ or j/k to move, Space to select, Enter to confirm, q to cancel[/dim]")
+    console.print()
+
+    table = Table(show_header=True, box=None, pad_edge=False)
+    table.add_column(" ", no_wrap=True)
+    table.add_column("Pick", no_wrap=True)
+    table.add_column("Selector", style="cyan", no_wrap=True)
+    table.add_column("Task")
+
+    for index, row in enumerate(rows):
+        pointer = ">" if index == cursor else " "
+        picked = "[x]" if index == selected_index else "[ ]"
+
+        task_text = Text("  " * row.depth)
+        task_text.append(row.text, style="green" if row.done else "")
+        if row.done:
+            task_text.append(" (done)", style="dim")
+
+        table.add_row(pointer, picked, row.selector, task_text)
+
+    console.print(table)
+
+
+def _read_key() -> str:
+    if os.name == "nt":
+        import msvcrt
+
+        first = msvcrt.getwch()
+        if first in ("\r", "\n"):
+            return "enter"
+        if first == " ":
+            return "space"
+        if first in ("\x00", "\xe0"):
+            second = msvcrt.getwch()
+            if second == "H":
+                return "up"
+            if second == "P":
+                return "down"
+            return "other"
+        if first == "\x1b":
+            return "escape"
+        if first.lower() == "k":
+            return "up"
+        if first.lower() == "j":
+            return "down"
+        return first.lower()
+
+    import termios
+    import tty
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        first = sys.stdin.read(1)
+        if first in ("\r", "\n"):
+            return "enter"
+        if first == " ":
+            return "space"
+        if first == "\x1b":
+            if _stdin_ready(fd):
+                second = sys.stdin.read(1)
+                if second == "[" and _stdin_ready(fd):
+                    third = sys.stdin.read(1)
+                    if third == "A":
+                        return "up"
+                    if third == "B":
+                        return "down"
+            return "escape"
+        if first.lower() == "k":
+            return "up"
+        if first.lower() == "j":
+            return "down"
+        return first.lower()
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def _stdin_ready(fd: int) -> bool:
+    ready, _, _ = select.select([fd], [], [], 0.02)
+    return bool(ready)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="task", description="Task Notes CLI")
+    parser.add_argument("--tasks-dir", type=Path, default=default_tasks_dir())
+    parser.add_argument(
+        "--unsafe-external-dir",
+        action="store_true",
+        help="allow using a tasks directory outside the default ~/.task-notes",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    ls_parser = subparsers.add_parser("ls", help="List projects")
+    ls_parser.add_argument("--json", action="store_true")
+
+    show_parser = subparsers.add_parser("show", help="Show project tree")
+    show_parser.add_argument("project")
+    show_parser.add_argument("--json", action="store_true")
+
+    next_parser = subparsers.add_parser("next", help="Find next open leaf task")
+    next_parser.add_argument("project")
+    next_parser.add_argument("--json", action="store_true")
+
+    new_parser = subparsers.add_parser("new", help="Create project")
+    new_parser.add_argument("project")
+    new_parser.add_argument("contents", nargs="+")
+    new_parser.add_argument("--json", action="store_true")
+
+    add_parser = subparsers.add_parser("add", help="Add tasks")
+    add_parser.add_argument("project")
+    add_parser.add_argument("contents", nargs="+")
+    add_parser.add_argument("--parent")
+    add_parser.add_argument("--json", action="store_true")
+
+    edit_parser = subparsers.add_parser("edit", help="Edit task content")
+    edit_parser.add_argument("project")
+    edit_parser.add_argument("--path")
+    edit_parser.add_argument("content", nargs="?")
+    edit_parser.add_argument("-i", "--interactive", action="store_true")
+    edit_parser.add_argument("--json", action="store_true")
+
+    del_parser = subparsers.add_parser("del", help="Delete task by selector")
+    del_parser.add_argument("project")
+    del_parser.add_argument("--path", required=True)
+    del_parser.add_argument("--json", action="store_true")
+
+    rm_parser = subparsers.add_parser("rm", help="Delete project")
+    rm_parser.add_argument("project")
+    rm_parser.add_argument("--json", action="store_true")
+
+    check_parser = subparsers.add_parser("check", help="Mark a task as done")
+    check_parser.add_argument("project")
+    check_parser.add_argument("--path", required=True)
+    check_parser.add_argument("--json", action="store_true")
+
+    uncheck_parser = subparsers.add_parser("uncheck", help="Mark a task as todo")
+    uncheck_parser.add_argument("project")
+    uncheck_parser.add_argument("--path", required=True)
+    uncheck_parser.add_argument("--json", action="store_true")
+
+    toggle_parser = subparsers.add_parser("toggle", help="Toggle task status")
+    toggle_parser.add_argument("project")
+    toggle_parser.add_argument("--path", required=True)
+    toggle_parser.add_argument("--json", action="store_true")
+
+    return parser
+
+
+def main() -> None:
+    raise SystemExit(run_cli(sys.argv[1:]))
+
+
+def run_cli(argv: list[str]) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    emit_json = bool(getattr(args, "json", False))
+
+    try:
+        tasks_dir = normalize_tasks_dir(args.tasks_dir)
+        validate_tasks_dir(tasks_dir, allow_external=args.unsafe_external_dir)
+        store = ProjectStore(tasks_dir)
+        match args.command:
+            case "ls":
+                projects = store.list_projects()
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "ls",
+                        "projects": [
+                            {
+                                "index": index,
+                                "project": item.name,
+                                "done": item.done,
+                                "total": item.total,
+                                "path": str(item.path),
+                            }
+                            for index, item in enumerate(projects, start=1)
+                        ],
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    _render_ls(projects)
+                return 0
+            case "show":
+                document = store.load_project(args.project)
+                rows = []
+                for selector, node in iter_selectors(document.nodes):
+                    rows.append(
+                        {
+                            "selector": selector,
+                            "done": node.done,
+                            "text": node.text,
+                        }
+                    )
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "show",
+                        "project": slugify(args.project),
+                        "rows": rows,
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    _render_show(document)
+                return 0
+            case "next":
+                task = store.next_task(args.project)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "next",
+                        "project": slugify(args.project),
+                        "selector": task.selector if task else None,
+                        "message": task.text if task else "all tasks completed",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    if task:
+                        print(f"OK next: {task.selector} {task.text}")
+                    else:
+                        print("OK next: all tasks completed")
+                return 0
+            case "new":
+                path = store.new_project(args.project, args.contents)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "new",
+                        "project": slugify(args.project),
+                        "path": str(path),
+                        "message": "project created",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    print(f"OK new: {slugify(args.project)}")
+                return 0
+            case "add":
+                store.add_tasks(args.project, args.contents, parent_selector=args.parent)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "add",
+                        "project": slugify(args.project),
+                        "selector": args.parent,
+                        "message": "tasks added",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    target = args.parent if args.parent else "root"
+                    print(f"OK add: {slugify(args.project)} {target}")
+                return 0
+            case "edit":
+                selector: str | None = args.path
+                content: str | None = args.content
+
+                if args.interactive or (args.path is None and args.content is None):
+                    selector, content = _interactive_edit(store, args.project)
+                    if selector is None or content is None:
+                        if emit_json:
+                            payload = {
+                                "ok": True,
+                                "action": "edit",
+                                "project": slugify(args.project),
+                                "selector": None,
+                                "message": "edit canceled",
+                            }
+                            print(json.dumps(payload, ensure_ascii=False))
+                        else:
+                            print(f"OK edit: {slugify(args.project)} canceled")
+                        return 0
+
+                if selector is None or content is None:
+                    raise TaskError("edit requires both --path and content, or use --interactive")
+
+                store.edit_task(args.project, selector, content)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "edit",
+                        "project": slugify(args.project),
+                        "selector": selector,
+                        "message": "task updated",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    print(f"OK edit: {slugify(args.project)} {selector}")
+                return 0
+            case "del":
+                store.delete_task(args.project, args.path)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "del",
+                        "project": slugify(args.project),
+                        "selector": args.path,
+                        "message": "task deleted",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    print(f"OK del: {slugify(args.project)} {args.path}")
+                return 0
+            case "rm":
+                store.remove_project(args.project)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "rm",
+                        "project": slugify(args.project),
+                        "message": "project deleted",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    print(f"OK rm: {slugify(args.project)}")
+                return 0
+            case "check":
+                store.set_done(args.project, args.path, done=True)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "check",
+                        "project": slugify(args.project),
+                        "selector": args.path,
+                        "message": "task checked",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    print(f"OK check: {slugify(args.project)} {args.path}")
+                return 0
+            case "uncheck":
+                store.set_done(args.project, args.path, done=False)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "uncheck",
+                        "project": slugify(args.project),
+                        "selector": args.path,
+                        "message": "task unchecked",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    print(f"OK uncheck: {slugify(args.project)} {args.path}")
+                return 0
+            case "toggle":
+                store.toggle_done(args.project, args.path)
+                if emit_json:
+                    payload = {
+                        "ok": True,
+                        "action": "toggle",
+                        "project": slugify(args.project),
+                        "selector": args.path,
+                        "message": "task toggled",
+                    }
+                    print(json.dumps(payload, ensure_ascii=False))
+                else:
+                    print(f"OK toggle: {slugify(args.project)} {args.path}")
+                return 0
+            case _:
+                parser.error("unknown command")
+                return 2
+    except (TaskError, TaskNotFoundError, SelectorError, ProjectExistsError) as error:
+        return _emit_error(args, error)
+
+
+def _emit_error(args: argparse.Namespace, error: Exception) -> int:
+    emit_json = bool(getattr(args, "json", False))
+    if emit_json:
+        payload = {
+            "ok": False,
+            "action": args.command,
+            "project": slugify(args.project) if hasattr(args, "project") else None,
+            "error_code": error.__class__.__name__,
+            "error_message": str(error),
+        }
+        print(json.dumps(payload, ensure_ascii=False))
+    else:
+        print(f"ERR {error.__class__.__name__}: {error}")
+    return 1
+
+
+if __name__ == "__main__":
+    main()

task_notes/core.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import fcntl
+import os
+from pathlib import Path
+import re
+from typing import Callable
+
+
+TASK_LINE_RE = re.compile(r"^(?P<indent>\s*)- \[(?P<mark>[ xX])\] (?P<text>.*)$")
+HEADING_RE = re.compile(r"^# (?P<title>.+)$")
+SELECTOR_RE = re.compile(r"^\[?(?P<value>\d+(?:\.\d+)*)\]?$")
+SLUG_RE = re.compile(r"[^a-z0-9\-]+")
+
+
+class TaskError(Exception):
+    pass
+
+
+class TaskNotFoundError(TaskError):
+    pass
+
+
+class SelectorError(TaskError):
+    pass
+
+
+class ProjectExistsError(TaskError):
+    pass
+
+
+@dataclass(slots=True)
+class TaskNode:
+    text: str
+    done: bool = False
+    children: list["TaskNode"] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class TaskDocument:
+    title: str
+    nodes: list[TaskNode] = field(default_factory=list)
+
+    @property
+    def progress(self) -> tuple[int, int]:
+        done = 0
+        total = 0
+        for node in iter_nodes(self.nodes):
+            total += 1
+            if node.done:
+                done += 1
+        return done, total
+
+
+@dataclass(slots=True)
+class ProjectSummary:
+    name: str
+    path: Path
+    done: int
+    total: int
+
+
+@dataclass(slots=True)
+class NextTask:
+    selector: str
+    text: str
+
+
+def slugify(name: str) -> str:
+    raw = name.strip().lower().replace("_", "-").replace(" ", "-")
+    slug = SLUG_RE.sub("-", raw).strip("-")
+    if not slug:
+        raise TaskError("project name cannot be empty")
+    return slug
+
+
+def parse_selector(selector: str) -> list[int]:
+    match = SELECTOR_RE.match(selector.strip())
+    if not match:
+        raise SelectorError(f"invalid selector: {selector}")
+    parts = [int(part) for part in match.group("value").split(".")]
+    if any(part <= 0 for part in parts):
+        raise SelectorError(f"invalid selector: {selector}")
+    return parts
+
+
+def parse_markdown(content: str, default_title: str) -> TaskDocument:
+    title = default_title
+    seen_heading = False
+    roots: list[TaskNode] = []
+    stack: list[TaskNode] = []
+
+    for line in content.splitlines():
+        heading_match = HEADING_RE.match(line)
+        if heading_match and not seen_heading and not roots:
+            title = heading_match.group("title").strip()
+            seen_heading = True
+            continue
+
+        line_match = TASK_LINE_RE.match(line)
+        if not line_match:
+            continue
+
+        indent = len(line_match.group("indent"))
+        if indent % 2 != 0:
+            raise TaskError("invalid indentation: checklist indentation must be 2 spaces")
+        depth = indent // 2
+        if depth > len(stack):
+            raise TaskError("invalid indentation: depth jump is not allowed")
+
+        node = TaskNode(
+            text=line_match.group("text").strip(),
+            done=line_match.group("mark").lower() == "x",
+        )
+
+        if depth == 0:
+            roots.append(node)
+            stack = [node]
+            continue
+
+        parent = stack[depth - 1]
+        parent.children.append(node)
+        if len(stack) == depth:
+            stack.append(node)
+        else:
+            stack[depth] = node
+            del stack[depth + 1 :]
+
+    return TaskDocument(title=title, nodes=roots)
+
+
+def to_markdown(document: TaskDocument) -> str:
+    lines = [f"# {document.title}", ""]
+    for node in document.nodes:
+        _append_node_lines(lines, node, depth=0)
+    if lines and lines[-1] != "":
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _append_node_lines(lines: list[str], node: TaskNode, depth: int) -> None:
+    indent = "  " * depth
+    mark = "x" if node.done else " "
+    lines.append(f"{indent}- [{mark}] {node.text}")
+    for child in node.children:
+        _append_node_lines(lines, child, depth + 1)
+
+
+def iter_nodes(nodes: list[TaskNode]) -> list[TaskNode]:
+    output: list[TaskNode] = []
+    for node in nodes:
+        output.append(node)
+        output.extend(iter_nodes(node.children))
+    return output
+
+
+def iter_selectors(nodes: list[TaskNode], prefix: str = "") -> list[tuple[str, TaskNode]]:
+    output: list[tuple[str, TaskNode]] = []
+    for index, node in enumerate(nodes, start=1):
+        selector = f"{prefix}.{index}" if prefix else str(index)
+        output.append((selector, node))
+        output.extend(iter_selectors(node.children, selector))
+    return output
+
+
+def resolve_selector(nodes: list[TaskNode], selector: str) -> tuple[list[TaskNode], int, TaskNode]:
+    parts = parse_selector(selector)
+    current_list = nodes
+    for depth, part in enumerate(parts):
+        index = part - 1
+        if index < 0 or index >= len(current_list):
+            raise SelectorError(f"selector not found: {selector}")
+        node = current_list[index]
+        if depth == len(parts) - 1:
+            return current_list, index, node
+        current_list = node.children
+    raise SelectorError(f"selector not found: {selector}")
+
+
+def first_open_leaf(nodes: list[TaskNode], prefix: str = "") -> NextTask | None:
+    for index, node in enumerate(nodes, start=1):
+        selector = f"{prefix}.{index}" if prefix else str(index)
+        if not node.children and not node.done:
+            return NextTask(selector=selector, text=node.text)
+        candidate = first_open_leaf(node.children, selector)
+        if candidate is not None:
+            return candidate
+    return None
+
+
+class ProjectStore:
+    def __init__(self, base_dir: Path) -> None:
+        self.base_dir = base_dir
+
+    def list_projects(self) -> list[ProjectSummary]:
+        if not self.base_dir.exists():
+            return []
+        projects: list[ProjectSummary] = []
+        for path in sorted(self.base_dir.glob("*.md")):
+            document = self._read_document(path)
+            done, total = document.progress
+            projects.append(ProjectSummary(name=path.stem, path=path, done=done, total=total))
+        return projects
+
+    def new_project(self, project: str, contents: list[str]) -> Path:
+        name = slugify(project)
+        path = self._project_path(name)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        with self._lock_for(path):
+            if path.exists():
+                raise ProjectExistsError(f"project already exists: {name}")
+            document = TaskDocument(title=name, nodes=[TaskNode(text=item) for item in contents])
+            self._write_document(path, document)
+        return path
+
+    def remove_project(self, project: str) -> None:
+        path = self._existing_project_path(project)
+        lock_path = path.with_suffix(path.suffix + ".lock")
+        with self._lock_for(path):
+            if not path.exists():
+                raise TaskNotFoundError(f"project not found: {slugify(project)}")
+            path.unlink()
+        if lock_path.exists():
+            lock_path.unlink(missing_ok=True)
+
+    def load_project(self, project: str) -> TaskDocument:
+        path = self._existing_project_path(project)
+        with self._lock_for(path):
+            return self._read_document(path)
+
+    def add_tasks(self, project: str, contents: list[str], parent_selector: str | None = None) -> TaskDocument:
+        return self._update_project(
+            project,
+            lambda document: self._apply_add(document, contents, parent_selector),
+        )
+
+    def edit_task(self, project: str, selector: str, content: str) -> TaskDocument:
+        def update(document: TaskDocument) -> None:
+            _, _, node = resolve_selector(document.nodes, selector)
+            node.text = content
+
+        return self._update_project(project, update)
+
+    def delete_task(self, project: str, selector: str) -> TaskDocument:
+        def update(document: TaskDocument) -> None:
+            parent, index, _ = resolve_selector(document.nodes, selector)
+            del parent[index]
+
+        return self._update_project(project, update)
+
+    def set_done(self, project: str, selector: str, done: bool) -> TaskDocument:
+        def update(document: TaskDocument) -> None:
+            _, _, node = resolve_selector(document.nodes, selector)
+            node.done = done
+
+        return self._update_project(project, update)
+
+    def toggle_done(self, project: str, selector: str) -> TaskDocument:
+        def update(document: TaskDocument) -> None:
+            _, _, node = resolve_selector(document.nodes, selector)
+            node.done = not node.done
+
+        return self._update_project(project, update)
+
+    def next_task(self, project: str) -> NextTask | None:
+        path = self._existing_project_path(project)
+        with self._lock_for(path):
+            document = self._read_document(path)
+        return first_open_leaf(document.nodes)
+
+    def _apply_add(self, document: TaskDocument, contents: list[str], parent_selector: str | None) -> None:
+        if parent_selector is None:
+            document.nodes.extend(TaskNode(text=item) for item in contents)
+            return
+        _, _, node = resolve_selector(document.nodes, parent_selector)
+        node.children.extend(TaskNode(text=item) for item in contents)
+
+    def _update_project(self, project: str, update: Callable[[TaskDocument], None]) -> TaskDocument:
+        path = self._existing_project_path(project)
+        with self._lock_for(path):
+            document = self._read_document(path)
+            update(document)
+            self._write_document(path, document)
+            return document
+
+    def _existing_project_path(self, project: str) -> Path:
+        name = slugify(project)
+        path = self._project_path(name)
+        if not path.exists():
+            raise TaskNotFoundError(f"project not found: {name}")
+        return path
+
+    def _project_path(self, project: str) -> Path:
+        return self.base_dir / f"{project}.md"
+
+    def _read_document(self, path: Path) -> TaskDocument:
+        if not path.exists():
+            raise TaskNotFoundError(f"project not found: {path.stem}")
+        content = path.read_text(encoding="utf-8")
+        return parse_markdown(content, default_title=path.stem)
+
+    def _write_document(self, path: Path, document: TaskDocument) -> None:
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        content = to_markdown(document)
+        tmp_path = path.with_suffix(path.suffix + ".tmp")
+        tmp_path.write_text(content, encoding="utf-8")
+        os.replace(tmp_path, path)
+
+    def _lock_for(self, path: Path):
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        lock_path = path.with_suffix(path.suffix + ".lock")
+        return _FileLock(lock_path)
+
+
+class _FileLock:
+    def __init__(self, lock_path: Path) -> None:
+        self.lock_path = lock_path
+        self.handle = None
+
+    def __enter__(self) -> "_FileLock":
+        self.lock_path.parent.mkdir(parents=True, exist_ok=True)
+        self.handle = self.lock_path.open("a+", encoding="utf-8")
+        fcntl.flock(self.handle.fileno(), fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self.handle is not None:
+            fcntl.flock(self.handle.fileno(), fcntl.LOCK_UN)
+            self.handle.close()
+            self.handle = None

task_notes-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: task-notes
+Version: 0.1.0
+Summary: LLM-friendly Markdown task notes CLI
+Keywords: agent,cli,llm,markdown,tasks
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: rich>=14.1.0
+Description-Content-Type: text/markdown
+
+# task-notes
+
+一个面向 LLM/Agent 的任务管理 CLI。  
+用 Markdown checklist 保存任务，支持多级子任务、稳定 selector（如 `1.2.3`）、文本/JSON 双输出，以及 Rich 终端展示。
+
+## 功能
+
+- 单项目单文件：`<project>.md`
+- 多级树状任务
+- selector 定位：`1`、`1.2`、`2.1.3`
+- 原子写入 + 文件锁（并发安全）
+- Rich 展示（`ls` 表格、`show` 树）
+- `edit` 支持交互选择（方向键/jk + Space + Enter）
+- `--json` 机读输出
+
+## 安装与运行
+
+### 使用 uv（推荐）
+
+在项目目录内：
+
+```bash
+uv run task --help
+```
+
+临时执行（不安装到全局）：
+
+```bash
+uvx --from . task --help
+```
+
+安装为全局工具：
+
+```bash
+uv tool install --editable .
+task --help
+```
+
+### 使用 pip
+
+```bash
+pip install .
+task --help
+```
+
+## 默认数据目录与安全策略
+
+- 默认目录：`~/.task-notes`
+- 可自定义目录：`--tasks-dir <path>`
+- 安全限制：默认禁止写入非 `~/.task-notes` 目录；若要使用其他目录，必须显式加：
+
+```bash
+--unsafe-external-dir
+```
+
+示例：
+
+```bash
+task --unsafe-external-dir --tasks-dir ./tasks ls
+```
+
+## 快速开始
+
+```bash
+task new app-redesign "梳理需求" "实现功能" "验收发布"
+task add app-redesign --parent 2 "实现 task ls/show"
+task show app-redesign
+task next app-redesign
+task check app-redesign --path 1
+task edit app-redesign --path 2.1 "实现 ls/show/tree 输出"
+```
+
+## 命令概览
+
+```bash
+task ls [--json]
+task show <project> [--json]
+task next <project> [--json]
+task new <project> <content...> [--json]
+task add <project> [--parent <selector>] <content...> [--json]
+task edit <project> --path <selector> <content> [--json]
+task edit <project> -i [--json]
+task del <project> --path <selector> [--json]
+task rm <project> [--json]
+task check <project> --path <selector> [--json]
+task uncheck <project> --path <selector> [--json]
+task toggle <project> --path <selector> [--json]
+```
+
+## 交互式编辑
+
+```bash
+task edit <project> -i
+```
+
+按键：
+
+- `↑/↓` 或 `j/k`：移动光标
+- `Space`：选择当前任务
+- `Enter`：确认并编辑文本
+- `q` / `Esc`：取消
+
+## JSON 输出
+
+适合 tools/LLM 集成：
+
+```bash
+task show app-redesign --json
+```
+
+错误时返回非 0，并输出：
+
+- `ok: false`
+- `error_code`
+- `error_message`
+
+## 开发
+
+运行测试：
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py' -v
+```
+
+## 发布到 PyPI（建议流程）
+
+```bash
+uv build
+uvx twine check dist/*
+# uvx twine upload dist/*
+```

task_notes-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+task_notes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+task_notes/cli.py,sha256=ew32YrMNPZezVbHMC5NaGAXuLR22AQWtcM-vIXPNUqE,19827
+task_notes/core.py,sha256=KDtyWAGcDcBWD93r_7XUqcIppoMveL7dwMou78bIuSo,11076
+task_notes-0.1.0.dist-info/METADATA,sha256=3aJ10xy_UbkxR73bDMYKYXd_yCHV3nPVnVP-gz1NdzE,3052
+task_notes-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+task_notes-0.1.0.dist-info/entry_points.txt,sha256=gonuMoyT-ZKBD6ZC6S-kCYkX9hSpIl71pvYQDmahW-8,45
+task_notes-0.1.0.dist-info/RECORD,,

task_notes-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

task_notes-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+task = task_notes.cli:main