se-admin 0.2.0__py3-none-any.whl

se_admin/__init__.py

@@ -0,0 +1 @@
+"""Structural Explainability admin package."""

se_admin/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point."""
+
+from se_admin.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

se_admin/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

se_admin/actions/__init__.py

@@ -0,0 +1,35 @@
+"""se_admin actions layer - primitive mutations, single responsibility each.
+
+Every action:
+- is deterministic
+- is idempotent (no-op if already in target state)
+- returns ActionResult
+- scopes side effects to the target repo_path
+"""
+
+from dataclasses import dataclass
+from typing import Self
+
+
+@dataclass
+class ActionResult:
+    """Result of performing an action."""
+
+    ok: bool
+    changed: bool
+    message: str | None = None
+
+    @classmethod
+    def noop(cls, message: str | None = None) -> Self:
+        """Return an ActionResult representing a no-op (no changes made)."""
+        return cls(ok=True, changed=False, message=message)
+
+    @classmethod
+    def done(cls, message: str | None = None) -> Self:
+        """Return an ActionResult representing a successful action with changes."""
+        return cls(ok=True, changed=True, message=message)
+
+    @classmethod
+    def error(cls, message: str) -> Self:
+        """Return an ActionResult representing a failed action."""
+        return cls(ok=False, changed=False, message=message)

se_admin/actions/copy_file.py

@@ -0,0 +1,57 @@
+"""Filesystem mutation actions.
+
+CopyFile      - copy a file from source repo into target repo
+DeleteFile    - delete a file (no-op if missing)
+EnsureDirectory - create a directory if absent
+"""
+
+from pathlib import Path
+import shutil
+
+from se_admin.actions import ActionResult
+from se_admin.domain.operations import CopyFile, DeleteFile, EnsureDirectory
+
+
+def run_copy_file(
+    op: CopyFile,
+    *,
+    target_path: Path,
+    source_path: Path,
+) -> ActionResult:
+    """Copy src (relative to source_path) to dest (relative to target_path).
+
+    Idempotent: overwrites if already present (content may differ).
+    Creates intermediate directories as needed.
+    """
+    src = source_path / op.src
+    dest = target_path / op.dest
+
+    if not src.exists():
+        return ActionResult.error(f"Source not found: {src}")
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    already_identical = dest.exists() and dest.read_bytes() == src.read_bytes()
+    if already_identical:
+        return ActionResult.noop(f"Already identical: {op.dest}")
+
+    shutil.copy2(src, dest)
+    return ActionResult.done(f"Copied {op.src} to {op.dest}")
+
+
+def run_delete_file(op: DeleteFile, *, target_path: Path) -> ActionResult:
+    """Delete a file.  No-op if already missing."""
+    p = target_path / op.path
+    if not p.exists():
+        return ActionResult.noop(f"Already absent: {op.path}")
+    p.unlink()
+    return ActionResult.done(f"Deleted {op.path}")
+
+
+def run_ensure_directory(op: EnsureDirectory, *, target_path: Path) -> ActionResult:
+    """Create a directory (and parents) if not already present."""
+    d = target_path / op.path
+    if d.is_dir():
+        return ActionResult.noop(f"Already exists: {op.path}")
+    d.mkdir(parents=True, exist_ok=True)
+    return ActionResult.done(f"Created directory {op.path}")

se_admin/actions/dependabot.py

@@ -0,0 +1,58 @@
+"""src/se_admin/actions/dependabot.py.
+
+Actions related to Dependabot PRs, using GitHub CLI.
+"""
+
+import json
+from pathlib import Path
+
+from se_admin.utils.subprocesses import run_command
+
+# === List Dependabot PRs ===
+
+
+def list_dependabot_prs(repo_path: Path) -> list[dict]:
+    """List open Dependabot PRs in the given repo, with metadata."""
+    result = run_command(
+        [
+            "gh",
+            "pr",
+            "list",
+            "--author",
+            "dependabot[bot]",
+            "--state",
+            "open",
+            "--json",
+            "number,title,mergeable,reviewDecision,statusCheckRollup",
+        ],
+        cwd=repo_path,
+    )
+
+    if result.returncode != 0:
+        return []
+
+    return json.loads(result.stdout)
+
+
+# === Merge Dependabot PR ===
+
+
+def merge_dependabot_pr(repo_path: Path, pr_number: int) -> tuple[bool, str]:
+    """Merge the given Dependabot PR number in the given repo, using squash merge."""
+    result = run_command(
+        [
+            "gh",
+            "pr",
+            "merge",
+            str(pr_number),
+            "--squash",
+            "--delete-branch",
+        ],
+        cwd=repo_path,
+    )
+
+    if result.returncode == 0:
+        return True, result.stdout.strip()
+
+    message = result.stderr.strip() or result.stdout.strip()
+    return False, message

se_admin/actions/git_pull.py

@@ -0,0 +1,18 @@
+"""src/se_admin/actions/git_pull.py."""
+
+from pathlib import Path
+
+from se_admin.utils.subprocesses import run_command
+
+# === Git Pull ===
+
+
+def git_pull(repo_path: Path) -> tuple[bool, str]:
+    """Perform a git pull --ff-only in the given repo."""
+    result = run_command(["git", "pull", "--ff-only"], cwd=repo_path)
+
+    if result.returncode == 0:
+        return True, result.stdout.strip()
+
+    message = result.stderr.strip() or result.stdout.strip()
+    return False, message

se_admin/actions/patch_markdown.py

@@ -0,0 +1,108 @@
+"""Markdown section mutation action.
+
+PatchMarkdownSection - find a heading block and replace, insert, or remove it.
+
+Section boundaries are defined by ATX headings (# through ######).
+A section runs from its heading line to the line before the next
+heading of equal or lesser depth (or end of file).
+"""
+
+from pathlib import Path
+import re
+
+from se_admin.actions import ActionResult
+from se_admin.domain.operations import PatchMarkdownSection
+
+_HEADING = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)
+
+
+def _heading_depth(line: str) -> int:
+    m = re.match(r"^(#{1,6})\s", line)
+    return len(m.group(1)) if m else 0
+
+
+def _find_section(lines: list[str], heading_text: str) -> tuple[int, int] | None:
+    """Return (start, end) line indices for the section, or None if not found.
+
+    *start* is the heading line; *end* is exclusive (first line of next
+    same-or-lesser-depth heading, or len(lines)).
+    """
+    for i, line in enumerate(lines):
+        m = re.match(r"^(#{1,6})\s+(.+)$", line.rstrip())
+        if m and m.group(2).strip() == heading_text.strip():
+            depth = len(m.group(1))
+            end = len(lines)
+            for j in range(i + 1, len(lines)):
+                d = _heading_depth(lines[j])
+                if d > 0 and d <= depth:
+                    end = j
+                    break
+            return i, end
+    return None
+
+
+def run_patch_markdown_section(
+    op: PatchMarkdownSection, *, target_path: Path
+) -> ActionResult:
+    """Run the given PatchMarkdownSection operation on the target repo."""
+    dispatch = {
+        "replace": _replace_section,
+        "insert": _insert_section,
+        "remove": _remove_section,
+    }
+    fn = dispatch.get(op.operation)
+    if fn is None:
+        return ActionResult.error(
+            f"Unknown PatchMarkdownSection operation: {op.operation!r}"
+        )
+    return fn(op, target_path=target_path)
+
+
+def _replace_section(op: PatchMarkdownSection, *, target_path: Path) -> ActionResult:
+    p = target_path / op.file
+    if not p.exists():
+        return ActionResult.error(f"File not found: {op.file}")
+
+    lines = p.read_text(encoding="utf-8").splitlines(keepends=True)
+    span = _find_section(lines, op.section)
+    if span is None:
+        return ActionResult.error(f"Section not found: {op.section!r} in {op.file}")
+
+    start, end = span
+    replacement = (op.content or "").rstrip("\n") + "\n"
+    new_lines = lines[:start] + [replacement] + lines[end:]
+    p.write_text("".join(new_lines), encoding="utf-8")
+    return ActionResult.done(f"Replaced section {op.section!r} in {op.file}")
+
+
+def _insert_section(op: PatchMarkdownSection, *, target_path: Path) -> ActionResult:
+    """Append the section at end of file if not already present."""
+    p = target_path / op.file
+    text = p.read_text(encoding="utf-8") if p.exists() else ""
+    lines = text.splitlines(keepends=True)
+
+    if _find_section(lines, op.section) is not None:
+        return ActionResult.noop(
+            f"Section already present: {op.section!r} in {op.file}"
+        )
+
+    content = (op.content or "").rstrip("\n") + "\n"
+    separator = "\n" if text and not text.endswith("\n\n") else ""
+    p.write_text(text + separator + content, encoding="utf-8")
+    return ActionResult.done(f"Inserted section {op.section!r} in {op.file}")
+
+
+def _remove_section(op: PatchMarkdownSection, *, target_path: Path) -> ActionResult:
+    p = target_path / op.file
+    if not p.exists():
+        return ActionResult.noop(f"File absent: {op.file}")
+
+    lines = p.read_text(encoding="utf-8").splitlines(keepends=True)
+    span = _find_section(lines, op.section)
+    if span is None:
+        return ActionResult.noop(f"Section already absent: {op.section!r} in {op.file}")
+
+    start, end = span
+    new_lines = lines[:start] + lines[end:]
+    p.write_text("".join(new_lines), encoding="utf-8")
+    return ActionResult.done(f"Removed section {op.section!r} from {op.file}")

se_admin/actions/patch_toml.py

@@ -0,0 +1,149 @@
+"""TOML mutation action.
+
+PatchToml dispatches to one of five operations:
+  set_key            - write a value at a dotted key path
+  remove_key         - delete a key (no-op if absent)
+  add_dependency     - append to optional-dependency group (idempotent)
+  remove_dependency  - remove from optional-dependency group (idempotent)
+  ensure_table       - create a table header if absent
+
+Uses tomlkit for style-preserving round-trip editing.
+"""
+
+from pathlib import Path
+
+import tomlkit
+
+from se_admin.actions import ActionResult
+from se_admin.domain.operations import PatchToml
+
+
+def _load(p: Path) -> tomlkit.TOMLDocument:
+    if p.exists():
+        return tomlkit.parse(p.read_text(encoding="utf-8"))
+    return tomlkit.document()
+
+
+def _save(p: Path, doc: tomlkit.TOMLDocument) -> None:
+    p.write_text(tomlkit.dumps(doc), encoding="utf-8")
+
+
+def _resolve(doc: tomlkit.TOMLDocument, dotted: str) -> tuple[dict, str]:
+    """Walk dotted key path; return (parent_table, final_key)."""
+    parts = dotted.split(".")
+    current: dict = doc  # type: ignore[assignment]
+    for part in parts[:-1]:
+        if part not in current:
+            current[part] = tomlkit.table()
+        current = current[part]  # type: ignore[assignment]
+    return current, parts[-1]
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+
+def run_patch_toml(op: PatchToml, *, target_path: Path) -> ActionResult:
+    """Run a PatchToml operation."""
+    dispatch = {
+        "set_key": _set_key,
+        "remove_key": _remove_key,
+        "add_dependency": _add_dependency,
+        "remove_dependency": _remove_dependency,
+        "ensure_table": _ensure_table,
+    }
+    fn = dispatch.get(op.operation)
+    if fn is None:
+        return ActionResult.error(f"Unknown PatchToml operation: {op.operation!r}")
+    return fn(op, target_path=target_path)
+
+
+# ---------------------------------------------------------------------------
+# Operations
+# ---------------------------------------------------------------------------
+
+
+def _set_key(op: PatchToml, *, target_path: Path) -> ActionResult:
+    """Set a key in a TOML file."""
+    p = target_path / op.file
+    doc = _load(p)
+    parent, key = _resolve(doc, op.key)  # type: ignore[arg-type]
+    if parent.get(key) == op.value:
+        return ActionResult.noop(f"Key already set: {op.key}")
+    parent[key] = op.value
+    _save(p, doc)
+    return ActionResult.done(f"Set {op.key} = {op.value!r} in {op.file}")
+
+
+def _remove_key(op: PatchToml, *, target_path: Path) -> ActionResult:
+    p = target_path / op.file
+    if not p.exists():
+        return ActionResult.noop(f"File absent: {op.file}")
+    doc = _load(p)
+    parts = op.key.split(".")  # type: ignore[union-attr]
+    current: dict = doc  # type: ignore[assignment]
+    for part in parts[:-1]:
+        if part not in current:
+            return ActionResult.noop(f"Key already absent: {op.key}")
+        current = current[part]  # type: ignore[assignment]
+    final = parts[-1]
+    if final not in current:
+        return ActionResult.noop(f"Key already absent: {op.key}")
+    del current[final]
+    _save(p, doc)
+    return ActionResult.done(f"Removed {op.key} from {op.file}")
+
+
+def _add_dependency(op: PatchToml, *, target_path: Path) -> ActionResult:
+    """Add op.name to [project.optional-dependencies.<group>]."""
+    p = target_path / op.file
+    doc = _load(p)
+
+    project = doc.setdefault("project", tomlkit.table())
+    opt = project.setdefault("optional-dependencies", tomlkit.table())
+    group_list: list = opt.setdefault(op.group, tomlkit.array())
+
+    name_lower = op.name.lower()  # type: ignore[union-attr]
+    if any(str(d).lower().startswith(name_lower) for d in group_list):
+        return ActionResult.noop(f"{op.name!r} already in [{op.group}] in {op.file}")
+
+    group_list.append(op.name)
+    _save(p, doc)
+    return ActionResult.done(f"Added {op.name!r} to [{op.group}] in {op.file}")
+
+
+def _remove_dependency(op: PatchToml, *, target_path: Path) -> ActionResult:
+    """Remove op.name from [project.optional-dependencies.<group>]."""
+    p = target_path / op.file
+    if not p.exists():
+        return ActionResult.noop(f"File absent: {op.file}")
+    doc = _load(p)
+
+    group_list: list = (
+        doc.get("project", {}).get("optional-dependencies", {}).get(op.group, [])
+    )
+
+    name_lower = op.name.lower()  # type: ignore[union-attr]
+    matches = [d for d in group_list if str(d).lower().startswith(name_lower)]
+    if not matches:
+        return ActionResult.noop(
+            f"{op.name!r} already absent from [{op.group}] in {op.file}"
+        )
+
+    for m in matches:
+        group_list.remove(m)
+    _save(p, doc)
+    return ActionResult.done(f"Removed {op.name!r} from [{op.group}] in {op.file}")
+
+
+def _ensure_table(op: PatchToml, *, target_path: Path) -> ActionResult:
+    """Create a table at the dotted key path if not already present."""
+    p = target_path / op.file
+    doc = _load(p)
+    parent, key = _resolve(doc, op.key)  # type: ignore[arg-type]
+    if key in parent:
+        return ActionResult.noop(f"Table already exists: {op.key}")
+    parent[key] = tomlkit.table()
+    _save(p, doc)
+    return ActionResult.done(f"Created table {op.key} in {op.file}")

se_admin/actions/replace_file.py

@@ -0,0 +1,93 @@
+"""File replacement and workflow mutation actions.
+
+ReplaceFile     - overwrite a file unconditionally from canonical source
+EnsureWorkflow  - copy workflow into .github/workflows/ if not present
+ReplaceWorkflow - overwrite a workflow file unconditionally
+RemoveWorkflow  - delete a workflow file (no-op if missing)
+"""
+
+from pathlib import Path
+import shutil
+
+from se_admin.actions import ActionResult
+from se_admin.domain.operations import (
+    EnsureWorkflow,
+    RemoveWorkflow,
+    ReplaceFile,
+    ReplaceWorkflow,
+)
+
+_WORKFLOWS = ".github/workflows"
+
+
+def run_replace_file(
+    op: ReplaceFile,
+    *,
+    target_path: Path,
+    source_path: Path,
+) -> ActionResult:
+    """Overwrite dest in target_path from src in source_path.
+
+    Always writes (unconditional replacement).
+    Creates intermediate directories as needed.
+    """
+    src = source_path / op.src
+    dest = target_path / op.dest
+
+    if not src.exists():
+        return ActionResult.error(f"Source not found: {src}")
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)
+    return ActionResult.done(f"Replaced {op.dest}")
+
+
+def run_ensure_workflow(
+    op: EnsureWorkflow,
+    *,
+    target_path: Path,
+    source_path: Path,
+) -> ActionResult:
+    """Copy workflow into .github/workflows/ only if not already present."""
+    dest = target_path / _WORKFLOWS / op.name
+    if dest.exists():
+        return ActionResult.noop(f"Workflow already present: {op.name}")
+
+    src = source_path / op.src
+    if not src.exists():
+        return ActionResult.error(f"Source workflow not found: {src}")
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)
+    return ActionResult.done(f"Added workflow {op.name}")
+
+
+def run_replace_workflow(
+    op: ReplaceWorkflow,
+    *,
+    target_path: Path,
+    source_path: Path,
+) -> ActionResult:
+    """Overwrite a workflow file unconditionally."""
+    src = source_path / op.src
+    dest = target_path / _WORKFLOWS / op.name
+
+    if not src.exists():
+        return ActionResult.error(f"Source workflow not found: {src}")
+
+    already_identical = dest.exists() and dest.read_bytes() == src.read_bytes()
+    if already_identical:
+        return ActionResult.noop(f"Workflow already up to date: {op.name}")
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)
+    return ActionResult.done(f"Replaced workflow {op.name}")
+
+
+def run_remove_workflow(op: RemoveWorkflow, *, target_path: Path) -> ActionResult:
+    """Delete a workflow file.  No-op if already missing."""
+    p = target_path / _WORKFLOWS / op.name
+    if not p.exists():
+        return ActionResult.noop(f"Workflow already absent: {op.name}")
+    p.unlink()
+    return ActionResult.done(f"Removed workflow {op.name}")

se_admin/actions/run_command.py

@@ -0,0 +1,38 @@
+"""Process mutation action.
+
+RunCommand - run a shell command inside the target repo directory.
+"""
+
+from pathlib import Path
+import subprocess
+
+from se_admin.actions import ActionResult
+from se_admin.domain.operations import RunCommand
+
+
+def run_run_command(op: RunCommand, *, target_path: Path) -> ActionResult:
+    """Run op.command with op.args in target_path.
+
+    Returns ActionResult.done on exit code 0, ActionResult.error otherwise.
+    stdout/stderr are captured and surfaced in the message on failure.
+    """
+    cmd = [op.command, *op.args]
+
+    result = subprocess.run(  # noqa: S603
+        cmd,
+        cwd=target_path,
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode == 0:
+        return ActionResult.done(
+            f"Ran {' '.join(cmd)!r}"
+            + (f": {result.stdout.strip()}" if result.stdout.strip() else "")
+        )
+
+    detail = result.stderr.strip() or result.stdout.strip()
+    return ActionResult.error(
+        f"Command failed (exit {result.returncode}): {' '.join(cmd)!r}"
+        + (f"\n{detail}" if detail else "")
+    )