potent 0.1.0__tar.gz

potent-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.3
+Name: potent
+Version: 0.1.0
+Summary: Add your description here
+Author: David Brownman
+Author-email: David Brownman <oss@xavd.id>
+Requires-Dist: pydantic>=2.11.9
+Requires-Dist: rich>=14.1.0
+Requires-Dist: typer>=0.19.2
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# potent
+
+A CLI for running idem**potent** shell scripts.

potent-0.1.0/README.md

@@ -0,0 +1,3 @@
+# potent
+
+A CLI for running idem**potent** shell scripts.

potent-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "potent"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "David Brownman", email = "oss@xavd.id" }]
+requires-python = ">=3.12"
+dependencies = ["pydantic>=2.11.9", "rich>=14.1.0", "typer>=0.19.2"]
+
+[project.scripts]
+potent = "potent:main"
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = [
+    "E",    # PEP8 recommendations
+    "F",    # bugs
+    "I001", # import sorting
+    "BLE",  # catching root Exception
+    "A",    # built-in shadowing
+    "C4",   # unnecessary comprehensions
+    "ISC",  # implicit string concat
+    "PIE",  # misc useful lints
+    "Q",    # better quoting behavior
+    "RSE",  # no parens on exceptions that lack args
+    "RET",  # more correct return behavior
+    "SIM",  # general style things
+    "TC",   # type-only imports should be in a typecheck block
+    "ARG",  # unused args
+    "PTH",  # use pathlib
+    "FLY",  # short "".join calls
+    "PERF", # performance hints
+    "PL",   # pylint, general recommendations
+    # "RUF", # these are a little picky for me
+]
+
+ignore = [
+    "E501",    # skip enforcing line length
+    "E741",    # ignore short variable names
+    "PLR2004", # magic values
+    "PLR0911", # too many returns
+    "PLR0912", # too many branches
+    "PLR0913", # too many arguments
+    'Q000',    # single quotes; handled by formatter
+]
+
+unfixable = [
+    "F401", # don't remove unused imports
+    "F841", # don't remove unused variables
+]
+
+[dependency-groups]
+dev = ["pytest>=8.4.2", "ruff>=0.13.3"]

potent-0.1.0/src/potent/__init__.py

@@ -0,0 +1,25 @@
+import typer
+
+from potent.commands.dump_schema import app as dump_schema
+from potent.commands.reset import app as reset
+from potent.commands.run import app as run
+from potent.commands.validate import app as validate
+
+# COMMAND IMPORTS ^
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Idempotently run commands across folders.",
+    # hide the completion args
+    add_completion=False,
+)
+
+app.add_typer(validate)
+app.add_typer(dump_schema)
+app.add_typer(run)
+app.add_typer(reset)
+# COMMANDS ^
+
+
+def main():
+    app()

potent-0.1.0/src/potent/commands/_types.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+
+def is_plan_json(_ctx: typer.Context, _param: typer.CallbackParam, value: Path):
+    if value.suffixes != [".plan", ".json"]:
+        raise typer.BadParameter("File must have .plan.json extension")
+    return value
+
+
+# important that this _doesn't_ have a `type PlainJson =` declaration
+PlanJson = Annotated[
+    Path,
+    typer.Argument(
+        exists=True, dir_okay=False, resolve_path=True, callback=is_plan_json
+    ),
+]

potent-0.1.0/src/potent/commands/dump_schema.py

@@ -0,0 +1,15 @@
+import json
+from pathlib import Path
+
+import typer
+
+from potent.shellprint import Shellprint
+
+app = typer.Typer()
+
+
+@app.command()
+def dump_schema():
+    Path(__file__, "..", "..", "..", "..", "schema.json").resolve().write_text(
+        json.dumps(Shellprint.model_json_schema(), indent=2)
+    )

potent-0.1.0/src/potent/commands/reset.py

@@ -0,0 +1,17 @@
+import typer
+
+from potent.commands._types import PlanJson
+from potent.shellprint import Shellprint
+
+app = typer.Typer()
+
+
+@app.command()
+def reset(path: PlanJson):
+    """
+    Resets a plan file so it can be run again from scratch.
+    """
+    with path.open("r+") as plan_file:
+        plan = Shellprint.from_file(plan_file)
+        plan.reset()
+        plan.save(plan_file)

