se-admin 0.2.0__py3-none-any.whl

se_admin/app.py

@@ -0,0 +1,374 @@
+"""Application orchestration for se_admin."""
+
+from pathlib import Path
+
+from se_admin.actions import ActionResult
+from se_admin.actions.copy_file import (
+    run_copy_file,
+    run_delete_file,
+)
+from se_admin.actions.patch_toml import run_patch_toml
+from se_admin.actions.replace_file import (
+    run_ensure_workflow,
+    run_remove_workflow,
+    run_replace_workflow,
+)
+from se_admin.checks import run_profile_checks
+from se_admin.domain.capabilities import CAPABILITY_LABELS, Capability
+from se_admin.domain.findings import Finding
+from se_admin.domain.operations import (
+    CopyFile,
+    DeleteFile,
+    EnsureWorkflow,
+    PatchToml,
+    RemoveWorkflow,
+    ReplaceWorkflow,
+)
+from se_admin.domain.profiles import ProfileRegistry
+from se_admin.domain.repos import RepoEntry, RepoRegistry
+from se_admin.domain.selectors import (
+    PatternSelector,
+    RepoNameSelector,
+    RepoSetSelector,
+)
+from se_admin.domain.tasks import Task
+
+# ---------------------------------------------------------------------------
+# show
+# ---------------------------------------------------------------------------
+
+
+def run_show(*, area: str = "all") -> int:
+    """Show available admin capabilities."""
+    targets: list[Capability] = [*Capability] if area == "all" else [Capability(area)]
+    print("SE admin capabilities:")
+    for cap in targets:
+        print(f"  {cap.value}: {CAPABILITY_LABELS[cap]}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# repos
+# ---------------------------------------------------------------------------
+
+
+def run_repos(
+    *,
+    data: Path,
+    repo_set: str | None = None,
+    active_only: bool = False,
+) -> int:
+    """List repos from repos.toml."""
+    registry = RepoRegistry.from_toml(data / "repos.toml")
+
+    if repo_set:
+        repos = registry.repos_in_set(repo_set)
+    elif active_only:
+        repos = registry.active_repos()
+    else:
+        repos = list(registry.repos.values())
+
+    if not repos:
+        print("No repos matched.")
+        return 0
+
+    print(f"{'name':<40} {'set':<16} {'profiles'}")
+    print("-" * 72)
+    for repo in sorted(repos, key=lambda r: r.name):
+        profiles = ", ".join(repo.profiles)
+        status = f" [{repo.status}]" if repo.status != "active" else ""
+        print(f"{repo.name + status:<40} {repo.repo_set:<16} {profiles}")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# tasks
+# ---------------------------------------------------------------------------
+
+
+def run_tasks(*, data: Path) -> int:
+    """List available tasks from data/tasks/."""
+    tasks_dir = data / "tasks"
+    if not tasks_dir.exists():
+        print("No tasks directory found.")
+        return 1
+
+    tasks = Task.load_all(tasks_dir)
+    if not tasks:
+        print("No tasks found.")
+        return 0
+
+    print(f"{'id':<48} label")
+    print("-" * 72)
+    for task_id, task in sorted(tasks.items()):
+        print(f"{task_id:<48} {task.label}")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# check
+# ---------------------------------------------------------------------------
+
+
+def run_check(
+    *,
+    data: Path,
+    repo: str | None = None,
+    repo_set: str | None = None,
+    profile: str | None = None,
+) -> int:
+    """Run profile checks against a repo or set."""
+    repo_registry = RepoRegistry.from_toml(data / "repos.toml")
+    profile_registry = ProfileRegistry.from_toml(data / "profiles.toml")
+    workspace = repo_registry.workspace_path()
+
+    if repo:
+        entry = repo_registry.repos.get(repo)
+        if entry is None:
+            print(f"Unknown repo: {repo!r}")
+            return 1
+        entries = [entry]
+    elif repo_set:
+        entries = repo_registry.repos_in_set(repo_set)
+        if not entries:
+            print(f"No repos in set: {repo_set!r}")
+            return 1
+    else:
+        print("Specify --repo or --set.")
+        return 2
+
+    all_findings: list[Finding] = []
+
+    for entry in entries:
+        profile_names = [profile] if profile else entry.profiles
+        profiles = profile_registry.resolve(profile_names)
+        for prof in profiles:
+            findings = run_profile_checks(
+                entry,
+                prof,
+                workspace_path=workspace,
+                profile_registry=profile_registry,
+            )
+            all_findings.extend(findings)
+
+    _print_findings(all_findings)
+    failures = [f for f in all_findings if f.failed]
+    return 1 if failures else 0
+
+
+def _print_findings(findings: list[Finding]) -> None:
+    if not findings:
+        print("No findings.")
+        return
+
+    by_repo: dict[str, list[Finding]] = {}
+    for f in findings:
+        by_repo.setdefault(f.repo, []).append(f)
+
+    for repo_name, repo_findings in sorted(by_repo.items()):
+        passed = sum(1 for f in repo_findings if f.passed)
+        failed = sum(1 for f in repo_findings if f.failed)
+        print(f"\n{repo_name}  ({passed} pass, {failed} fail)")
+        for f in repo_findings:
+            icon = "✓" if f.passed else ("✗" if f.failed else "–")
+            path = f"  {f.path}" if f.path else ""
+            msg = f"  {f.message}" if f.message else ""
+            print(f"  {icon} [{f.check}]{path}{msg}")
+
+
+# ---------------------------------------------------------------------------
+# run (task executor)
+# ---------------------------------------------------------------------------
+
+
+def run_task(
+    *,
+    data: Path,
+    task_id: str,
+    dry_run: bool = False,
+) -> int:
+    """Execute a task by id."""
+    tasks = Task.load_all(data / "tasks")
+    task = tasks.get(task_id)
+    if task is None:
+        available = ", ".join(sorted(tasks.keys()))
+        print(
+            f"Unknown task: {task_id!r}\n"
+            f"  Add a task file: data/tasks/{task_id}.toml\n"
+            f"  Available tasks: {available}"
+        )
+        return 1
+
+    repo_registry = RepoRegistry.from_toml(data / "repos.toml")
+    workspace = repo_registry.workspace_path()
+
+    source_path: Path | None = None
+    if task.source:
+        source_path = workspace / task.source.repo
+
+    entries = _resolve_selector(task, repo_registry)
+    if not entries:
+        print(f"Task {task_id!r}: no repos matched selector.")
+        return 0
+
+    label = "[dry-run] " if dry_run else ""
+    print(f"{label}Task: {task.label}")
+
+    total_changed = 0
+    total_errors = 0
+
+    for entry in entries:
+        target_path = workspace / entry.name
+        print(f"\n  to {entry.name}")
+        for op_dict in task.operations:
+            result = _dispatch(
+                op_dict,
+                target_path=target_path,
+                source_path=source_path,
+                dry_run=dry_run,
+            )
+            icon = "✓" if result.ok else "✗"
+            changed = " (changed)" if result.changed else ""
+            msg = f": {result.message}" if result.message else ""
+            print(f"    {icon} {op_dict.get('type', '?')}{changed}{msg}")
+            if result.changed:
+                total_changed += 1
+            if not result.ok:
+                total_errors += 1
+
+    print(f"\n{total_changed} change(s), {total_errors} error(s).")
+    return 1 if total_errors else 0
+
+
+def _resolve_selector(task: Task, registry: RepoRegistry) -> list[RepoEntry]:
+    if task.selector is None:
+        return []
+    sel = task.selector
+    if isinstance(sel, RepoSetSelector):
+        entries: list[RepoEntry] = []
+        for set_name in sel.repo_sets:
+            entries.extend(registry.repos_in_set(set_name))
+        return entries
+    if isinstance(sel, RepoNameSelector):
+        return [registry.repos[n] for n in sel.repos if n in registry.repos]
+    if isinstance(sel, PatternSelector):
+        import re
+
+        pattern = re.compile(sel.pattern)
+        return [r for r in registry.repos.values() if pattern.search(r.name)]
+    return []
+
+
+# ---------------------------------------------------------------------------
+# Operation interpreter
+# ---------------------------------------------------------------------------
+
+
+def _dispatch(
+    op: dict,
+    *,
+    target_path: Path,
+    source_path: Path | None,
+    dry_run: bool,
+) -> ActionResult:
+    """Map a raw TOML operation dict to an action and execute it."""
+    op_type = op.get("type", "")
+
+    if dry_run:
+        return ActionResult.noop(f"would run {op_type}")
+
+    if op_type == "ensure_exact_files":
+        results = [
+            run_copy_file(
+                CopyFile(src=p, dest=p),
+                target_path=target_path,
+                source_path=source_path or target_path,
+            )
+            for p in op.get("paths", [])
+        ]
+        changed = any(r.changed for r in results)
+        errors = [r.message for r in results if not r.ok]
+        if errors:
+            return ActionResult.error("; ".join(e for e in errors if e))
+        return ActionResult(ok=True, changed=changed)
+
+    if op_type == "delete_files":
+        results = [
+            run_delete_file(DeleteFile(path=p), target_path=target_path)
+            for p in op.get("paths", [])
+        ]
+        changed = any(r.changed for r in results)
+        return ActionResult(ok=True, changed=changed)
+
+    if op_type == "add_dependency":
+        return run_patch_toml(
+            PatchToml(
+                file="pyproject.toml",
+                operation="add_dependency",
+                group=op.get("group"),
+                name=op.get("name"),
+            ),
+            target_path=target_path,
+        )
+
+    if op_type == "remove_dependency":
+        return run_patch_toml(
+            PatchToml(
+                file="pyproject.toml",
+                operation="remove_dependency",
+                group=op.get("group"),
+                name=op.get("name"),
+            ),
+            target_path=target_path,
+        )
+
+    if op_type == "ensure_workflow":
+        return run_ensure_workflow(
+            EnsureWorkflow(name=op["name"], src=op.get("src", op["name"])),
+            target_path=target_path,
+            source_path=source_path or target_path,
+        )
+
+    if op_type == "replace_workflow":
+        return run_replace_workflow(
+            ReplaceWorkflow(name=op["name"], src=op.get("src", op["name"])),
+            target_path=target_path,
+            source_path=source_path or target_path,
+        )
+
+    if op_type == "remove_workflow":
+        return run_remove_workflow(
+            RemoveWorkflow(name=op["name"]),
+            target_path=target_path,
+        )
+
+    if op_type == "git_pull":
+        from se_admin.actions.git_pull import git_pull
+
+        ok, message = git_pull(target_path)
+        return ActionResult(ok=ok, changed=ok, message=message or None)
+
+    if op_type == "merge_dependabot_prs":
+        from se_admin.actions.dependabot import (
+            list_dependabot_prs,
+            merge_dependabot_pr,
+        )
+
+        prs = list_dependabot_prs(target_path)
+        if not prs:
+            return ActionResult.noop("No open Dependabot PRs")
+        merged = 0
+        merge_errors: list[str] = []
+        for pr in prs:
+            ok, msg = merge_dependabot_pr(target_path, pr["number"])
+            if ok:
+                merged += 1
+            else:
+                merge_errors.append(f"#{pr['number']}: {msg}")
+        if merge_errors:
+            return ActionResult.error("; ".join(merge_errors))
+        return ActionResult.done(f"Merged {merged} Dependabot PR(s)")
+
+    return ActionResult.error(f"Unknown operation type: {op_type!r}")

se_admin/checks/__init__.py

@@ -0,0 +1,83 @@
+"""se_admin checks layer - pure comparisons, no side effects.
+
+Each check reads actual state via observe/ and returns Finding objects.
+Nothing in this layer writes to disk or calls external services
+(except checks/tags.py which reads from the GitHub API).
+"""
+
+from pathlib import Path
+
+from se_admin.checks.exact_files import check_exact_files
+from se_admin.checks.python_version import check_python_version
+from se_admin.checks.reference_files import check_reference_files
+from se_admin.checks.required_paths import check_required_paths
+from se_admin.checks.tags import check_tags
+from se_admin.checks.workflows import check_required_workflows
+from se_admin.domain.findings import Finding
+from se_admin.domain.profiles import Profile, ProfileRegistry
+from se_admin.domain.repos import RepoEntry
+
+
+def run_profile_checks(
+    repo: RepoEntry,
+    profile: Profile,
+    *,
+    workspace_path: Path,
+    source_path: Path | None = None,
+    profile_registry: ProfileRegistry | None = None,
+) -> list[Finding]:
+    """Run all checks implied by a profile against a repo.
+
+    Returns the combined list of Finding objects.
+    source_path is required only for exact_files checks.
+
+    Args:
+        repo: the repository to check
+        profile: the profile whose checks to run
+        *: keyword-only arguments after this point
+        workspace_path: the base path where repositories are located on disk
+        source_path: optional path to use as source for exact_files checks
+        profile_registry: optional profile registry for resolving extended profiles
+
+    Returns:
+        list of Finding objects for all checks that failed
+    """
+    repo_path = workspace_path / repo.name
+    findings: list[Finding] = []
+
+    # Expand extended profiles first
+    if profile.extends and profile_registry is not None:
+        for extended_id in profile.extends:
+            extended = profile_registry.get(extended_id)
+            if extended is None:
+                raise KeyError(
+                    f"Profile {profile.id!r} extends unknown profile: {extended_id!r}"
+                )
+            findings += run_profile_checks(
+                repo,
+                extended,
+                workspace_path=workspace_path,
+                source_path=source_path,
+                profile_registry=profile_registry,
+            )
+
+    if profile.required_paths:
+        findings += check_required_paths(repo.name, repo_path, profile.required_paths)
+
+    if profile.required_workflows:
+        findings += check_required_workflows(
+            repo.name, repo_path, profile.required_workflows
+        )
+
+    return findings
+
+
+__all__ = [
+    "check_exact_files",
+    "check_python_version",
+    "check_reference_files",
+    "check_required_paths",
+    "check_required_workflows",
+    "check_tags",
+    "run_profile_checks",
+]

se_admin/checks/exact_files.py

@@ -0,0 +1,72 @@
+"""Check that files in a repo match the canonical source exactly."""
+
+from pathlib import Path
+
+from se_admin.domain.findings import Finding, FindingStatus
+
+
+def check_exact_files(
+    repo: str,
+    repo_path: Path,
+    paths: list[str],
+    source_path: Path,
+) -> list[Finding]:
+    """Compare each path byte-for-byte against the canonical source.
+
+    Findings:
+      FAIL - file missing in target
+      FAIL - file present but differs from source
+      PASS - file matches source exactly
+      SKIP - source file missing (cannot compare)
+    """
+    findings: list[Finding] = []
+
+    for rel in paths:
+        src = source_path / rel
+        dest = repo_path / rel
+
+        if not src.exists():
+            findings.append(
+                Finding(
+                    repo=repo,
+                    check="exact_files",
+                    status=FindingStatus.SKIP,
+                    path=rel,
+                    message=f"Source file not found, cannot compare: {rel}",
+                )
+            )
+            continue
+
+        if not dest.exists():
+            findings.append(
+                Finding(
+                    repo=repo,
+                    check="exact_files",
+                    status=FindingStatus.FAIL,
+                    path=rel,
+                    message=f"File missing in target: {rel}",
+                )
+            )
+            continue
+
+        if dest.read_bytes() == src.read_bytes():
+            findings.append(
+                Finding(
+                    repo=repo,
+                    check="exact_files",
+                    status=FindingStatus.PASS,
+                    path=rel,
+                )
+            )
+        else:
+            findings.append(
+                Finding(
+                    repo=repo,
+                    check="exact_files",
+                    status=FindingStatus.FAIL,
+                    path=rel,
+                    message=f"File differs from canonical source: {rel}",
+                )
+            )
+
+    return findings

se_admin/checks/python_version.py

@@ -0,0 +1,94 @@
+"""Check Python version alignment in a repo.
+
+Two distinct checks:
+  python_version_file   - .python-version pin matches expected
+  requires_python       - pyproject.toml requires-python specifier present
+"""
+
+from pathlib import Path
+
+from se_admin.domain.findings import Finding, FindingStatus
+from se_admin.observe.pyproject import get_python_version_file, get_requires_python
+
+
+def check_python_version(
+    repo: str,
+    repo_path: Path,
+    expected_version: str,
+) -> list[Finding]:
+    """Check .python-version pin equals expected_version (e.g. '3.12')."""
+    actual = get_python_version_file(repo_path)
+
+    if actual is None:
+        return [
+            Finding(
+                repo=repo,
+                check="python_version_file",
+                status=FindingStatus.FAIL,
+                path=".python-version",
+                message=".python-version file missing",
+            )
+        ]
+
+    if actual == expected_version:
+        return [
+            Finding(
+                repo=repo,
+                check="python_version_file",
+                status=FindingStatus.PASS,
+                path=".python-version",
+            )
+        ]
+
+    return [
+        Finding(
+            repo=repo,
+            check="python_version_file",
+            status=FindingStatus.FAIL,
+            path=".python-version",
+            message=f"Expected {expected_version!r}, found {actual!r}",
+        )
+    ]
+
+
+def check_requires_python(
+    repo: str,
+    repo_path: Path,
+    expected_specifier: str | None = None,
+) -> list[Finding]:
+    """Check that requires-python is set in pyproject.toml.
+
+    If expected_specifier is given, also assert it matches exactly.
+    """
+    actual = get_requires_python(repo_path)
+
+    if actual is None:
+        return [
+            Finding(
+                repo=repo,
+                check="requires_python",
+                status=FindingStatus.FAIL,
+                path="pyproject.toml",
+                message="requires-python not set in [project]",
+            )
+        ]
+
+    if expected_specifier is not None and actual != expected_specifier:
+        return [
+            Finding(
+                repo=repo,
+                check="requires_python",
+                status=FindingStatus.FAIL,
+                path="pyproject.toml",
+                message=f"Expected requires-python={expected_specifier!r}, found {actual!r}",
+            )
+        ]
+
+    return [
+        Finding(
+            repo=repo,
+            check="requires_python",
+            status=FindingStatus.PASS,
+            path="pyproject.toml",
+        )
+    ]

se_admin/checks/reference_files.py

@@ -0,0 +1,63 @@
+"""Check that a repo's reference/ directory exists and contains expected files."""
+
+from pathlib import Path
+
+from se_admin.domain.findings import Finding, FindingStatus
+from se_admin.observe.filesystem import is_directory, path_exists
+
+_REFERENCE_DIR = "reference"
+
+
+def check_reference_files(
+    repo: str,
+    repo_path: Path,
+    expected_paths: list[str] | None = None,
+) -> list[Finding]:
+    """Check the reference/ directory and optionally specific files within it.
+
+    Without expected_paths: PASS if reference/ exists, FAIL if not.
+    With expected_paths: one Finding per path under reference/.
+    """
+    findings: list[Finding] = []
+
+    dir_present = is_directory(repo_path, _REFERENCE_DIR)
+
+    if not dir_present:
+        findings.append(
+            Finding(
+                repo=repo,
+                check="reference_files",
+                status=FindingStatus.FAIL,
+                path=_REFERENCE_DIR,
+                message="reference/ directory missing",
+            )
+        )
+        # No point checking contents if directory is absent
+        return findings
+
+    findings.append(
+        Finding(
+            repo=repo,
+            check="reference_files",
+            status=FindingStatus.PASS,
+            path=_REFERENCE_DIR,
+        )
+    )
+
+    if expected_paths:
+        for rel in expected_paths:
+            full_rel = f"{_REFERENCE_DIR}/{rel}"
+            exists = path_exists(repo_path, full_rel)
+            findings.append(
+                Finding(
+                    repo=repo,
+                    check="reference_files",
+                    status=FindingStatus.PASS if exists else FindingStatus.FAIL,
+                    path=full_rel,
+                    message=None
+                    if exists
+                    else f"Expected reference file missing: {full_rel}",
+                )
+            )
+
+    return findings