chitty 0.1.0__py3-none-any.whl

chitty/check.py

@@ -0,0 +1,67 @@
+"""Cross-file validation: every file parses, IDs are unique, references resolve."""
+
+from collections import defaultdict
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from chitty import ids
+from chitty.errors import ChittyError
+from chitty.ids import TaskId
+from chitty.model import Task, parse
+from chitty.store import Context, Repo, scan
+
+
+@dataclass(frozen=True)
+class Problem:
+    path: Path
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}: {self.message}"
+
+
+def check(repo: Repo, contexts: Sequence[Context], paths: Sequence[Path]) -> list[Problem]:
+    """Problems in the given contexts, or only in the given paths if any are given.
+
+    References are always resolved against the whole repo.
+    """
+    problems: list[Problem] = []
+    by_id: dict[TaskId, list[Path]] = defaultdict(list)
+    tasks: dict[Path, Task] = {}
+    in_context: dict[Path, Context] = {}
+    for context in repo.contexts():
+        for archived in (False, True):
+            for path, problem in scan(context, archived):
+                in_context[path] = context
+                if problem:
+                    problems.append(Problem(path, problem))
+                    continue
+                by_id[ids.parse_filename(path.name)[0]].append(path)
+                try:
+                    tasks[path] = parse(path.read_text())
+                except ChittyError as error:
+                    problems.append(Problem(path, str(error)))
+    for task_id, task_paths in by_id.items():
+        if len(task_paths) > 1:
+            others = ", ".join(str(p) for p in task_paths)
+            problems += [
+                Problem(p, f"{task_id} is used by more than one file: {others}") for p in task_paths
+            ]
+    for path, task in tasks.items():
+        own_id = ids.parse_filename(path.name)[0]
+        for reference in task.frontmatter.depends_on:
+            if reference == str(own_id):
+                problems.append(Problem(path, "depends_on lists the task itself"))
+            elif TaskId.parse(reference) not in by_id:
+                problems.append(Problem(path, f"depends_on {reference}: no such task"))
+
+    if paths:
+        wanted = {p.resolve() for p in paths}
+        problems += [
+            Problem(p, "not a task file in any chitty context")
+            for p in sorted(wanted - set(in_context))
+        ]
+        return [p for p in problems if p.path in wanted]
+    names = {c.name for c in contexts}
+    return [p for p in problems if p.path not in in_context or in_context[p.path].name in names]

chitty/cli.py

