ai-push-hooks 0.1.18 → 0.2.0

package/pyproject.toml

@@ -4,23 +4,31 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.1.18"
-description = "Modular AI push-hook workflow runner"
+version = "0.2.0"
+description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
-authors = [{ name = "ai-push-hooks contributors" }]
+authors = [{ name = "Shane Bishop" }]
 keywords = ["git", "lefthook", "docs", "ai", "pre-push"]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Software Development :: Version Control :: Git",
 ]
+dependencies = ["tomli>=2.0.0; python_version < '3.11'"]
+
+[project.urls]
+Homepage = "https://github.com/shanebishop1/ai-push-hooks"
+Repository = "https://github.com/shanebishop1/ai-push-hooks.git"
+Issues = "https://github.com/shanebishop1/ai-push-hooks/issues"
+Changelog = "https://github.com/shanebishop1/ai-push-hooks/blob/main/CHANGELOG.md"
 
 [project.scripts]
 ai-push-hooks = "ai_push_hooks.cli:main"

package/src/ai_push_hooks/artifacts.py

@@ -6,6 +6,15 @@ from datetime import datetime, timezone
 from typing import Any
 from uuid import uuid4
 
+from .paths import (
+    ensure_private_directory,
+    is_path_within,
+    path_has_symlink,
+    path_is_link_or_reparse,
+    resolve_contained_path,
+    validate_path_component,
+    write_text_no_follow,
+)
 from .types import HookError, ModuleRuntimeState
 
 
@@ -19,13 +28,42 @@ class ArtifactStore:
         self.run_dir = run_dir
 
     def prepare(self) -> pathlib.Path:
-        self.run_dir.mkdir(parents=True, exist_ok=True)
-        return self.run_dir
+        if path_is_link_or_reparse(self.run_dir):
+            raise HookError(
+                f"Artifact run directory must not be a symlink or reparse point: {self.run_dir}"
+            )
+        return ensure_private_directory(self.run_dir)
 
     def step_dir(self, module_id: str, step_index: int, step_id: str) -> pathlib.Path:
-        path = self.run_dir / module_id / f"{step_index:02d}-{step_id}"
-        path.mkdir(parents=True, exist_ok=True)
-        return path
+        module_name = validate_path_component(module_id, "Artifact module id")
+        step_name = validate_path_component(step_id, "Artifact step id")
+        lexical_module_path = self.run_dir / module_name
+        if path_has_symlink(self.run_dir, lexical_module_path):
+            raise HookError(f"Artifact module path must not traverse a symlink: {module_id}")
+        module_path = resolve_contained_path(self.run_dir, module_name, "Artifact module path")
+        lexical_step_path = module_path / f"{step_index:02d}-{step_name}"
+        if path_has_symlink(self.run_dir, lexical_step_path):
+            raise HookError(f"Artifact step path must not traverse a symlink: {step_id}")
+        path = resolve_contained_path(
+            module_path,
+            f"{step_index:02d}-{step_name}",
+            "Artifact step path",
+        )
+        return ensure_private_directory(path)
+
+    def _artifact_path(
+        self,
+        module_id: str,
+        step_index: int,
+        step_id: str,
+        artifact_name: str,
+    ) -> pathlib.Path:
+        name = validate_path_component(artifact_name, "Artifact name")
+        return resolve_contained_path(
+            self.step_dir(module_id, step_index, step_id),
+            name,
+            "Artifact output path",
+        )
 
     def register(
         self,
@@ -34,6 +72,13 @@ class ArtifactStore:
         artifact_name: str,
         path: pathlib.Path,
     ) -> pathlib.Path:
+        validate_path_component(step_id, "Artifact step id")
+        validate_path_component(artifact_name, "Artifact name")
+        resolved_run_dir = self.run_dir.resolve(strict=False)
+        if path_has_symlink(self.run_dir, path):
+            raise HookError(f"Artifact path must not traverse a symlink: {path}")
+        if not is_path_within(path.resolve(strict=False), resolved_run_dir):
+            raise HookError(f"Artifact path escapes run directory: {path}")
         state.artifacts[f"{step_id}/{artifact_name}"] = path
         return path
 
@@ -45,8 +90,8 @@ class ArtifactStore:
         artifact_name: str,
         content: str,
     ) -> pathlib.Path:
-        path = self.step_dir(state.module.id, step_index, step_id) / artifact_name
-        path.write_text(content, encoding="utf-8")
+        path = self._artifact_path(state.module.id, step_index, step_id, artifact_name)
+        write_text_no_follow(path, content)
         return self.register(state, step_id, artifact_name, path)
 
     def write_json(
@@ -57,14 +102,17 @@ class ArtifactStore:
         artifact_name: str,
         payload: Any,
     ) -> pathlib.Path:
-        path = self.step_dir(state.module.id, step_index, step_id) / artifact_name
-        path.write_text(json.dumps(payload, ensure_ascii=True, indent=2) + "\n", encoding="utf-8")
+        path = self._artifact_path(state.module.id, step_index, step_id, artifact_name)
+        write_text_no_follow(path, json.dumps(payload, ensure_ascii=True, indent=2) + "\n")
         return self.register(state, step_id, artifact_name, path)
 
     def resolve_input(self, state: ModuleRuntimeState, reference: str) -> pathlib.Path:
         if ":" in reference:
