ai-push-hooks 0.3.0 → 0.3.2

package/SECURITY.md

@@ -52,8 +52,9 @@ or the environment. A single-file callback may import dependencies already
 installed in the interpreter running the hook, but the host never runs `pip`;
 sibling/package-relative imports and installed-module references are not a
 supported loading mechanism. The callback runs in-process as trusted user code:
-there is no SDK, sandbox, filesystem write prevention, or enforceable hard
-timeout. Its `PluginContext` has frozen mappings/snapshots and validated `Path`
+there is no SDK, sandbox, filesystem write prevention, or in-process timeout.
+The configured timeout applies to child runner processes, not callback code.
+Its `PluginContext` has frozen mappings/snapshots and validated `Path`
 values, but those paths do not make file contents read-only. Callback prints and
 direct writes can disclose or modify host data and are outside host
 sanitization. Use a separately managed low-privilege process/container/VM when
@@ -97,22 +98,26 @@ captured stdout/stderr are each bounded to 16 MiB; staging is bounded to 10,000
 entries/256 MiB and Git metadata snapshots to 20,000 entries/64 MiB. These
 limits are resource and scope controls, not isolation. Existing baseline checks
 are not an atomic CAS against arbitrary external writers, and automatic rollback
-is avoided to protect pre-existing user changes. See the README's [runner
-profiles and access modes](README.md#runner-profiles-and-access-modes).
+is avoided to protect pre-existing user changes. See [runner profiles and
+access modes](docs/configuration.md#runner-profiles).
+
+Apply intentionally repeats integrity and state scans: it snapshots the checkout
+and Git metadata, inventories staging before and after the runner, checks each
+propagation operation against its baseline, and verifies the propagated result
+and protected state afterward. These repeated checks are defense in depth, not
+an atomic CAS or an automatic rollback.
 
 Timeout cleanup has platform limits: POSIX uses a private process group on a
 best-effort basis, while Windows can terminate only the direct child. Neither
 is a sandbox; Windows has no native beta evidence.
 
-## Tested security boundary
-
-The final pinned-Lefthook suite passed **407 tests with no skips**. The current
-evidence also includes the real OpenCode **1.18.29** contract smoke test with an
-in-process loopback mock provider and no external model call; its read probe
-checks that no Git-visible project files were mutated. It does not cover every
-provider, model, authentication mode, or live `apply` path.
-Installed Codex **0.148.0** and Claude **2.1.220** checks use only version/help
-output. Live Codex/Pi verification was intentionally not run pending separate
-approval; Claude live verification is pending because no subscription is
-available. Treat generated-hook path checks and the Lefthook runner as
-integration safeguards, not isolation boundaries.
+## Historical 0.3.0 security evidence
+
+The [0.3.0 release record](CHANGELOG.md#030---2026-09-09) documented a pinned
+Lefthook suite reporting **407 tests with no skips**, an OpenCode **1.18.29**
+contract smoke test with an in-process loopback mock provider and no external
+model call, and version/help-only checks for Codex **0.148.0** and Claude
+**2.1.220**. This is historical evidence, not a current suite result or proof
+for every provider, model, authentication mode, platform, or live `apply` path.
+Treat generated-hook path checks and the Lefthook runner as integration
+safeguards, not isolation boundaries.

package/ai-push-hooks.toml

@@ -12,7 +12,7 @@ base_branch = "main"
 # Repository callbacks use python = "path/to/file.py:callable" and command
 # steps use a direct argv array; both are trusted local code.
 runner = "opencode"
-model = "openai/gpt-5.6-terra"
+model = "openai/gpt-5.6-luna"
 variant = ""
 timeout_seconds = 800
 max_parallel = 2

package/bin/ai-push-hooks.js

@@ -6,16 +6,16 @@ const path = require('node:path');
 
 const packageRoot = path.resolve(__dirname, '..');
 const srcDir = path.join(packageRoot, 'src');
+const tomliWheel = path.join(packageRoot, 'vendor', 'tomli-2.4.0-py3-none-any.whl');
 const args = ['-m', 'ai_push_hooks', ...process.argv.slice(2)];
-const pythonCommands = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3', 'python'];
+const pythonCommands = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3', 'python'];
 
 function buildEnv() {
   const env = { ...process.env };
   env.AI_PUSH_HOOKS_NODE_EXECUTABLE = process.execPath;
   env.AI_PUSH_HOOKS_NODE_SCRIPT = fs.realpathSync(__filename);
-  env.PYTHONPATH = env.PYTHONPATH
-    ? `${srcDir}${path.delimiter}${env.PYTHONPATH}`
-    : srcDir;
+  // Pure-Python wheels are importable archives; no pip or install scripts needed.
+  env.PYTHONPATH = [srcDir, tomliWheel, env.PYTHONPATH].filter(Boolean).join(path.delimiter);
   return env;
 }
 
@@ -33,7 +33,7 @@ function canRunPackage(command) {
       '-c',
       'import sys; assert sys.version_info >= (3, 10); __import__("tomllib" if sys.version_info >= (3, 11) else "tomli")',
     ],
-    { stdio: 'ignore' },
+    { stdio: 'ignore', env: buildEnv() },
   );
   return check.status === 0;
 }
@@ -41,7 +41,7 @@ function canRunPackage(command) {
 const pythonCommand = pythonCommands.find(canRunPackage);
 if (!pythonCommand) {
   console.error(
-    '[ai-push-hooks] Python 3.11+ is required for npm installs. Python 3.10 can be used if tomli is installed.',
+    '[ai-push-hooks] Python 3.10+ is required and must be available on PATH.',
   );
   process.exit(1);
 }

package/docs/configuration.md

@@ -0,0 +1,263 @@
+# Configuration
+
+Define workflows in `ai-push-hooks.toml` at the repository root. Start with the [README example](../README.md#example-check-your-rules) or the [starter configuration](../ai-push-hooks.toml).
+
+## Installation
+
+The [npm quick start](../README.md#quick-start) installs a repository-local wrapper. It needs Node 18+ and Python 3.10-3.13 on the hook's `PATH`; the npm package does not bundle Python.
+
+For pnpm:
+
+```bash
+pnpm add -D ai-push-hooks@beta
+pnpm exec ai-push-hooks init --template minimal-docs
+pnpm exec ai-push-hooks install
+```
+
+For a Python-only installation:
+
+```bash
+python -m pip install ai-push-hooks
+ai-push-hooks init --template minimal-docs
+ai-push-hooks install
+```
+
+`uv tool install ai-push-hooks` or `pipx install ai-push-hooks` can replace the pip command. npm uses the `beta` tag while the package is in beta.
+
+AI steps need the selected CLI installed and authenticated with an available model. Deterministic-only workflows do not need one. `init` and `install` refuse to overwrite existing files; `--force` explicitly replaces them.
+
+## Modules And Steps
+
+`[workflow].modules` selects the modules to run. Define each module under `modules.<name>` with a non-empty list of steps. Modules are enabled by default; set `enabled = false` to disable one.
+
+Step inputs refer to earlier artifacts in the same module: `collect/push.diff`, for example. Cross-module inputs are not supported. Independent `collect` and `ask` work may run concurrently; built-in `exec`, `assert`, and `apply` steps are serialized. Trusted custom command runners, including project-access `ask` commands, are not enforced read-only.
+
+| Field | Used by | Meaning |
+| --- | --- | --- |
+| `id` | All | Unique step name within the module. |
+| `type` | All | `collect`, `ask`, `apply`, `exec`, or `assert`. |
+| `inputs` | Non-collector steps | Earlier module-local artifacts. |
+| `when_env` | All | Run only when the named environment variable is true. |
+| `collector` | `collect` | Built-in collector name. |
+| `prompt` | `ask`, `apply` | Inline instructions. |
+| `prompt_file` | `ask`, `apply` | Repository-relative prompt file. |
+| `fallback_prompt_id` | `ask`, `apply` | Built-in prompt name. |
+| `runner` | `ask`, `apply` | Override the default runner profile. |
+| `output` | `ask` | Required response artifact filename. |
+| `schema` | `ask` | Optional JSON schema name. Omit for plain text. |
+| `allow_paths` | `apply` | Required list of permitted edit globs. |
+| `executor` | `exec` | Built-in action name. |
+| `assertion` | `assert` | Built-in assertion name. |
+| `python` | `collect`, `exec`, `assert` | Repository-local callback reference. |
+| `options` | Python steps | JSON-compatible callback options. |
+| `command` | `exec`, `assert` | Direct argv command. |
+| `stdin` | Command steps | One declared input to send on stdin. |
+| `timeout_seconds` | Command steps | Positive timeout; default `60`. |
+
+Choose one handler per deterministic step: a built-in, a callback, or a command. Prompt resolution uses `prompt`, then `prompt_file`, then `fallback_prompt_id`.
+
+`ask` produces a response, not an automatic policy verdict. Use `assert` to evaluate findings when they should block. `apply` can run without a preceding `ask`; an input ending in `issues.json` containing `[]` skips the apply step.
+
+Upgrading from 0.2.1? Rename `type = "llm"` steps to `type = "ask"`.
+
+## Runner Profiles
+
+`[llm].runner` selects the default; a step's `runner` overrides it. Referenced profiles must exist under `[runners.<name>]`, except for the implicit OpenCode default.
+
+| Profile field | Values / behavior |
+| --- | --- |
+| `type` | Required: `opencode`, `codex`, `claude`, or `command`. |
+| `model` | Runner-specific model identifier. |
+| `project_access` | `artifacts` or `project`; OpenCode defaults to `artifacts`, others to `project`. |
+| `variant` | Optional OpenCode variant. |
+| `command` | Required argv array for command runners. |
+| `prompt_transport` | Command runners: `stdin` (default) or `argv`. |
+
+Without an explicit OpenCode profile, `[llm].model` and `[llm].variant` configure it. Explicit profiles use their own model settings. `AI_PUSH_HOOKS_MODEL` overrides the selected profile's model.
+
+Artifact mode supplies collected inputs in a scratch directory. Project mode lets analysis inspect the checkout. Apply always uses a temporary staging copy, with propagation limited by `allow_paths`.
+
+OpenCode runs with isolated configuration and permissions; project/global configuration, external plugins, and MCP servers are not loaded. Codex uses read-only analysis and workspace-write apply modes. Claude Code uses separate analysis and editing permissions. Authenticate the CLI before using it in a hook.
+
+Apply requires a single pushed branch whose local commit is the checked-out `HEAD`. Staging excludes Git metadata, `AGENTS.md`, ignored files, symlinks, and special files. These controls are not an OS sandbox or an automatic rollback system. See [Security](../SECURITY.md).
+
+### Apply and manual commits
+
+`apply` is generic: it can edit any eligible checkout file matching `allow_paths`; it is not limited to Markdown. The runner edits a temporary staging copy, and only validated changes propagate back to the checkout. Those edits do not enter the commit already being pushed, and `apply` never creates a Git commit.
+
+The existing `docs_apply_requires_manual_commit` assertion is a workflow gate, not human-review enforcement. It prevents the original push from passing after `apply` changes files; it cannot prove that anyone reviewed the edits or that they conform to policy. Add it after the `apply` step when that gate is desired:
+
+```toml
+[[modules.docs.steps]]
+id = "manual-commit"
+type = "assert"
+assertion = "docs_apply_requires_manual_commit"
+inputs = ["apply/result.json"]
+```
+
+The assertion checks `apply/result.json`'s `changed_files` and intentionally blocks when edits were propagated. Review `git diff`, run the relevant checks, commit the approved changes, and retry the push. On the retry, the assertion passes when the apply step reports no changes.
+
+## Custom Runners
+
+Use a command profile for another CLI, including Pi, or your own wrapper. This example expects a local `scripts/review-agent` program that reads the prompt from stdin and writes its final response to stdout:
+
+```toml
+[runners.custom]
+type = "command"
+command = ["/absolute/path/to/scripts/review-agent"]
+prompt_transport = "stdin"
+project_access = "project"
+```
+
+Select it with `runner = "custom"` on an `ask` or `apply` step. The runner receives the full instruction and artifact packet. For apply, its working directory is the staging copy.
+
+Commands are argv arrays, not shell strings. Whole-argument placeholders are `{model}`, `{cwd}`, `{stage}`, and `{prompt}`. The `argv` transport requires exactly one `{prompt}` argument; stdin avoids exposing prompts in process listings. Custom programs inherit the user environment and own their permissions and session lifecycle.
+
+## Commands And Callbacks
+
+Command steps run in the real repository, with no implicit shell. Exit zero means success; a nonzero exit blocks the workflow. stdout, stderr, and a `result.json` report are saved as step artifacts.
+
+```toml
+[[modules.verify.steps]]
+id = "tests"
+type = "exec"
+command = ["{python}", "-m", "pytest", "-q"]
+timeout_seconds = 300
+```
+
+Available whole-argument placeholders are `{repo}`, `{python}`, and `{input:<step/artifact>}`. Input placeholders must also appear in `inputs`. Stdin is closed unless `stdin` names a declared input. Command output is bounded to 16 MiB per stream.
+
+For custom context or policy, reference a top-level synchronous Python function:
+
+```toml
+[[modules.policy.steps]]
+id = "change-size"
+type = "assert"
+python = "checks/hooks.py:check_size"
+options = { max_files = 25 }
+```
+
+In `checks/hooks.py`:
+
+```python
+from ai_push_hooks.plugins import PluginContext
+
+
+def check_size(context: PluginContext) -> dict:
+    ok = len(context.push.changed_files) <= context.options["max_files"]
+    return {"ok": ok, "message": "Change exceeds the configured file limit." if not ok else ""}
+```
+
+Add `policy` to `[workflow].modules` to enable it. Callbacks receive repository and step identifiers, push facts, input paths, options, prior module metadata, and a logger.
+
+| Callback type | Return value |
+| --- | --- |
+| `collect` | `CollectorResult` from `ai_push_hooks.plugins`, with artifacts and metadata. |
+| `exec` | JSON-serializable dictionary, saved as `result.json`. |
+| `assert` | Dictionary with boolean `ok` and optional string `message`; false blocks. |
+
+Callbacks run as trusted in-process code with already-installed dependencies. There is no callback timeout or automatic dependency installation. Collectors may run concurrently, so custom collectors must be concurrency-safe.
+
+## Built-In Handlers
+
+| Kind | Name | Purpose |
+| --- | --- | --- |
+| Collector | `docs_context` | Push diff, changed files, docs excerpts, recent commits. |
+| Collector | `beads_status_context` | Branch and Beads task context. |
+| Collector | `pr_context` | Context for a pull request. |
+| Action | `beads_alignment` | Apply supported `bd update` / `bd close` operations. |
+| Action | `gh_pr_create` | Create or reuse a PR through `gh`. |
+| Assertion | `docs_apply_requires_manual_commit` | Block after applied docs changes. |
+| Assertion | `beads_alignment_clean` | Block on unresolved task alignment. |
+
+Beads steps need the native `bd` CLI; PR creation needs `gh`. Gate optional actions with `when_env = "AI_PUSH_HOOKS_CREATE_PR"`, for example. Beads schema and database maintenance remain separate from hook execution.
+
+| JSON schema | Payload |
+| --- | --- |
+| `string_array` | Array of strings. |
+| `docs_issue_array` | Array of objects with `file` and `description`. |
+| `beads_alignment_result` | Object with optional `commands` string array. |
+| `pr_create_payload` | Object containing PR creation fields. |
+
+Built-in prompts: `docs-query-basic`, `docs-analysis-basic`, `docs-apply-basic`, `beads-plan-basic`, and `pr-compose-basic`.
+
+## Settings
+
+These optional settings supplement the workflow and runner definitions:
+
+| Section | Key | Default |
+| --- | --- | --- |
+| `general` | `enabled` | `true` |
+| `general` | `allow_push_on_error` | `false` |
+| `general` | `require_clean_worktree` | `false` |
+| `general` | `skip_on_sync_branch` | `true` |
+| `general` | `base_branch` | `"main"` |
+| `llm` | `runner` | `"opencode"` |
+| `llm` | `model` | `"openai/gpt-5.6-luna"` (implicit OpenCode profile) |
+| `llm` | `variant` | `""` |
+| `llm` | `timeout_seconds` | `800` |
+| `llm` | `max_parallel` | `2` |
+| `llm` | `json_max_retries` | `2` |
+| `llm` | `invalid_json_feedback_max_chars` | `6000` |
+| `llm` | `json_retry_new_session` | `true` |
+| `llm` | `delete_session_after_run` | `true` |
+| `llm` | `max_diff_bytes` | `180000` |
+| `llm` | `session_title_prefix` | `"ai-push-hooks"` |
+| `logging` | `level` | `"status"` (`info` and `debug` also available) |
+| `logging` | `jsonl` | `true` |
+| `logging` | `capture_llm_transcript` | `true` (OpenCode only) |
+| `logging` | `print_llm_output` | `false` |
+| `logging` | `dir` | `".git/ai-push-hooks/logs"` |
+| `logging` | `transcript_dir` | `".git/ai-push-hooks/transcripts"` |
+| `logging` | `summary_dir` | `".git/ai-push-hooks/summaries"` |
+
+Model availability depends on the provider. Select one available to your account rather than assuming the starter's model is accessible.
+
+## Environment Overrides
+
+| Variable | Effect |
+| --- | --- |
+| `AI_PUSH_HOOKS_SKIP=1` | Skip the hook before loading configuration. |
+| `AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR=1` | Log errors but allow the push. |
+| `AI_PUSH_HOOKS_REQUIRE_CLEAN=1` | Require a clean worktree. |
+| `AI_PUSH_HOOKS_ALLOW_DIRTY=1` | Allow a dirty worktree. |
+| `AI_PUSH_HOOKS_BASE_BRANCH` | Override the base branch. |
+| `AI_PUSH_HOOKS_MODEL` | Override the selected runner's model. |
+| `AI_PUSH_HOOKS_VARIANT` | Override the OpenCode variant. |
+| `AI_PUSH_HOOKS_TIMEOUT_SECONDS` | Override the runner timeout. |
+| `AI_PUSH_HOOKS_LOG_LEVEL` | Set console verbosity. |
+| `AI_PUSH_HOOKS_PRINT_LLM_OUTPUT=1` | Print normalized, redacted final responses; sensitive opt-in. |
+
+Boolean values accept `1/0`, `true/false`, `yes/no`, `y/n`, and `on/off`. Skips and fail-open settings are explicit policy choices, not successful checks.
+
+## Hook Managers
+
+The built-in `install` command creates a repository-local pre-push hook without changing Git configuration. Existing hooks require explicit `--force` replacement; shared/external paths and symlinks are refused. Keep the installed Python executable or local npm package available at its installed location.
+
+For Lefthook, use this in `lefthook.yml` instead of the built-in installer:
+
+```yaml
+pre-push:
+  commands:
+    ai-checks:
+      run: npx --no-install ai-push-hooks hook {1} {2}
+      use_stdin: true
+```
+
+Run `lefthook install`. For a Python installation, omit the `npx --no-install` prefix. Other hook managers must likewise forward Git's remote arguments, ref-update stdin, and exit status. If earlier commands consume stdin, capture it first and replay it to ai-push-hooks.
+
+To remove the generated hook, inspect `git rev-parse --git-path hooks/pre-push` and remove only the ai-push-hooks delegate or its entry in your hook manager. Preserve unrelated hook commands.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Hook does not run | Reinstall with your chosen hook manager and inspect `git config --get core.hooksPath`. |
+| Missing runner or authentication failure | Ensure the CLI is on the hook's `PATH`, authenticated, and configured with an available model. |
+| Unknown profile | Match `runner` to an existing `[runners.<name>]`. |
+| Runner capability error | Update the CLI to a version with the required adapter flags. |
+| Invalid JSON | Check the prompt and schema; invalid JSON is retried twice by default. |
+| Push blocked after edits | Review `git diff`, run checks, commit approved changes, and retry the push. |
+| Need diagnostics | Inspect `.git/ai-push-hooks/logs` and `.git/ai-push-hooks/summaries`. |
+
+For validation commands, see [Contributing](../CONTRIBUTING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {
@@ -30,16 +30,17 @@
     "ai-push-hooks": "bin/ai-push-hooks.js"
   },
   "scripts": {
-    "test": "uv run --no-project --with pytest pytest tests -q",
+    "test": "uv run --no-project --with \".[dev]\" python -m pytest tests -q",
     "test:npm-pack": "node tests/npm-pack-smoke.mjs"
   },
   "files": [
     "bin",
     "src/**/*.py",
+    "vendor",
     "README.md",
+    "docs/configuration.md",
     "CHANGELOG.md",
     "SECURITY.md",
-    "run.sh",
     "pyproject.toml",
     "LICENSE",
     "ai-push-hooks.toml"

package/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.3.0"
+version = "0.3.2"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,7 +34,7 @@ Changelog = "https://github.com/shanebishop1/ai-push-hooks/blob/main/CHANGELOG.m
 ai-push-hooks = "ai_push_hooks.cli:main"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = ["pytest>=8.0", "build", "pip", "ruff", "twine"]
 
 [tool.setuptools]
 include-package-data = true
@@ -44,3 +44,12 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"

package/src/ai_push_hooks/artifacts.py

@@ -45,11 +45,17 @@ class ArtifactStore:
         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")
+            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}")
+            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}",
@@ -125,7 +131,9 @@ class ArtifactStore:
         payload: Any,
     ) -> pathlib.Path:
         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")
+        write_text_no_follow(
+            path, json.dumps(payload, ensure_ascii=True, indent=2) + "\n"
+        )
         return self.register(state, step_id, artifact_name, path)
 
     def serialize_plugin_artifacts(
@@ -152,7 +160,10 @@ class ArtifactStore:
             try:
                 if isinstance(payload, (dict, list)) or artifact_name.endswith(".json"):
                     content = (
-                        json.dumps(payload, ensure_ascii=True, indent=2, allow_nan=False) + "\n"
+                        json.dumps(
+                            payload, ensure_ascii=True, indent=2, allow_nan=False
+                        )
+                        + "\n"
                     ).encode("utf-8")
                 elif isinstance(payload, str):
                     content = payload.encode("utf-8")
@@ -169,7 +180,9 @@ class ArtifactStore:
                 )
             total_bytes += len(content)
             if total_bytes > max_total_bytes:
-                raise HookError("CollectorResult artifacts exceed the aggregate size limit")
+                raise HookError(
+                    "CollectorResult artifacts exceed the aggregate size limit"
+                )
             serialized[artifact_name] = content
         return serialized
 
@@ -194,16 +207,3 @@ class ArtifactStore:
                 )
             raise HookError(f"Unknown artifact reference: {reference}")
         return path
-
-    def register_external(
-        self,
-        state: ModuleRuntimeState,
-        module_id: str,
-        step_id: str,
-        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

@@ -43,30 +43,44 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
         except FileNotFoundError:
             metadata = None
         except OSError as exc:
-            raise HookError(f"Could not inspect config path {config_path}: {exc}") from 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}")
+                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}")
+                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
+            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
+            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}")
+                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}")
+                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:
@@ -76,7 +90,9 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
                 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
+            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