methodology-framework 0.1.0__py3-none-any.whl

methodology_framework/populate_acus.py

@@ -0,0 +1,210 @@
+"""Scan story files for unpopulated agent_acus fields and backfill from Devin API."""
+
+from __future__ import annotations
+
+import glob
+import logging
+import re
+import sys
+from dataclasses import dataclass
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+_SESSION_URL_RE = re.compile(
+    r"agent_session_url:\s*[\"']?https://app\.devin\.ai/sessions/([a-zA-Z0-9_-]+)[\"']?"
+)
+_ACUS_PENDING_RE = re.compile(r"^(\s*)agent_acus:\s*[\"']?pending[\"']?\s*$", re.MULTILINE)
+_ACUS_NUMERIC_RE = re.compile(r"^\s*agent_acus:\s*[0-9]", re.MULTILINE)
+_ACUS_PRESENT_RE = re.compile(r"^(\s*)agent_acus:\s*\S", re.MULTILINE)
+_SESSION_URL_LINE_RE = re.compile(r"^(\s*)agent_session_url:\s*\S", re.MULTILINE)
+
+
+@dataclass
+class PopulateResult:
+    """Result of processing a single story file."""
+
+    path: str
+    session_id: str
+    acus: float
+    action: str  # "replaced" | "inserted"
+
+
+def extract_session_id(content: str) -> str | None:
+    """Extract the Devin session ID from a story file's agent_session_url field."""
+    m = _SESSION_URL_RE.search(content)
+    return m.group(1) if m else None
+
+
+def needs_population(content: str) -> bool:
+    """Return True if the file has agent_acus pending or missing (with session URL present)."""
+    if _ACUS_PENDING_RE.search(content):
+        return True
+    has_session_url = _SESSION_URL_LINE_RE.search(content)
+    has_acus = _ACUS_PRESENT_RE.search(content)
+    return bool(has_session_url) and not bool(has_acus)
+
+
+def rewrite_acus(content: str, acus_value: float) -> tuple[str, str]:
+    """Rewrite agent_acus in the content. Returns (new_content, action).
+
+    action is "replaced" if pending was replaced, "inserted" if the field was added.
+    """
+    m = _ACUS_PENDING_RE.search(content)
+    if m:
+        indent = m.group(1)
+        new_content = _ACUS_PENDING_RE.sub(f"{indent}agent_acus: {acus_value}", content)
+        return new_content, "replaced"
+
+    if _ACUS_NUMERIC_RE.search(content):
+        return content, ""
+
+    m = _SESSION_URL_LINE_RE.search(content)
+    if m:
+        indent = m.group(0).split("agent_session_url")[0]
+        line_end = content.find("\n", m.start())
+        if line_end == -1:
+            insert_pos = len(content)
+            new_content = content + f"\n{indent}agent_acus: {acus_value}"
+        else:
+            insert_pos = line_end + 1
+            new_content = (
+                content[:insert_pos] + f"{indent}agent_acus: {acus_value}\n" + content[insert_pos:]
+            )
+        return new_content, "inserted"
+
+    return content, ""
+
+
+def fetch_acus_from_devin(session_id: str, api_token: str) -> float | None:
+    """Fetch ACU consumption from Devin API for a given session ID.
+
+    Returns the ACU value or None on error.
+    # Devin API v2: GET /v2/session/{session_id} returns JSON with
+    # "total_acus" at the top level of the response object.
+    """
+    url = f"https://api.devin.ai/v2/session/{session_id}"
+    headers = {"Authorization": f"Bearer {api_token}"}
+    try:
+        resp = requests.get(url, headers=headers, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+        acus = data.get("total_acus")
+        if acus is None:
+            # Fallback: try nested under "status_enum" or "acus"
+            acus = data.get("acus")
+        if acus is not None:
+            return float(acus)
+        logger.warning(
+            "Session %s: no ACU field found in response keys: %s",
+            session_id,
+            list(data.keys()),
+        )
+        return None
+    except requests.HTTPError as exc:
+        logger.warning("Devin API error for session %s: %s", session_id, exc)
+        return None
+    except (requests.ConnectionError, requests.Timeout) as exc:
+        logger.warning("Devin API connection error for session %s: %s", session_id, exc)
+        return None
+
+
+def scan_and_populate(
+    story_path_pattern: str,
+    api_token: str,
+    *,
+    dry_run: bool = False,
+) -> list[PopulateResult]:
+    """Scan story files and populate agent_acus from Devin API.
+
+    Returns a list of PopulateResult for each file that was updated.
+    """
+    results: list[PopulateResult] = []
+    files = sorted(glob.glob(story_path_pattern, recursive=True))
+    logger.info("Scanning %d story files matching %s", len(files), story_path_pattern)
+
+    for filepath in files:
+        with open(filepath, encoding="utf-8") as f:
+            content = f.read()
+
+        if not needs_population(content):
+            continue
+
+        session_id = extract_session_id(content)
+        if not session_id:
+            logger.info("Skipping %s: no agent_session_url found", filepath)
+            continue
+
+        acus = fetch_acus_from_devin(session_id, api_token)
+        if acus is None:
+            logger.warning(
+                "Skipping %s: could not fetch ACUs for session %s",
+                filepath,
+                session_id,
+            )
+            continue
+
+        new_content, action = rewrite_acus(content, acus)
+        if not action:
+            continue
+
+        if not dry_run:
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(new_content)
+
+        results.append(
+            PopulateResult(
+                path=filepath,
+                session_id=session_id,
+                acus=acus,
+                action=action,
+            )
+        )
+        logger.info("Updated %s: agent_acus=%s (%s)", filepath, acus, action)
+
+    return results
+
+
+def main() -> int:
+    """CLI entry point for populate-acus."""
+    import argparse
+    import os
+
+    parser = argparse.ArgumentParser(
+        description="Populate agent_acus in story files from Devin API",
+    )
+    parser.add_argument(
+        "--story-path-pattern",
+        default="docs/stories/**/*.md",
+        help="Glob pattern for story files (default: docs/stories/**/*.md)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would be changed without modifying files",
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+
+    api_token = os.environ.get("DEVIN_API_TOKEN", "")
+    if not api_token:
+        logger.error("DEVIN_API_TOKEN environment variable is required")
+        return 1
+
+    results = scan_and_populate(args.story_path_pattern, api_token, dry_run=args.dry_run)
+
+    if not results:
+        print("Nothing to do — all agent_acus fields already populated.")
+        return 0
+
+    print(f"\nPopulated agent_acus for {len(results)} story file(s):")
+    for r in results:
+        print(f"  {r.path}: {r.acus} ({r.action})")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

methodology_framework/register_playbook_with_devin.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""Register a rendered playbook with Devin's API and verify the registration.
+
+Usage:
+    python scripts/register_playbook_with_devin.py \
+        --playbook-id scrum-router \
+        --rendered-body /path/to/rendered.md \
+        --macro '!scrum_pickup'
+
+The --playbook-id value must match the ``playbook_id`` field in the source
+body's YAML frontmatter.  It is used as the lookup slug against Devin's API.
+
+Environment:
+    DEVIN_API_TOKEN   Devin API key (cog_ prefix). Required.
+
+Exit codes:
+    0  Registration succeeded and smoke-verify passed.
+    1  Any failure (auth, API error, SHA256 mismatch, playbook not found).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from typing import Any
+
+MACRO_PATTERN = re.compile(r"^![A-Za-z0-9_]+$")
+
+DEVIN_API_BASE = "https://api.devin.ai/v1"
+
+
+def _request(
+    method: str,
+    path: str,
+    token: str,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Make an authenticated request to the Devin API."""
+    url = f"{DEVIN_API_BASE}{path}"
+    body = json.dumps(data).encode("utf-8") if data else None
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        method=method,
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            result: dict[str, Any] = json.loads(resp.read().decode("utf-8"))
+            return result
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8", errors="replace")
+        print(
+            f"ERROR: Devin API {method} {path} returned {e.code}: {error_body}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def sha256hex(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def list_playbooks(token: str) -> list[dict[str, Any]]:
+    """List all playbooks accessible to the token's org."""
+    resp: Any = _request("GET", "/playbooks", token)
+    # v1 returns {"playbooks": [...]} or a bare list
+    if isinstance(resp, list):
+        return resp
+    items: list[dict[str, Any]] = resp.get("playbooks", resp.get("data", []))
+    return items
+
+
+def find_playbook_by_name(playbooks: list[dict[str, Any]], name: str) -> dict[str, Any] | None:
+    """Find a playbook by its display name (exact match)."""
+    for p in playbooks:
+        pname = p.get("name") or p.get("title") or ""
+        if pname == name:
+            return p
+    return None
+
+
+def _build_payload(title: str, content: str, macro: str | None = None) -> dict[str, Any]:
+    """Build the JSON payload for CREATE or UPDATE requests.
+
+    Centralizes field-name choices (REST uses 'body', not 'content').
+    Includes 'macro' only when a value is provided.
+    """
+    payload: dict[str, Any] = {"title": title, "body": content}
+    if macro is not None:
+        payload["macro"] = macro
+    return payload
+
+
+def update_playbook(
+    token: str, playbook_id: str, title: str, content: str, macro: str | None = None
+) -> dict[str, Any]:
+    """Update a playbook's title and content (full replace)."""
+    payload = _build_payload(title, content, macro)
+    return _request("PUT", f"/playbooks/{playbook_id}", token, payload)
+
+
+def get_playbook(token: str, playbook_id: str) -> dict[str, Any]:
+    """Read back a playbook by ID."""
+    return _request("GET", f"/playbooks/{playbook_id}", token)
+
+
+def create_playbook(
+    token: str, slug: str, title: str, content: str, macro: str | None = None
+) -> dict[str, Any]:
+    """Create a new playbook with the given slug, title, and content."""
+    payload = _build_payload(title, content, macro)
+    payload["playbook_id"] = slug
+    return _request("POST", "/playbooks", token, payload)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--playbook-id",
+        required=True,
+        help="Playbook slug (from source body frontmatter playbook_id:).",
+    )
+    parser.add_argument(
+        "--playbook-name",
+        default=None,
+        help="Display name / title (used only when creating a new playbook).",
+    )
+    parser.add_argument(
+        "--rendered-body",
+        required=True,
+        help="Path to the rendered playbook markdown file.",
+    )
+    parser.add_argument(
+        "--macro",
+        default=None,
+        help=(
+            "Macro trigger name (e.g. '!scrum_pickup'). "
+            "Included in CREATE/UPDATE payloads when provided."
+        ),
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List playbooks and show what would be updated, but don't write.",
+    )
+    args = parser.parse_args()
+
+    if args.macro is not None and not MACRO_PATTERN.match(args.macro):
+        print(
+            f"ERROR: --macro value must start with '!' followed by word characters "
+            f"(letters, digits, underscores). Got: {args.macro!r}",
+            file=sys.stderr,
+        )
+        return 1
+
+    token = os.environ.get("DEVIN_API_TOKEN", "")
+    if not token:
+        print("ERROR: DEVIN_API_TOKEN environment variable is not set.", file=sys.stderr)
+        return 1
+
+    rendered_path = args.rendered_body
+    try:
+        rendered_content = open(rendered_path, encoding="utf-8").read()
+    except FileNotFoundError:
+        print(f"ERROR: Rendered body file not found: {rendered_path}", file=sys.stderr)
+        return 1
+
+    rendered_sha = sha256hex(rendered_content)
+    print(f"Rendered body SHA256: {rendered_sha}", file=sys.stderr)
+    print(f"Rendered body length: {len(rendered_content)} chars", file=sys.stderr)
+
+    slug: str = args.playbook_id
+    name: str = args.playbook_name or slug
+
+    # Step 1: List playbooks and find the target by name
+    print("Listing playbooks...", file=sys.stderr)
+    playbooks = list_playbooks(token)
+    names = [p.get("name") or p.get("title") or "?" for p in playbooks]
+    print(f"Found {len(playbooks)} playbook(s); available names: {names}", file=sys.stderr)
+
+    matches = [p for p in playbooks if (p.get("name") or p.get("title")) == name]
+    if len(matches) >= 2:
+        ids = [p.get("id") or p.get("playbook_id") for p in matches]
+        print(
+            f"ERROR: Multiple playbooks found with name '{name}': "
+            f"{', '.join(str(i) for i in ids)}.\n"
+            f"Operator action required: delete duplicates in Devin's webapp, "
+            f"leaving exactly one '{name}' playbook. Then re-run.",
+            file=sys.stderr,
+        )
+        return 1
+    target = matches[0] if matches else None
+
+    if target is None:
+        print(
+            f"No existing playbook with name '{name}'. Creating new playbook...",
+            file=sys.stderr,
+        )
+        if args.dry_run:
+            print("DRY RUN — would create new playbook.", file=sys.stderr)
+            return 0
+        created = create_playbook(token, slug, name, rendered_content, args.macro)
+        created_id: str = created.get("playbook_id") or created.get("id") or ""
+        print(f"Created playbook: id={created_id}, title={name}", file=sys.stderr)
+
+        # Smoke-verify the creation
+        print("Smoke-verifying creation...", file=sys.stderr)
+        readback = get_playbook(token, created_id)
+        readback_content = readback.get("content") or readback.get("body") or ""
+        readback_sha = sha256hex(readback_content)
+        if readback_sha != rendered_sha:
+            print(
+                f"ERROR: Smoke-verify FAILED. "
+                f"Rendered SHA256: {rendered_sha}, "
+                f"Read-back SHA256: {readback_sha}",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"Smoke-verify PASSED. SHA256 match: {rendered_sha}", file=sys.stderr)
+        return 0
+
+    playbook_id: str = target.get("playbook_id") or target.get("id") or ""
+    playbook_title: str = target.get("title") or target.get("name") or name
+    if not playbook_id:
+        print("ERROR: Could not determine playbook ID from API response.", file=sys.stderr)
+        return 1
+    print(
+        f"Found playbook: id={playbook_id}, title={playbook_title}; matched '{name}'; updating...",
+        file=sys.stderr,
+    )
+
+    if args.dry_run:
+        print("DRY RUN — skipping update and verify.", file=sys.stderr)
+        return 0
+
+    # Step 2: Check if content or macro has changed
+    existing_content: str = target.get("content") or target.get("body") or ""
+    existing_sha = sha256hex(existing_content)
+    existing_macro: str | None = target.get("macro")
+    body_matches = existing_sha == rendered_sha
+    macro_matches = existing_macro == args.macro
+    if body_matches and macro_matches:
+        print(
+            "Registered body already matches rendered output (SHA256 identical) "
+            "and macro is in sync. Skipping registration.",
+            file=sys.stderr,
+        )
+        return 0
+
+    reasons: list[str] = []
+    if not body_matches:
+        reasons.append(f"content differs (existing SHA256: {existing_sha})")
+    if not macro_matches:
+        reasons.append(f"macro differs (existing: {existing_macro!r}, target: {args.macro!r})")
+    print(f"Update needed: {'; '.join(reasons)}. Updating...", file=sys.stderr)
+
+    # Step 3: Update the playbook
+    update_playbook(token, playbook_id, playbook_title, rendered_content, args.macro)
+    print("Playbook updated successfully.", file=sys.stderr)
+
+    # Step 4: Smoke-verify — read back and compare SHA256
+    print("Smoke-verifying registration...", file=sys.stderr)
+    readback = get_playbook(token, playbook_id)
+    readback_content = readback.get("content") or readback.get("body") or ""
+    readback_sha = sha256hex(readback_content)
+
+    if readback_sha != rendered_sha:
+        print(
+            f"ERROR: Smoke-verify FAILED. "
+            f"Rendered SHA256: {rendered_sha}, "
+            f"Read-back SHA256: {readback_sha}",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"Smoke-verify PASSED. SHA256 match: {rendered_sha}",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())