ai-dev-workflow 0.1.0__py3-none-any.whl

composite_work_item.py

@@ -0,0 +1,62 @@
+"""Composite WorkItem sync: ADO business item + GitHub execution overlay."""
+from __future__ import annotations
+
+COARSE_DEFAULT = {
+    "new": "New",
+    "brainstorming": "New",
+    "defining": "New",
+    "approval-pending": "New",
+    "approved": "Active",
+    "test-design": "Active",
+    "test-ready": "Active",
+    "implementing": "Active",
+    "code-review": "Active",
+    "verify": "Active",
+    "runtime-verify": "Active",
+    "runtime-pending": "Active",
+    "done": "Done",
+}
+
+
+def build_composite_config(
+    *,
+    ado: dict,
+    github: dict,
+    field_mapping: dict | None = None,
+    state_sync: dict | None = None,
+) -> dict:
+    return {
+        "provider": "composite",
+        "business": {
+            "provider": "azure-devops",
+            **ado,
+        },
+        "execution": {
+            "provider": "github-issues",
+            **github,
+        },
+        "sync": {
+            "state": dict(state_sync or COARSE_DEFAULT),
+            "field_mapping": field_mapping or {},
+        },
+    }
+
+
+def sync_projection(config: dict, *, wit_ref: str, phase: str, values: dict | None = None) -> dict:
+    """Return provider-neutral desired ADO mutations for an execution phase change."""
+    sync = config.get("sync", {})
+    state_map = sync.get("state", {})
+    field_mapping = sync.get("field_mapping", {})
+    state = state_map.get(phase)
+
+    updates = {}
+    values = {"workflow_phase": phase, **(values or {})}
+    for key, value in values.items():
+        mapping = (field_mapping.get(wit_ref, {}) or {}).get(key)
+        if mapping and mapping.get("field"):
+            updates[mapping["field"]] = value
+
+    return {
+        "state": state,
+        "fields": updates,
+    }

framework_update.py