potent-0.1.0/src/potent/commands/run.py

@@ -0,0 +1,80 @@
+from pathlib import Path
+from subprocess import CalledProcessError
+from time import sleep
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+# from rich.live import Live
+from potent.commands._types import PlanJson
+from potent.shellprint import Shellprint
+
+app = typer.Typer()
+
+
+def directory_header(console: Console, directory: Path) -> None:
+    return console.rule(
+        f"📂 [bold underline]{directory.name}[/] 📂", style="bright_cyan"
+    )
+
+
+@app.command()
+def run(path: PlanJson):
+    # TODO: probably make this internal to the class??
+    # can maybe use a generator so the presentation is controlled in the CLI
+    plan = Shellprint.from_path(path)
+    console = Console()
+
+    console.print(f"Running [bold yellow]{str(path)}")
+
+    with path.open("r+") as plan_file:
+        for directory in plan.directories:
+            console.print()
+            if plan.directory_complete(directory):
+                directory_header(console, directory)
+
+                # directory_spinner.ok(f"☑️ {directory.name}")
+                console.print("☑️ [green]already finished")
+                continue
+
+            try:
+                directory_header(console, directory)
+
+                for step in plan.steps:
+                    success = None
+                    output = ""
+                    style = ""
+                    if step.completed(directory):
+                        output = "Already completed"
+                        subtitle = "skipped"
+                    else:
+                        result = step.run(directory)
+                        plan.save(plan_file)
+                        if success := result.success:
+                            style = "green"
+                            subtitle = "Succeeded"
+                        else:
+                            style = "red"
+                            subtitle = "Failed"
+
+                        output = result.output or "[dim]no output"
+
+                    console.print(
+                        Panel(
+                            f"\n{output.strip()}\n",
+                            title=f"[dim white]step[not dim]: {step.slug}",
+                            title_align="left",
+                            border_style=style,
+                            subtitle=f"[dim white]result:[/] {subtitle}",
+                            subtitle_align="left",
+                        )
+                    )
+                    console.print()
+                    if success is False:
+                        break
+
+            except NotImplementedError:
+                # directory_spinner.fail("ERR")
+                print("    err!")
+                continue

potent-0.1.0/src/potent/commands/validate.py

@@ -0,0 +1,24 @@
+import rich
+import typer
+
+from potent.commands._types import PlanJson
+from potent.shellprint import Shellprint
+
+app = typer.Typer()
+
+
+@app.command()
+def validate(path: PlanJson):
+    # can handle this pretty cleanly by pegging the step location and the error type (missing, etc)
+    # probably want to hide the traceback though
+    # and maybe return
+    # can raise typer.Exit(code=int)
+    # print(f"Shellprint @ {str(path)}")
+    # print(Shellprint.from_path(path))
+    rich.print(Shellprint.from_path(path).summarize(path))
+
+
+# could try to wrap, but the basic error is pretty good:
+# from pydantic import ValidationError
+# except ValidationError as e:
+# print(e.errors()[0])

potent-0.1.0/src/potent/directives/_base.py

