@flydocs/cli 0.5.0-beta.0

package/template/.claude/skills/flydocs-local/cursor-rule.mdc

@@ -0,0 +1,43 @@
+---
+description: File-based issue management — local mechanism for FlyDocs
+alwaysApply: true
+---
+
+<!-- Condensed from SKILL.md — update both when changing patterns -->
+
+# FlyDocs Local Mechanism
+
+Issues stored as markdown files with YAML frontmatter. No accounts, no API keys, no network.
+
+## Script Contract
+
+All scripts: `python3 .claude/skills/flydocs-local/scripts/<script>`
+
+| Script | Key Arguments |
+|--------|---------------|
+| `create_issue.py` | `--title "..." --type feature [--priority 0-4] [--estimate 1-5] [--assignee STR] [--triage]` |
+| `transition.py` | `<ref> <STATUS> "<comment>"` |
+| `comment.py` | `<ref> "<comment>"` |
+| `list_issues.py` | `[--status STATUS] [--mine] [--limit N]` |
+| `get_issue.py` | `<ref>` |
+| `assign.py` | `<ref> <assignee>` |
+| `update_description.py` | `<ref> --text "..." \| --file PATH` |
+| `status_summary.py` | `[--project ID]` |
+
+## Status Values
+
+`BACKLOG`, `READY`, `IMPLEMENTING`, `BLOCKED`, `REVIEW`, `TESTING`, `COMPLETE`, `ARCHIVED`, `CANCELED`, `DUPLICATE`
+
+## Storage Layout
+
+```
+flydocs/issues/
+  backlog/        implementing/     review/
+  ready/          testing/          done/
+```
+
+Issues: `FD-XXX-slug.md` with YAML frontmatter. IDs auto-increment via `.flydocs/issues/.counter`.
+
+## Error Handling
+
+Exit 0 = success (JSON on stdout). Exit 1 = error (message on stderr).

