@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.20

package/template/.claude/skills/{flydocs-local/scripts/flydocs_api.py → flydocs-workflow/scripts/_local/file_store.py}

@@ -1,11 +1,15 @@
-"""FlyDocs Local API — filesystem-based issue management."""
+"""FlyDocs Local Backend — filesystem-based issue management.
+
+All local tier operations are implemented here. The unified client
+delegates to this module when tier is "local".
+"""
 
 import json
-import os
 import re
 from datetime import datetime
 from pathlib import Path
 
+
 # Status directories map to workflow states
 STATUSES = {
     "BACKLOG": "backlog",
@@ -23,33 +27,28 @@ STATUSES = {
 ISSUE_TYPES = {"feature", "bug", "chore", "idea"}
 
 
-def _issues_root() -> Path:
-    """Find flydocs/issues/ relative to repo root."""
-    cwd = Path.cwd()
-    # Walk up to find .flydocs/config.json
-    for parent in [cwd, *cwd.parents]:
-        if (parent / ".flydocs" / "config.json").exists():
-            root = parent / "flydocs" / "issues"
-            root.mkdir(parents=True, exist_ok=True)
-            return root
-    raise RuntimeError("Not in a FlyDocs project (no .flydocs/config.json found)")
+def _issues_root(project_root: Path) -> Path:
+    """Find flydocs/issues/ relative to project root."""
+    root = project_root / "flydocs" / "issues"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
 
 
-def _ensure_dirs() -> Path:
+def _ensure_dirs(project_root: Path) -> Path:
     """Ensure all status directories exist."""
-    root = _issues_root()
+    root = _issues_root(project_root)
     for dirname in set(STATUSES.values()):
         (root / dirname).mkdir(exist_ok=True)
     return root
 
 
-def _counter_path() -> Path:
-    return _issues_root().parent.parent / ".flydocs" / "issues.counter"
+def _counter_path(project_root: Path) -> Path:
+    return project_root / ".flydocs" / "issues.counter"
 
 
-def _next_id() -> str:
+def _next_id(project_root: Path) -> str:
     """Auto-increment and return next FD-XXX identifier."""
-    path = _counter_path()
+    path = _counter_path(project_root)
     path.parent.mkdir(parents=True, exist_ok=True)
     current = int(path.read_text().strip()) if path.exists() else 0
     next_num = current + 1
@@ -76,7 +75,6 @@ def _parse_issue(filepath: Path) -> dict:
         if ":" in line:
             key, val = line.split(":", 1)
             val = val.strip()
-            # Handle numeric values
             if val.isdigit():
                 val = int(val)
             frontmatter[key.strip()] = val
@@ -96,9 +94,9 @@ def _parse_issue(filepath: Path) -> dict:
     return {**frontmatter, "description": description, "comments": comments, "_path": filepath}
 
 
-def _find_issue(ref: str) -> Path:
-    """Find an issue file by its identifier (e.g., FD-001) across all directories."""
-    root = _issues_root()
+def _find_issue(project_root: Path, ref: str) -> Path:
+    """Find an issue file by its identifier across all directories."""
+    root = _issues_root(project_root)
     prefix = ref.upper() + "-"
     for dirname in set(STATUSES.values()):
         dirpath = root / dirname
@@ -128,11 +126,14 @@ def _write_issue(filepath: Path, frontmatter: dict, description: str, comments:
     filepath.write_text("".join(parts) + "\n")
 
 
-def create_issue(title: str, issue_type: str, description: str = "",
+# --- Public API (matches relay backend interface) ---
+
+
+def create_issue(project_root: Path, title: str, issue_type: str, description: str = "",
                  priority: int = 3, estimate: int = 0,
-                 assignee: str = "", triage: bool = False) -> dict:
-    root = _ensure_dirs()
-    identifier = _next_id()
+                 assignee: str = "", triage: bool = False, **_kwargs: object) -> dict:
+    root = _ensure_dirs(project_root)
+    identifier = _next_id(project_root)
     slug = _slugify(title)
     filename = f"{identifier}-{slug}.md"
     now = datetime.now().strftime("%Y-%m-%d")
@@ -152,22 +153,22 @@ def create_issue(title: str, issue_type: str, description: str = "",
         frontmatter["triage"] = "true"
 
     _write_issue(filepath, frontmatter, description or f"## Context\n\n{title}", [])
-    return {"id": identifier, "identifier": identifier, "title": title}
+    return {"id": identifier, "identifier": identifier, "title": title, "url": ""}
 
 
-def transition(ref: str, new_status: str, comment: str) -> dict:
-    filepath = _find_issue(ref)
+def transition(project_root: Path, ref: str, status: str, comment: str) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     prev_status = _status_from_path(filepath)
 
+    new_status = status.upper()
     if new_status not in STATUSES:
         raise ValueError(f"Invalid status: {new_status}. Valid: {', '.join(STATUSES.keys())}")
 
-    target_dir = _issues_root() / STATUSES[new_status]
+    target_dir = _issues_root(project_root) / STATUSES[new_status]
     target_dir.mkdir(exist_ok=True)
     new_path = target_dir / filepath.name
 
-    # Append transition comment
     now = datetime.now().strftime("%Y-%m-%d %H:%M")
     data["comments"].append(f"**{new_status}** — {comment}\n_{now}_")
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
@@ -180,11 +181,11 @@ def transition(ref: str, new_status: str, comment: str) -> dict:
     return {"success": True, "issue": ref, "previousStatus": prev_status, "newStatus": new_status}
 
 
-def add_comment(ref: str, comment: str) -> dict:
-    filepath = _find_issue(ref)
+def add_comment(project_root: Path, ref: str, body: str) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     now = datetime.now().strftime("%Y-%m-%d %H:%M")
-    data["comments"].append(f"{comment}\n_{now}_")
+    data["comments"].append(f"{body}\n_{now}_")
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
 
     fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
@@ -192,9 +193,10 @@ def add_comment(ref: str, comment: str) -> dict:
     return {"success": True, "commentId": len(data["comments"])}
 
 
-def list_issues(status: str = "", assignee: str = "", limit: int = 50) -> list[dict]:
-    root = _issues_root()
-    results = []
+def list_issues(project_root: Path, status: str = "", assignee: str = "",
+                limit: int = 50, **_kwargs: object) -> list[dict]:
+    root = _issues_root(project_root)
+    results: list[dict] = []
     dirs_to_scan = [STATUSES[status]] if status and status in STATUSES else list(set(STATUSES.values()))
 
     for dirname in dirs_to_scan:
@@ -220,8 +222,8 @@ def list_issues(status: str = "", assignee: str = "", limit: int = 50) -> list[d
     return results
 
 
-def get_issue(ref: str) -> dict:
-    filepath = _find_issue(ref)
+def get_issue(project_root: Path, ref: str, **_kwargs: object) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     return {
         "id": data.get("id", ""),
@@ -236,10 +238,13 @@ def get_issue(ref: str) -> dict:
     }
 
 
-def assign_issue(ref: str, assignee: str) -> dict:
-    filepath = _find_issue(ref)
+def assign_issue(project_root: Path, ref: str, assignee: str | None) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
-    data["assignee"] = assignee
+    if assignee is None:
+        data.pop("assignee", None)
+    else:
+        data["assignee"] = assignee
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
 
     fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
@@ -247,8 +252,8 @@ def assign_issue(ref: str, assignee: str) -> dict:
     return {"success": True, "issue": ref, "assignee": assignee}
 
 
-def update_description(ref: str, text: str) -> dict:
-    filepath = _find_issue(ref)
+def update_description(project_root: Path, ref: str, text: str) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
 
@@ -257,9 +262,94 @@ def update_description(ref: str, text: str) -> dict:
     return {"success": True, "issue": ref}
 
 
-def status_summary() -> dict:
-    root = _issues_root()
-    counts = {}
+def update_issue(project_root: Path, ref: str, **fields: object) -> dict:
+    """Bulk update — set multiple fields on an issue."""
+    filepath = _find_issue(project_root, ref)
+    data = _parse_issue(filepath)
+    updated: list[str] = []
+
+    # Handle state transition separately
+    state = fields.get("state")
+    comment = fields.get("comment")
+    if state and isinstance(state, str):
+        result = transition(project_root, ref, state, str(comment or f"Transitioned to {state}"))
+        updated.append("state")
+        # Re-find the file after transition (it may have moved)
+        filepath = _find_issue(project_root, ref)
+        data = _parse_issue(filepath)
+
+    # Handle comment separately (if no state transition already handled it)
+    if comment and isinstance(comment, str) and "state" not in updated:
+        add_comment(project_root, ref, comment)
+        updated.append("comment")
+        data = _parse_issue(filepath)
+
+    # Update simple fields
+    for field in ("title", "priority", "estimate", "assignee"):
+        val = fields.get(field)
+        if val is not None:
+            data[field] = val
+            updated.append(field)
+
+    # Update description
+    desc = fields.get("description")
+    if desc and isinstance(desc, str):
+        data["description"] = desc
+        updated.append("description")
+
+    data["updated"] = datetime.now().strftime("%Y-%m-%d")
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(filepath, fm, data.get("description", ""), data.get("comments", []))
+
+    return {"success": True, "issue": ref, "updated": updated}
+
+
+def estimate_issue(project_root: Path, ref: str, estimate: int) -> dict:
+    filepath = _find_issue(project_root, ref)
+    data = _parse_issue(filepath)
+    data["estimate"] = estimate
+    data["updated"] = datetime.now().strftime("%Y-%m-%d")
+
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(filepath, fm, data["description"], data.get("comments", []))
+    return {"success": True, "issue": ref, "estimate": estimate}
+
+
+def priority_issue(project_root: Path, ref: str, priority: int) -> dict:
+    filepath = _find_issue(project_root, ref)
+    data = _parse_issue(filepath)
+    data["priority"] = priority
+    data["updated"] = datetime.now().strftime("%Y-%m-%d")
+
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(filepath, fm, data["description"], data.get("comments", []))
+    return {"success": True, "issue": ref, "priority": priority}
+
+
+def link_issues(project_root: Path, ref: str, related_ref: str, link_type: str) -> dict:
+    add_comment(project_root, ref, f"Linked ({link_type}): {related_ref}")
+    add_comment(project_root, related_ref, f"Linked ({link_type}): {ref}")
+    return {"success": True, "type": link_type}
+
+
+def project_update(project_root: Path, health: str, body: str, **_kwargs: object) -> dict:
+    """Write a project update as a markdown file."""
+    updates_dir = project_root / "flydocs" / "updates"
+    updates_dir.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now()
+    timestamp = now.strftime("%Y%m%d-%H%M%S")
+    filename = f"{timestamp}.md"
+
+    content = f"---\nhealth: {health}\ndate: {now.strftime('%Y-%m-%d')}\n---\n\n{body}\n"
+    (updates_dir / filename).write_text(content)
+
+    return {"success": True, "id": timestamp}
+
+
+def status_summary(project_root: Path) -> dict:
+    root = _issues_root(project_root)
+    counts: dict[str, int] = {}
     total = 0
     for status, dirname in STATUSES.items():
         dirpath = root / dirname