@@ -0,0 +1,355 @@
+"""Command-line interface. Thin: parse flags, call store/model, print."""
+
+import json
+from datetime import date
+from pathlib import Path
+from typing import Any, TextIO, cast
+
+import click
+
+from chitty.check import check as check_repo
+from chitty.config import find_root, search_root
+from chitty.errors import ChittyError
+from chitty.model import ACCEPTANCE_CRITERIA, FIELD_ORDER, PRIORITIES, SECTION_ORDER, STATUSES
+from chitty.store import (
+    Change,
+    Edit,
+    Repo,
+    StoredTask,
+    Which,
+    init_repo,
+    matches,
+    resolve_add_target,
+)
+
+
+class _Group(click.Group):
+    def invoke(self, ctx: click.Context) -> Any:
+        try:
+            return super().invoke(ctx)
+        except ChittyError as error:
+            raise click.ClickException(str(error)) from error
+
+
+@click.group(cls=_Group)
+@click.version_option(package_name="chitty")
+def cli() -> None:
+    """Markdown-native task tracker for humans and coding agents.
+
+    Tasks are markdown files under chitty/<context>/. IDs are PREFIX-N
+    (e.g. TASK-13); a bare number means the default context.
+    """
+
+
+def main() -> None:
+    cli()
+
+
+json_option = click.option("--json", "as_json", is_flag=True, help="Print JSON.")
+context_option = click.option(
+    "-c", "--context", help="Context name (default: default_context from chitty.toml)."
+)
+
+
+def _repo() -> Repo:
+    return Repo.open(find_root(Path.cwd()))
+
+
+def _print_json(data: Any) -> None:
+    click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def _report(change: Change, as_json: bool, verb: str) -> None:
+    """Print the result of a write."""
+    if as_json:
+        _print_json(change.task.as_dict())
+    elif change.paths:
+        click.echo(f"{verb} {change.task.id} {change.task.path}")
+    else:
+        click.echo(f"unchanged {change.task.id}")
+
+
+def _priority(_ctx: click.Context, _param: click.Parameter, value: str | None) -> str | None:
+    if value is not None and value not in (*PRIORITIES, ""):
+        raise click.BadParameter(f"must be one of {', '.join(PRIORITIES)}, or '' to unset")
+    return value
+
+
+def _text(value: str | None, file: TextIO | None, name: str) -> str | None:
+    if value is not None and file is not None:
+        raise click.UsageError(f"give --{name} or --{name}-file, not both")
+    return file.read() if file is not None else value
+
+
+@cli.command()
+@click.option("--prefix", default="TASK", show_default=True, help="ID prefix for tasks/.")
+def init(prefix: str) -> None:
+    """Write chitty.toml and chitty/tasks/, and add the agent guide to AGENTS.md."""
+    for path in init_repo(Path.cwd(), prefix):
+        click.echo(f"wrote {path}")
+
+
+@cli.command()
+@click.argument("title")
+@context_option
+@click.option("-d", "--description", required=True, help="The Description section.")
+@click.option("--ac", "criteria", multiple=True, help="Acceptance criterion (repeatable).")
+@click.option("-l", "--label", "labels", multiple=True, help="Label (repeatable).")
+@click.option("-p", "--priority", type=click.Choice(PRIORITIES))
+@click.option("--owner", help="Free text: human, a name, an agent.")
+@click.option("--depends-on", multiple=True, help="Task ID this is blocked on (repeatable).")
+@json_option
+def add(
+    title: str,
+    context: str | None,
+    description: str,
+    criteria: tuple[str, ...],
+    labels: tuple[str, ...],
+    priority: str | None,
+    owner: str | None,
+    depends_on: tuple[str, ...],
+    as_json: bool,
+) -> None:
+    """Create a task with status todo.
+
+    -c may also name a context from ~/.config/chitty/contexts.toml: the file
+    is written into that repo's working tree and nothing else happens there.
+    """
+    root = search_root(Path.cwd())
+    target = resolve_add_target(Repo.open(root) if root else None, context)
+    fields = {
+        "labels": list(dict.fromkeys(labels)),
+        "priority": priority,
+        "owner": owner,
+        "depends_on": list(depends_on),
+    }
+    change = target.repo.add(target.context, title, description, criteria, fields, date.today())
+    _report(change, as_json, "added")
+
+
+@cli.command("list")
+@context_option
+@click.option("-s", "--status", "statuses", multiple=True, type=click.Choice(STATUSES))
+@click.option("-l", "--label", "labels", multiple=True, help="Only tasks with every label.")
+@click.option("--owner")
+@click.option("--search", help="Case-insensitive match on title and body.")
+@click.option("--archived", is_flag=True, help="Only archived tasks.")
+@click.option("--all", "all_", is_flag=True, help="Archived and non-archived tasks.")
+@json_option
+def list_(
+    context: str | None,
+    statuses: tuple[str, ...],
+    labels: tuple[str, ...],
+    owner: str | None,
+    search: str | None,
+    archived: bool,
+    all_: bool,
+    as_json: bool,
+) -> None:
+    """List tasks, one per line."""
+    if archived and all_:
+        raise click.UsageError("give --archived or --all, not both")
+    which: Which = "all" if all_ else "archived" if archived else "active"
+    repo = _repo()
+    target = repo.context(context) if context else repo.default_context
+    tasks = [t for t in repo.tasks(target, which) if matches(t, statuses, labels, owner, search)]
+    if as_json:
+        _print_json([t.as_dict() for t in tasks])
+        return
+    width = max((len(str(t.id)) for t in tasks), default=0)
+    for stored in tasks:
+        fm = stored.task.frontmatter
+        line = f"{stored.id!s:<{width}}  {fm.status:<6}  {fm.title}"
+        if fm.labels:
+            line += f"  [{','.join(sorted(fm.labels))}]"
+        if stored.archived:
+            line += "  (archived)"
+        click.echo(line)
+
+
+@cli.command()
+@click.argument("task_id", metavar="ID")
+@json_option
+def show(task_id: str, as_json: bool) -> None:
+    """Show a task, with acceptance criteria numbered."""
+    repo = _repo()
+    stored = repo.find(repo.resolve(task_id))
+    if as_json:
+        _print_json(stored.as_dict())
+    else:
+        click.echo(_format(stored))
+
+
+def _format(stored: StoredTask) -> str:
+    fm = stored.task.frontmatter.model_dump(mode="json", exclude_defaults=True)
+    lines = [f"{stored.id}{'  (archived)' if stored.archived else ''}"]
+    for key in FIELD_ORDER:
+        value = fm.get(key)
+        if isinstance(value, list):
+            lines.append(f"{key}: {', '.join(cast(list[str], value))}")
+        elif value is not None:
+            lines.append(f"{key}: {value}")
+    lines.append(f"path: {stored.path}")
+    for name in SECTION_ORDER:
+        if name == ACCEPTANCE_CRITERIA:
+            criteria = stored.task.criteria
+            content = "\n".join(
+                f"{n}. [{'x' if c.checked else ' '}] {c.text}"
+                for n, c in enumerate(criteria, start=1)
+            )
+        else:
+            content = stored.task.section(name)
+        if content:
+            lines += ["", f"## {name}", "", content]
+    return "\n".join(lines)
+
+
+@cli.command()
+@click.argument("task_id", metavar="ID")
+@click.option("--title")
+@click.option("-s", "--status", type=click.Choice(STATUSES))
+@click.option("--add-label", multiple=True)
+@click.option("--rm-label", multiple=True)
+@click.option("-p", "--priority", callback=_priority, help="low, medium, high; '' unsets.")
+@click.option("--owner", help="'' unsets.")
+@click.option("--depends-on", multiple=True, help="Add a dependency (repeatable).")
+@click.option("--rm-depends-on", multiple=True, help="Remove a dependency (repeatable).")
+@click.option("-d", "--description", help="Replace the Description section.")
+@click.option("--description-file", type=click.File(), help="Read --description from a file.")
+@click.option("--ac", multiple=True, help="Append an acceptance criterion (repeatable).")
+@click.option("--rm-ac", type=int, multiple=True, help="Remove criterion N (repeatable).")
+@click.option("--check", type=int, multiple=True, help="Tick criterion N (repeatable).")
+@click.option("--uncheck", type=int, multiple=True, help="Untick criterion N (repeatable).")
+@click.option("--plan", help="Replace the Plan section; '' removes it.")
+@click.option("--plan-file", type=click.File(), help="Read --plan from a file.")
+@click.option("--note", help="Append a paragraph to Notes.")
+@json_option
+def edit(
+    task_id: str,
+    title: str | None,
+    status: str | None,
+    add_label: tuple[str, ...],
+    rm_label: tuple[str, ...],
+    priority: str | None,
+    owner: str | None,
+    depends_on: tuple[str, ...],
+    rm_depends_on: tuple[str, ...],
+    description: str | None,
+    description_file: TextIO | None,
+    ac: tuple[str, ...],
+    rm_ac: tuple[int, ...],
+    check: tuple[int, ...],
+    uncheck: tuple[int, ...],
+    plan: str | None,
+    plan_file: TextIO | None,
+    note: str | None,
+    as_json: bool,
+) -> None:
+    """Change a task. Criterion numbers refer to the list before this edit."""
+    repo = _repo()
+    changes = Edit(
+        title=title,
+        status=status,
+        add_labels=add_label,
+        rm_labels=rm_label,
+        priority=priority,
+        owner=owner,
+        depends_on=depends_on,
+        rm_depends_on=rm_depends_on,
+        description=_text(description, description_file, "description"),
+        add_criteria=ac,
+        rm_criteria=rm_ac,
+        check=check,
+        uncheck=uncheck,
+        plan=_text(plan, plan_file, "plan"),
+        note=note,
+    )
+    _report(repo.edit(repo.resolve(task_id), changes), as_json, "updated")
+
+
+@cli.command("check")
+@context_option
+@click.argument("paths", nargs=-1, type=click.Path(path_type=Path))
+@json_option
+def check_(context: str | None, paths: tuple[Path, ...], as_json: bool) -> None:
+    """Validate task files. Exits non-zero if there are any problems.
+
+    With PATHs, only those files are checked; otherwise every context, or
+    just -c CONTEXT.
+    """
+    repo = _repo()
+    contexts = [repo.context(context)] if context else repo.contexts()
+    problems = check_repo(repo, contexts, paths)
+    if as_json:
+        _print_json([{"path": str(p.path), "message": p.message} for p in problems])
+    else:
+        for problem in problems:
+            click.echo(str(problem))
+    if problems:
+        raise click.ClickException(f"{len(problems)} problem(s)")
+
+
+@cli.command()
+@click.argument("task_id", metavar="ID")
+@json_option
+def path(task_id: str, as_json: bool) -> None:
+    """Print the task's file path."""
+    repo = _repo()
+    stored = repo.find(repo.resolve(task_id))
+    if as_json:
+        _print_json({"id": str(stored.id), "path": str(stored.path)})
+    else:
+        click.echo(str(stored.path))
+
+
+@cli.command()
+@click.argument("task_id", metavar="ID")
+@click.argument("context")
+@json_option
+def move(task_id: str, context: str, as_json: bool) -> None:
+    """Move a task to another context in this repo.
+
+    It gets the next ID there (keeping its slug), records moved_from, and
+    every depends_on reference to the old ID is rewritten.
+    """
+    repo = _repo()
+    change = repo.move(repo.resolve(task_id), repo.context(context))
+    _report(change, as_json, "moved")
+    if not as_json:
+        for touched in change.paths[2:]:
+            click.echo(f"rewrote reference in {touched}")
+
+
+@cli.command()
+@click.argument("task_id", metavar="ID")
+@json_option
+def archive(task_id: str, as_json: bool) -> None:
+    """Move a task into its context's archive/."""
+    repo = _repo()
+    change = repo.archive(repo.resolve(task_id))
+    _report(change, as_json, "archived")
+
+
+@cli.command()
+@click.argument("task_id", metavar="ID")
+@json_option
+def restore(task_id: str, as_json: bool) -> None:
+    """Move an archived task back out of archive/."""
+    repo = _repo()
+    change = repo.restore(repo.resolve(task_id))
+    _report(change, as_json, "restored")
+
+
+@cli.command()
+def mcp() -> None:
+    """Run the stdio MCP server (needs the mcp extra)."""
+    # Imported here because the mcp package is an optional extra.
+    try:
+        from chitty.mcp import run
+    except ModuleNotFoundError as error:
+        if error.name is None or not error.name.startswith("mcp"):
+            raise
+        raise ChittyError(
+            "chitty mcp needs the mcp extra: uv tool install 'chitty[mcp]'"
+        ) from error
+    run()