@@ -0,0 +1,81 @@
+import subprocess
+from pathlib import Path
+from typing import Annotated, Literal, Optional, final
+
+from pydantic import AfterValidator, BaseModel, DirectoryPath
+
+from potent.util import truthy_list
+
+Status = Literal["not-started", "failed", "completed"]
+
+
+# useful for writing back absolute paths, which is good for portability
+def make_abs_path(value: Path) -> Path:
+    if not value.is_absolute():
+        raise ValueError("path is not absolute")
+    return value
+
+
+AbsPath = Annotated[
+    DirectoryPath,
+    AfterValidator(make_abs_path),
+]
+
+
+class DirectiveResult(BaseModel):
+    success: bool
+    output: str
+
+    @staticmethod
+    def from_process(result: subprocess.CompletedProcess[str]):
+        return DirectiveResult(success=result.returncode == 0, output=result.stdout)
+
+
+class EmptyConfig(BaseModel):
+    pass
+
+
+class BaseDirective(BaseModel):
+    comment: Optional[str] = None
+    directory_statuses: dict[AbsPath, Status] = {}
+    config: EmptyConfig = EmptyConfig()
+
+    @final
+    def run(self, directory: Path) -> DirectiveResult:
+        # try:
+        result = self._run(directory)
+        # except Exception:  # noqa: BLE001
+        #     success = False
+
+        self.directory_statuses[directory] = "completed" if result.success else "failed"
+        return result
+
+    def _run(self, directory: Path) -> DirectiveResult:
+        raise NotImplementedError
+
+    def reset(self) -> None:
+        self.directory_statuses = {}
+
+    def completed(self, directory: Path) -> bool:
+        return self.directory_statuses.get(directory) == "completed"
+
+    def failed(self, directory: Path) -> bool:
+        return self.directory_statuses.get(directory) == "failed"
+
+    def initialize_dirs(self, directories: list[Path]) -> None:
+        self.directory_statuses |= dict.fromkeys(directories, "not-started")
+
+    def _run_cmd(
+        self, directory: Path, cmd: list[str]
+    ) -> subprocess.CompletedProcess[str]:
+        """
+        helper for shelling out
+        """
+        return subprocess.run(
+            truthy_list(cmd),
+            cwd=directory,
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )

potent-0.1.0/src/potent/directives/clean_workdir.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+from time import sleep
+from typing import Literal, override
+
+from potent.directives._base import BaseDirective, DirectiveResult
+
+
+class CleanWorkdir(BaseDirective):
+    slug: Literal["clean-status"]
+
+    @override
+    def _run(self, directory: Path) -> DirectiveResult:
+        result = self._run_cmd(directory, ["git", "status", "--porcelain"])
+        sleep(2)
+
+        success = not result.stdout
+
+        return DirectiveResult(
+            success=success,
+            output="Working directory clean!"
+            if success
+            else "Uncommitted changes; clear before proceeding.",
+        )

potent-0.1.0/src/potent/directives/git_pull.py

@@ -0,0 +1,21 @@
+import subprocess
+from pathlib import Path
+from typing import Literal
+
+from potent.directives._base import BaseDirective, DirectiveResult
+
+
+class GitPull(BaseDirective):
+    slug: Literal["git-pull"]
+
+    def _run(self, directory: Path) -> DirectiveResult:
+        result = self._run_cmd(directory, ["git", "pull"])
+
+        # print stdout? not sure if/when it's useful, can be long
+        return DirectiveResult.from_process(result)
+
+        if result.returncode == 0:
+            return True
+
+        # print(result.stderr)
+        return False

potent-0.1.0/src/potent/directives/switch_branch.py

@@ -0,0 +1,49 @@
+import subprocess
+from pathlib import Path
+from typing import Literal, override
+
+from pydantic import BaseModel
+
+from potent.directives._base import BaseDirective, DirectiveResult
+from potent.util import truthy_list
+
+
+class Config(BaseModel):
+    branch: str
+    create: bool = False
+
+
+class SwitchBranch(BaseDirective):
+    """
+    Creates a branch if missing. Re-verifies that you're on that branch during every run.
+    """
+
+    slug: Literal["switch-branch"]
+    config: Config
+    """
+    branch name
+    """
+    # base: Optional[str]
+    # """
+    # Branch to base the new branch off of. Will switch to this first to create the branch.
+    # """
+
+    @override
+    def _run(self, directory: Path) -> DirectiveResult:
+        result = self._run_cmd(
+            directory,
+            ["git", "switch", "-c" if self.config.create else "", self.config.branch],
+        )
+
+        return DirectiveResult.from_process(result)
+
+        if result.returncode == 0:
+            return True
+
+        print(result.stderr)
+        return False
+
+    # def verify(self) -> None:
+    #     """
+    #     verify branch on every run
+    #     """

potent-0.1.0/src/potent/shellprint.py

