patchshuttle 0.1.0a2__py3-none-any.whl

patchshuttle/resources/AI_GUIDE.md

@@ -0,0 +1,163 @@
+# PatchShuttle AI Guide
+
+This file is the provider-neutral contract for ChatGPT and other AI services
+that prepare PatchShuttle jobs for this project.
+
+## Project identity
+
+- Protocol: `1`
+- Project ID: `{{PROJECT_ID}}`
+- Canonical job extension: `.psh.yaml`
+
+Every job must use exactly this project ID. Do not copy an ID from another
+project or invent a replacement.
+
+## Required AI response
+
+When asked for a PatchShuttle job:
+
+1. Return exactly one UTF-8 YAML document.
+2. Do not wrap it in Markdown fences.
+3. Do not add prose before or after the YAML.
+4. Keep the job focused on one reviewable goal.
+5. Use only the actions and checks listed below.
+6. Never provide shell commands, Python code to execute the job, or policy
+   overrides.
+7. Preserve the same job ID when correcting a rejected job only when the user
+   explicitly requests a correction of that same attempt.
+8. Never add confirmation or rollback choices to YAML. `--yes` and
+   `--keep-changes` are user-controlled CLI decisions, not job fields.
+
+## Job kinds
+
+- `audit` - one or more read-only audit actions, no checks.
+- `patch` - one or more change actions and appropriate checks.
+- `verify` - one or more checks, no actions.
+
+## Audit actions
+
+- `tree` - bounded directory tree.
+- `read` - bounded text-file excerpt.
+- `search` - literal text search.
+- `find_files` - bounded glob search.
+- `file_info` - file metadata.
+- `hash` - SHA-256 file hash.
+- `git_status` - Git status when Git is available.
+- `environment` - bounded development-environment summary.
+
+## Change actions
+
+- `create_directory` - create one directory.
+- `create_file` - create one new text file.
+- `replace_exact` - replace an exact text occurrence count.
+- `insert_before` - insert text before an exact anchor.
+- `insert_after` - insert text after an exact anchor.
+- `delete_exact` - delete exact text with an expected count.
+- `apply_diff` - apply a unified diff to existing text files.
+
+## Checks
+
+- `compileall`
+- `pytest` - optional arguments are limited to `-q`, `--quiet`, `-v`,
+  `--verbose`, `-x`, `--exitfirst`, `-s`, `--disable-warnings`,
+  `--strict-config`, `--strict-markers`, positive `--maxfail=N`,
+  `--tb=auto|long|short|line|native|no`, and
+  `--capture=fd|sys|no|tee-sys`.
+- `unittest`
+- `django_check`
+- `django_migrations_check`
+- `django_test` - labels must be dotted Python identifiers.
+- `import_check`
+- `profile` - only a profile already defined by the user in
+  `patches/patchshuttle.toml`.
+
+## Audit example
+
+```yaml
+protocol: 1
+project_id: {{PROJECT_ID}}
+id: AUDIT-001
+kind: audit
+title: Inspect the project structure
+actions:
+  - tree:
+      path: .
+      depth: 4
+  - git_status: {}
+```
+
+## Patch example
+
+```yaml
+protocol: 1
+project_id: {{PROJECT_ID}}
+id: PATCH-001
+kind: patch
+title: Create a small Python module
+actions:
+  - create_directory:
+      path: src/example
+  - create_file:
+      path: src/example/__init__.py
+      content: |
+        VALUE = 1
+checks:
+  - compileall:
+      paths: [src]
+```
+
+## Verify example
+
+```yaml
+protocol: 1
+project_id: {{PROJECT_ID}}
+id: VERIFY-001
+kind: verify
+title: Run the project tests without changing files
+checks:
+  - pytest:
+      paths: [tests]
+      args: [-q]
+```
+
+## Local workflow
+
+The user saves the YAML in `patches/inbox/`, validates it, runs
+`patchshuttle plan`, and reviews the read-only plan locally. An audit can run
+without confirmation. Patch and verify jobs require explicit confirmation or
+deliberate `--yes` automation. If validation or planning fails, ask for the
+exact terminal result. After every recorded attempt, ask the user for the
+generated `.log` file or a fresh `patchshuttle handoff` file and use its final
+`PATCHSHUTTLE_AI_HANDOFF` block before preparing the next job. Never state that
+a job was applied merely because YAML or a successful plan was created.
+
+Interpret failure states conservatively:
+
+- `ROLLED_BACK` means declared transaction paths were restored, but reported
+  external check side effects still require review.
+- `SKIPPED_CHANGES_KEPT` means the user explicitly retained partial declared
+  changes. Request a fresh audit or handoff before producing a corrective job.
+- `SKIPPED_NO_CHANGES` means rollback was skipped before a declared change was
+  published; still use the log as the authoritative result.
+- `ROLLBACK_FAILED` means restoration is incomplete. Stop proposing new
+  changes until the user resolves the listed paths.
+
+This `0.1.0a2` build provides workspace initialization, validation, read-only
+planning, bounded audit execution, approved patch execution, and approved
+one-pass verification. Patch execution uses all text change actions,
+controlled initial checks, changed-Python-only isort then Black, final checks,
+bounded before/after workspace inventory, undeclared side-effect reporting,
+rollback of declared transaction paths, exact CLI job archives, an atomic
+registry, and fixed-section redacted logs. Completed patches also support
+guarded manual rollback. An explicitly user-approved `--keep-changes` run can
+retain partial declared changes after failure and records that decision
+distinctly. Snapshot and handoff commands produce bounded context without
+dumping source contents. The same completed job ID and normalized hash returns
+`ALREADY_APPLIED`; the same ID with different content returns
+`PATCH_ID_CONFLICT`. An `UNEXPECTED_WORKSPACE_CHANGE` result means the reported
+external path must be reviewed separately; for a normal patch, declared paths
+are rolled back. Redaction is best-effort; do not tell the user that a log is
+guaranteed to contain no secrets.
+
+See `PATCHSHUTTLE_PROTOCOL.md` and `patchshuttle.schema.json` for the detailed
+syntax.

