tsk-cli 0.1.0__py3-none-any.whl

tsk_cli/pull.py

@@ -0,0 +1,432 @@
+"""
+tsk pull -- fetch projects and things from the API, write .task/ directory.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import click
+
+from .api import api_get
+from .config import get_default_org
+
+
+def pull(target_dir: Path | None = None) -> None:
+    org = get_default_org()
+    if not org:
+        click.echo("No default organization set. Run: tsk orgs", err=True)
+        raise SystemExit(1)
+
+    org_id = org["id"]
+    org_name = org["name"]
+
+    click.echo(f"Pulling from org: {org_name}")
+
+    projects: list[dict[str, Any]] = api_get(f"/api/projects/?organization={org_id}")  # type: ignore[assignment]
+
+    if not projects:
+        click.echo("No projects found.")
+        return
+
+    root = (target_dir or Path.cwd()) / ".task"
+    projects_dir = root / "projects"
+    snapshot_projects_dir = root / ".snapshot" / "projects"
+
+    # Clean previous pull (user-facing + baseline for tsk push)
+    import shutil
+
+    if projects_dir.exists():
+        shutil.rmtree(projects_dir)
+    if snapshot_projects_dir.exists():
+        shutil.rmtree(snapshot_projects_dir)
+    projects_dir.mkdir(parents=True, exist_ok=True)
+    snapshot_projects_dir.mkdir(parents=True, exist_ok=True)
+
+    total_things = 0
+    all_things: dict[str, list[dict[str, Any]]] = {}
+
+    for proj in projects:
+        abbr: str = proj["abbreviation"]
+        proj_dir = projects_dir / abbr
+        things_dir = proj_dir / "things"
+        things_dir.mkdir(parents=True, exist_ok=True)
+
+        snap_proj_dir = snapshot_projects_dir / abbr
+        snap_things_dir = snap_proj_dir / "things"
+        snap_things_dir.mkdir(parents=True, exist_ok=True)
+
+        proj_meta: dict[str, Any] = {
+            "id": proj["id"],
+            "name": proj["name"],
+            "abbreviation": abbr,
+            "organization": org_id,
+            "thing_count": proj.get("thing_count", 0),
+            "thing_count_by_status": proj.get("thing_count_by_status", {}),
+        }
+        if proj.get("github_repo"):
+            proj_meta["github_repo"] = proj["github_repo"]
+        proj_dir.joinpath("project.json").write_text(
+            json.dumps(proj_meta, indent=2) + "\n"
+        )
+
+        things: list[dict[str, Any]] = api_get(  # type: ignore[assignment]
+            f"/api/things/?organization={org_id}&project={proj['id']}"
+        )
+
+        all_things[abbr] = things
+        for thing in things:
+            content = _thing_file_content(abbr, thing)
+            things_dir.joinpath(content.filename).write_text(content.text)
+            snap_things_dir.joinpath(content.filename).write_text(content.text)
+            total_things += 1
+
+    # Write .task/config.json
+    root.joinpath("config.json").write_text(
+        json.dumps(
+            {
+                "org_id": org_id,
+                "org_name": org_name,
+                "pulled_at": datetime.now(timezone.utc).isoformat(),
+            },
+            indent=2,
+        )
+        + "\n"
+    )
+
+    # Write .task/AGENTS.md for local AI agents
+    _write_agents_md(root, org_name, projects, all_things)
+
+    # Ensure .task is git-ignored
+    gitignore = root / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*\n")
+
+    click.echo(
+        f"Pulled {len(projects)} project(s), {total_things} thing(s) into .task/"
+    )
+
+
+def _write_agents_md(
+    root: Path,
+    org_name: str,
+    projects: list[dict[str, Any]],
+    all_things: dict[str, list[dict[str, Any]]],
+) -> None:
+    """Generate .task/AGENTS.md -- instructions for local AI agents."""
+    lines: list[str] = []
+    w = lines.append
+
+    w("# TSK Agent Instructions")
+    w("")
+    w(f"Organization: **{org_name}**")
+    w("")
+    w("This directory (`.task/`) is managed by the `tsk` CLI. It contains")
+    w("projects and things (work items) pulled from [tsk.tools](https://tsk.tools).")
+    w("")
+
+    # ── Workflow (imperative, first thing agents read) ─────────────
+    w("## Workflow")
+    w("")
+    w("Follow these steps when working on a thing:")
+    w("")
+    w("1. **Before you start**: run `tsk start <ref>` (e.g. `tsk start FE-001`).")
+    w("   This sets the thing's status to `in_progress`.")
+    w("2. **Every commit**: prefix the message with the thing ref.")
+    w("   Example: `git commit -m 'FE-001 fix auth race condition'`.")
+    w("3. **Branch names**: include the ref so merged PRs are linked automatically.")
+    w("   Example: `git checkout -b FE-001-fix-auth`.")
+    w("4. **Code comments**: when you leave a relevant comment in source code,")
+    w("   include the ref (e.g. `// FE-001: guard against nil`). These are")
+    w("   detected and surfaced as linked code on the thing.")
+    w("5. **When finished**: run `tsk done <ref>` or `tsk review <ref>`.")
+    w("")
+
+    # ── How code linking works ────────────────────────────────────
+    w("## How code gets linked to a thing")
+    w("")
+    w("The server automatically scans the project's linked GitHub repo for the")
+    w("ref pattern `ABBR-NNN` (case-insensitive). A match in **any** of the")
+    w("following places creates a link:")
+    w("")
+    w("- **Commit messages** -- the most reliable method.")
+    w("- **PR titles and branch names** -- caught when the PR is merged.")
+    w("- **Source code** -- comments, strings, or any text in tracked files")
+    w("  (found via GitHub Code Search).")
+    w("")
+    w("Good commit messages:")
+    w("")
+    w("```")
+    w("FE-001 fix auth race condition")
+    w("FE-001 add loading spinner to dashboard")
+    w("```")
+    w("")
+    w("Bad commit messages (ref is missing -- nothing gets linked):")
+    w("")
+    w("```")
+    w("fix auth race condition")
+    w("update dashboard")
+    w("```")
+    w("")
+
+    # ── Valid statuses ────────────────────────────────────────────
+    w("## Valid statuses")
+    w("")
+    w("| Status | Meaning |")
+    w("|--------|---------|")
+    w("| `not_started` | Default. Work has not begun. |")
+    w("| `in_progress` | Actively being worked on. |")
+    w("| `in_review` | Work is complete, awaiting review. |")
+    w("| `done` | Finished. |")
+    w("")
+
+    # ── Updating things ──────────────────────────────────────────
+    w("## Updating things")
+    w("")
+    w("Quick status commands (preferred -- updates the server immediately):")
+    w("")
+    w("```")
+    w("tsk start <ref>      # set to in_progress")
+    w("tsk review <ref>     # set to in_review")
+    w("tsk done <ref>       # set to done")
+    w("```")
+    w("")
+    w("For other edits (rename, body, arbitrary status):")
+    w("")
+    w("1. Edit the `.md` file under `.task/projects/<ABBR>/things/`.")
+    w("2. Run `tsk push` to upload changes to the server.")
+    w("")
+
+    # ── Thing file format ────────────────────────────────────────
+    w("## Thing file format")
+    w("")
+    w("Each thing is a Markdown file with YAML frontmatter:")
+    w("")
+    w("```yaml")
+    w("---")
+    w("id: <uuid>              # Read-only. Server primary key.")
+    w("ref: COM-001            # Read-only. Human-readable identifier.")
+    w("project: <uuid>         # Read-only. Parent project ID.")
+    w("status: not_started     # Editable. See valid statuses above.")
+    w("assigned_to: user@email # Read-only via CLI.")
+    w("created_at: <iso>       # Read-only.")
+    w("updated_at: <iso>       # Read-only. Updated by server on save.")
+    w("---")
+    w("# Thing title            # Editable. The name of the thing.")
+    w("")
+    w("Body text here.          # Editable. Markdown content.")
+    w("```")
+    w("")
+
+    # ── Directory layout ─────────────────────────────────────────
+    w("## Directory layout")
+    w("")
+    w("```")
+    w(".task/")
+    w("  AGENTS.md              # This file")
+    w("  config.json            # Pull metadata (org, timestamp)")
+    w("  projects/")
+    w("    <ABBR>/              # One folder per project (e.g. COM, IOS)")
+    w("      project.json       # Project metadata")
+    w("      things/")
+    w("        <ABBR>-NNN.md   # One file per thing")
+    w("  .snapshot/             # Baseline for tsk push (do not edit)")
+    w("```")
+    w("")
+
+    # ── Per-project summaries ────────────────────────────────────
+    w("## Projects and things")
+    w("")
+    for proj in projects:
+        abbr = proj["abbreviation"]
+        w(f"### {proj['name']} (`{abbr}`)")
+        w("")
+        gh = proj.get("github_repo")
+        if gh:
+            w(f"GitHub repo: `{gh}` -- <https://github.com/{gh}>")
+            w("")
+        w(f"When working on a thing from this project, include its ref")
+        w(f"(e.g. `{abbr}-001`) at the start of every commit message.")
+        w("")
+        things = all_things.get(abbr, [])
+        if things:
+            w("| Ref | Status | Title |")
+            w("|-----|--------|-------|")
+            for t in things:
+                tid = t.get("project_thing_id", 0)
+                ref = f"{abbr}-{tid:03d}"
+                st = t.get("status", "not_started")
+                name = t.get("name", "Untitled")
+                w(f"| `{ref}` | `{st}` | {name} |")
+            w("")
+        else:
+            w("No things in this project.")
+            w("")
+
+    # ── CLI quick reference (at the bottom) ──────────────────────
+    w("## CLI quick reference")
+    w("")
+    w("| Command | Description |")
+    w("|---------|-------------|")
+    w("| `tsk pull` | Fetch latest projects and things into `.task/` |")
+    w("| `tsk push [--force]` | Upload local edits to the server |")
+    w("| `tsk list [--status S] [--project ABBR]` | List things with optional filters |")
+    w("| `tsk show <ref>` | Display a thing's details |")
+    w("| `tsk set-status <ref> <status>` | Update status and push immediately |")
+    w("| `tsk start <ref>` | Set status to `in_progress` |")
+    w("| `tsk done <ref>` | Set status to `done` |")
+    w("| `tsk review <ref>` | Set status to `in_review` |")
+    w("| `tsk open <ref>` | Open thing in browser at tsk.tools |")
+    w("| `tsk status` | Show current config and auth state |")
+    w("")
+
+    root.joinpath("AGENTS.md").write_text("\n".join(lines) + "\n")
+
+
+@dataclass
+class ThingFileContent:
+    filename: str
+    text: str
+
+
+def _thing_file_content(abbr: str, thing: dict[str, Any]) -> ThingFileContent:
+    """Build markdown for a single thing (<ABBR>-NNN.md with YAML frontmatter)."""
+    tid: int = thing.get("project_thing_id", 0)
+    ref = f"{abbr}-{tid:03d}"
+    filename = f"{ref}.md"
+
+    body = _extract_body(thing)
+
+    frontmatter_lines = [
+        "---",
+        f"id: {thing['id']}",
+        f"ref: {ref}",
+        f"project: {thing.get('project', '')}",
+        f"status: {thing.get('status', 'not_started')}",
+        f"assigned_to: {thing.get('assigned_to_email', '')}",
+        f"created_at: {thing.get('created_at', '')}",
+        f"updated_at: {thing.get('updated_at', '')}",
+        "---",
+    ]
+
+    text = "\n".join(frontmatter_lines) + "\n"
+    text += f"# {thing.get('name', 'Untitled')}\n\n"
+    if body:
+        text += body + "\n"
+
+    return ThingFileContent(filename=filename, text=text)
+
+
+def _extract_body(thing: dict[str, Any]) -> str:
+    """
+    Convert body_json (TipTap ProseMirror JSON) to plain markdown-ish text.
+    Falls back to the HTML body field stripped of tags.
+    """
+    body_json_str = thing.get("body_json", "")
+    if body_json_str:
+        try:
+            doc = json.loads(body_json_str)
+            return _prosemirror_to_text(doc)
+        except (json.JSONDecodeError, TypeError, KeyError):
+            pass
+
+    html_body = thing.get("body", "")
+    if html_body:
+        return _strip_html(html_body)
+
+    return ""
+
+
+def _prosemirror_to_text(doc: dict) -> str:
+    """
+    Minimal ProseMirror JSON -> markdown converter.
+    Handles paragraphs, headings, bullet/ordered lists, task lists, and code blocks.
+    """
+    if not isinstance(doc, dict):
+        return ""
+    content = doc.get("content", [])
+    return "\n".join(_render_node(node) for node in content).strip()
+
+
+def _render_node(node: dict, depth: int = 0) -> str:
+    ntype = node.get("type", "")
+
+    if ntype == "text":
+        text = node.get("text", "")
+        marks = node.get("marks", [])
+        for mark in marks:
+            mt = mark.get("type", "")
+            if mt == "bold":
+                text = f"**{text}**"
+            elif mt == "italic":
+                text = f"*{text}*"
+            elif mt == "code":
+                text = f"`{text}`"
+        return text
+
+    if ntype == "paragraph":
+        inner = _render_children(node)
+        return inner + "\n"
+
+    if ntype == "heading":
+        level = node.get("attrs", {}).get("level", 1)
+        inner = _render_children(node)
+        return "#" * level + " " + inner + "\n"
+
+    if ntype == "bulletList":
+        items = node.get("content", [])
+        lines = []
+        for item in items:
+            text = _render_children(item).strip()
+            lines.append(f"{'  ' * depth}- {text}")
+        return "\n".join(lines) + "\n"
+
+    if ntype == "orderedList":
+        items = node.get("content", [])
+        lines = []
+        for i, item in enumerate(items, 1):
+            text = _render_children(item).strip()
+            lines.append(f"{'  ' * depth}{i}. {text}")
+        return "\n".join(lines) + "\n"
+
+    if ntype == "taskList":
+        items = node.get("content", [])
+        lines = []
+        for item in items:
+            checked = item.get("attrs", {}).get("checked", False)
+            marker = "[x]" if checked else "[ ]"
+            text = _render_children(item).strip()
+            lines.append(f"{'  ' * depth}- {marker} {text}")
+        return "\n".join(lines) + "\n"
+
+    if ntype == "codeBlock":
+        lang = node.get("attrs", {}).get("language", "")
+        inner = _render_children(node)
+        return f"```{lang}\n{inner}\n```\n"
+
+    if ntype == "blockquote":
+        inner = _render_children(node)
+        return "\n".join(f"> {line}" for line in inner.split("\n")) + "\n"
+
+    if ntype == "hardBreak":
+        return "\n"
+
+    # Fallback: render children
+    return _render_children(node)
+
+
+def _render_children(node: dict) -> str:
+    children = node.get("content", [])
+    return "".join(_render_node(c) for c in children)
+
+
+def _strip_html(html: str) -> str:
+    """Crude HTML tag stripper for fallback body rendering."""
+    import re
+    text = re.sub(r"<br\s*/?>", "\n", html)
+    text = re.sub(r"<[^>]+>", "", text)
+    return text.strip()

tsk_cli/push.py

@@ -0,0 +1,246 @@
+"""
+tsk push -- upload local .task/ thing edits to the server.
+
+Compares each thing file to .task/.snapshot/ (baseline from last pull).
+Uses optimistic concurrency: server updated_at must match snapshot unless --force.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import click
+import requests
+
+from .api import api_get, api_patch
+
+
+@dataclass
+class ParsedThingFile:
+    frontmatter: dict[str, str]
+    name: str
+    body: str  # markdown body below the # title line
+    raw: str
+
+
+def parse_thing_markdown(text: str) -> ParsedThingFile:
+    """Parse a thing .md file: YAML frontmatter, # title, body."""
+    text = text.replace("\r\n", "\n")
+    if not text.startswith("---\n"):
+        raise ValueError("Expected YAML frontmatter starting with ---")
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        raise ValueError("Expected closing --- for frontmatter")
+
+    fm_block = text[4:end]
+    rest = text[end + 5 :]
+
+    frontmatter: dict[str, str] = {}
+    for line in fm_block.split("\n"):
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        if ":" in line:
+            k, v = line.split(":", 1)
+            frontmatter[k.strip()] = v.strip()
+
+    lines = rest.split("\n")
+    name = "Untitled"
+    body_start = 0
+    if lines and lines[0].startswith("# "):
+        name = lines[0][2:].strip()
+        body_start = 1
+    elif lines and lines[0].startswith("#"):
+        name = lines[0].lstrip("#").strip()
+        body_start = 1
+
+    body_lines = lines[body_start:]
+    while body_lines and not body_lines[0].strip():
+        body_lines.pop(0)
+    body = "\n".join(body_lines).rstrip("\n")
+
+    return ParsedThingFile(
+        frontmatter=frontmatter, name=name, body=body, raw=text
+    )
+
+
+def build_thing_markdown(frontmatter: dict[str, str], name: str, body: str) -> str:
+    """Rebuild .md content; frontmatter key order matches pull output."""
+    order = [
+        "id",
+        "ref",
+        "project",
+        "status",
+        "assigned_to",
+        "created_at",
+        "updated_at",
+    ]
+    lines = ["---"]
+    for key in order:
+        if key in frontmatter:
+            lines.append(f"{key}: {frontmatter[key]}")
+    for k, v in sorted(frontmatter.items()):
+        if k not in order:
+            lines.append(f"{k}: {v}")
+    lines.append("---")
+    text = "\n".join(lines) + "\n"
+    text += f"# {name}\n\n"
+    if body:
+        text += body + "\n"
+    return text
+
+
+def markdown_body_to_html(body: str) -> str:
+    """Convert plain / markdown-ish body to HTML the backend can migrate to ProseMirror."""
+    body = body.replace("\r\n", "\n").strip()
+    if not body:
+        return ""
+
+    parts: list[str] = []
+    for para in body.split("\n\n"):
+        para = para.strip()
+        if not para:
+            continue
+        inner = html.escape(para).replace("\n", "<br/>")
+        parts.append(f"<p>{inner}</p>")
+    return "".join(parts)
+
+
+def _semantic_tuple(p: ParsedThingFile) -> tuple[str, str, str]:
+    return (p.name, p.frontmatter.get("status", ""), p.body)
+
+
+def push(*, force: bool = False, target_dir: Path | None = None) -> None:
+    root = (target_dir or Path.cwd()) / ".task"
+    projects_dir = root / "projects"
+    snapshot_root = root / ".snapshot" / "projects"
+
+    if not projects_dir.is_dir():
+        click.echo("No .task/projects directory. Run: tsk pull", err=True)
+        raise SystemExit(1)
+
+    if not snapshot_root.is_dir():
+        click.echo(
+            "No .task/.snapshot baseline. Run: tsk pull (to refresh snapshots for push)",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    unchanged = 0
+    pushed = 0
+    conflicts = 0
+    errors = 0
+
+    for local_path in sorted(projects_dir.glob("**/things/*.md")):
+        rel = local_path.relative_to(projects_dir)
+        snap_path = snapshot_root / rel
+
+        if not snap_path.is_file():
+            click.echo(
+                f"  skip {rel}: no snapshot (run tsk pull)", err=True
+            )
+            errors += 1
+            continue
+
+        try:
+            local_raw = local_path.read_text()
+            snap_raw = snap_path.read_text()
+        except OSError as e:
+            click.echo(f"  skip {rel}: read error: {e}", err=True)
+            errors += 1
+            continue
+
+        if local_raw == snap_raw:
+            unchanged += 1
+            continue
+
+        try:
+            local_p = parse_thing_markdown(local_raw)
+            snap_p = parse_thing_markdown(snap_raw)
+        except ValueError as e:
+            click.echo(f"  skip {rel}: parse error: {e}", err=True)
+            errors += 1
+            continue
+
+        thing_id = local_p.frontmatter.get("id", "")
+        if not thing_id:
+            click.echo(f"  skip {rel}: missing id in frontmatter", err=True)
+            errors += 1
+            continue
+
+        if _semantic_tuple(local_p) == _semantic_tuple(snap_p):
+            unchanged += 1
+            continue
+
+        ref = local_p.frontmatter.get("ref", rel.stem)
+
+        if not force:
+            try:
+                server_thing = api_get(f"/api/things/{thing_id}/")
+            except Exception as e:
+                click.echo(f"  {ref}: could not fetch server state: {e}", err=True)
+                errors += 1
+                continue
+
+            if not isinstance(server_thing, dict):
+                click.echo(f"  {ref}: unexpected API response", err=True)
+                errors += 1
+                continue
+
+            snap_updated = snap_p.frontmatter.get("updated_at", "")
+            srv_updated = str(server_thing.get("updated_at", ""))
+            if srv_updated != snap_updated:
+                click.echo(
+                    f"  conflict {ref}: server was modified since last pull "
+                    f"(run tsk pull, then re-apply edits). Use --force to overwrite.",
+                    err=True,
+                )
+                conflicts += 1
+                continue
+
+        payload: dict[str, Any] = {}
+        if local_p.name != snap_p.name:
+            payload["name"] = local_p.name
+        if local_p.frontmatter.get("status") != snap_p.frontmatter.get("status"):
+            payload["status"] = local_p.frontmatter.get("status", "not_started")
+        if local_p.body != snap_p.body:
+            payload["body"] = markdown_body_to_html(local_p.body)
+
+        if not payload:
+            unchanged += 1
+            continue
+
+        try:
+            updated = api_patch(f"/api/things/{thing_id}/", payload)
+        except requests.HTTPError as e:
+            click.echo(f"  {ref}: PATCH failed: {e}", err=True)
+            if e.response is not None and e.response.text:
+                click.echo(f"    {e.response.text[:500]}", err=True)
+            errors += 1
+            continue
+        except Exception as e:
+            click.echo(f"  {ref}: PATCH failed: {e}", err=True)
+            errors += 1
+            continue
+
+        if not isinstance(updated, dict) or not updated.get("updated_at"):
+            updated = api_get(f"/api/things/{thing_id}/")
+
+        if isinstance(updated, dict) and updated.get("updated_at"):
+            local_p.frontmatter["updated_at"] = str(updated["updated_at"])
+            new_raw = build_thing_markdown(
+                local_p.frontmatter, local_p.name, local_p.body
+            )
+            local_path.write_text(new_raw)
+            snap_path.write_text(new_raw)
+
+        pushed += 1
+        click.echo(f"  pushed {ref}")
+
+    click.echo(
+        f"Done: {pushed} pushed, {unchanged} unchanged, "
+        f"{conflicts} conflict(s), {errors} error(s)"
+    )