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

planning_context.py

@@ -0,0 +1,151 @@
+"""Normalize and validate provider-neutral workspace planning context."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - CLI dependency error
+    yaml = None
+
+REPOSITORY = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+REF = re.compile(r"^[A-Za-z0-9._/-]+$")
+ACCESS = {"read", "read-write"}
+
+
+def _text(value, field):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field} must be a non-empty string")
+    return value.strip()
+
+
+def normalize_workspace(raw: dict) -> dict:
+    if not isinstance(raw, dict) or raw.get("version") != 1:
+        raise ValueError("workspace version must be 1")
+
+    workspace = raw.get("workspace")
+    if not isinstance(workspace, dict):
+        raise ValueError("workspace section is required")
+    workspace_name = _text(workspace.get("name"), "workspace.name")
+
+    project = raw.get("github_project")
+    normalized_project = None
+    if project is not None:
+        if not isinstance(project, dict):
+            raise ValueError("github_project must be an object")
+        owner = _text(project.get("owner"), "github_project.owner")
+        number = project.get("number")
+        if type(number) is not int or number < 1:
+            raise ValueError("github_project.number must be a positive integer")
+        normalized_project = {"owner": owner, "number": number}
+
+    repos = raw.get("repositories")
+    if not isinstance(repos, list) or not repos:
+        raise ValueError("repositories must be a non-empty list")
+
+    seen = set()
+    normalized_repos = []
+    for index, item in enumerate(repos):
+        if not isinstance(item, dict):
+            raise ValueError(f"repositories[{index}] must be an object")
+        repository = _text(item.get("repository"), f"repositories[{index}].repository")
+        if not REPOSITORY.fullmatch(repository):
+            raise ValueError(f"invalid repository: {repository}")
+        if repository in seen:
+            raise ValueError(f"duplicate repository: {repository}")
+        seen.add(repository)
+
+        purpose = _text(item.get("purpose"), f"repositories[{index}].purpose")
+        ref = _text(item.get("ref", "main"), f"repositories[{index}].ref")
+        if not REF.fullmatch(ref) or ".." in ref or ref.startswith("/") or ref.endswith("/"):
+            raise ValueError(f"invalid ref for {repository}: {ref}")
+        access = item.get("access", "read")
+        if access not in ACCESS:
+            raise ValueError(f"invalid access for {repository}: {access}")
+        context = item.get("context", [])
+        if not isinstance(context, list) or any(not isinstance(p, str) or not p.strip() for p in context):
+            raise ValueError(f"context for {repository} must be a list of non-empty paths")
+        normalized_repos.append({
+            "repository": repository,
+            "purpose": purpose,
+            "ref": ref,
+            "access": access,
+            "context": [p.strip() for p in context],
+        })
+
+    planning = raw.get("planning", {})
+    if not isinstance(planning, dict):
+        raise ValueError("planning must be an object")
+    default_repo = planning.get("default_repository") or normalized_repos[0]["repository"]
+    if default_repo not in seen:
+        raise ValueError("planning.default_repository must exist in repositories")
+
+    initiatives = raw.get("initiatives", {})
+    if not isinstance(initiatives, dict):
+        raise ValueError("initiatives must be an object")
+    normalized_initiatives = {}
+    for key, value in sorted(initiatives.items()):
+        if not isinstance(key, str) or not re.fullmatch(r"[a-z0-9][a-z0-9._-]*", key):
+            raise ValueError(f"invalid initiative key: {key}")
+        if not isinstance(value, dict):
+            raise ValueError(f"initiative {key} must be an object")
+        title = _text(value.get("title"), f"initiatives.{key}.title")
+        required_issues = value.get("required_issues", [])
+        if not isinstance(required_issues, list) or any(
+            not isinstance(item, str) or not item.strip() for item in required_issues
+        ):
+            raise ValueError(f"initiatives.{key}.required_issues must be a list of non-empty strings")
+        completion = value.get("completion", {})
+        if not isinstance(completion, dict):
+            raise ValueError(f"initiatives.{key}.completion must be an object")
+        require_all = completion.get("require_all_issues_closed", True)
+        require_runtime = completion.get("require_runtime_pass", False)
+        if type(require_all) is not bool or type(require_runtime) is not bool:
+            raise ValueError(f"initiatives.{key}.completion values must be booleans")
+        normalized_initiatives[key] = {
+            "title": title,
+            "required_issues": [item.strip() for item in required_issues],
+            "completion": {
+                "require_all_issues_closed": require_all,
+                "require_runtime_pass": require_runtime,
+            },
+        }
+
+    return {
+        "version": 1,
+        "planning_context": {
+            "workspace": workspace_name,
+            "github_project": normalized_project,
+            "default_repository": default_repo,
+            "repositories": sorted(normalized_repos, key=lambda x: x["repository"]),
+            "initiatives": normalized_initiatives,
+        },
+    }
+
+
+def load_workspace(path: Path) -> dict:
+    if yaml is None:
+        raise RuntimeError("PyYAML is required to read .ai-workspace.yml")
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return normalize_workspace(data)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("workspace", type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    result = load_workspace(args.workspace)
+    content = json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    if args.output:
+        args.output.write_text(content, encoding="utf-8")
+    else:
+        print(content, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

setup_context.py

@@ -0,0 +1,99 @@
+"""Repository context analysis for first-run workflow setup."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+SIGNALS = {
+    "agents_file": "AGENTS.md",
+    "current_router": "CURRENT.md",
+    "workflow_config": ".ai-workflow.yml",
+    "workspace_config": ".ai-workspace.yml",
+    "devcontainer": ".devcontainer/devcontainer.json",
+}
+
+DOC_GLOBS = ("docs/**/*.md", "*.md")
+TEST_DIRS = ("tests", "test", "__tests__", "spec")
+WORKFLOW_DIR = ".github/workflows"
+
+
+def analyze_repository(root: Path | str = ".") -> dict:
+    root = Path(root)
+    signals = {name: (root / rel).exists() for name, rel in SIGNALS.items()}
+    docs = set()
+    for pattern in DOC_GLOBS:
+        for path in root.glob(pattern):
+            if path.is_file():
+                try:
+                    docs.add(str(path.relative_to(root)))
+                except ValueError:
+                    pass
+
+    tests = []
+    for dirname in TEST_DIRS:
+        path = root / dirname
+        if path.exists():
+            tests.append(dirname)
+
+    workflows = []
+    workflow_dir = root / WORKFLOW_DIR
+    if workflow_dir.exists():
+        for path in sorted(workflow_dir.glob("*.y*ml")):
+            workflows.append(str(path.relative_to(root)))
+
+    languages = []
+    indicators = {
+        "python": ("pyproject.toml", "requirements.txt", "setup.py"),
+        "node": ("package.json",),
+        "dotnet": ("*.sln", "*.csproj"),
+        "rust": ("Cargo.toml",),
+        "go": ("go.mod",),
+    }
+    for language, patterns in indicators.items():
+        found = False
+        for pattern in patterns:
+            if "*" in pattern:
+                found = any(root.glob(pattern))
+            else:
+                found = (root / pattern).exists()
+            if found:
+                languages.append(language)
+                break
+
+    recommendations = []
+    if not signals["agents_file"]:
+        recommendations.append("create AGENTS.md")
+    if not signals["current_router"]:
+        recommendations.append("create CURRENT.md")
+    if not signals["workflow_config"]:
+        recommendations.append("create .ai-workflow.yml")
+    if not signals["devcontainer"]:
+        recommendations.append("create devcontainer when Codespaces is enabled")
+    if not tests:
+        recommendations.append("define project test command/conventions")
+
+    return {
+        "root": str(root.resolve()),
+        "signals": signals,
+        "languages": languages,
+        "tests": tests,
+        "workflows": workflows,
+        "docs": sorted(docs)[:100],
+        "recommendations": recommendations,
+    }
+
+
+def setup_agent_context(analysis: dict) -> dict:
+    """Provider-neutral input contract for a SetupAgent."""
+    return {
+        "role": "SetupAgent",
+        "goal": "Recommend initial ai-dev-workflow configuration without changing project intent.",
+        "repository_context": analysis,
+        "expected_output": {
+            "workflow_policy": "recommended TDD/reviewer/runtime policy",
+            "role_assignments": "recommended provider per agent role",
+            "execution_environment": "none or codespaces",
+            "context_files": "files the agents should load first",
+            "manual_setup": "credentials/settings the user must configure",
+        },
+    }