-            module_and_step, artifact_name = reference.split("/", 1)
-            module_id, step_id = module_and_step.split(":", 1)
+            try:
+                module_and_step, artifact_name = reference.split("/", 1)
+                module_id, step_id = module_and_step.split(":", 1)
+            except ValueError as exc:
+                raise HookError(f"Invalid artifact reference: {reference}") from exc
             key = f"{module_id}:{step_id}/{artifact_name}"
         else:
             key = reference
@@ -72,6 +120,11 @@ class ArtifactStore:
         if path is None:
             path = state.artifacts.get(reference)
         if path is None:
+            if ":" in reference:
+                raise HookError(
+                    f"Unknown artifact reference: {reference}. Artifact references are module-local; "
+                    "use '<step>/<artifact>' from an earlier step in the same module."
+                )
             raise HookError(f"Unknown artifact reference: {reference}")
         return path
 
@@ -83,4 +136,7 @@ class ArtifactStore:
         artifact_name: str,
         path: pathlib.Path,
     ) -> None:
+        validate_path_component(module_id, "Artifact module id")
+        validate_path_component(step_id, "Artifact step id")
+        validate_path_component(artifact_name, "Artifact name")
         state.artifacts[f"{module_id}:{step_id}/{artifact_name}"] = path

package/src/ai_push_hooks/cli.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 
 import argparse
+import os
 import pathlib
+import stat
 import sys
 
 from .hook import run_hook
+from .install import install_hook
+from .paths import path_is_link_or_reparse, write_text_no_follow
 from .prompts_builtin import MINIMAL_DOCS_TEMPLATE
 from .types import HookError
 
@@ -20,6 +24,11 @@ def _build_parser() -> argparse.ArgumentParser:
     init_parser = subparsers.add_parser("init", help="Write a starter config")
     init_parser.add_argument("--template", default="minimal-docs")
     init_parser.add_argument("--force", action="store_true")
+
+    install_parser = subparsers.add_parser(
+        "install", help="Install a repo-local pre-push hook"
+    )
+    install_parser.add_argument("--force", action="store_true")
     return parser
 
 
@@ -28,9 +37,55 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
         raise HookError("Only `minimal-docs` is supported")
     target_dir = cwd or pathlib.Path.cwd()
     config_path = target_dir / "ai-push-hooks.toml"
-    if config_path.exists() and not force:
-        raise HookError(f"Refusing to overwrite existing config without --force: {config_path}")
-    config_path.write_text(MINIMAL_DOCS_TEMPLATE, encoding="utf-8")
+    if force:
+        try:
+            metadata = config_path.lstat()
+        except FileNotFoundError:
+            metadata = None
+        except OSError as exc:
+            raise HookError(f"Could not inspect config path {config_path}: {exc}") from exc
+        if metadata is not None:
+            if path_is_link_or_reparse(config_path):
+                raise HookError(f"Refusing to replace symlink or reparse point: {config_path}")
+            if not stat.S_ISREG(metadata.st_mode):
+                raise HookError(f"Refusing to replace non-regular config path: {config_path}")
+        try:
+            write_text_no_follow(config_path, MINIMAL_DOCS_TEMPLATE)
+        except HookError:
+            raise
+        except OSError as exc:
+            raise HookError(f"Could not write config file {config_path}: {exc}") from exc
+    else:
+        try:
+            metadata = config_path.lstat()
+        except FileNotFoundError:
+            metadata = None
+        except OSError as exc:
+            raise HookError(f"Could not inspect config path {config_path}: {exc}") from exc
+        if metadata is not None:
+            if path_is_link_or_reparse(config_path):
+                raise HookError(f"Refusing to overwrite symlink or reparse point: {config_path}")
+            if not stat.S_ISREG(metadata.st_mode):
+                raise HookError(f"Refusing to overwrite non-regular config path: {config_path}")
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0)
+        flags |= getattr(os, "O_NOFOLLOW", 0)
+        try:
+            descriptor = os.open(config_path, flags, 0o600)
+        except FileExistsError as exc:
+            raise HookError(
+                f"Refusing to overwrite existing config without --force: {config_path}"
+            ) from exc
+        except OSError as exc:
+            raise HookError(f"Could not create config file {config_path}: {exc}") from exc
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                descriptor = -1
+                handle.write(MINIMAL_DOCS_TEMPLATE)
+                handle.flush()
+                os.fsync(handle.fileno())
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
     sys.stdout.write(str(config_path) + "\n")
     return 0
 
@@ -43,6 +98,8 @@ def main(argv: list[str] | None = None) -> int:
             return run_hook(args.remote_name, args.remote_url)
         if args.command == "init":
             return init_config(args.template, args.force)
+        if args.command == "install":
+            return install_hook(args.force)
         raise HookError(f"Unknown command: {args.command}")
     except HookError as exc:
         sys.stderr.write(f"[ai-push-hooks] {exc}\n")