patchshuttle 0.1.0a2__py3-none-any.whl

patchshuttle/config.py

@@ -0,0 +1,247 @@
+"""Typed loading and default rendering for ``patches/patchshuttle.toml``."""
+
+from __future__ import annotations
+
+import json
+import stat
+from enum import Enum
+from os import PathLike
+from pathlib import Path
+from typing import Annotated, Literal, TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from patchshuttle.errors import WorkspaceError, WorkspaceErrorCode
+from patchshuttle.identifiers import ProjectId
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10 compatibility
+    import tomli as tomllib  # type: ignore[no-redef]
+
+StrictString: TypeAlias = Annotated[str, Field(strict=True, min_length=1)]
+PositiveInteger: TypeAlias = Annotated[int, Field(strict=True, ge=1)]
+
+DEFAULT_PROTECTED_PATHS = (
+    ".git/**",
+    ".env",
+    ".env.*",
+    "patches/**",
+    ".venv/**",
+    "venv/**",
+    "node_modules/**",
+)
+DEFAULT_PROTECTED_PATH_EXCEPTIONS = (
+    ".env.example",
+    ".env.sample",
+    ".env.template",
+)
+DEFAULT_IGNORED_PATHS = (
+    ".git/**",
+    "patches/backups/**",
+    "patches/logs/**",
+    "patches/state/**",
+    ".venv/**",
+    "venv/**",
+    "node_modules/**",
+    "**/__pycache__/**",
+    ".pytest_cache/**",
+    ".mypy_cache/**",
+    ".ruff_cache/**",
+)
+
+
+class ProjectOrigin(str, Enum):
+    """How a workspace was classified during its first initialization."""
+
+    EXISTING = "existing"
+    NEW = "new"
+
+
+class _ConfigModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, validate_default=True)
+
+
+class ProjectSettings(_ConfigModel):
+    project_id: ProjectId
+    origin: ProjectOrigin
+    protected_paths: tuple[StrictString, ...] = DEFAULT_PROTECTED_PATHS
+    protected_path_exceptions: tuple[StrictString, ...] = (
+        DEFAULT_PROTECTED_PATH_EXCEPTIONS
+    )
+    ignored_paths: tuple[StrictString, ...] = DEFAULT_IGNORED_PATHS
+
+
+class ExecutionSettings(_ConfigModel):
+    confirm: bool = Field(default=True, strict=True)
+    auto_rollback: bool = Field(default=True, strict=True)
+    allow_keep_changes: bool = Field(default=True, strict=True)
+    default_timeout_seconds: PositiveInteger = 300
+    max_job_bytes: PositiveInteger = 2_000_000
+    max_actions: PositiveInteger = 100
+    max_single_file_bytes: PositiveInteger = 1_000_000
+    max_command_output_bytes: PositiveInteger = 2_000_000
+    max_inventory_entries: PositiveInteger = 50_000
+    max_inventory_bytes: PositiveInteger = 1_000_000_000
+
+
+class FormattingSettings(_ConfigModel):
+    enabled: bool = Field(default=True, strict=True)
+    order: tuple[Literal["isort"], Literal["black"]] = ("isort", "black")
+    scope: Literal["changed_python_files"] = "changed_python_files"
+    rerun_checks: bool = Field(default=True, strict=True)
+
+
+class LoggingSettings(_ConfigModel):
+    timezone: StrictString = "local"
+    include_command_output: bool = Field(default=True, strict=True)
+    redact_known_secrets: bool = Field(default=True, strict=True)
+
+
+class CheckProfileSettings(_ConfigModel):
+    argv: Annotated[tuple[StrictString, ...], Field(min_length=1)]
+    timeout_seconds: PositiveInteger = 300
+    allow_job_args: bool = Field(default=False, strict=True)
+
+
+class ChecksSettings(_ConfigModel):
+    require_at_least_one_for_patch: bool = Field(default=True, strict=True)
+    profiles: dict[str, CheckProfileSettings] = Field(default_factory=dict)
+
+
+class PatchShuttleConfig(_ConfigModel):
+    """The complete local policy document used by one workspace."""
+
+    project: ProjectSettings
+    execution: ExecutionSettings = Field(default_factory=ExecutionSettings)
+    formatting: FormattingSettings = Field(default_factory=FormattingSettings)
+    logging: LoggingSettings = Field(default_factory=LoggingSettings)
+    checks: ChecksSettings = Field(default_factory=ChecksSettings)
+
+
+def load_config(path: str | PathLike[str]) -> PatchShuttleConfig:
+    """Load one UTF-8 TOML configuration with a closed typed schema."""
+
+    config_path = Path(path)
+    if config_path.is_symlink():
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_NOT_REGULAR,
+            "configuration path must not be a symbolic link",
+        )
+
+    try:
+        file_stat = config_path.stat()
+    except FileNotFoundError as exc:
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_NOT_FOUND,
+            "workspace configuration was not found",
+        ) from exc
+    except OSError as exc:
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_READ_FAILED,
+            "configuration metadata could not be read",
+        ) from exc
+
+    if not stat.S_ISREG(file_stat.st_mode):
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_NOT_REGULAR,
+            "configuration path must identify a regular file",
+        )
+
+    try:
+        raw = config_path.read_bytes()
+    except OSError as exc:
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_READ_FAILED,
+            "configuration file could not be read",
+        ) from exc
+
+    try:
+        text = raw.decode("utf-8")
+        value = tomllib.loads(text)
+        return PatchShuttleConfig.model_validate(value)
+    except UnicodeDecodeError as exc:
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_INVALID,
+            "configuration must be valid UTF-8 text",
+        ) from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_INVALID,
+            "configuration contains invalid TOML syntax",
+        ) from exc
+    except ValidationError as exc:
+        first_error = exc.errors(include_url=False)[0]
+        raise WorkspaceError(
+            WorkspaceErrorCode.CONFIG_INVALID,
+            str(first_error["msg"]),
+            path=_format_validation_path(first_error["loc"]),
+        ) from exc
+
+
+def render_default_config(
+    project_id: str,
+    origin: ProjectOrigin | str,
+) -> str:
+    """Render the canonical default configuration for a new workspace."""
+
+    project = ProjectSettings(project_id=project_id, origin=origin)
+    return (
+        "[project]\n"
+        f"project_id = {json.dumps(project.project_id)}\n"
+        f"origin = {json.dumps(project.origin.value)}\n\n"
+        f"protected_paths = {_render_array(project.protected_paths)}\n\n"
+        "protected_path_exceptions = "
+        f"{_render_array(project.protected_path_exceptions)}\n\n"
+        f"ignored_paths = {_render_array(project.ignored_paths)}\n\n"
+        "[execution]\n"
+        "confirm = true\n"
+        "auto_rollback = true\n"
+        "allow_keep_changes = true\n"
+        "default_timeout_seconds = 300\n"
+        "max_job_bytes = 2000000\n"
+        "max_actions = 100\n"
+        "max_single_file_bytes = 1000000\n"
+        "max_command_output_bytes = 2000000\n"
+        "max_inventory_entries = 50000\n"
+        "max_inventory_bytes = 1000000000\n\n"
+        "[formatting]\n"
+        "enabled = true\n"
+        'order = ["isort", "black"]\n'
+        'scope = "changed_python_files"\n'
+        "rerun_checks = true\n\n"
+        "[logging]\n"
+        'timezone = "local"\n'
+        "include_command_output = true\n"
+        "redact_known_secrets = true\n\n"
+        "[checks]\n"
+        "require_at_least_one_for_patch = true\n"
+    )
+
+
+def _render_array(values: tuple[str, ...]) -> str:
+    lines = ["["]
+    lines.extend(f"  {json.dumps(value)}," for value in values)
+    lines.append("]")
+    return "\n".join(lines)
+
+
+def _format_validation_path(location: tuple[int | str, ...]) -> str:
+    path = "$"
+    for part in location:
+        path = f"{path}[{part}]" if isinstance(part, int) else f"{path}.{part}"
+    return path
+
+
+__all__ = [
+    "CheckProfileSettings",
+    "ChecksSettings",
+    "ExecutionSettings",
+    "FormattingSettings",
+    "LoggingSettings",
+    "PatchShuttleConfig",
+    "ProjectOrigin",
+    "ProjectSettings",
+    "load_config",
+    "render_default_config",
+]