package/template/.claude/skills/flydocs-local/scripts/assign.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Assign an issue to a person."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import assign_issue
+
+if len(sys.argv) < 3:
+    print("Usage: assign.py <ref> <assignee>", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    result = assign_issue(sys.argv[1], sys.argv[2])
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/comment.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Add a comment to an issue."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import add_comment
+
+if len(sys.argv) < 2:
+    print("Usage: comment.py <ref> [<comment>]  (or pipe via stdin)", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    ref = sys.argv[1]
+    body = sys.argv[2] if len(sys.argv) > 2 else ""
+    if not body and not sys.stdin.isatty():
+        body = sys.stdin.read().strip()
+    if not body:
+        print("Provide comment as argument or pipe via stdin", file=sys.stderr)
+        sys.exit(1)
+    result = add_comment(ref, body)
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/create_issue.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Create a new local issue."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import create_issue, ISSUE_TYPES
+
+parser = argparse.ArgumentParser(description="Create a new issue")
+parser.add_argument("--title", required=True)
+parser.add_argument("--type", required=True, choices=sorted(ISSUE_TYPES), dest="issue_type")
+parser.add_argument("--description", default="")
+parser.add_argument("--description-file", default="", dest="description_file")
+parser.add_argument("--priority", type=int, default=3, choices=range(5))
+parser.add_argument("--estimate", type=int, default=0, choices=range(6))
+parser.add_argument("--assignee", default="")
+parser.add_argument("--triage", action="store_true")
+
+try:
+    args = parser.parse_args()
+
+    # Resolve description: --description-file > stdin > --description
+    description = args.description
+    if args.description_file:
+        description = Path(args.description_file).read_text()
+    elif not description and not sys.stdin.isatty():
+        description = sys.stdin.read().strip()
+
+    result = create_issue(
+        title=args.title,
+        issue_type=args.issue_type,
+        description=description,
+        priority=args.priority,
+        estimate=args.estimate,
+        assignee=args.assignee,
+        triage=args.triage,
+    )
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/estimate.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Set estimate on an issue."""
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import _find_issue, _parse_issue, _write_issue
+
+if len(sys.argv) < 3:
+    print("Usage: estimate.py <ref> <1-5>", file=sys.stderr)
+    sys.exit(1)
+
+ref = sys.argv[1]
+try:
+    estimate = int(sys.argv[2])
+    if estimate < 1 or estimate > 5:
+        raise ValueError
+except ValueError:
+    print("Estimate must be a number (1-5)", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    filepath = _find_issue(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["comments"])
+
+    print(json.dumps({"success": True, "issue": ref, "estimate": estimate}))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/flydocs_api.py

@@ -0,0 +1,272 @@
+"""FlyDocs Local API — filesystem-based issue management."""
+
+import json
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+
+# Status directories map to workflow states
+STATUSES = {
+    "BACKLOG": "backlog",
+    "READY": "ready",
+    "IMPLEMENTING": "implementing",
+    "BLOCKED": "blocked",
+    "REVIEW": "review",
+    "TESTING": "testing",
+    "COMPLETE": "done",
+    "ARCHIVED": "done",
+    "CANCELED": "done",
+    "DUPLICATE": "done",
+}
+
+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 _ensure_dirs() -> Path:
+    """Ensure all status directories exist."""
+    root = _issues_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 _next_id() -> str:
+    """Auto-increment and return next FD-XXX identifier."""
+    path = _counter_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    current = int(path.read_text().strip()) if path.exists() else 0
+    next_num = current + 1
+    path.write_text(str(next_num))
+    return f"FD-{next_num:03d}"
+
+
+def _slugify(title: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+    return slug[:50]
+
+
+def _parse_issue(filepath: Path) -> dict:
+    """Parse a markdown issue file into frontmatter dict + body + comments."""
+    text = filepath.read_text()
+    if not text.startswith("---"):
+        raise ValueError(f"Invalid issue file: {filepath}")
+    _, fm_raw, *rest = text.split("---", 2)
+    body_and_comments = rest[0] if rest else ""
+
+    # Parse YAML frontmatter manually (avoid pyyaml dependency)
+    frontmatter = {}
+    for line in fm_raw.strip().splitlines():
+        if ":" in line:
+            key, val = line.split(":", 1)
+            val = val.strip()
+            # Handle numeric values
+            if val.isdigit():
+                val = int(val)
+            frontmatter[key.strip()] = val
+
+    # Split body and comments
+    parts = body_and_comments.split("\n---\n## Comments", 1)
+    description = parts[0].strip()
+    comments_raw = parts[1].strip() if len(parts) > 1 else ""
+
+    comments = []
+    if comments_raw:
+        for block in re.split(r"\n(?=\*\*)", comments_raw):
+            block = block.strip()
+            if block:
+                comments.append(block)
+
+    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()
+    prefix = ref.upper() + "-"
+    for dirname in set(STATUSES.values()):
+        dirpath = root / dirname
+        if not dirpath.exists():
+            continue
+        for f in dirpath.iterdir():
+            if f.name.upper().startswith(prefix) and f.suffix == ".md":
+                return f
+    raise FileNotFoundError(f"Issue {ref} not found")
+
+
+def _status_from_path(filepath: Path) -> str:
+    """Get the FlyDocs status from a file's parent directory."""
+    dirname = filepath.parent.name
+    for status, dname in STATUSES.items():
+        if dname == dirname:
+            return status
+    return "BACKLOG"
+
+
+def _write_issue(filepath: Path, frontmatter: dict, description: str, comments: list[str]) -> None:
+    """Write an issue file with frontmatter, description, and comments."""
+    fm_lines = "\n".join(f"{k}: {v}" for k, v in frontmatter.items() if not k.startswith("_"))
+    parts = [f"---\n{fm_lines}\n---\n\n{description}"]
+    if comments:
+        parts.append("\n---\n## Comments\n\n" + "\n\n".join(comments))
+    filepath.write_text("".join(parts) + "\n")
+
+
+def create_issue(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()
+    slug = _slugify(title)
+    filename = f"{identifier}-{slug}.md"
+    now = datetime.now().strftime("%Y-%m-%d")
+    filepath = root / "backlog" / filename
+
+    frontmatter = {
+        "id": identifier,
+        "title": title,
+        "type": issue_type,
+        "priority": priority,
+        "estimate": estimate,
+        "assignee": assignee,
+        "created": now,
+        "updated": now,
+    }
+    if triage:
+        frontmatter["triage"] = "true"
+
+    _write_issue(filepath, frontmatter, description or f"## Context\n\n{title}", [])
+    return {"id": identifier, "identifier": identifier, "title": title}
+
+
+def transition(ref: str, new_status: str, comment: str) -> dict:
+    filepath = _find_issue(ref)
+    data = _parse_issue(filepath)
+    prev_status = _status_from_path(filepath)
+
+    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.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")
+
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(new_path, fm, data["description"], data["comments"])
+    if new_path != filepath:
+        filepath.unlink()
+
+    return {"success": True, "issue": ref, "previousStatus": prev_status, "newStatus": new_status}
+
+
+def add_comment(ref: str, comment: str) -> dict:
+    filepath = _find_issue(ref)
+    data = _parse_issue(filepath)
+    now = datetime.now().strftime("%Y-%m-%d %H:%M")
+    data["comments"].append(f"{comment}\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")}
+    _write_issue(filepath, fm, data["description"], data["comments"])
+    return {"success": True, "commentId": len(data["comments"])}
+
+
+def list_issues(status: str = "", assignee: str = "", limit: int = 50) -> list[dict]:
+    root = _issues_root()
+    results = []
+    dirs_to_scan = [STATUSES[status]] if status and status in STATUSES else list(set(STATUSES.values()))
+
+    for dirname in dirs_to_scan:
+        dirpath = root / dirname
+        if not dirpath.exists():
+            continue
+        for f in sorted(dirpath.iterdir()):
+            if f.suffix != ".md":
+                continue
+            data = _parse_issue(f)
+            if assignee and data.get("assignee", "") != assignee:
+                continue
+            results.append({
+                "id": data.get("id", ""),
+                "identifier": data.get("id", ""),
+                "title": data.get("title", ""),
+                "status": _status_from_path(f),
+                "assignee": data.get("assignee", ""),
+                "priority": data.get("priority", 3),
+            })
+            if len(results) >= limit:
+                return results
+    return results
+
+
+def get_issue(ref: str) -> dict:
+    filepath = _find_issue(ref)
+    data = _parse_issue(filepath)
+    return {
+        "id": data.get("id", ""),
+        "identifier": data.get("id", ""),
+        "title": data.get("title", ""),
+        "description": data.get("description", ""),
+        "status": _status_from_path(filepath),
+        "assignee": data.get("assignee", ""),
+        "priority": data.get("priority", 3),
+        "estimate": data.get("estimate", 0),
+        "comments": data.get("comments", []),
+    }
+
+
+def assign_issue(ref: str, assignee: str) -> dict:
+    filepath = _find_issue(ref)
+    data = _parse_issue(filepath)
+    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")}
+    _write_issue(filepath, fm, data["description"], data["comments"])
+    return {"success": True, "issue": ref, "assignee": assignee}
+
+
+def update_description(ref: str, text: str) -> dict:
+    filepath = _find_issue(ref)
+    data = _parse_issue(filepath)
+    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, text, data["comments"])
+    return {"success": True, "issue": ref}
+
+
+def status_summary() -> dict:
+    root = _issues_root()
+    counts = {}
+    total = 0
+    for status, dirname in STATUSES.items():
+        dirpath = root / dirname
+        if not dirpath.exists():
+            continue
+        count = len([f for f in dirpath.iterdir() if f.suffix == ".md"])
+        if count > 0:
+            counts[status] = counts.get(status, 0) + count
+            total += count
+    return {"statuses": counts, "total": total}

package/template/.claude/skills/flydocs-local/scripts/get_issue.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Get full details for an issue."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_issue
+
+if len(sys.argv) < 2:
+    print("Usage: get_issue.py <ref>", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    result = get_issue(sys.argv[1])
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/link.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Create a relationship between two issues."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import _find_issue, add_comment
+
+LINK_TYPES = {"blocks", "related", "duplicate"}
+
+if len(sys.argv) < 4:
+    print(f"Usage: link.py <ref> <related_ref> <type>\nTypes: {', '.join(sorted(LINK_TYPES))}", file=sys.stderr)
+    sys.exit(1)
+
+ref, related_ref, link_type = sys.argv[1], sys.argv[2], sys.argv[3].lower()
+if link_type not in LINK_TYPES:
+    print(f"Invalid type: {link_type}. Valid: {', '.join(sorted(LINK_TYPES))}", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    # Verify both issues exist
+    _find_issue(ref)
+    _find_issue(related_ref)
+
+    # Record the link as comments on both issues
+    if link_type == "blocks":
+        add_comment(ref, f"**Link**: blocks {related_ref}")
+        add_comment(related_ref, f"**Link**: blocked by {ref}")
+    elif link_type == "duplicate":
+        add_comment(ref, f"**Link**: duplicate of {related_ref}")
+        add_comment(related_ref, f"**Link**: duplicate of {ref}")
+    else:
+        add_comment(ref, f"**Link**: related to {related_ref}")
+        add_comment(related_ref, f"**Link**: related to {ref}")
+
+    print(json.dumps({"success": True, "type": link_type}))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/list_issues.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""List issues with optional filters."""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import list_issues
+
+TERMINAL_STATUSES = {"COMPLETE", "ARCHIVED", "CANCELED", "DUPLICATE"}
+
+parser = argparse.ArgumentParser(description="List issues")
+parser.add_argument("--status", default="")
+parser.add_argument("--active", action="store_true",
+                    help="All non-terminal states (excludes Done, Archived, Canceled, Duplicate)")
+parser.add_argument("--assignee", default="")
+parser.add_argument("--mine", action="store_true")
+parser.add_argument("--limit", type=int, default=50)
+
+try:
+    args = parser.parse_args()
+    assignee = args.assignee
+    if args.mine:
+        assignee = os.environ.get("USER", os.environ.get("USERNAME", ""))
+    result = list_issues(status=args.status.upper() if args.status else "", assignee=assignee, limit=args.limit)
+    if args.active:
+        result = [r for r in result if r.get("status") not in TERMINAL_STATUSES]
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/priority.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Set priority on an issue."""
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import _find_issue, _parse_issue, _write_issue
+
+if len(sys.argv) < 3:
+    print("Usage: priority.py <ref> <0-4>", file=sys.stderr)
+    sys.exit(1)
+
+ref = sys.argv[1]
+try:
+    priority = int(sys.argv[2])
+    if priority < 0 or priority > 4:
+        raise ValueError
+except ValueError:
+    print("Priority must be a number (0-4)", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    filepath = _find_issue(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["comments"])
+
+    print(json.dumps({"success": True, "issue": ref, "priority": priority}))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/project_update.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Post a project health update (local: saves to flydocs/updates/)."""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+HEALTH_VALUES = {"onTrack", "atRisk", "offTrack"}
+
+parser = argparse.ArgumentParser(description="Post project update")
+parser.add_argument("--health", required=True, choices=sorted(HEALTH_VALUES))
+parser.add_argument("--body", default="")
+parser.add_argument("--body-file", default="")
+parser.add_argument("--project", default=None)
+
+try:
+    args = parser.parse_args()
+
+    body = args.body
+    if args.body_file:
+        p = Path(args.body_file)
+        if not p.exists():
+            print(f"File not found: {args.body_file}", file=sys.stderr)
+            sys.exit(1)
+        body = p.read_text().strip()
+    if not body and not sys.stdin.isatty():
+        body = sys.stdin.read().strip()
+    if not body:
+        print("Provide --body, --body-file, or pipe via stdin", file=sys.stderr)
+        sys.exit(1)
+
+    # Find project root
+    cwd = Path.cwd()
+    root = None
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".flydocs" / "config.json").exists():
+            root = parent
+            break
+    if not root:
+        print("Not in a FlyDocs project", file=sys.stderr)
+        sys.exit(1)
+
+    # Save update to flydocs/updates/
+    updates_dir = root / "flydocs" / "updates"
+    updates_dir.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now()
+    update_id = now.strftime("%Y%m%d-%H%M%S")
+    filename = f"{update_id}.md"
+
+    content = f"""---
+health: {args.health}
+date: {now.strftime("%Y-%m-%d")}
+time: {now.strftime("%H:%M")}
+---
+
+{body}
+"""
+
+    (updates_dir / filename).write_text(content)
+
+    print(json.dumps({"success": True, "id": update_id}))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

package/template/.claude/skills/flydocs-local/scripts/status_summary.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Show project status summary (issue counts by status)."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import status_summary
+
+try:
+    result = status_summary()
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)