chitty/config.py

@@ -0,0 +1,140 @@
+"""Repo `chitty.toml` and user-level `contexts.toml`."""
+
+import os
+import re
+import tomllib
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, ValidationError, field_validator, model_validator
+
+from chitty.errors import ChittyError
+from chitty.ids import PREFIX_RE
+
+CONFIG_NAME = "chitty.toml"
+BACKLOG_DIR = "chitty"
+ROOT_ENV = "CHITTY_ROOT"
+CONTEXT_NAME_RE = re.compile(r"[a-z0-9][a-z0-9_-]*")
+RESERVED_CONTEXT_NAMES = ("archive",)
+INITIAL_CONFIG = """\
+format = 1
+default_context = "tasks"
+autocommit = false
+
+[contexts.tasks]
+prefix = "{prefix}"
+
+[contexts.human]
+prefix = "HUMAN"
+"""
+
+
+class ContextConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    prefix: str
+
+    @field_validator("prefix")
+    @classmethod
+    def _prefix(cls, value: str) -> str:
+        if not PREFIX_RE.fullmatch(value):
+            raise ValueError(f"{value!r} must be upper-case letters only, e.g. TASK")
+        return value
+
+
+class RepoConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    format: Literal[1]
+    default_context: str
+    autocommit: bool
+    contexts: dict[str, ContextConfig]
+
+    @model_validator(mode="after")
+    def _consistent(self) -> "RepoConfig":
+        for name in self.contexts:
+            if not CONTEXT_NAME_RE.fullmatch(name) or name in RESERVED_CONTEXT_NAMES:
+                raise ValueError(f"context name {name!r} is not allowed")
+        if self.default_context not in self.contexts:
+            raise ValueError(f"default_context {self.default_context!r} is not in [contexts]")
+        prefixes = [c.prefix for c in self.contexts.values()]
+        duplicates = sorted({p for p in prefixes if prefixes.count(p) > 1})
+        if duplicates:
+            raise ValueError(f"prefix {duplicates[0]!r} is used by more than one context")
+        return self
+
+
+class UserContext(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    repo: str
+    context: str | None = None
+
+
+class UserContexts(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    contexts: dict[str, UserContext] = {}
+
+
+def find_root(start: Path) -> Path:
+    """`CHITTY_ROOT` if set, else the nearest ancestor containing chitty.toml."""
+    root = search_root(start)
+    if root is None:
+        raise ChittyError(f"no {CONFIG_NAME} in {start} or any parent (run `chitty init`)")
+    return root
+
+
+def search_root(start: Path) -> Path | None:
+    """Like find_root, but None when no chitty.toml is found by walking up."""
+    override = os.environ.get(ROOT_ENV)
+    if override:
+        root = Path(override).expanduser().resolve()
+        if not (root / CONFIG_NAME).is_file():
+            raise ChittyError(f"{ROOT_ENV}={override} has no {CONFIG_NAME}")
+        return root
+    start = start.resolve()
+    for directory in (start, *start.parents):
+        if (directory / CONFIG_NAME).is_file():
+            return directory
+    return None
+
+
+def load_repo_config(root: Path) -> RepoConfig:
+    return _load(root / CONFIG_NAME, RepoConfig)
+
+
+def user_contexts_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or "~/.config"
+    return Path(base).expanduser() / "chitty" / "contexts.toml"
+
+
+def load_user_contexts() -> UserContexts:
+    path = user_contexts_path()
+    if not path.exists():
+        return UserContexts()
+    return _load(path, UserContexts)
+
+
+def validate_repo_config(text: str, source: Path) -> RepoConfig:
+    return _validate(text, source, RepoConfig)
+
+
+def _load[M: BaseModel](path: Path, model: type[M]) -> M:
+    return _validate(path.read_text(), path, model)
+
+
+def _validate[M: BaseModel](text: str, path: Path, model: type[M]) -> M:
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise ChittyError(f"{path}: invalid TOML: {error}") from None
+    try:
+        return model.model_validate(data)
+    except ValidationError as error:
+        reasons = [
+            f"{'.'.join(str(p) for p in e['loc']) or 'config'}: "
+            + str(e["msg"]).removeprefix("Value error, ")
+            for e in error.errors()
+        ]
+        raise ChittyError(f"{path}: {'; '.join(reasons)}") from None

chitty/errors.py

@@ -0,0 +1,2 @@
+class ChittyError(Exception):
+    """A user-facing error: the message says what is wrong and where."""

chitty/git.py

@@ -0,0 +1,29 @@
+"""Optional autocommit: commit exactly the paths a write touched."""
+
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+
+from chitty.errors import ChittyError
+
+
+def commit(root: Path, paths: Sequence[Path], message: str) -> None:
+    """Commit only `paths`, so nothing the user had staged is swept in.
+
+    Deleted paths are included only if git tracks them.
+    """
+    relative = [str(path.relative_to(root)) for path in paths]
+    present = [p for p in relative if (root / p).exists()]
+    tracked = set(_git(root, "ls-files", "--", *relative).splitlines())
+    included = [p for p in relative if p in present or p in tracked]
+    _git(root, "add", "--", *present)
+    _git(root, "commit", "--quiet", "--only", "-m", message, "--", *included)
+
+
+def _git(root: Path, *args: str) -> str:
+    command = ["git", *args]
+    result = subprocess.run(command, check=False, cwd=root, capture_output=True, text=True)
+    if result.returncode != 0:
+        shown = " ".join(command)
+        raise ChittyError(f"autocommit failed: `{shown}` in {root}:\n{result.stderr.strip()}")
+    return result.stdout

chitty/guide.md

@@ -0,0 +1,14 @@
+## Chitty
+
+Tasks live in `chitty/`. Use the `chitty` CLI (or MCP tools); do not hand-edit
+task files. `chitty --help` is the full command reference.
+
+- Work on one task per session. Start with `chitty show <ID>`.
+- Before writing code, write your approach with `chitty edit <ID> --plan` and
+  set `-s doing`. Wait for approval if the human asked for it.
+- Tick acceptance criteria as you meet them: `chitty edit <ID> --check N`
+  (numbers are shown by `chitty show`).
+- Record anything surprising with `--note`. Set `-s done` when every
+  criterion is ticked and the work is verified.
+- Found unrelated work? `chitty add` it (`-c human` if it needs a person).
+  Don't do it in this session.

chitty/ids.py

@@ -0,0 +1,73 @@
+"""Task IDs, filenames and slugs."""
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from chitty.errors import ChittyError
+
+SLUG_MAX_LENGTH = 60
+
+ID_RE = re.compile(r"(?P<prefix>[A-Z]+)-(?P<number>[1-9][0-9]*)")
+PREFIX_RE = re.compile(r"[A-Z]+")
+SLUG_RE = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+NUMBER_RE = re.compile(r"[1-9][0-9]*")
+FILENAME_SEPARATOR = "--"
+SUFFIX = ".md"
+
+
+class IdError(ChittyError):
+    pass
+
+
+@dataclass(frozen=True, order=True)
+class TaskId:
+    prefix: str
+    number: int
+
+    def __str__(self) -> str:
+        return f"{self.prefix}-{self.number}"
+
+    @classmethod
+    def parse(cls, text: str) -> "TaskId":
+        match = ID_RE.fullmatch(text)
+        if match is None:
+            raise IdError(f"invalid task ID {text!r}: expected PREFIX-N, e.g. TASK-13")
+        return cls(match["prefix"], int(match["number"]))
+
+
+def resolve(text: str, default_prefix: str) -> TaskId:
+    """Parse a user-supplied reference: `TASK-13`, or bare `13` for the default prefix."""
+    if NUMBER_RE.fullmatch(text):
+        return TaskId(default_prefix, int(text))
+    return TaskId.parse(text)
+
+
+def slugify(title: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+    return slug[:SLUG_MAX_LENGTH].rstrip("-")
+
+
+def filename(task_id: TaskId, slug: str) -> str:
+    if not slug:
+        return f"{task_id}{SUFFIX}"
+    return f"{task_id}{FILENAME_SEPARATOR}{slug}{SUFFIX}"
+
+
+def parse_filename(name: str) -> tuple[TaskId, str]:
+    """Split `TASK-13--add-search.md` into its ID and slug."""
+    if not name.endswith(SUFFIX):
+        raise IdError(f"task filename {name!r} must end with {SUFFIX}")
+    stem = name.removesuffix(SUFFIX)
+    id_text, _, slug = stem.partition(FILENAME_SEPARATOR)
+    task_id = TaskId.parse(id_text)
+    if FILENAME_SEPARATOR in stem and not SLUG_RE.fullmatch(slug):
+        raise IdError(
+            f"task filename {name!r} has an invalid slug {slug!r}: "
+            "expected lowercase letters, digits and single hyphens"
+        )
+    return task_id, slug
+
+
+def next_number(existing: Iterable[int]) -> int:
+    return max(existing, default=0) + 1