patchshuttle/context.py

@@ -0,0 +1,370 @@
+"""Bounded project snapshots and upload-friendly AI handoffs."""
+
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from patchshuttle._process import ProcessCommand, ProcessStatus, run_process
+from patchshuttle._version import __version__
+from patchshuttle.errors import ExecutionError, ExecutionErrorCode
+from patchshuttle.inventory import (
+    InventoryEntryKind,
+    InventoryError,
+    WorkspaceInventory,
+    capture_inventory,
+)
+from patchshuttle.logging import current_run_clock, write_named_log
+from patchshuttle.registry import Registry, load_registry
+from patchshuttle.runner import acquire_workspace_lock
+from patchshuttle.workspace import Workspace
+
+_AUDIT_ACTIONS = (
+    "tree, read, search, find_files, file_info, hash, git_status, environment"
+)
+_CHANGE_ACTIONS = (
+    "create_directory, create_file, replace_exact, insert_before, insert_after, "
+    "delete_exact, apply_diff"
+)
+_CHECKS = (
+    "compileall, pytest, unittest, django_check, django_migrations_check, "
+    "django_test, import_check, profile"
+)
+_TREE_LIMIT = 500
+_FILE_LIMIT = 2_000
+_HISTORY_LIMIT = 20
+_TRUNCATION = "\n[TRUNCATED BY PATCHSHUTTLE]\n"
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotResult:
+    """One generated read-only project snapshot."""
+
+    path: Path
+    inventory_entries: int
+    output_truncated: bool
+
+
+@dataclass(frozen=True, slots=True)
+class HandoffResult:
+    """One generated AI-facing project handoff."""
+
+    path: Path
+    inventory_entries: int
+    recent_jobs: int
+    output_truncated: bool
+
+
+def create_snapshot(workspace: Workspace) -> SnapshotResult:
+    """Capture bounded metadata without including source-file contents."""
+
+    clock = current_run_clock(workspace)
+    with acquire_workspace_lock(workspace):
+        inventory = _capture(workspace)
+        registry = load_registry(workspace)
+        content = _snapshot_text(workspace, inventory, registry, clock.iso_timestamp)
+        content, truncated = _bounded(
+            content,
+            workspace.config.execution.max_command_output_bytes,
+        )
+        path = write_named_log(
+            workspace,
+            clock=clock,
+            label="SNAPSHOT",
+            content=content,
+        )
+    return SnapshotResult(
+        path=path,
+        inventory_entries=len(inventory.entries),
+        output_truncated=truncated,
+    )
+
+
+def create_handoff(workspace: Workspace) -> HandoffResult:
+    """Create one compact provider-neutral context file for an AI service."""
+
+    clock = current_run_clock(workspace)
+    with acquire_workspace_lock(workspace):
+        inventory = _capture(workspace)
+        registry = load_registry(workspace)
+        latest_summary, latest_handoff = _latest_run_context(workspace)
+        recent = _recent_records(registry)
+        content = _handoff_text(
+            workspace,
+            inventory,
+            recent,
+            clock.iso_timestamp,
+            latest_summary=latest_summary,
+            latest_handoff=latest_handoff,
+        )
+        content, truncated = _bounded(
+            content,
+            workspace.config.execution.max_command_output_bytes,
+        )
+        path = write_named_log(
+            workspace,
+            clock=clock,
+            label="HANDOFF",
+            content=content,
+        )
+    return HandoffResult(
+        path=path,
+        inventory_entries=len(inventory.entries),
+        recent_jobs=len(recent),
+        output_truncated=truncated,
+    )
+
+
+def _snapshot_text(
+    workspace: Workspace,
+    inventory: WorkspaceInventory,
+    registry: Registry,
+    timestamp: str,
+) -> str:
+    tree_lines, tree_truncated = _tree_lines(inventory)
+    file_lines, files_truncated = _file_lines(inventory)
+    recent = _recent_records(registry)
+    return "\n".join(
+        (
+            "=== PATCHSHUTTLE_SNAPSHOT ===",
+            "protocol: 1",
+            f"timestamp: {timestamp}",
+            f"project_id: {workspace.project_id}",
+            f"patchshuttle_version: {__version__}",
+            f"python_version: {platform.python_version()}",
+            f"workspace_root: {workspace.root.as_posix()}",
+            f"inventory_entries: {len(inventory.entries)}",
+            f"inventory_hashed_bytes: {inventory.hashed_bytes}",
+            "",
+            "=== CAPABILITIES ===",
+            "job_kinds: audit, patch, verify",
+            f"audit_actions: {_AUDIT_ACTIONS}",
+            f"change_actions: {_CHANGE_ACTIONS}",
+            f"checks: {_CHECKS}",
+            "",
+            "=== POLICY_SUMMARY ===",
+            "ignored_paths: "
+            + json.dumps(
+                workspace.config.project.ignored_paths,
+                ensure_ascii=False,
+            ),
+            "protected_paths: "
+            + json.dumps(
+                workspace.config.project.protected_paths,
+                ensure_ascii=False,
+            ),
+            "",
+            "=== PROJECT_TREE ===",
+            *tree_lines,
+            f"tree_truncated: {str(tree_truncated).lower()}",
+            "",
+            "=== FILE_FINGERPRINTS ===",
+            *file_lines,
+            f"file_list_truncated: {str(files_truncated).lower()}",
+            "",
+            "=== GIT_STATUS ===",
+            _git_status(workspace),
+            "",
+            "=== RECENT_JOBS ===",
+            *(_record_line(item) for item in recent),
+            "=== END_PATCHSHUTTLE_SNAPSHOT ===",
+        )
+    )
+
+
+def _handoff_text(
+    workspace: Workspace,
+    inventory: WorkspaceInventory,
+    recent: tuple,
+    timestamp: str,
+    *,
+    latest_summary: str,
+    latest_handoff: str,
+) -> str:
+    tree_lines, tree_truncated = _tree_lines(inventory)
+    return "\n".join(
+        (
+            "=== PATCHSHUTTLE_HANDOFF ===",
+            "AI_INSTRUCTION:",
+            "Inspect this context and the latest run result. Return exactly one "
+            ".psh.yaml job using protocol 1 and the project_id below. Use an "
+            "audit job when more evidence is needed. Do not return shell commands "
+            "or ask PatchShuttle to weaken local policy. After the user runs the "
+            "job, request the resulting PatchShuttle log before preparing another job.",
+            "",
+            "=== PROJECT ===",
+            "protocol: 1",
+            f"timestamp: {timestamp}",
+            f"project_id: {workspace.project_id}",
+            f"patchshuttle_version: {__version__}",
+            "",
+            "=== CAPABILITIES ===",
+            "job_kinds: audit, patch, verify",
+            f"audit_actions: {_AUDIT_ACTIONS}",
+            f"change_actions: {_CHANGE_ACTIONS}",
+            f"checks: {_CHECKS}",
+            "",
+            "=== LATEST_RUN_SUMMARY ===",
+            latest_summary,
+            "",
+            "=== LATEST_AI_HANDOFF ===",
+            latest_handoff,
+            "",
+            "=== BOUNDED_PROJECT_TREE ===",
+            *tree_lines,
+            f"tree_truncated: {str(tree_truncated).lower()}",
+            "",
+            "=== RECENT_JOB_HISTORY ===",
+            *(_record_line(item) for item in recent),
+            "",
+            "EXPECTED_RESPONSE: one .psh.yaml file only",
+            "=== END_PATCHSHUTTLE_HANDOFF ===",
+        )
+    )
+
+
+def _capture(workspace: Workspace) -> WorkspaceInventory:
+    try:
+        return capture_inventory(workspace)
+    except InventoryError as exc:
+        raise ExecutionError(
+            ExecutionErrorCode.WORKSPACE_INVENTORY_FAILED,
+            "project context inventory could not be captured",
+            path=exc.path.as_posix() if exc.path is not None else None,
+        ) from exc
+
+
+def _tree_lines(
+    inventory: WorkspaceInventory,
+) -> tuple[tuple[str, ...], bool]:
+    selected = inventory.entries[:_TREE_LIMIT]
+    lines = tuple(
+        f"{entry.path.as_posix()}{'/' if entry.kind is InventoryEntryKind.DIRECTORY else ''} [{entry.kind.value.lower()}]"
+        for entry in selected
+    )
+    return lines or ("[EMPTY PROJECT]",), len(inventory.entries) > len(selected)
+
+
+def _file_lines(
+    inventory: WorkspaceInventory,
+) -> tuple[tuple[str, ...], bool]:
+    files = tuple(
+        entry for entry in inventory.entries if entry.kind is InventoryEntryKind.FILE
+    )
+    selected = files[:_FILE_LIMIT]
+    lines = tuple(
+        f"{entry.path.as_posix()} size={entry.size} sha256={entry.sha256}"
+        for entry in selected
+    )
+    return lines or ("[NO FILES]",), len(files) > len(selected)
+
+
+def _recent_records(registry: Registry) -> tuple:
+    return tuple(
+        sorted(
+            registry.jobs.values(),
+            key=lambda item: (item.latest_run_at, item.job_id),
+            reverse=True,
+        )[:_HISTORY_LIMIT]
+    )
+
+
+def _record_line(record) -> str:
+    return (
+        f"{record.job_id} kind={record.kind} result={record.latest_result} "
+        f"hash={record.job_hash[:8]} at={record.latest_run_at}"
+    )
+
+
+def _git_status(workspace: Workspace) -> str:
+    executable = shutil.which("git")
+    marker = workspace.root / ".git"
+    if executable is None or not marker.exists() or marker.is_symlink():
+        return "NOT_AVAILABLE"
+    process = run_process(
+        ProcessCommand(
+            argv=(
+                executable,
+                "-c",
+                "color.ui=false",
+                "status",
+                "--short",
+                "--branch",
+                "--untracked-files=normal",
+            ),
+            working_directory=workspace.root,
+            timeout_seconds=workspace.config.execution.default_timeout_seconds,
+        ),
+        maximum_output_bytes=workspace.config.execution.max_command_output_bytes,
+    )
+    if process.status is not ProcessStatus.PASSED:
+        return "NOT_AVAILABLE"
+    value = process.stdout.rstrip("\n") or "CLEAN"
+    return value + ("\n[TRUNCATED]" if process.stdout_truncated else "")
+
+
+def _latest_run_context(workspace: Workspace) -> tuple[str, str]:
+    directory = workspace.patches_dir / "logs"
+    try:
+        candidates = sorted(
+            (
+                path
+                for path in directory.iterdir()
+                if path.name.startswith("log_") and path.suffix == ".log"
+            ),
+            key=lambda path: (path.lstat().st_mtime_ns, path.name),
+            reverse=True,
+        )
+    except OSError as exc:
+        raise ExecutionError(
+            ExecutionErrorCode.OPERATIONAL_RECORD_FAILED,
+            "run logs could not be inspected for handoff generation",
+            path="patches/logs",
+        ) from exc
+    maximum = workspace.config.execution.max_command_output_bytes
+    for path in candidates:
+        try:
+            metadata = path.lstat()
+            if not stat.S_ISREG(metadata.st_mode) or metadata.st_size > maximum:
+                continue
+            text = path.read_text("utf-8")
+        except (OSError, UnicodeError):
+            continue
+        summary = _section(text, "SUMMARY")
+        handoff = _section(text, "PATCHSHUTTLE_AI_HANDOFF")
+        if summary is not None and handoff is not None:
+            return summary, handoff
+    return "NOT_AVAILABLE", "NOT_AVAILABLE"
+
+
+def _section(value: str, name: str) -> str | None:
+    marker = f"=== {name} ===\n"
+    start = value.find(marker)
+    if start < 0:
+        return None
+    content_start = start + len(marker)
+    end = value.find("\n=== ", content_start)
+    return value[content_start : end if end >= 0 else None].strip()
+
+
+def _bounded(value: str, maximum: int) -> tuple[str, bool]:
+    raw = value.encode("utf-8")
+    if len(raw) <= maximum:
+        return value, False
+    marker = _TRUNCATION.encode("utf-8")
+    if maximum <= len(marker):
+        return marker[:maximum].decode("utf-8"), True
+    retained = raw[: max(0, maximum - len(marker))]
+    return retained.decode("utf-8", errors="ignore") + _TRUNCATION, True
+
+
+__all__ = [
+    "HandoffResult",
+    "SnapshotResult",
+    "create_handoff",
+    "create_snapshot",
+]