@@ -0,0 +1,145 @@
+"""Safe update engine for installed ai-dev-workflow projects."""
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+
+CURRENT_SCHEMA_VERSION = 1
+DEFAULT_FRAMEWORK_SOURCE = "vuthethienlong/ai-dev-workflow"
+
+# Only these files are owned by the framework after installation.
+# AGENTS.md, CURRENT.md, project docs/config and workspace files are project-owned.
+FRAMEWORK_MANAGED_FILES = (
+    ".github/workflows/ai-workflow.yml",
+)
+
+
+def framework_metadata(config: dict) -> dict:
+    meta = config.get("framework") or {}
+    return {
+        "source": meta.get("source", DEFAULT_FRAMEWORK_SOURCE),
+        "ref": meta.get("ref", "main"),
+        "schema_version": int(meta.get("schema_version", config.get("version", 1))),
+        "update_policy": meta.get("update_policy", "manual"),
+    }
+
+
+def ensure_framework_metadata(config: dict, *, source=DEFAULT_FRAMEWORK_SOURCE, ref="main") -> dict:
+    result = deepcopy(config)
+    existing = result.get("framework") or {}
+    result["framework"] = {
+        "source": existing.get("source", source),
+        "ref": existing.get("ref", ref),
+        "schema_version": int(existing.get("schema_version", CURRENT_SCHEMA_VERSION)),
+        "update_policy": existing.get("update_policy", "manual"),
+    }
+    return result
+
+
+def migrate_config(config: dict, target_schema: int = CURRENT_SCHEMA_VERSION) -> tuple[dict, list[str]]:
+    """Run deterministic idempotent migrations without replacing project-owned sections."""
+    result = deepcopy(config)
+    meta = framework_metadata(result)
+    current = meta["schema_version"]
+    if current > target_schema:
+        raise ValueError(
+            f"config schema {current} is newer than supported schema {target_schema}"
+        )
+    migrations = []
+    # Reserved migration chain. Add explicit N -> N+1 transforms here.
+    while current < target_schema:
+        next_version = current + 1
+        migration = f"{current}-to-{next_version}"
+        raise ValueError(f"missing framework migration: {migration}")
+    result = ensure_framework_metadata(
+        result, source=meta["source"], ref=meta["ref"]
+    )
+    result["framework"]["schema_version"] = target_schema
+    return result, migrations
+
+
+def build_update_plan(
+    config: dict,
+    *,
+    target_ref: str | None = None,
+    target_source: str | None = None,
+    workflow_path: str = ".github/workflows/ai-workflow.yml",
+) -> dict:
+    meta = framework_metadata(config)
+    source = target_source or meta["source"]
+    ref = target_ref or "main"
+    return {
+        "current": meta,
+        "target": {
+            "source": source,
+            "ref": ref,
+            "schema_version": CURRENT_SCHEMA_VERSION,
+        },
+        "update_available": (
+            meta["source"] != source
+            or meta["ref"] != ref
+            or meta["schema_version"] != CURRENT_SCHEMA_VERSION
+        ),
+        "managed_files": [workflow_path],
+        "preserved": [
+            ".ai-workflow.yml custom/project sections",
+            ".ai-workspace.yml",
+            "AGENTS.md",
+            "CURRENT.md",
+            "work item mappings",
+            "ADO field defaults",
+            "AI providers",
+            "workers",
+            "project workflow overrides",
+        ],
+    }
+
+
+def apply_update(
+    config: dict,
+    *,
+    target_ref: str,
+    generated_workflow: str | None = None,
+    expected_current_workflow: str | None = None,
+    root: str | Path = ".",
+    target_source: str | None = None,
+    force: bool = False,
+) -> tuple[dict, dict]:
+    """Apply metadata/migrations and update framework-managed files only."""
+    root = Path(root)
+    migrated, migrations = migrate_config(config)
+    meta = framework_metadata(migrated)
+    source = target_source or meta["source"]
+    migrated["framework"] = {
+        **migrated.get("framework", {}),
+        "source": source,
+        "ref": target_ref,
+        "schema_version": CURRENT_SCHEMA_VERSION,
+    }
+
+    changed, skipped = [], []
+    if generated_workflow is not None:
+        path = root / ".github/workflows/ai-workflow.yml"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists():
+            current = path.read_text(encoding="utf-8")
+            relative = str(path.relative_to(root))
+            if current == generated_workflow:
+                skipped.append(relative)
+            elif expected_current_workflow is not None and current != expected_current_workflow and not force:
+                skipped.append(relative + " (locally modified; use --force)")
+            else:
+                path.write_text(generated_workflow, encoding="utf-8")
+                changed.append(relative)
+        else:
+            path.write_text(generated_workflow, encoding="utf-8")
+            changed.append(str(path.relative_to(root)))
+
+    return migrated, {
+        "migrations": migrations,
+        "changed_files": changed,
+        "skipped_files": skipped,
+        "preserved_project_files": [
+            "AGENTS.md", "CURRENT.md", ".ai-workspace.yml"
+        ],
+    }

github_work_item_provider.py

