agent-rules-kit 0.2.1__py3-none-any.whl

agent_rules_kit/init_write.py

@@ -0,0 +1,143 @@
+"""Explicit write mode for agent instruction init."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from agent_rules_kit.init_plan import InitPlanAction, build_init_plan
+
+BASELINE_AGENTS_CONTENT = """# Agent Instructions
+
+These baseline instructions were generated by agent-rules-kit.
+Review and adapt them before relying on them for a specific project.
+
+## Scope
+
+These instructions apply from the repository root unless a more specific instruction file
+defines a narrower scope.
+
+## Authority
+
+Follow explicit user requests first. Then follow this file and any more specific
+instruction files for the files being changed.
+
+## Secret handling
+
+Do not commit, print, or log secrets, tokens, credentials, API keys, private URLs, or private data.
+
+## Command execution
+
+Read the repository before changing files.
+Ask for explicit confirmation before destructive commands or broad filesystem changes.
+
+## Review and CI
+
+Keep the repository review process, CI requirements, branch protection, and maintainer
+approval intact.
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class WrittenInitFile:
+    """A file action performed by init write mode."""
+
+    path: str
+    action: InitPlanAction
+    backup_path: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class InitWriteResult:
+    """Result of explicit init write mode."""
+
+    repository: str
+    files: tuple[WrittenInitFile, ...]
+
+
+def write_init_files(root: Path | str) -> InitWriteResult:
+    """Write baseline init files, backing up existing files before replacement."""
+    plan = build_init_plan(root)
+    root_path = Path(root)
+    written_files: list[WrittenInitFile] = []
+
+    for planned_file in plan.files:
+        target = root_path / planned_file.path
+        backup_path: Path | None = None
+
+        if target.is_symlink():
+            raise ValueError("refusing to write init file through symlinked path: AGENTS.md")
+
+        if planned_file.action == InitPlanAction.BACKUP_AND_REPLACE:
+            backup_path = _next_backup_path(target)
+            _copy_file_to_new_regular_path(target, backup_path)
+
+        _write_text_atomic(target, BASELINE_AGENTS_CONTENT)
+
+        written_files.append(
+            WrittenInitFile(
+                path=planned_file.path,
+                action=planned_file.action,
+                backup_path=(
+                    backup_path.relative_to(root_path).as_posix()
+                    if backup_path is not None
+                    else None
+                ),
+            )
+        )
+
+    return InitWriteResult(
+        repository=plan.repository,
+        files=tuple(written_files),
+    )
+
+
+def _write_text_atomic(target: Path, content: str) -> None:
+    temporary_path = _next_available_path(
+        target.with_name(f".{target.name}.agent-rules-kit.tmp")
+    )
+    temporary_created = False
+
+    try:
+        with temporary_path.open("x", encoding="utf-8") as temporary_file:
+            temporary_created = True
+            temporary_file.write(content)
+        temporary_path.replace(target)
+    finally:
+        if temporary_created and _path_exists_or_is_symlink(temporary_path):
+            temporary_path.unlink()
+
+
+def _copy_file_to_new_regular_path(source: Path, destination: Path) -> None:
+    with source.open("rb") as source_file, destination.open("xb") as destination_file:
+        shutil.copyfileobj(source_file, destination_file)
+    shutil.copystat(source, destination, follow_symlinks=False)
+
+
+def _next_backup_path(target: Path) -> Path:
+    return _next_available_path(target.with_name(f"{target.name}.agent-rules-kit.bak"))
+
+
+def _next_available_path(candidate: Path) -> Path:
+    if not _path_exists_or_is_symlink(candidate):
+        return candidate
+
+    for index in range(1, 1000):
+        indexed_candidate = candidate.with_name(f"{candidate.name}.{index}")
+        if not _path_exists_or_is_symlink(indexed_candidate):
+            return indexed_candidate
+
+    raise RuntimeError(f"could not find available backup path for: {candidate}")
+
+
+def _path_exists_or_is_symlink(candidate: Path) -> bool:
+    return candidate.exists() or candidate.is_symlink()
+
+
+__all__ = [
+    "BASELINE_AGENTS_CONTENT",
+    "InitWriteResult",
+    "WrittenInitFile",
+    "write_init_files",
+]

agent_rules_kit/redaction.py

@@ -0,0 +1,78 @@
+"""Redaction helpers for secret-like values."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from re import Pattern
+
+REDACTION_TEXT = "[REDACTED]"
+
+
+@dataclass(frozen=True, slots=True)
+class RedactionPattern:
+    """A named pattern used to redact secret-like values."""
+
+    name: str
+    pattern: Pattern[str]
+
+
+SECRET_LIKE_PATTERNS: tuple[RedactionPattern, ...] = (
+    RedactionPattern(
+        name="anthropic_api_key",
+        pattern=re.compile(r"sk-ant-[A-Za-z0-9_-]{12,}"),
+    ),
+    RedactionPattern(
+        name="openai_api_key",
+        pattern=re.compile(r"sk-[A-Za-z0-9_-]{12,}"),
+    ),
+    RedactionPattern(
+        name="jwt_token",
+        pattern=re.compile(r"eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"),
+    ),
+    RedactionPattern(
+        name="github_token",
+        pattern=re.compile(r"gh[pousr]_[A-Za-z0-9_]{20,}"),
+    ),
+    RedactionPattern(
+        name="aws_access_key",
+        pattern=re.compile(r"AKIA[0-9A-Z]{16}"),
+    ),
+    RedactionPattern(
+        name="huggingface_token",
+        pattern=re.compile(r"hf_[A-Za-z0-9]{20,}"),
+    ),
+    RedactionPattern(
+        name="slack_token",
+        pattern=re.compile(r"xox[bpsa]-[A-Za-z0-9-]{10,}"),
+    ),
+    RedactionPattern(
+        name="npm_token",
+        pattern=re.compile(r"npm_[A-Za-z0-9]{20,}"),
+    ),
+    RedactionPattern(
+        name="private_key_block",
+        pattern=re.compile(
+            r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----",
+            re.DOTALL,
+        ),
+    ),
+)
+
+
+def redact_secret_like_values(text: str) -> str:
+    """Redact supported secret-like values from text."""
+    redacted = text
+
+    for item in SECRET_LIKE_PATTERNS:
+        redacted = item.pattern.sub(REDACTION_TEXT, redacted)
+
+    return redacted
+
+
+__all__ = [
+    "REDACTION_TEXT",
+    "RedactionPattern",
+    "SECRET_LIKE_PATTERNS",
+    "redact_secret_like_values",
+]