patchshuttle/resources/AUDIT-EXAMPLE.psh.yaml

@@ -0,0 +1,10 @@
+protocol: 1
+project_id: {{PROJECT_ID}}
+id: AUDIT-EXAMPLE
+kind: audit
+title: Inspect the initial project structure
+actions:
+  - tree:
+      path: .
+      depth: 4
+  - environment: {}

patchshuttle/resources/PATCH-EXAMPLE.psh.yaml

@@ -0,0 +1,17 @@
+protocol: 1
+project_id: {{PROJECT_ID}}
+id: PATCH-EXAMPLE
+kind: patch
+title: Create a small Python package
+actions:
+  - create_directory:
+      path: src/example
+  - create_file:
+      path: src/example/__init__.py
+      content: |
+        """Example package created through a PatchShuttle job."""
+
+        VALUE = 1
+checks:
+  - compileall:
+      paths: [src]

patchshuttle/resources/PATCHSHUTTLE_PROTOCOL.md

@@ -0,0 +1,109 @@
+# PatchShuttle Protocol 1
+
+Project ID for this workspace: `{{PROJECT_ID}}`
+
+PatchShuttle jobs are single UTF-8 YAML documents whose filenames end exactly
+with `.psh.yaml`. Unknown fields, duplicate mapping keys, custom YAML tags,
+anchors, and aliases are rejected.
+
+## Top-level fields
+
+- `protocol` - required integer `1`.
+- `project_id` - required workspace identifier.
+- `id` - required stable job identifier matching
+  `[A-Z][A-Z0-9_-]{2,63}`.
+- `kind` - `audit`, `patch`, or `verify`.
+- `title` - optional text.
+- `description` - optional text.
+- `actions` - action list.
+- `checks` - check list.
+
+An `audit` job requires audit actions and forbids checks. A `patch` job requires
+change actions. A `verify` job requires checks and forbids actions.
+
+Each action or check list entry is a mapping containing exactly one operation
+name.
+
+## Audit actions
+
+- `tree`: `path`, `depth`, `max_entries`, `include_hidden`.
+- `read`: `path`, `start_line`, `end_line`, `max_bytes`.
+- `search`: `path`, `text`, `glob`, `case_sensitive`, `max_results`.
+- `find_files`: `path`, `glob`, `max_results`.
+- `file_info`: `path`.
+- `hash`: `path`, optional `algorithm: sha256`.
+- `git_status`: empty mapping.
+- `environment`: empty mapping.
+
+## Change actions
+
+- `create_directory`: `path`.
+- `create_file`: `path`, `content`, optional `encoding` and `newline`.
+- `replace_exact`: `path`, `old`, `new`, `expected_count`.
+- `insert_before`: `path`, `anchor`, `content`, `expected_count`.
+- `insert_after`: `path`, `anchor`, `content`, `expected_count`.
+- `delete_exact`: `path`, `text`, `expected_count`.
+- `apply_diff`: `diff`, optional `strip` from `0` through `2`.
+
+## Checks
+
+- `compileall`: non-empty `paths`, optional `quiet` from `0` through `2`.
+- `pytest`: optional `paths`, `args`, and `timeout_seconds`. Allowed arguments:
+  `-q`, `--quiet`, `-v`, `--verbose`, `-x`, `--exitfirst`, `-s`,
+  `--disable-warnings`, `--strict-config`, `--strict-markers`, positive
+  `--maxfail=N`, `--tb=auto|long|short|line|native|no`, and
+  `--capture=fd|sys|no|tee-sys`.
+- `unittest`: `discover` and `pattern`.
+- `django_check`: `manage_py`.
+- `django_migrations_check`: `manage_py`.
+- `django_test`: `manage_py` and optional dotted-identifier `labels`.
+- `import_check`: non-empty dotted Python `modules`.
+- `profile`: `name` of a local profile already defined in
+  `patches/patchshuttle.toml`.
+
+## Local authority and safety
+
+Jobs cannot change project identity, protected paths, confirmation, backups,
+rollback, formatting order, command allowlists, size limits, or shell policy.
+There is no arbitrary-shell action. Project checks can execute project code with
+the current user's permissions, so PatchShuttle is not an operating-system
+sandbox.
+
+All job paths are relative to the workspace root. The implemented planner
+rejects absolute paths, parent traversal, protected or ignored targets,
+symbolic-link escapes, binary targets, special files, and files outside
+configured limits.
+
+Use `patchshuttle validate patches/inbox/JOB.psh.yaml`, then review
+`patchshuttle plan patches/inbox/JOB.psh.yaml`. Planning is read-only and does
+not mean the job was applied. `patchshuttle run JOB.psh.yaml` accepts every job
+kind. `patchshuttle audit JOB.psh.yaml` requires an audit job and does not
+prompt. `patchshuttle verify JOB.psh.yaml` requires a verify job and, like a
+patch, uses a deny-by-default confirmation unless `--yes` is supplied. The
+public Python equivalent is `execute_plan(plan, approved=True)`; audit plans do
+not require approval. `patchshuttle run PATCH.psh.yaml --keep-changes` is a
+user-controlled patch-only mode that requires separate confirmation unless
+combined with `--yes`. It is not a YAML field and local policy may forbid it.
+
+Audit output and traversal are bounded and a workspace comparison verifies
+read-only behavior. Verify jobs run their checks once and record workspace side
+effects. Patch execution includes controlled initial checks, scoped isort then
+Black, repeated final checks, bounded before/after workspace inventory, and
+automatic rollback. Final changes outside declared transaction paths and
+configured ignored paths are reported as `UNEXPECTED_WORKSPACE_CHANGE`.
+Declared patch paths are rolled back; reported external check side effects are
+not removed automatically. If the user explicitly accepts `--keep-changes`, a
+failed patch retains published declared changes and records
+`SKIPPED_CHANGES_KEPT`; if no declared change was published, it records
+`SKIPPED_NO_CHANGES`.
+
+Every recorded job attempt writes a timestamped fixed-section log, archives
+the exact CLI job in `applied/` or `failed/`, and atomically updates the
+registry. The same completed ID and hash returns `ALREADY_APPLIED`; different
+normalized content under an existing ID returns `PATCH_ID_CONFLICT`. Use
+`patchshuttle rollback PATCH_ID` for guarded manual restoration of a completed
+patch, `snapshot` for bounded project metadata, `handoff` for upload-friendly
+AI context, `logs --last` for the newest log, and `status [JOB_ID]` for registry
+state. Log redaction is best-effort, so review a log before sharing it. The JSON
+Schema in `patchshuttle.schema.json` is the exact structural schema produced by
+the installed model version.

