methodology-framework 0.1.0__py3-none-any.whl

methodology_framework/__init__.py

@@ -0,0 +1,17 @@
+"""methodology-framework — portable process tooling for agent-driven delivery."""
+
+__version__ = "0.1.0"
+
+from methodology_framework import (
+    bootstrap_jira,
+    build_playbook,
+    register_playbook_with_devin,
+    sync_stories_to_jira,
+)
+
+__all__ = [
+    "bootstrap_jira",
+    "build_playbook",
+    "register_playbook_with_devin",
+    "sync_stories_to_jira",
+]

methodology_framework/__main__.py

@@ -0,0 +1,28 @@
+"""Entry point for ``python -m methodology_framework <subcommand>``."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    """Route subcommands to their implementations."""
+    if len(sys.argv) < 2:
+        print("Usage: python -m methodology_framework <subcommand>", file=sys.stderr)
+        print("Available subcommands: bootstrap-jira", file=sys.stderr)
+        sys.exit(1)
+
+    subcommand = sys.argv[1]
+
+    if subcommand == "bootstrap-jira":
+        from methodology_framework.bootstrap_jira import main as bootstrap_main
+
+        sys.exit(bootstrap_main(sys.argv[2:]))
+    else:
+        print(f"Unknown subcommand: {subcommand}", file=sys.stderr)
+        print("Available subcommands: bootstrap-jira", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

methodology_framework/bootstrap_jira.py

@@ -0,0 +1,427 @@
+"""Bootstrap a Jira project with the methodology-framework's canonical shape.
+
+CLI entry point: ``python -m methodology_framework bootstrap-jira``
+
+Three operating modes:
+  --dry-run  (default)  Print what would be applied; no side-effects.
+  --apply               POST/PUT to Jira admin API (needs JIRA_ADMIN_TOKEN).
+  --export <path>       Emit an importable config bundle at <path>; no API calls.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.resources
+import logging
+import os
+import re
+import sys
+from typing import Any
+
+import requests
+import yaml
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Shape-def loading
+# ---------------------------------------------------------------------------
+
+_SHAPE_FILES = ("workflow.yaml", "custom_fields.yaml", "automation_rules.yaml")
+
+
+def _load_shape_file(name: str) -> dict[str, Any]:
+    """Load a YAML shape-def from package data and return as a dict."""
+    ref = importlib.resources.files("methodology_framework") / "jira_shapes" / name
+    text = ref.read_text(encoding="utf-8")
+    data: dict[str, Any] = yaml.safe_load(text)
+    return data
+
+
+def load_all_shapes() -> dict[str, dict[str, Any]]:
+    """Load all three shape-def files and return keyed by stem name."""
+    result: dict[str, dict[str, Any]] = {}
+    for name in _SHAPE_FILES:
+        stem = name.removesuffix(".yaml")
+        result[stem] = _load_shape_file(name)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# {{PROJECT_KEY}} substitution
+# ---------------------------------------------------------------------------
+
+_PLACEHOLDER_RE = re.compile(r"\{\{PROJECT_KEY\}\}")
+
+
+def substitute_project_key(
+    shapes: dict[str, dict[str, Any]], project_key: str
+) -> dict[str, dict[str, Any]]:
+    """Deep-substitute ``{{PROJECT_KEY}}`` with *project_key* in all shapes."""
+
+    def _walk(obj: Any) -> Any:
+        if isinstance(obj, str):
+            return _PLACEHOLDER_RE.sub(project_key, obj)
+        if isinstance(obj, dict):
+            return {k: _walk(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [_walk(item) for item in obj]
+        return obj
+
+    substituted: dict[str, dict[str, Any]] = {}
+    for key, val in shapes.items():
+        walked = _walk(val)
+        assert isinstance(walked, dict)
+        substituted[key] = walked
+    return substituted
+
+
+# ---------------------------------------------------------------------------
+# JiraAdminClient — thin wrapper for Jira Cloud REST API v3
+# ---------------------------------------------------------------------------
+
+
+class JiraAdminClient:
+    """Minimal Jira Cloud admin client for bootstrap operations."""
+
+    def __init__(self, jira_host: str, token: str) -> None:
+        self._base = f"https://{jira_host}/rest/api/3"
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        )
+
+    # -- connectivity check --------------------------------------------------
+
+    def check_connectivity(self) -> None:
+        """Validate reachability via GET /rest/api/3/myself."""
+        resp = self._session.get(f"{self._base}/myself")
+        resp.raise_for_status()
+        logger.info("Connected as %s", resp.json().get("displayName", "unknown"))
+
+    # -- workflow operations -------------------------------------------------
+
+    def get_statuses(self, project_key: str) -> list[dict[str, Any]]:
+        """Return the current statuses for *project_key*."""
+        resp = self._session.get(f"{self._base}/project/{project_key}/statuses")
+        resp.raise_for_status()
+        raw: list[dict[str, Any]] = resp.json()
+        statuses: list[dict[str, Any]] = []
+        for issue_type in raw:
+            for s in issue_type.get("statuses", []):
+                if not any(existing["id"] == s["id"] for existing in statuses):
+                    statuses.append(s)
+        return statuses
+
+    def create_status(self, spec: dict[str, Any]) -> None:
+        """Create a workflow status from *spec*."""
+        resp = self._session.post(f"{self._base}/statuses", json=spec)
+        resp.raise_for_status()
+
+    # -- custom field operations ---------------------------------------------
+
+    def get_fields(self) -> list[dict[str, Any]]:
+        """Return all fields (system + custom)."""
+        resp = self._session.get(f"{self._base}/field")
+        resp.raise_for_status()
+        result: list[dict[str, Any]] = resp.json()
+        return result
+
+    def create_custom_field(self, spec: dict[str, Any]) -> dict[str, Any]:
+        """Create a custom field from *spec*."""
+        resp = self._session.post(f"{self._base}/field", json=spec)
+        resp.raise_for_status()
+        result: dict[str, Any] = resp.json()
+        return result
+
+    # -- automation rule operations ------------------------------------------
+
+    def get_automation_rules(self, project_key: str) -> list[dict[str, Any]]:
+        """Return automation rules for *project_key*."""
+        resp = self._session.get(f"{self._base}/project/{project_key}/automation/rule")
+        if resp.status_code == 404:
+            logger.warning(
+                "Automation rules API not available (404). "
+                "Use --export mode and import rules via the Jira admin UI."
+            )
+            return []
+        resp.raise_for_status()
+        result: list[dict[str, Any]] = resp.json()
+        return result
+
+    def create_automation_rule(self, project_key: str, spec: dict[str, Any]) -> dict[str, Any]:
+        """Create an automation rule from *spec*."""
+        resp = self._session.post(
+            f"{self._base}/project/{project_key}/automation/rule",
+            json=spec,
+        )
+        resp.raise_for_status()
+        result: dict[str, Any] = resp.json()
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Diff / display helpers
+# ---------------------------------------------------------------------------
+
+
+def _format_diff(shapes: dict[str, dict[str, Any]]) -> str:
+    """Return a human-readable summary of the shape definitions."""
+    lines: list[str] = []
+    workflow = shapes.get("workflow", {})
+    for status in workflow.get("statuses", []):
+        name = status.get("name", "?")
+        desc = status.get("description", "").strip().split("\n")[0]
+        transitions = status.get("transitions", [])
+        lines.append(f"  + Status: {name}")
+        lines.append(f"    {desc}")
+        for t in transitions:
+            actors = ", ".join(t.get("allowed_actors", []))
+            lines.append(f"      -> {t['target']} (actors: {actors})")
+    lines.append("")
+
+    custom_fields = shapes.get("custom_fields", {})
+    for field in custom_fields.get("custom_fields", []):
+        name = field.get("name", "?")
+        ftype = field.get("type", "?")
+        lines.append(f"  + Custom field: {name} (type: {ftype})")
+    lines.append("")
+
+    automation = shapes.get("automation_rules", {})
+    for rule in automation.get("automation_rules", []):
+        name = rule.get("name", "?")
+        lines.append(f"  + Automation rule: {name}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Mode handlers
+# ---------------------------------------------------------------------------
+
+
+def _handle_dry_run(shapes: dict[str, dict[str, Any]]) -> int:
+    """Print what would be applied; no side-effects."""
+    print("=== Methodology Framework — Jira Bootstrap (dry-run) ===\n")
+    print("The following Jira shape would be applied:\n")
+    print("[Workflow statuses + transitions]")
+    print(_format_diff(shapes))
+    print("[Custom fields]")
+    for field in shapes.get("custom_fields", {}).get("custom_fields", []):
+        print(f"  {field['name']} ({field['type']}): {field.get('description', '')[:80]}")
+    print()
+    print("[Automation rules]")
+    for rule in shapes.get("automation_rules", {}).get("automation_rules", []):
+        print(f"  {rule['name']}: {rule.get('description', '')[:80]}")
+    print("\nNo changes applied (dry-run mode).")
+    return 0
+
+
+def _handle_export(shapes: dict[str, dict[str, Any]], export_path: str) -> int:
+    """Emit an importable config bundle at *export_path*."""
+    bundle = {
+        "schema_version": "1.0",
+        "description": "Jira project bootstrap bundle generated by methodology-framework.",
+        "workflow": shapes.get("workflow", {}),
+        "custom_fields": shapes.get("custom_fields", {}),
+        "automation_rules": shapes.get("automation_rules", {}),
+    }
+    with open(export_path, "w", encoding="utf-8") as fh:
+        yaml.dump(bundle, fh, default_flow_style=False, sort_keys=False, allow_unicode=True)
+    print(export_path)
+    return 0
+
+
+def _handle_apply(
+    shapes: dict[str, dict[str, Any]],
+    project_key: str,
+    jira_host: str,
+    token: str,
+    force: bool = False,
+) -> int:
+    """Apply the shape definitions to a Jira project via the admin API."""
+    client = JiraAdminClient(jira_host, token)
+
+    logger.info("Validating connectivity to %s ...", jira_host)
+    try:
+        client.check_connectivity()
+    except requests.HTTPError as exc:
+        logger.error("Connectivity check failed: %s", exc)
+        return 1
+
+    # -- statuses -----------------------------------------------------------
+    logger.info("Checking workflow statuses ...")
+    existing_statuses = client.get_statuses(project_key)
+    existing_names = {s.get("name", "").lower() for s in existing_statuses}
+    desired = shapes.get("workflow", {}).get("statuses", [])
+    statuses_created = 0
+    for status_spec in desired:
+        if status_spec["name"].lower() in existing_names:
+            logger.info("  Status '%s' already exists — skipping.", status_spec["name"])
+        else:
+            if not force:
+                answer = input(f"  Create status '{status_spec['name']}'? [y/N] ").strip().lower()
+                if answer != "y":
+                    logger.info("  Skipped '%s'.", status_spec["name"])
+                    continue
+            logger.info("  Creating status '%s' ...", status_spec["name"])
+            client.create_status(
+                {"name": status_spec["name"], "description": status_spec.get("description", "")}
+            )
+            statuses_created += 1
+
+    # -- custom fields ------------------------------------------------------
+    logger.info("Checking custom fields ...")
+    existing_fields = client.get_fields()
+    existing_field_names = {f.get("name", "").lower() for f in existing_fields}
+    desired_fields = shapes.get("custom_fields", {}).get("custom_fields", [])
+    fields_created = 0
+    for field_spec in desired_fields:
+        if field_spec["name"].lower() in existing_field_names:
+            logger.info("  Field '%s' already exists — skipping.", field_spec["name"])
+        else:
+            if not force:
+                answer = (
+                    input(f"  Create custom field '{field_spec['name']}'? [y/N] ").strip().lower()
+                )
+                if answer != "y":
+                    logger.info("  Skipped '%s'.", field_spec["name"])
+                    continue
+            logger.info("  Creating field '%s' ...", field_spec["name"])
+            client.create_custom_field(
+                {
+                    "name": field_spec["name"],
+                    "type": field_spec.get("type", "string"),
+                    "description": field_spec.get("description", ""),
+                }
+            )
+            fields_created += 1
+
+    # -- automation rules ---------------------------------------------------
+    logger.info("Checking automation rules ...")
+    existing_rules = client.get_automation_rules(project_key)
+    existing_rule_names = {r.get("name", "").lower() for r in existing_rules}
+    desired_rules = shapes.get("automation_rules", {}).get("automation_rules", [])
+    rules_created = 0
+    for rule_spec in desired_rules:
+        if rule_spec["name"].lower() in existing_rule_names:
+            logger.info("  Rule '%s' already exists — skipping.", rule_spec["name"])
+        else:
+            if not force:
+                answer = (
+                    input(f"  Create automation rule '{rule_spec['name']}'? [y/N] ")
+                    .strip()
+                    .lower()
+                )
+                if answer != "y":
+                    logger.info("  Skipped '%s'.", rule_spec["name"])
+                    continue
+            logger.info("  Creating rule '%s' ...", rule_spec["name"])
+            client.create_automation_rule(project_key, rule_spec)
+            rules_created += 1
+
+    logger.info(
+        "Apply complete: %d statuses, %d fields, %d rules created.",
+        statuses_created,
+        fields_created,
+        rules_created,
+    )
+    if statuses_created == 0 and fields_created == 0 and rules_created == 0:
+        logger.info("Already up to date.")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser for ``bootstrap-jira``."""
+    parser = argparse.ArgumentParser(
+        prog="bootstrap-jira",
+        description="Bootstrap a Jira project with methodology-framework's canonical shape.",
+    )
+    parser.add_argument(
+        "--project-key",
+        required=True,
+        help="Jira project key (e.g. SCRUM). Used for {{PROJECT_KEY}} substitution.",
+    )
+    parser.add_argument(
+        "--jira-host",
+        required=True,
+        help="Jira Cloud host (e.g. myorg.atlassian.net). No https:// prefix.",
+    )
+
+    mode_group = parser.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="Print what would be applied; no side-effects (default).",
+    )
+    mode_group.add_argument(
+        "--apply",
+        action="store_true",
+        default=False,
+        help="Apply shape defs to the Jira project via admin API.",
+    )
+    mode_group.add_argument(
+        "--export",
+        metavar="PATH",
+        default=None,
+        help="Emit an importable config bundle at PATH; no API calls.",
+    )
+
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        default=False,
+        help="Skip confirmation prompts during --apply.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point. Returns exit code."""
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # Load and substitute shape defs
+    try:
+        shapes = load_all_shapes()
+    except (yaml.YAMLError, FileNotFoundError) as exc:
+        logger.error("Failed to load shape definitions: %s", exc)
+        return 1
+
+    shapes = substitute_project_key(shapes, args.project_key)
+
+    # Determine mode (default to dry-run)
+    if args.apply:
+        token = os.environ.get("JIRA_ADMIN_TOKEN", "")
+        if not token:
+            logger.error(
+                "JIRA_ADMIN_TOKEN env var required for --apply mode. "
+                "Set it to a Jira admin API token or OAuth Bearer token."
+            )
+            return 1
+        return _handle_apply(
+            shapes,
+            project_key=args.project_key,
+            jira_host=args.jira_host,
+            token=token,
+            force=args.force,
+        )
+    elif args.export is not None:
+        return _handle_export(shapes, args.export)
+    else:
+        return _handle_dry_run(shapes)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

methodology_framework/build_playbook.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Build a concrete, project-bound playbook from the parameterized body + bindings.
+
+Reads the parameterized playbook body from methodology/playbooks/scrum-router.body.md
+and substitutes {{PLACEHOLDER}} tokens with the project-specific bindings defined in
+docs/jira-pickup-config.md § 5.1 (the playbook_bindings YAML block).
+
+The '## Variables required' section is preserved verbatim so placeholder
+documentation remains legible in the rendered output.  The frontmatter
+``version:`` value is injected as the ``{{VERSION}}`` binding automatically.
+
+Usage:
+    python scripts/build_playbook.py [--output PATH] [--check]
+
+Options:
+    --output PATH   Write the built playbook to PATH (default: stdout).
+    --check         Validate only: exit 0 if no unreplaced tokens, exit 1 otherwise.
+                    Does not write output.
+
+The script is designed to be run from the repo root. It uses relative paths to locate
+the body and bindings files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+BODY_PATH = REPO_ROOT / "methodology" / "playbooks" / "scrum-router.body.md"
+CONFIG_PATH = REPO_ROOT / "docs" / "jira-pickup-config.md"
+
+PLACEHOLDER_RE = re.compile(r"\{\{(\w+)\}\}")
+VARS_SECTION_RE = re.compile(
+    r"(^## Variables required$\n.*?)(?=^## |\Z)",
+    re.MULTILINE | re.DOTALL,
+)
+FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
+
+
+def extract_bindings(config_text: str) -> dict[str, str]:
+    """Extract playbook_bindings from the config doc's YAML code block."""
+    in_block = False
+    bindings: dict[str, str] = {}
+    for line in config_text.splitlines():
+        if line.strip() == "playbook_bindings:":
+            in_block = True
+            continue
+        if in_block:
+            if line.strip() == "```" or (not line.startswith(" ") and line.strip()):
+                break
+            match = re.match(r'\s+(\w+):\s*"([^"]*)"', line)
+            if match:
+                bindings[match.group(1)] = match.group(2)
+    return bindings
+
+
+def extract_version(body: str) -> str:
+    """Extract the ``version:`` value from the body's YAML frontmatter."""
+    fm_match = FRONTMATTER_RE.match(body)
+    if not fm_match:
+        return ""
+    for line in fm_match.group(1).splitlines():
+        stripped = line.strip()
+        if stripped.startswith("version:"):
+            return stripped.split(":", 1)[1].strip().strip('"').strip("'")
+    return ""
+
+
+def substitute(body: str, bindings: dict[str, str]) -> str:
+    """Replace all {{PLACEHOLDER}} tokens with their bound values.
+
+    The ``## Variables required`` section is excluded from substitution so
+    that the placeholder-documentation table remains legible in the rendered
+    output.
+    """
+
+    def replacer(m: re.Match[str]) -> str:
+        key = m.group(1)
+        if key in bindings:
+            return bindings[key]
+        return m.group(0)
+
+    preserved_sections: list[tuple[int, int, str]] = []
+    for sec_match in VARS_SECTION_RE.finditer(body):
+        preserved_sections.append((sec_match.start(), sec_match.end(), sec_match.group(0)))
+
+    if not preserved_sections:
+        return PLACEHOLDER_RE.sub(replacer, body)
+
+    parts: list[str] = []
+    prev_end = 0
+    for start, end, original in preserved_sections:
+        parts.append(PLACEHOLDER_RE.sub(replacer, body[prev_end:start]))
+        parts.append(original)
+        prev_end = end
+    parts.append(PLACEHOLDER_RE.sub(replacer, body[prev_end:]))
+    return "".join(parts)
+
+
+def find_unreplaced(text: str) -> list[str]:
+    """Return a list of any remaining {{PLACEHOLDER}} tokens.
+
+    Tokens inside the preserved ``## Variables required`` section are
+    expected and excluded from the check.
+    """
+    stripped = VARS_SECTION_RE.sub("", text)
+    return PLACEHOLDER_RE.findall(stripped)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        help="Write built playbook to this path (default: stdout)",
+    )
+    parser.add_argument(
+        "--check", action="store_true", help="Validate only; exit 1 if unreplaced tokens remain"
+    )
+    args = parser.parse_args()
+
+    if not BODY_PATH.exists():
+        print(f"ERROR: Body file not found: {BODY_PATH}", file=sys.stderr)
+        return 1
+
+    if not CONFIG_PATH.exists():
+        print(f"ERROR: Config file not found: {CONFIG_PATH}", file=sys.stderr)
+        return 1
+
+    body = BODY_PATH.read_text()
+    config = CONFIG_PATH.read_text()
+
+    bindings = extract_bindings(config)
+    if not bindings:
+        print("ERROR: No playbook_bindings found in config doc.", file=sys.stderr)
+        return 1
+
+    version = extract_version(body)
+    if version:
+        bindings["VERSION"] = version
+        print(f"Version from frontmatter: {version}", file=sys.stderr)
+    else:
+        print("WARNING: No version found in body frontmatter.", file=sys.stderr)
+
+    print(f"Bindings loaded: {bindings}", file=sys.stderr)
+
+    result = substitute(body, bindings)
+
+    unreplaced = find_unreplaced(result)
+    if unreplaced:
+        print(f"ERROR: Unreplaced tokens: {unreplaced}", file=sys.stderr)
+        return 1
+
+    if args.check:
+        print("OK: All tokens substituted.", file=sys.stderr)
+        return 0
+
+    if args.output:
+        Path(args.output).write_text(result)
+        print(f"Built playbook written to: {args.output}", file=sys.stderr)
+    else:
+        sys.stdout.write(result)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())