potent 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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/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/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))

potent-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+potent/__init__.py,sha256=ce918eb97d15f4a3960ef5f2b5dd0764eb851483a1ca7d80309bd9841cebf7b4,525
+potent/commands/_types.py,sha256=47779c61185599d4d8aa3028c40ebc278c0b6439e3e9434d6839704cee2bfaf4,496
+potent/commands/dump_schema.py,sha256=4bd3e87987e7d938718d8762c8a53d48e524ddb5803d22d1535fadb54eb71c84,297
+potent/commands/reset.py,sha256=667887b00ee9439fe514344ff5cc019c4db5c24dec26e06a64c5de4dc470722e,376
+potent/commands/run.py,sha256=930eee66eb58e821bba1b4c9f6fca36b65e36ffd5d0e6447366e14173e89085d,2681
+potent/commands/validate.py,sha256=558d26917e2a52dc2b1bce5d18cdbe1ac85be69098255f1460f1bae13e5475cb,680
+potent/directives/_base.py,sha256=27e57e0e150eae39f34b9a7f25c147bea1c88ae1855156d609a6bd9bb44adc09,2207
+potent/directives/clean_workdir.py,sha256=13267d8c6fdb366c671006d29201603af58e41898b200282a7462f091b528349,632
+potent/directives/git_pull.py,sha256=81206ffcfd80fc34a7bf8f09151b8c6ff74de7827a0e14bddca5f22816ce8857,548
+potent/directives/switch_branch.py,sha256=13214177ccad7fa7fe7cc3222cea693e0a94c835e1b823530d43eea09eee2ce2,1137
+potent/shellprint.py,sha256=d5398996012996e9c983c086be233334b0a0f26f82d4ad6311d903dbea654202,4035
+potent/util.py,sha256=3296ad7a17b5de3d650b87cd6f88ec7513b3830e24e628b88a44c918b459d249,142
+potent-0.1.0.dist-info/WHEEL,sha256=b6dc288e80aa2d1b1518ddb3502fd5b53e8fd6cb507ed2a4f932e9e6088b264a,78
+potent-0.1.0.dist-info/entry_points.txt,sha256=1bebb82783e5027775b9f2a63e7d53332c7db78888b88ceb13513e786b98bcc9,40
+potent-0.1.0.dist-info/METADATA,sha256=510f1974b0b45981d5ce14084d261e24e1c066d13bdf2943c37dacbb61cad12c,363
+potent-0.1.0.dist-info/RECORD,,

potent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.4
+Root-Is-Purelib: true
+Tag: py3-none-any

potent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+potent = potent:main
+