@@ -0,0 +1,134 @@
+"""GitHub Issues WorkItemProvider discovery."""
+from __future__ import annotations
+
+import json
+import re
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+
+from work_item_provider import CANONICAL_STATES
+
+
+class GitHubIssues:
+    def __init__(self, repository: str, token: str, api_url="https://api.github.com"):
+        self.repository = repository
+        self.base = api_url.rstrip("/") + "/repos/" + repository
+        self.token = token
+
+    def request(self, path: str):
+        req = Request(
+            self.base + path,
+            headers={
+                "Authorization": "Bearer " + self.token,
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+        try:
+            with urlopen(req, timeout=30) as response:
+                return json.load(response)
+        except HTTPError as exc:
+            body = exc.read().decode("utf-8", "replace")
+            raise RuntimeError(f"GitHub API {exc.code}: {body}") from exc
+
+    def labels(self):
+        return self.request("/labels?per_page=100")
+
+    def create_label(self, name: str, color: str, description: str):
+        req = Request(
+            self.base + "/labels",
+            method="POST",
+            data=json.dumps({"name": name, "color": color, "description": description}).encode(),
+            headers={
+                "Authorization": "Bearer " + self.token,
+                "Accept": "application/vnd.github+json",
+                "Content-Type": "application/json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+        try:
+            with urlopen(req, timeout=30) as response:
+                return json.load(response)
+        except HTTPError as exc:
+            body = exc.read().decode("utf-8", "replace")
+            raise RuntimeError(f"GitHub API {exc.code}: {body}") from exc
+
+    def discover(self) -> dict:
+        labels = [
+            {
+                "name": item.get("name"),
+                "description": item.get("description") or "",
+                "color": item.get("color") or "",
+            }
+            for item in self.labels()
+            if item.get("name")
+        ]
+        return {
+            "repository": self.repository,
+            "labels": sorted(labels, key=lambda x: x["name"].lower()),
+            "system_states": ["open", "closed"],
+        }
+
+
+def _normalize(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", " ", value.lower()).strip()
+
+
+def suggest_github_state(label_name: str, description: str = "") -> str | None:
+    text = _normalize(label_name + " " + description)
+    rules = (
+        ("runtime-pending", ("runtime pending", "runtime verify", "runtime verification", "awaiting runtime", "uat")),
+        ("release-pending", ("release pending", "ready release", "deploy pending")),
+        ("in-review", ("in review", "review", "qa", "validation")),
+        ("in-progress", ("in progress", "working", "doing", "active")),
+        ("blocked", ("blocked", "hold", "waiting")),
+        ("ready", ("status ready", "ready", "approved", "todo", "to do")),
+        ("completed", ("completed", "done", "closed")),
+        ("draft", ("draft", "new", "backlog")),
+    )
+    for canonical, phrases in rules:
+        if any(phrase in text for phrase in phrases):
+            return canonical
+    return None
+
+
+MANAGED_STATUS_LABELS = {
+    "status:ready": ("0E8A16", "Frozen and ready for execution"),
+    "status:in-progress": ("1D76DB", "Accepted by a real agent/provider and currently executing"),
+    "status:blocked": ("B60205", "Blocked and requires recovery or external action"),
+    "status:in-review": ("5319E7", "Implementation finished and under review"),
+    "status:runtime-pending": ("FBCA04", "Offline work done; real runtime verification still required"),
+    "status:release-pending": ("D4C5F9", "Ready for release/promotion after required gates"),
+}
+
+
+def ensure_managed_status_labels(api: GitHubIssues, discovery: dict) -> list[str]:
+    existing = {item["name"] for item in discovery.get("labels", [])}
+    created = []
+    for name, (color, description) in MANAGED_STATUS_LABELS.items():
+        if name not in existing:
+            api.create_label(name, color, description)
+            created.append(name)
+    return created
+
+
+def build_github_mapping(discovery: dict) -> dict:
+    mapping = {"@closed": "completed"}
+    for label in discovery.get("labels", []):
+        suggestion = suggest_github_state(label["name"], label.get("description", ""))
+        if suggestion is not None:
+            mapping[label["name"]] = suggestion
+    return mapping
+
+
+def validate_github_mapping(discovery: dict, mapping: dict) -> list[str]:
+    errors = []
+    known = {item["name"] for item in discovery.get("labels", [])}
+    known.add("@closed")
+    for label, canonical in mapping.items():
+        if label not in known:
+            errors.append(f"mapped GitHub label does not exist: {label}")
+        if canonical not in CANONICAL_STATES:
+            errors.append(f"invalid canonical state for GitHub label {label}: {canonical}")
+    return errors

issue_publisher.py

@@ -0,0 +1,243 @@
+"""Publish a frozen planning decision to GitHub Issue + optional Project v2."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+from pathlib import Path
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+
+REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+STATUS_READY = "status:ready"
+
+
+class GitHub:
+    def __init__(self, token: str, api_url="https://api.github.com"):
+        self.token = token
+        self.api_url = api_url.rstrip("/")
+
+    def _request(self, url, method="GET", data=None):
+        req = Request(
+            url, method=method,
+            data=json.dumps(data).encode() if data is not None else None,
+            headers={
+                "Authorization": "Bearer " + self.token,
+                "Accept": "application/vnd.github+json",
+                "Content-Type": "application/json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+        try:
+            with urlopen(req, timeout=30) as response:
+                if response.status == 204:
+                    return {}
+                return json.load(response)
+        except HTTPError as exc:
+            body = exc.read().decode("utf-8", "replace")
+            raise RuntimeError(f"GitHub API {exc.code}: {body}") from exc
+
+    def repo(self, full_name):
+        return self._request(f"{self.api_url}/repos/{full_name}")
+
+    def graphql(self, query, variables):
+        return self._request(
+            f"{self.api_url}/graphql", "POST", {"query": query, "variables": variables}
+        )
+
+    def resolve_project_v2(self, owner, number):
+        query = """
+        query($owner:String!, $number:Int!) {
+          user(login:$owner) { projectV2(number:$number) { id title } }
+          organization(login:$owner) { projectV2(number:$number) { id title } }
+        }
+        """
+        data = self.graphql(query, {"owner": owner, "number": number})
+        if data.get("errors"):
+            raise RuntimeError("GitHub Project lookup failed: " + json.dumps(data["errors"]))
+        root = data.get("data") or {}
+        for key in ("user", "organization"):
+            obj = root.get(key)
+            if obj and obj.get("projectV2"):
+                return obj["projectV2"]
+        raise RuntimeError(f"GitHub Project v2 not found: {owner}#{number}")
+
+    def add_issue_to_project(self, project_id, issue_node_id):
+        query = """
+        mutation($project:ID!, $content:ID!) {
+          addProjectV2ItemById(input:{projectId:$project, contentId:$content}) {
+            item { id }
+          }
+        }
+        """
+        data = self.graphql(query, {"project": project_id, "content": issue_node_id})
+        if data.get("errors"):
+            raise RuntimeError("GitHub Project add failed: " + json.dumps(data["errors"]))
+        return data["data"]["addProjectV2ItemById"]["item"]
+
+
+def validate_decision(context: dict, decision: dict) -> dict:
+    planning = context.get("planning_context") if "planning_context" in context else context
+    if not isinstance(planning, dict):
+        raise ValueError("planning_context is required")
+    repos = {r["repository"]: r for r in planning.get("repositories", [])}
+    target = decision.get("target_repository")
+    if target not in repos:
+        raise ValueError("target_repository is not registered in workspace")
+    if repos[target].get("access") != "read-write":
+        raise ValueError("target_repository must have read-write access")
+
+    affected = decision.get("affected_repositories", [])
+    if not isinstance(affected, list):
+        raise ValueError("affected_repositories must be a list")
+    for item in affected:
+        if not isinstance(item, dict) or item.get("repository") not in repos:
+            raise ValueError("affected repository is not registered in workspace")
+        access = item.get("access", repos[item["repository"]].get("access"))
+        if access not in ("read", "read-write"):
+            raise ValueError("invalid affected repository access")
+        if access == "read-write" and repos[item["repository"]].get("access") != "read-write":
+            raise ValueError("planning decision escalates repository access")
+
+    initiative = decision.get("initiative")
+    if initiative:
+        initiatives = planning.get("initiatives", {})
+        if initiative not in initiatives:
+            raise ValueError("unknown initiative")
+
+    project = decision.get("github_project", planning.get("github_project"))
+    if project is not None:
+        if not isinstance(project, dict) or not project.get("owner") or type(project.get("number")) is not int:
+            raise ValueError("invalid github_project")
+
+    frozen = bool(decision.get("frozen", False))
+    priority = decision.get("priority", "priority:P2")
+    if priority not in ("priority:P0", "priority:P1", "priority:P2"):
+        raise ValueError("invalid priority")
+
+    return {
+        "target_repository": target,
+        "affected_repositories": affected,
+        "github_project": project,
+        "initiative": initiative,
+        "dependencies": decision.get("dependencies", []),
+        "issue_type": decision.get("issue_type", "feature"),
+        "runtime_required": bool(decision.get("runtime_required", False)),
+        "frozen": frozen,
+        "priority": priority,
+    }
+
+
+def render_issue_body(spec: dict, normalized: dict) -> str:
+    dependencies = normalized["dependencies"] or []
+    dep_text = "\n".join(f"- {d}" for d in dependencies) if dependencies else "None"
+    runtime = "Required" if normalized["runtime_required"] else "None"
+    return f"""## Status
+{"Ready Freeze" if normalized["frozen"] else "Draft"}
+
+## Goal
+{spec["goal"]}
+
+## Context / links
+{spec.get("context", "Workspace planning context")}
+
+## Scope
+{spec.get("scope", "")}
+
+## Out of scope
+{spec.get("out_of_scope", "")}
+
+## Dependencies
+{dep_text}
+
+## Acceptance Criteria / Done When
+{spec["acceptance_criteria"]}
+
+## Verification offline
+{spec.get("verification_offline", "Project-defined")}
+
+## Runtime Verification
+{runtime}
+
+## Spec
+{spec.get("spec", "")}
+
+## ADR
+{spec.get("adr", "")}
+
+## Planning metadata
+- Initiative: {normalized.get("initiative") or "None"}
+- Issue type: {normalized["issue_type"]}
+- Affected repositories: {", ".join(x["repository"] for x in normalized["affected_repositories"]) or normalized["target_repository"]}
+"""
+
+
+def publish(api, context: dict, decision: dict, spec: dict) -> dict:
+    normalized = validate_decision(context, decision)
+
+    title = spec.get("title")
+    goal = spec.get("goal")
+    acceptance = spec.get("acceptance_criteria")
+    if not all(isinstance(v, str) and v.strip() for v in (title, goal, acceptance)):
+        raise ValueError("spec title, goal and acceptance_criteria are required")
+
+    repo = normalized["target_repository"]
+    api.repo(repo)  # fail before mutation if repository is inaccessible
+
+
+    labels = [normalized["priority"]]
+    labels.append(STATUS_READY if normalized["frozen"] else "status:blocked")
+    issue = api.create_issue(
+        repo,
+        title.strip(),
+        render_issue_body(spec, normalized),
+        labels
+    )
+
+    project_item = None
+    if normalized["github_project"]:
+        project = api.resolve_project_v2(
+            normalized["github_project"]["owner"],
+            normalized["github_project"]["number"],
+        )
+        node_id = issue.get("node_id")
+        if not node_id:
+            raise RuntimeError("created Issue did not return node_id for Project v2")
+        project_item = api.add_issue_to_project(project["id"], node_id)
+
+    return {
+        "repository": repo,
+        "issue_number": issue["number"],
+        "issue_url": issue.get("html_url"),
+        "project_item_id": project_item.get("id") if project_item else None,
+        "status": STATUS_READY if normalized["frozen"] else "draft",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--context", required=True, type=Path)
+    parser.add_argument("--decision", required=True, type=Path)
+    parser.add_argument("--spec", required=True, type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+
+    api = GitHub(os.environ["GH_TOKEN"], os.environ.get("GITHUB_API_URL", "https://api.github.com"))
+    result = publish(
+        api,
+        json.loads(args.context.read_text(encoding="utf-8")),
+        json.loads(args.decision.read_text(encoding="utf-8")),
+        json.loads(args.spec.read_text(encoding="utf-8")),
+    )
+    text = json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    if args.output:
+        args.output.write_text(text, encoding="utf-8")
+    else:
+        print(text, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())