setup_wizard.py

@@ -0,0 +1,221 @@
+"""Step-by-step repository setup for ai-dev-workflow."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ado_provider import AzureDevOps, build_state_mapping, available_fields
+from github_work_item_provider import GitHubIssues, build_github_mapping, ensure_managed_status_labels
+from setup_context import analyze_repository, setup_agent_context
+from ai_provider import credential_requirements_for_providers, provider_template
+from source_connection import resolve_github_token
+from ado_mcp import build_ado_mcp, ado_mcp_credentials
+from worker_registry import worker_credential_requirements
+
+CANONICAL_HELP = (
+    "draft, ready, in-progress, in-review, runtime-pending, "
+    "release-pending, blocked, completed"
+)
+
+DEFAULT_WORKFLOW = {
+    "tdd": True,
+    "reviewer": {"mode": "manual"},
+    "runtime_verification": {"mode": "project-defined"},
+}
+
+
+def credential_requirements(work_items: str, environment: str, agents: dict, providers: dict | None = None, github_auth=None, ado_mcp=None, workers: list[dict] | None = None) -> list[dict]:
+    requirements = []
+    if work_items in ("github-issues", "composite"):
+        if (github_auth or {}).get("type") == "gh-cli-oauth":
+            requirements.append({
+                "name": "GitHub CLI OAuth session",
+                "purpose": "Authenticate GitHub API through existing gh auth login session.",
+                "required_for_setup": True,
+                "store": "GitHub CLI credential store",
+            })
+        else:
+            requirements.append({
+                "name": (github_auth or {}).get("env", "GH_TOKEN"),
+                "purpose": "Authenticate GitHub API using token environment fallback.",
+                "required_for_setup": True,
+                "store": "environment or GitHub Actions secret; never commit",
+            })
+    if work_items in ("azure-devops", "composite"):
+        requirements.append({
+            "name": "AZURE_DEVOPS_TOKEN",
+            "purpose": "Discover ADO process/WIT states and manage work items.",
+            "required_for_setup": True,
+            "store": "environment/secret store; never commit",
+        })
+    if environment == "codespaces":
+        requirements.append({
+            "name": "CODESPACES_TOKEN",
+            "purpose": "Provision/start/stop GitHub Codespaces worker environments.",
+            "required_for_setup": False,
+            "store": "GitHub Actions repository secret",
+        })
+    requirements.extend(credential_requirements_for_providers(providers or {}))
+    requirements.extend(ado_mcp_credentials(ado_mcp or {}))
+    requirements.extend(worker_credential_requirements(workers or [], work_items))
+    return requirements
+
+
+def build_setup_plan(
+    root=".",
+    work_items="github-issues",
+    discovery=None,
+    mapping=None,
+    workflow=None,
+    agents=None,
+    environment=None,
+    providers=None,
+    github_auth=None,
+    ado_mcp=None,
+    workers=None,
+    ado_field_mapping=None,
+) -> dict:
+    analysis = analyze_repository(root)
+    if providers is None:
+        providers = {}
+        referenced = {item.get("provider") for item in (agents or {}).values() if isinstance(item, dict)}
+        if "codex" in referenced:
+            providers["codex"] = provider_template("chatgpt-codex")
+        if "manual" in referenced:
+            providers["manual"] = provider_template("interactive")
+    return {
+        "version": 1,
+        "status": "review-required",
+        "phases": [
+            {"id": 1, "name": "connect-source-host", "status": "complete"},
+            {"id": 2, "name": "analyze-context", "status": "complete"},
+            {"id": 3, "name": "select-work-item-provider", "status": "complete"},
+            {"id": 4, "name": "connect-work-item-provider", "status": "complete"},
+            {"id": 5, "name": "discover-existing-statuses", "status": "complete" if discovery is not None else "pending"},
+            {"id": 6, "name": "confirm-status-mapping", "status": "review-required"},
+            {"id": 7, "name": "configure-workflow-and-agents", "status": "review-required"},
+            {"id": 8, "name": "register-workers", "status": "review-required"},
+            {"id": 9, "name": "configure-environment-and-credentials", "status": "review-required"},
+            {"id": 10, "name": "doctor-and-apply", "status": "pending"},
+        ],
+        "context": analysis,
+        "setup_agent": setup_agent_context(analysis),
+        "source_connection": {"github": github_auth or {}},
+        "work_items": {
+            "provider": work_items,
+            "discovery": discovery,
+            "suggested_mapping": mapping or {},
+            "mapping_confirmed": False,
+            "ado_field_mapping": ado_field_mapping or {},
+        },
+        "workflow": workflow or DEFAULT_WORKFLOW,
+        "agents": agents or {},
+        "providers": providers or {},
+        "ado_mcp": ado_mcp or {},
+        "workers": workers or [],
+        "execution_environment": environment or {"type": "none"},
+        "credential_requirements": credential_requirements(
+            work_items,
+            (environment or {"type": "none"}).get("type", "none"),
+            agents or {},
+            providers or {},
+            github_auth,
+            ado_mcp,
+            workers or [],
+        ),
+    }
+
+
+def discover_provider(args):
+    if args.work_items in ("azure-devops", "composite"):
+        token = os.environ.get(args.ado_token_env)
+        if not token:
+            raise RuntimeError(f"{args.ado_token_env} is required for ADO discovery")
+        discovery = AzureDevOps(args.ado_organization, token).discover(args.ado_project)
+        return discovery, build_state_mapping(discovery)
+
+    token, _ = resolve_github_token(args.github_auth, args.github_token_env)
+    discovery = GitHubIssues(args.github_repository, token).discover()
+    return discovery, build_github_mapping(discovery)
+
+
+def interactive_ado_field_mapping(discovery: dict, input_fn=input, output_fn=print) -> dict:
+    result = {}
+    output_fn("\nADO existing-field mapping (existing fields only; setup will not create fields)")
+    for wit in discovery.get("work_item_types", []):
+        ref = wit["reference_name"]
+        fields = available_fields(discovery, ref)
+        if not fields:
+            continue
+        output_fn(f"\nWork Item Type: {wit['name']} ({ref})")
+        by_ref = {f["reference_name"]: f for f in fields}
+        configured = {}
+        for key in ("workflow_phase","github_issue","worker","agent_role","pull_request","test_status","runtime_status","workflow_profile"):
+            field_ref = input_fn(f"  Map {key} to existing field reference (blank=skip): ").strip()
+            if not field_ref:
+                continue
+            if field_ref not in by_ref:
+                raise ValueError(f"ADO field does not exist for {ref}: {field_ref}")
+            default = input_fn(f"    Default value for {key} (blank=no default): ")
+            item = {"field": field_ref}
+            if default != "":
+                item["default"] = default
+            configured[key] = item
+        if configured:
+            result[ref] = configured
+    return result
+
+
+def interactive_mapping(provider: str, discovery: dict, suggestions: dict, input_fn=input, output_fn=print):
+    output_fn(f"Canonical states: {CANONICAL_HELP}")
+    if provider == "azure-devops":
+        result = {}
+        for wit in discovery.get("work_item_types", []):
+            ref = wit["reference_name"]
+            result[ref] = {}
+            output_fn(f"\nWork Item Type: {wit['name']} ({ref})")
+            for state in wit.get("states", []):
+                if state.get("hidden"):
+                    continue
+                name = state["name"]
+                default = suggestions.get(ref, {}).get(name, "draft")
+                value = input_fn(f"  {name} [{default}]: ").strip() or default
+                result[ref][name] = value
+        return result
+
+    result = {}
+    labels = discovery.get("labels", [])
+    for item in labels:
+        name = item["name"]
+        default = suggestions.get(name)
+        prompt_default = default or "skip"
+        value = input_fn(f"  {name} [{prompt_default}]: ").strip()
+        if not value:
+            value = default
+        if value and value != "skip":
+            result[name] = value
+    return result
+
+
+def apply_github_status_bootstrap(args, mapping: dict) -> tuple[dict, dict, list[str]]:
+    token, _ = resolve_github_token(args.github_auth, args.github_token_env)
+    api = GitHubIssues(args.github_repository, token)
+    before = api.discover()
+    created = ensure_managed_status_labels(api, before)
+    after = api.discover() if created else before
+    refreshed = build_github_mapping(after)
+    refreshed.update(mapping)
+    return after, refreshed, created
+
+
+def render_user_steps(plan: dict) -> str:
+    lines = ["Setup phases:"]
+    for phase in plan["phases"]:
+        lines.append(f"{phase['id']}. {phase['name']} — {phase['status']}")
+    lines.append("")
+    lines.append("Manual credential/settings checklist:")
+    if not plan["credential_requirements"]:
+        lines.append("- none")
+    for item in plan["credential_requirements"]:
+        lines.append(f"- {item['name']}: {item['purpose']} Store: {item['store']}.")
+    return "\n".join(lines)

source_connection.py

@@ -0,0 +1,21 @@
+"""Source-host connection helpers."""
+from __future__ import annotations
+import os, subprocess
+
+
+def resolve_github_token(mode: str, env_name: str = "GH_TOKEN") -> tuple[str, dict]:
+    if mode == "gh-cli":
+        proc = subprocess.run(
+            ["gh", "auth", "token"],
+            check=True, capture_output=True, text=True,
+        )
+        token = proc.stdout.strip()
+        if not token:
+            raise RuntimeError("gh auth token returned an empty token")
+        return token, {"type": "gh-cli-oauth"}
+    if mode == "token-env":
+        token = os.environ.get(env_name)
+        if not token:
+            raise RuntimeError(f"{env_name} is required")
+        return token, {"type": "token-env", "env": env_name}
+    raise ValueError(f"unsupported GitHub auth mode: {mode}")

work_item_provider.py

@@ -0,0 +1,20 @@
+"""Provider-neutral work item state model."""
+CANONICAL_STATES = (
+    "draft",
+    "ready",
+    "in-progress",
+    "in-review",
+    "runtime-pending",
+    "release-pending",
+    "blocked",
+    "completed",
+)
+
+REQUIRED_CANONICAL_STATES = ("ready", "completed")
+SETUP_AGENT_ROLE = "SetupAgent"
+
+REQUIRED_AGENT_ROLES = (
+    "ArchitectAgent",
+    "TesterAgent",
+    "ImplementerAgent",
+)

work_item_registry.py

@@ -0,0 +1,25 @@
+"""Registry of WorkItemProvider adapters used by setup."""
+BUILTIN_WORK_ITEM_PROVIDERS = {
+    "github-issues": {
+        "type": "github-issues",
+        "requires_source_connection": "github",
+    },
+    "azure-devops": {
+        "type": "azure-devops",
+        "requires_source_connection": None,
+        "supports_mcp": True,
+    },
+    "composite": {
+        "type": "composite",
+        "business_provider": "azure-devops",
+        "execution_provider": "github-issues",
+        "supports_mcp": True,
+    },
+}
+
+
+def validate_work_item_provider(provider_id: str, registry=None) -> list[str]:
+    registry = registry or BUILTIN_WORK_ITEM_PROVIDERS
+    if provider_id not in registry:
+        return [f"unknown work item provider: {provider_id}"]
+    return []