@flydocs/cli 0.6.0-alpha.3 → 0.6.0-alpha.31

package/template/.claude/skills/flydocs-workflow/scripts/projects.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Project, milestone, and cycle operations dispatcher.
+
+All subcommands are cloud-only. The unified client handles tier gating
+via require_cloud().
+
+Usage:
+    python projects.py list-projects [--active] [--all]
+    python projects.py create-project --name NAME [--description DESC]
+    python projects.py list-milestones [--all]
+    python projects.py create-milestone --name NAME [--project ID] [--target-date DATE]
+    python projects.py update-milestone MILESTONE_ID [--name] [--target-date] [--description]
+    python projects.py delete-milestone MILESTONE_ID
+    python projects.py list-cycles [--active]
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+
+def cmd_list_projects(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.list_projects(active=args.active, show_all=args.show_all)
+    output_json(result)
+
+
+def cmd_create_project(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.create_project(name=args.name, description=args.description)
+    output_json(result)
+
+
+def cmd_list_milestones(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.list_milestones(show_all=args.show_all)
+    output_json(result)
+
+
+def cmd_create_milestone(args: argparse.Namespace) -> None:
+    client = get_client()
+    # Default project from activeProjects if not explicitly provided
+    project = args.project
+    if not project and client.is_cloud:
+        active = client.config.get("workspace", {}).get("activeProjects", [])
+        if active:
+            project = active[0]
+    result = client.create_milestone(
+        name=args.name,
+        project=project,
+        target_date=args.target_date,
+    )
+    output_json(result)
+
+
+def cmd_update_milestone(args: argparse.Namespace) -> None:
+    client = get_client()
+    fields: dict = {}
+    if args.name is not None:
+        fields["name"] = args.name
+    if args.target_date is not None:
+        fields["targetDate"] = args.target_date
+    if args.description is not None:
+        fields["description"] = args.description
+    if not fields:
+        fail("At least one of --name, --target-date, or --description is required")
+    result = client.update_milestone(args.milestone_id, **fields)
+    output_json(result)
+
+
+def cmd_delete_milestone(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.delete_milestone(args.milestone_id)
+    output_json(result)
+
+
+def cmd_list_cycles(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.list_cycles(active=args.active)
+    output_json(result)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="FlyDocs project operations")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # list-projects
+    lp = sub.add_parser("list-projects", help="List projects")
+    lp.add_argument("--active", action="store_true", help="Active projects only")
+    lp.add_argument("--all", action="store_true", dest="show_all",
+                     help="Include all projects (bypass label filter)")
+
+    # create-project
+    cp = sub.add_parser("create-project", help="Create a project")
+    cp.add_argument("--name", required=True, help="Project name")
+    cp.add_argument("--description", default=None, help="Project description")
+
+    # list-milestones
+    lm = sub.add_parser("list-milestones", help="List milestones")
+    lm.add_argument("--all", action="store_true", dest="show_all",
+                     help="Include milestones from all projects")
+
+    # create-milestone
+    cm = sub.add_parser("create-milestone", help="Create a milestone")
+    cm.add_argument("--name", required=True, help="Milestone name")
+    cm.add_argument("--project", default=None, help="Project ID")
+    cm.add_argument("--target-date", default=None, dest="target_date",
+                     help="Target date (YYYY-MM-DD)")
+
+    # update-milestone
+    um = sub.add_parser("update-milestone", help="Update a milestone")
+    um.add_argument("milestone_id", help="Milestone ID")
+    um.add_argument("--name", default=None, help="New name")
+    um.add_argument("--target-date", default=None, dest="target_date",
+                     help="New target date (YYYY-MM-DD)")
+    um.add_argument("--description", default=None, help="New description")
+
+    # delete-milestone
+    dm = sub.add_parser("delete-milestone", help="Delete a milestone")
+    dm.add_argument("milestone_id", help="Milestone ID")
+
+    # list-cycles
+    lc = sub.add_parser("list-cycles", help="List cycles")
+    lc.add_argument("--active", action="store_true", help="Active cycles only")
+
+    args = parser.parse_args()
+
+    commands = {
+        "list-projects": cmd_list_projects,
+        "create-project": cmd_create_project,
+        "list-milestones": cmd_list_milestones,
+        "create-milestone": cmd_create_milestone,
+        "update-milestone": cmd_update_milestone,
+        "delete-milestone": cmd_delete_milestone,
+        "list-cycles": cmd_list_cycles,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-workflow/scripts/pull_services.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Pull workspace service descriptors from the relay.
+
+Fetches GET /api/relay/workspace/services and caches the composite
+at .flydocs/cache/workspace-services.json for local use.
+
+Usage:
+    python3 .claude/skills/flydocs-workflow/scripts/pull_services.py [--root PATH]
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from graph_utils import find_project_root, fail
+
+
+def load_api_key(root):
+    """Load FLYDOCS_API_KEY from environment or .env files."""
+    if os.environ.get("FLYDOCS_API_KEY"):
+        return os.environ["FLYDOCS_API_KEY"]
+    for name in [".env.local", ".env"]:
+        env_file = root / name
+        if env_file.exists():
+            with open(env_file, "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if line.startswith("#") or "=" not in line:
+                        continue
+                    k, _, v = line.partition("=")
+                    if k.strip() == "FLYDOCS_API_KEY":
+                        v = v.strip().strip("\"'")
+                        return v if v else None
+    return None
+
+
+def load_config(root):
+    """Load .flydocs/config.json."""
+    config_path = root / ".flydocs" / "config.json"
+    if config_path.exists():
+        with open(config_path, "r") as f:
+            return json.load(f)
+    return {}
+
+
+def resolve_base_url(config):
+    """Resolve relay base URL."""
+    env_url = os.environ.get("FLYDOCS_RELAY_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    config_url = config.get("relay", {}).get("url")
+    if config_url:
+        return config_url.rstrip("/")
+    return "https://app.flydocs.ai/api/relay"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Pull workspace service descriptors")
+    parser.add_argument("--root", type=str, default=None, help="Project root")
+    args = parser.parse_args()
+
+    root = Path(args.root) if args.root else find_project_root()
+    if not root:
+        fail("Could not find project root (no .flydocs/ directory found)")
+
+    config = load_config(root)
+    api_key = load_api_key(root)
+    if not api_key:
+        fail("FLYDOCS_API_KEY not found. Set in environment or .env file.")
+
+    workspace_id = config.get("workspaceId")
+    if not workspace_id:
+        fail("workspaceId not found in .flydocs/config.json. Run /flydocs-setup first.")
+
+    base_url = resolve_base_url(config)
+
+    # Fetch workspace services composite
+    url = f"{base_url}/workspace/services"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "X-Workspace": workspace_id,
+        "Accept": "application/json",
+    }
+
+    try:
+        req = urllib.request.Request(url, headers=headers, method="GET")
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8") if e.fp else ""
+        try:
+            error_data = json.loads(error_body) if error_body else {}
+        except json.JSONDecodeError:
+            error_data = {"error": error_body}
+        fail(f"Relay API error ({e.code}): {error_data.get('error', str(e))}")
+    except (urllib.error.URLError, TimeoutError) as e:
+        fail(f"Network error: {e}")
+
+    # Cache the composite locally
+    cache_dir = root / ".flydocs" / "cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    cache_file = cache_dir / "workspace-services.json"
+
+    cached = {
+        "fetchedAt": datetime.now(timezone.utc).isoformat(),
+        "services": result,
+    }
+    cache_file.write_text(json.dumps(cached, indent=2) + "\n", encoding="utf-8")
+
+    # Report
+    repos = result if isinstance(result, list) else result.get("repos", [])
+    with_descriptor = sum(1 for r in repos if r.get("serviceDescriptor"))
+    print(json.dumps({
+        "success": True,
+        "totalRepos": len(repos),
+        "withDescriptor": with_descriptor,
+        "cachedAt": cache_file.name,
+    }, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-workflow/scripts/push_service.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Push this repo's service descriptor to the relay.
+
+Reads flydocs/context/service.json, strips the local-only `structure` section,
+and pushes to PUT /api/relay/workspace/service.
+
+Usage:
+    python3 .claude/skills/flydocs-workflow/scripts/push_service.py [--root PATH]
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from graph_utils import find_project_root, fail
+
+
+def load_api_key(root):
+    """Load FLYDOCS_API_KEY from environment or .env files."""
+    if os.environ.get("FLYDOCS_API_KEY"):
+        return os.environ["FLYDOCS_API_KEY"]
+    for name in [".env.local", ".env"]:
+        env_file = root / name
+        if env_file.exists():
+            with open(env_file, "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if line.startswith("#") or "=" not in line:
+                        continue
+                    k, _, v = line.partition("=")
+                    if k.strip() == "FLYDOCS_API_KEY":
+                        v = v.strip().strip("\"'")
+                        return v if v else None
+    return None
+
+
+def load_config(root):
+    """Load .flydocs/config.json."""
+    config_path = root / ".flydocs" / "config.json"
+    if config_path.exists():
+        with open(config_path, "r") as f:
+            return json.load(f)
+    return {}
+
+
+def resolve_base_url(config):
+    """Resolve relay base URL."""
+    env_url = os.environ.get("FLYDOCS_RELAY_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    config_url = config.get("relay", {}).get("url")
+    if config_url:
+        return config_url.rstrip("/")
+    return "https://app.flydocs.ai/api/relay"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Push service descriptor to relay")
+    parser.add_argument("--root", type=str, default=None, help="Project root")
+    args = parser.parse_args()
+
+    root = Path(args.root) if args.root else find_project_root()
+    if not root:
+        fail("Could not find project root (no .flydocs/ directory found)")
+
+    # Load service descriptor
+    service_file = root / "flydocs" / "context" / "service.json"
+    if not service_file.exists():
+        fail("No service descriptor found at flydocs/context/service.json. Run /flydocs-setup first.")
+
+    descriptor = json.loads(service_file.read_text(encoding="utf-8"))
+
+    # Strip local-only structure section before pushing
+    export_descriptor = {k: v for k, v in descriptor.items() if k != "structure"}
+
+    # Load config and credentials
+    config = load_config(root)
+    api_key = load_api_key(root)
+    if not api_key:
+        fail("FLYDOCS_API_KEY not found. Set in environment or .env file.")
+
+    workspace_id = config.get("workspaceId")
+    if not workspace_id:
+        fail("workspaceId not found in .flydocs/config.json. Run /flydocs-setup first.")
+
+    repo_slug = config.get("workspace", {}).get("repoSlug")
+    if not repo_slug:
+        repo_slug = descriptor.get("repoSlug")
+    if not repo_slug:
+        fail("repoSlug not found in config or service descriptor.")
+
+    base_url = resolve_base_url(config)
+
+    # Push descriptor
+    url = f"{base_url}/workspace/service"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "X-Workspace": workspace_id,
+        "X-Repo": repo_slug,
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    data = json.dumps({"descriptor": export_descriptor}).encode("utf-8")
+
+    try:
+        req = urllib.request.Request(url, data=data, headers=headers, method="PUT")
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+            print(json.dumps({
+                "success": True,
+                "repoSlug": repo_slug,
+                "fieldsExported": list(export_descriptor.keys()),
+                "response": result,
+            }, indent=2))
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8") if e.fp else ""
+        try:
+            error_data = json.loads(error_body) if error_body else {}
+        except json.JSONDecodeError:
+            error_data = {"error": error_body}
+        fail(f"Relay API error ({e.code}): {error_data.get('error', str(e))}")
+    except (urllib.error.URLError, TimeoutError) as e:
+        fail(f"Network error: {e}")
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-workflow/scripts/session.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Session operations dispatcher — project updates and status summary."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail, resolve_text_input
+
+
+def cmd_project_update(args):
+    body = resolve_text_input(text_arg=args.body, file_arg=args.body_file)
+    if not body:
+        fail("Provide body via --body, --body-file, or stdin")
+    client = get_client()
+    # Resolve project: explicit flag > activeProjects[0] > relay discovery
+    project_id = args.project
+    if not project_id and client.is_cloud:
+        active = client.config.get("workspace", {}).get("activeProjects", [])
+        if active:
+            project_id = active[0]
+    result = client.project_update(args.health, body, project_id=project_id)
+    output_json(result)
+
+
+def cmd_status_summary(args):
+    client = get_client()
+    result = client.status_summary()
+    output_json(result)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="FlyDocs session operations")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("project-update", help="Post a project update")
+    p.add_argument("--health", required=True, choices=["onTrack", "atRisk", "offTrack"])
+    p.add_argument("--body", default=None)
+    p.add_argument("--body-file", default=None, dest="body_file")
+    p.add_argument("--project", default=None, help="Target project ID (defaults from activeProjects)")
+
+    sub.add_parser("status-summary", help="Show issue status counts")
+
+    args = parser.parse_args()
+    commands = {
+        "project-update": cmd_project_update,
+        "status-summary": cmd_status_summary,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-workflow/scripts/test_enforcement.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Tests for workflow enforcement logic.
+
+Run: python3 test_enforcement.py
+Tests the enforcement functions in issues.py, auto-approve.py, stop-gate.py,
+and post-transition-check.py without requiring API access.
+"""
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+# Add parent dirs to path for imports
+SCRIPT_DIR = Path(__file__).parent.resolve()
+HOOKS_DIR = SCRIPT_DIR.parent.parent.parent / "hooks"
+sys.path.insert(0, str(SCRIPT_DIR))
+sys.path.insert(0, str(HOOKS_DIR))
+
+passed = 0
+failed = 0
+
+
+def test(name: str):
+    """Decorator to register and run a test."""
+    def decorator(fn):
+        global passed, failed
+        try:
+            fn()
+            print(f"  PASS: {name}")
+            passed += 1
+        except AssertionError as e:
+            print(f"  FAIL: {name} — {e}")
+            failed += 1
+        except Exception as e:
+            print(f"  ERROR: {name} — {type(e).__name__}: {e}")
+            failed += 1
+        return fn
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# issues.py enforcement tests
+# ---------------------------------------------------------------------------
+
+print("\n## issues.py enforcement")
+
+
+@test("create rejects empty description")
+def _():
+    """issues.py create should fail with empty --description."""
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "create",
+         "--title", "Test", "--type", "feature", "--description", ""],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert result.returncode != 0, f"Expected failure, got rc={result.returncode}"
+    assert "Description is required" in result.stderr, f"Expected error message, got: {result.stderr[:200]}"
+
+
+@test("create rejects missing description")
+def _():
+    """issues.py create should fail without --description flag."""
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "create",
+         "--title", "Test", "--type", "feature"],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert result.returncode != 0, f"Expected failure, got rc={result.returncode}"
+
+
+@test("create allows --triage without description")
+def _():
+    """issues.py create with --triage should not fail on empty description."""
+    # This would succeed only if we have API access, so just check the
+    # enforcement bypass by testing the error message doesn't say "Description is required"
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "create",
+         "--title", "Quick test", "--type", "bug", "--triage"],
+        capture_output=True, text=True, timeout=10,
+    )
+    # It may fail for other reasons (no API), but NOT for missing description
+    assert "Description is required" not in result.stderr, \
+        f"--triage should bypass description check, got: {result.stderr[:200]}"
+
+
+@test("transition rejects empty comment")
+def _():
+    """issues.py transition should reject whitespace-only comment."""
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "transition",
+         "FLY-999", "REVIEW", "   "],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert result.returncode != 0, f"Expected failure, got rc={result.returncode}"
+    assert "comment cannot be empty" in result.stderr, f"Got: {result.stderr[:200]}"
+
+
+# ---------------------------------------------------------------------------
+# auto-approve.py enforcement tests
+# ---------------------------------------------------------------------------
+
+print("\n## auto-approve.py enforcement")
+
+
+@test("should_approve matches workflow scripts")
+def _():
+    # Import the function directly
+    sys.path.insert(0, str(HOOKS_DIR))
+    # We need to import carefully since it's a hook script
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert mod.should_approve("python3 .claude/skills/flydocs-workflow/scripts/issues.py create --title test")
+    assert mod.should_approve("python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate")
+    assert not mod.should_approve("python3 malicious.py")
+    assert not mod.should_approve("rm -rf /")
+
+
+@test("validate_create_args warns on missing description")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    warnings = mod.validate_create_args(
+        'python3 .claude/skills/flydocs-workflow/scripts/issues.py create --title "test" --type feature'
+    )
+    assert len(warnings) > 0, "Should warn about missing --description"
+    assert any("description" in w.lower() for w in warnings)
+
+
+@test("validate_create_args no warning when description present")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    warnings = mod.validate_create_args(
+        'python3 .claude/skills/flydocs-workflow/scripts/issues.py create --title "test" --type feature --description "Full description here with enough content"'
+    )
+    desc_warnings = [w for w in warnings if "Missing --description" in w]
+    assert len(desc_warnings) == 0, f"Should not warn when description present, got: {warnings}"
+
+
+@test("get_transition_comment_hint returns template for known status")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    hint = mod.get_transition_comment_hint("issues.py transition FLY-123 IMPLEMENTING")
+    assert hint is not None, "Should return hint for IMPLEMENTING"
+    assert "Starting implementation" in hint
+
+
+@test("get_transition_comment_hint returns None for non-transition")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    hint = mod.get_transition_comment_hint("issues.py list --status BACKLOG")
+    assert hint is None, "Should return None for non-transition commands"
+
+
+# ---------------------------------------------------------------------------
+# Transition validation tests
+# ---------------------------------------------------------------------------
+
+print("\n## Transition validation")
+
+
+@test("VALID_TRANSITIONS allows IMPLEMENTING -> REVIEW")
+def _():
+    # Test the transition map directly from issues.py
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("issues", SCRIPT_DIR / "issues.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert "REVIEW" in mod.VALID_TRANSITIONS["IMPLEMENTING"]
+    assert "BLOCKED" in mod.VALID_TRANSITIONS["IMPLEMENTING"]
+
+
+@test("VALID_TRANSITIONS blocks BACKLOG -> REVIEW")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("issues", SCRIPT_DIR / "issues.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert "REVIEW" not in mod.VALID_TRANSITIONS["BACKLOG"]
+
+
+@test("VALID_TRANSITIONS blocks READY -> REVIEW")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("issues", SCRIPT_DIR / "issues.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert "REVIEW" not in mod.VALID_TRANSITIONS["READY"]
+
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+print(f"\n{'='*50}")
+print(f"Results: {passed} passed, {failed} failed, {passed + failed} total")
+if failed > 0:
+    sys.exit(1)