@@ -0,0 +1,132 @@
+from pathlib import Path
+from typing import Annotated, Any, Literal, Optional, TextIO, Union
+
+from annotated_types import Len
+from pydantic import AfterValidator, BaseModel, Field
+from rich.console import Group
+from rich.tree import Tree
+
+from potent.directives._base import AbsPath
+from potent.directives.clean_workdir import CleanWorkdir
+from potent.directives.git_pull import GitPull
+from potent.directives.switch_branch import SwitchBranch
+
+
+def unique_items(v):
+    if len(v) != len(set(v)):
+        raise ValueError("list is not unique")
+    return v
+
+
+Version = Literal["v1"]
+
+
+class Shellprint(BaseModel):
+    version: Version = "v1"
+    comment: Optional[str] = None
+    steps: list[
+        Annotated[
+            Union[
+                GitPull,
+                SwitchBranch,
+                CleanWorkdir,
+            ],
+            Field(discriminator="slug"),
+        ]
+    ]
+    directories: Annotated[
+        list[AbsPath],
+        Len(min_length=1),
+        AfterValidator(unique_items),
+    ]
+    _path: Optional[Path] = None
+
+    @staticmethod
+    def from_file(f: TextIO) -> "Shellprint":
+        return Shellprint.model_validate_json(f.read())
+
+    @staticmethod
+    def from_path(f: Path) -> "Shellprint":
+        plan = Shellprint.model_validate_json(f.read_text())
+        plan._path = f
+        return plan
+
+    # def run(self):
+    #     if not self._path:
+    #         raise ValueError("Can't run plan without path")
+
+    #     with self._path.open("r+") as fp:
+    #         pass
+
+    def save(self, f: TextIO):
+        """
+        Operates on an open file for performance reasons
+        """
+        f.seek(0)
+        f.truncate()
+        f.write(self.model_dump_json(indent=2))
+        f.flush()
+
+    def reset(self):
+        for p in self.steps:
+            p.reset()
+
+    def render(self) -> Group:
+        """
+        Outputs a task tree suitable for Rich to show progress (w/ spinners)
+        """
+        raise NotImplementedError
+
+    def directory_complete(self, directory: Path) -> bool:
+        return all(s.completed(directory) for s in self.steps)
+
+    def directory_failed(self, directory: Path) -> bool:
+        return any(s.failed(directory) for s in self.steps)
+
+    # def directory_started(self, directory: Path) -> bool:
+    #     return any(s.completed(directory) for s in self.steps)
+
+    def summarize(self, path: Path) -> Tree:
+        """
+        Show this plan as plaintext
+        """
+
+        root = Tree(f"[yellow] {path.absolute()}")
+        # only print all steps if nothing has printed them yet
+        should_print_all = True
+
+        for d in self.directories:
+            # res.append("")
+            if self.directory_complete(d):
+                root.add(f"✅ {d.name}", style="green", guide_style="green")
+
+                # res.append(f"✅ {d.name}")
+            elif self.directory_failed(d):
+                should_print_all = False
+                failed = root.add(f"❌ {d.name}", style="red", guide_style="red")
+                # res.append(f"❌ {d.name}:\n")
+                for s in self.steps:
+                    if s.completed(d):
+                        failed.add(f"✅ {s.slug}", style="green")
+                        # res.append(f"  ✅ {s.slug}")
+                    elif s.failed(d):
+                        failed.add(f"❌ {s.slug}", style="red")
+                        # res.append(f"  ❌ {s.slug}")
+                    else:
+                        failed.add(f"⌛ {s.slug}", style="dim white")
+                        # res.append(f"  ⌛ {s.slug}")
+            else:
+                pending = root.add(f"⌛ {d.name}", style="yellow")
+                if should_print_all:
+                    should_print_all = False
+                    for s in self.steps:
+                        pending.add(f"{s.slug}", style="white")
+                else:
+                    pending.add("same as above", style="dim white")
+
+                # res.append(f"⌛ {d.name}")
+
+        # res.append("")
+
+        # return "\n".join(res)
+        return root

potent-0.1.0/src/potent/util.py

@@ -0,0 +1,5 @@
+def truthy_list[T](l: list[T]) -> list[T]:
+    """
+    Return a list with the falsy elements removed
+    """
+    return list(filter(None, l))