patchshuttle/resources/__init__.py

@@ -0,0 +1 @@
+"""Packaged templates copied into initialized PatchShuttle workspaces."""

patchshuttle/rollback.py

@@ -0,0 +1,306 @@
+"""Conservative rollback for paths created by one transaction attempt."""
+
+from __future__ import annotations
+
+import hashlib
+import stat
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+import patchshuttle.actions as actions
+from patchshuttle.backup import (
+    BackupEntryKind,
+    LoadedBackup,
+    OriginalState,
+    PreparedBackup,
+)
+from patchshuttle.errors import ExecutionError, ExecutionErrorCode, PolicyError
+from patchshuttle.policy import PathKind, Policy
+from patchshuttle.workspace import Workspace
+
+
+@dataclass(frozen=True, slots=True)
+class RollbackResult:
+    """Exact paths removed or left unresolved by a create-only rollback."""
+
+    removed_files: tuple[PurePosixPath, ...]
+    removed_directories: tuple[PurePosixPath, ...]
+    unresolved: tuple[PurePosixPath, ...]
+    restored_files: tuple[PurePosixPath, ...] = ()
+
+    @property
+    def success(self) -> bool:
+        return not self.unresolved
+
+
+def rollback_created(
+    workspace: Workspace,
+    *,
+    files: tuple[PurePosixPath, ...],
+    directories: tuple[PurePosixPath, ...],
+) -> RollbackResult:
+    """Remove only paths confirmed as created by the current attempt."""
+
+    policy = Policy(workspace)
+    removed_files: list[PurePosixPath] = []
+    removed_directories: list[PurePosixPath] = []
+    unresolved: list[PurePosixPath] = []
+
+    for path in reversed(files):
+        try:
+            target = policy.resolve(path, allow_missing=True)
+            if target.kind is PathKind.MISSING:
+                continue
+            if target.kind is not PathKind.FILE:
+                unresolved.append(path)
+                continue
+            target.absolute.unlink()
+            removed_files.append(path)
+        except (OSError, PolicyError):
+            unresolved.append(path)
+
+    for path in reversed(directories):
+        try:
+            target = policy.resolve(path, allow_missing=True)
+            if target.kind is PathKind.MISSING:
+                continue
+            if target.kind is not PathKind.DIRECTORY:
+                unresolved.append(path)
+                continue
+            target.absolute.rmdir()
+            removed_directories.append(path)
+        except (OSError, PolicyError):
+            unresolved.append(path)
+
+    return RollbackResult(
+        removed_files=tuple(removed_files),
+        removed_directories=tuple(removed_directories),
+        unresolved=tuple(unresolved),
+    )
+
+
+def rollback_transaction(
+    workspace: Workspace,
+    backup: PreparedBackup | LoadedBackup,
+    *,
+    modified_files: tuple[PurePosixPath, ...],
+    files: tuple[PurePosixPath, ...],
+    directories: tuple[PurePosixPath, ...],
+) -> RollbackResult:
+    """Restore modified originals, then remove paths created by the attempt."""
+
+    restored_files: list[PurePosixPath] = []
+    unresolved: list[PurePosixPath] = []
+    for path in reversed(modified_files):
+        try:
+            _restore_original(workspace, backup, path)
+            restored_files.append(path)
+        except (KeyError, OSError, PolicyError):
+            unresolved.append(path)
+
+    created = rollback_created(
+        workspace,
+        files=files,
+        directories=directories,
+    )
+    return RollbackResult(
+        removed_files=created.removed_files,
+        removed_directories=created.removed_directories,
+        unresolved=(*unresolved, *created.unresolved),
+        restored_files=tuple(restored_files),
+    )
+
+
+def rollback_completed_backup(
+    workspace: Workspace,
+    backup: LoadedBackup,
+) -> RollbackResult:
+    """Preflight and roll back one previously completed transaction."""
+
+    _preflight_manual_rollback(workspace, backup)
+    modified = tuple(
+        entry.path
+        for entry in backup.entries
+        if entry.kind is BackupEntryKind.FILE
+        and entry.original_state is OriginalState.PRESENT
+    )
+    created_files = tuple(
+        entry.path
+        for entry in backup.entries
+        if entry.kind is BackupEntryKind.FILE
+        and entry.original_state is OriginalState.ABSENT
+    )
+    created_directories = tuple(
+        entry.path
+        for entry in backup.entries
+        if entry.kind is BackupEntryKind.DIRECTORY
+        and entry.original_state is OriginalState.ABSENT
+    )
+    return rollback_transaction(
+        workspace,
+        backup,
+        modified_files=modified,
+        files=created_files,
+        directories=created_directories,
+    )
+
+
+def _restore_original(
+    workspace: Workspace,
+    backup: PreparedBackup | LoadedBackup,
+    path: PurePosixPath,
+) -> None:
+    entry = backup.entry_for(path)
+    if (
+        entry.original_state is not OriginalState.PRESENT
+        or entry.backup_path is None
+        or entry.original_sha256 is None
+        or entry.original_size is None
+        or entry.original_mode is None
+    ):
+        raise OSError(f"backup entry cannot restore a modified file: {path}")
+
+    raw = _read_original(backup, path)
+
+    actions.atomic_restore_file(
+        workspace,
+        path,
+        raw,
+        mode=entry.original_mode,
+    )
+    actions.verify_restored_file(
+        workspace,
+        path,
+        raw,
+        mode=entry.original_mode,
+    )
+
+
+def _preflight_manual_rollback(
+    workspace: Workspace,
+    backup: LoadedBackup,
+) -> None:
+    policy = Policy(workspace)
+    allowed = frozenset(entry.path for entry in backup.entries)
+    for entry in backup.entries:
+        try:
+            target = policy.resolve(entry.path)
+            metadata = target.absolute.lstat()
+            if stat.S_IMODE(metadata.st_mode) != entry.applied_mode:
+                raise OSError("applied mode changed")
+            if entry.kind is BackupEntryKind.FILE:
+                if (
+                    target.kind is not PathKind.FILE
+                    or entry.applied_size is None
+                    or entry.applied_sha256 is None
+                ):
+                    raise OSError("applied file state is incomplete")
+                before = target.absolute.lstat()
+                raw = target.absolute.read_bytes()
+                after = target.absolute.lstat()
+                if (
+                    _identity(before) != _identity(after)
+                    or len(raw) != entry.applied_size
+                    or hashlib.sha256(raw).hexdigest() != entry.applied_sha256
+                ):
+                    raise OSError("applied file changed after the job")
+            elif target.kind is not PathKind.DIRECTORY:
+                raise OSError("applied directory has the wrong type")
+            if entry.original_state is OriginalState.PRESENT:
+                _read_original(backup, entry.path)
+        except (KeyError, OSError, PolicyError) as exc:
+            raise ExecutionError(
+                ExecutionErrorCode.ROLLBACK_FAILED,
+                "manual rollback refused because the applied state changed or the backup is unsafe",
+                path=entry.path.as_posix(),
+                backup_path=backup.path,
+                rollback_succeeded=False,
+            ) from exc
+
+    for entry in backup.entries:
+        if entry.kind is not BackupEntryKind.DIRECTORY:
+            continue
+        target = workspace.root.joinpath(*entry.path.parts)
+        pending = [target]
+        while pending:
+            directory = pending.pop()
+            try:
+                children = tuple(directory.iterdir())
+            except OSError as exc:
+                raise ExecutionError(
+                    ExecutionErrorCode.ROLLBACK_FAILED,
+                    "manual rollback could not inspect a created directory",
+                    path=entry.path.as_posix(),
+                    backup_path=backup.path,
+                    rollback_succeeded=False,
+                ) from exc
+            for child in children:
+                relative = PurePosixPath(child.relative_to(workspace.root).as_posix())
+                if relative not in allowed:
+                    raise ExecutionError(
+                        ExecutionErrorCode.ROLLBACK_FAILED,
+                        "manual rollback refused to remove a directory containing undeclared entries",
+                        path=relative.as_posix(),
+                        backup_path=backup.path,
+                        rollback_succeeded=False,
+                    )
+                try:
+                    mode = child.lstat().st_mode
+                except OSError as exc:
+                    raise ExecutionError(
+                        ExecutionErrorCode.ROLLBACK_FAILED,
+                        "manual rollback could not inspect a created path",
+                        path=relative.as_posix(),
+                        backup_path=backup.path,
+                        rollback_succeeded=False,
+                    ) from exc
+                if stat.S_ISDIR(mode):
+                    pending.append(child)
+
+
+def _read_original(
+    backup: PreparedBackup | LoadedBackup,
+    path: PurePosixPath,
+) -> bytes:
+    entry = backup.entry_for(path)
+    if (
+        entry.original_state is not OriginalState.PRESENT
+        or entry.backup_path is None
+        or entry.original_sha256 is None
+        or entry.original_size is None
+        or entry.original_mode is None
+    ):
+        raise OSError(f"backup entry cannot restore a modified file: {path}")
+    source = backup.path.joinpath(*entry.backup_path.parts)
+    metadata = source.lstat()
+    if (
+        stat.S_ISLNK(metadata.st_mode)
+        or not stat.S_ISREG(metadata.st_mode)
+        or source.resolve() != source.absolute()
+    ):
+        raise OSError(f"original backup is not a regular file: {path}")
+    raw = source.read_bytes()
+    if (
+        len(raw) != entry.original_size
+        or hashlib.sha256(raw).hexdigest() != entry.original_sha256
+    ):
+        raise OSError(f"original backup failed integrity validation: {path}")
+    return raw
+
+
+def _identity(metadata) -> tuple[int, int, int, int, int]:
+    return (
+        metadata.st_dev,
+        metadata.st_ino,
+        metadata.st_size,
+        metadata.st_mtime_ns,
+        metadata.st_mode,
+    )
+
+
+__all__ = [
+    "RollbackResult",
+    "rollback_completed_backup",
+    "rollback_created",
+    "rollback_transaction",
+]