open-codev-workflow 0.1.0__py3-none-any.whl

codev_workflow/bundle/scripts/validate-development-workflow.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""Validate the repository's human-AI development workflow without dependencies."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+EXPECTED_SKILLS = {
+    "specify-project": [
+        "assets/specification.template.md",
+        "references/interview-coverage.md",
+        "scripts/validate_specification.py",
+    ],
+    "define-product": ["assets/brief.template.md"],
+    "design-solution": [
+        "assets/design.template.md",
+        "assets/decision.template.md",
+    ],
+    "plan-delivery": ["assets/delivery-plan.template.md"],
+    "build-change": ["assets/implementation-plan.template.md"],
+    "review-change": [],
+    "launch-product": ["assets/launch-plan.template.md"],
+}
+
+EXPECTED_HANDBOOKS = [
+    "PYTHON-PROJECT-HANDBOOK.md",
+    "LANGUAGE-AGNOSTIC-PROJECT-HANDBOOK.md",
+    "IDEA-TO-PRODUCTION-HANDBOOK.md",
+]
+
+EXPECTED_GUIDES = [
+    "AGENTS.md",
+    "docs/WORKFLOW-HUMAN.md",
+    "docs/for-ai/WORKFLOW-AGENTS.md",
+    "docs/WORKFLOW-COOKBOOK.md",
+    "docs/AI-WORKFLOW-PROMPTS.md",
+]
+
+EVALUATION_SCRIPT = "scripts/evaluate-development-workflow.py"
+EVALUATION_CATALOG = "evals/development-workflow/scenarios.json"
+
+
+def parse_frontmatter(text: str, path: Path, errors: list[str]) -> dict[str, str]:
+    lines = text.splitlines()
+    if not lines or lines[0] != "---":
+        errors.append(f"{path}: missing opening YAML delimiter")
+        return {}
+    try:
+        end = lines.index("---", 1)
+    except ValueError:
+        errors.append(f"{path}: missing closing YAML delimiter")
+        return {}
+
+    result: dict[str, str] = {}
+    for line in lines[1:end]:
+        match = re.fullmatch(r"([a-zA-Z0-9_-]+):\s*(.+)", line)
+        if not match:
+            errors.append(f"{path}: unsupported frontmatter line: {line!r}")
+            continue
+        result[match.group(1)] = match.group(2).strip().strip('"')
+    return result
+
+
+def validate_skill(root: Path, name: str, assets: list[str], errors: list[str]) -> None:
+    skill_dir = root / name
+    skill_file = skill_dir / "SKILL.md"
+    if not skill_file.is_file():
+        errors.append(f"{skill_file}: missing")
+        return
+
+    text = skill_file.read_text(encoding="utf-8")
+    metadata = parse_frontmatter(text, skill_file, errors)
+    if set(metadata) != {"name", "description"}:
+        errors.append(f"{skill_file}: frontmatter must contain only name and description")
+    if metadata.get("name") != name:
+        errors.append(f"{skill_file}: name must match directory {name!r}")
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", name) or len(name) > 64:
+        errors.append(f"{skill_file}: name must be hyphen-case and at most 64 characters")
+    description = metadata.get("description", "")
+    if len(description) < 80:
+        errors.append(f"{skill_file}: description is too short to trigger reliably")
+    if len(description) > 1024 or "<" in description or ">" in description:
+        errors.append(f"{skill_file}: description violates skill metadata limits")
+    if len(text.splitlines()) > 500:
+        errors.append(f"{skill_file}: exceeds the 500-line skill budget")
+    if re.search(r"\b(TODO|TBD)\b", text, re.IGNORECASE):
+        errors.append(f"{skill_file}: contains an unfinished placeholder")
+
+    ui_file = skill_dir / "agents" / "openai.yaml"
+    if not ui_file.is_file():
+        errors.append(f"{ui_file}: missing")
+    else:
+        ui = ui_file.read_text(encoding="utf-8")
+        for field in ("display_name", "short_description", "default_prompt"):
+            if not re.search(rf"^\s*{field}:\s*\".+\"\s*$", ui, re.MULTILINE):
+                errors.append(f"{ui_file}: missing quoted {field}")
+        if f"${name}" not in ui:
+            errors.append(f"{ui_file}: default_prompt must mention ${name}")
+
+    for relative in assets:
+        asset = skill_dir / relative
+        if not asset.is_file() or asset.stat().st_size == 0:
+            errors.append(f"{asset}: missing or empty")
+
+
+def validate_guides(repo: Path, errors: list[str]) -> None:
+    guides = [repo / relative for relative in EXPECTED_GUIDES]
+    for guide in guides:
+        if not guide.is_file():
+            errors.append(f"{guide}: missing")
+            continue
+        text = guide.read_text(encoding="utf-8")
+        for skill in EXPECTED_SKILLS:
+            if skill not in text:
+                errors.append(f"{guide}: does not reference {skill}")
+
+
+def validate_handbooks(repo: Path, errors: list[str]) -> None:
+    handbook_root = repo / "docs" / "handbooks"
+    for name in EXPECTED_HANDBOOKS:
+        handbook = handbook_root / name
+        if not handbook.is_file():
+            errors.append(f"{handbook}: missing")
+            continue
+        text = handbook.read_text(encoding="utf-8")
+        if len(text.splitlines()) < 100:
+            errors.append(f"{handbook}: unexpectedly short")
+        if re.search(r"\b(TODO|TBD)\b", text, re.IGNORECASE):
+            errors.append(f"{handbook}: contains an unfinished placeholder")
+        for skill in EXPECTED_SKILLS:
+            if skill not in text:
+                errors.append(f"{handbook}: does not reference {skill}")
+
+
+def validate_evaluations(repo: Path, errors: list[str]) -> int:
+    script = repo / EVALUATION_SCRIPT
+    catalog = repo / EVALUATION_CATALOG
+    if not script.is_file():
+        errors.append(f"{script}: missing")
+        return 0
+    if not catalog.is_file():
+        errors.append(f"{catalog}: missing")
+        return 0
+
+    for label, extra_args in (
+        ("catalog", []),
+        ("scorer self-test", ["--self-test"]),
+    ):
+        try:
+            completed = subprocess.run(
+                [sys.executable, str(script), "--repo", str(repo), *extra_args],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        except subprocess.TimeoutExpired:
+            errors.append(f"behavioral evaluation {label} timed out")
+            return 0
+        if completed.returncode != 0:
+            detail = (completed.stdout + completed.stderr).strip()
+            errors.append(f"behavioral evaluation {label} is invalid: {detail}")
+            return 0
+
+    try:
+        data = json.loads(catalog.read_text(encoding="utf-8"))
+        return len(data.get("scenarios", []))
+    except (OSError, ValueError, TypeError) as error:
+        errors.append(f"{catalog}: cannot count scenarios: {error}")
+        return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--repo",
+        type=Path,
+        default=Path(__file__).resolve().parents[1],
+        help="Repository root (defaults to the script's repository)",
+    )
+    args = parser.parse_args()
+    repo = args.repo.resolve()
+    skill_root = repo / ".agents" / "skills"
+    errors: list[str] = []
+
+    for skill, assets in EXPECTED_SKILLS.items():
+        validate_skill(skill_root, skill, assets, errors)
+    validate_guides(repo, errors)
+    validate_handbooks(repo, errors)
+    scenario_count = validate_evaluations(repo, errors)
+
+    if errors:
+        print("Workflow validation failed:")
+        for error in errors:
+            print(f"- {error}")
+        return 1
+
+    print(
+        "Workflow validation passed: "
+        f"{len(EXPECTED_SKILLS)} skills, {len(EXPECTED_GUIDES)} guides, and "
+        f"{len(EXPECTED_HANDBOOKS)} handbooks, plus {scenario_count} behavioral scenarios"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codev_workflow/cli.py

@@ -0,0 +1,140 @@
+"""Command-line interface for CoDev."""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from codev_workflow import __version__
+from codev_workflow.installer import (
+    CoDevError,
+    apply_plan,
+    check_project,
+    format_plan,
+    plan_init,
+    plan_remove,
+    plan_update,
+)
+
+
+def _target(value: str) -> Path:
+    return Path(value).expanduser()
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codev",
+        description="Install and maintain human-guided AI delivery workflows.",
+    )
+    parser.add_argument("--version", action="version", version=f"CoDev {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    init = commands.add_parser("init", help="install CoDev into a repository")
+    init.add_argument("--target", type=_target, default=Path.cwd())
+    init.add_argument(
+        "--platform",
+        action="append",
+        choices=("all", "codex", "opencode"),
+        default=None,
+        help="target adapter; repeat to select several (default: all)",
+    )
+    init.add_argument("--dry-run", action="store_true", help="show the plan only")
+
+    check = commands.add_parser("check", help="verify an installed bundle")
+    check.add_argument("--target", type=_target, default=Path.cwd())
+
+    doctor = commands.add_parser("doctor", help="show environment and bundle health")
+    doctor.add_argument("--target", type=_target, default=Path.cwd())
+
+    diff = commands.add_parser("diff", help="preview update changes")
+    diff.add_argument("--target", type=_target, default=Path.cwd())
+
+    update = commands.add_parser("update", help="apply a conflict-free bundle update")
+    update.add_argument("--target", type=_target, default=Path.cwd())
+
+    remove = commands.add_parser(
+        "remove", help="remove an unchanged CoDev installation"
+    )
+    remove.add_argument("--target", type=_target, default=Path.cwd())
+    remove.add_argument("--dry-run", action="store_true", help="show the plan only")
+    return parser
+
+
+def _print_check(target: Path) -> int:
+    result = check_project(target)
+    if result.ok:
+        print(
+            f"CoDev {result.version} is healthy: "
+            f"{result.managed_files} managed files, no drift."
+        )
+        return 0
+    print(f"CoDev check found {len(result.issues)} issue(s):")
+    for issue in result.issues:
+        print(f"- {issue}")
+    return 1
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "init":
+            target = args.target.resolve()
+            platforms = args.platform or ["all"]
+            plan = plan_init(target, platforms)
+            print(format_plan(plan))
+            if plan.conflicts:
+                print(f"Installation stopped: {len(plan.conflicts)} conflict(s).")
+                return 2
+            if args.dry_run:
+                print("Dry run complete; no files were written.")
+                return 0
+            apply_plan(target, plan)
+            print(f"Installed CoDev {__version__} into {target}")
+            return 0
+
+        if args.command == "check":
+            return _print_check(args.target.resolve())
+
+        if args.command == "doctor":
+            print(f"CoDev: {__version__}")
+            print(f"Python: {platform.python_version()} ({platform.system()})")
+            print(f"Target: {args.target.resolve()}")
+            return _print_check(args.target.resolve())
+
+        if args.command in {"diff", "update"}:
+            target = args.target.resolve()
+            plan = plan_update(target)
+            print(format_plan(plan))
+            if plan.conflicts:
+                print(f"Update stopped: {len(plan.conflicts)} conflict(s).")
+                return 2
+            if args.command == "diff":
+                print("Preview complete; no files were written.")
+                return 0
+            apply_plan(target, plan)
+            print(f"Updated CoDev bundle to {__version__} in {target}")
+            return 0
+
+        if args.command == "remove":
+            target = args.target.resolve()
+            plan = plan_remove(target)
+            print(format_plan(plan))
+            if plan.conflicts:
+                print(f"Removal stopped: {len(plan.conflicts)} conflict(s).")
+                return 2
+            if args.dry_run:
+                print("Dry run complete; no files were removed.")
+                return 0
+            apply_plan(target, plan)
+            print(f"Removed CoDev from {target}")
+            return 0
+    except CoDevError as error:
+        print(f"codev: {error}", file=sys.stderr)
+        return 2
+    except OSError as error:
+        print(f"codev: filesystem error: {error}", file=sys.stderr)
+        return 2
+    return 2