agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.1"

agentic_project_kit/absolute_path_portability_audit.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import re
+
+
+ABSOLUTE_PATH_PATTERNS = (
+    re.compile(r"/Users/[A-Za-z0-9._-]+/[^\s`\"')]+"),
+    re.compile(r"/home/[A-Za-z0-9._-]+/[^\s`\"')]+"),
+    re.compile(r"(?<![\w.-])/tmp/[^\s`\"')]+"),
+    re.compile(r"/var/folders/[^\s`\"')]+"),
+    re.compile(r"/mnt/data/[^\s`\"')]+"),
+)
+
+TEXT_SUFFIXES = {
+    ".md",
+    ".rst",
+    ".txt",
+    ".py",
+    ".toml",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".cff",
+    ".sh",
+}
+
+SKIP_DIR_PARTS = {
+    ".git",
+    ".venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    "node_modules",
+    "tmp",
+    "dist",
+    "build",
+}
+
+SKIP_DIR_PREFIXES = (
+    ".venv",
+)
+
+SKIP_FILENAMES = {
+    "Screen-Control_Output.txt",
+}
+
+SKIP_PATH_PREFIXES = (
+    "docs/reports/",
+    ".agentic/transfer/outbox/",
+)
+
+SAFE_PATH_PREFIXES = (
+    "tests/",
+    "docs/reports/",
+)
+
+SAFE_PATHS = {
+    "README.md",
+    "docs/STATUS.md",
+    "docs/handoff/CURRENT_HANDOFF.md",
+}
+
+HISTORICAL_MARKERS = (
+    "historical",
+    "legacy",
+    "obsolete",
+    "removed",
+    "deprecated",
+    "archived",
+    "archive",
+    "example",
+    "fixture",
+    "test",
+    "log",
+    "evidence",
+    "sandbox",
+)
+
+
+@dataclass(frozen=True)
+class AbsolutePathReference:
+    path: str
+    line: int
+    text: str
+    match: str
+    classification: str
+    reason: str
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class AbsolutePathAuditResult:
+    root: str
+    references: tuple[AbsolutePathReference, ...]
+    blockers: tuple[AbsolutePathReference, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.blockers
+
+    @property
+    def status(self) -> str:
+        return "PASS" if self.ok else "FAIL"
+
+    @property
+    def returncode(self) -> int:
+        return 0 if self.ok else 1
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "kind": "absolute_path_portability_audit",
+            "root": self.root,
+            "status": self.status,
+            "reference_count": len(self.references),
+            "blocker_count": len(self.blockers),
+            "references": [item.as_dict() for item in self.references],
+            "blockers": [item.as_dict() for item in self.blockers],
+        }
+
+
+def _is_text_file(path: Path) -> bool:
+    return path.suffix in TEXT_SUFFIXES
+
+
+def _iter_candidate_files(root: Path) -> list[Path]:
+    files: list[Path] = []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(root).as_posix()
+        relative_parts = path.relative_to(root).parts
+        if path.name in SKIP_FILENAMES:
+            continue
+        if any(part in SKIP_DIR_PARTS for part in relative_parts):
+            continue
+        if any(part.startswith(prefix) for part in relative_parts for prefix in SKIP_DIR_PREFIXES):
+            continue
+        if any(relative.startswith(prefix) for prefix in SKIP_PATH_PREFIXES):
+            continue
+        if not _is_text_file(path):
+            continue
+        files.append(path)
+    return sorted(files)
+
+
+def _classify(relative: str, line: str, match: str) -> tuple[str, str]:
+    lowered = line.lower()
+
+    if relative == "src/agentic_project_kit/absolute_path_portability_audit.py":
+        return "audit_implementation", "absolute path tokens are classifier patterns, not user-facing paths"
+
+    if relative.startswith(SAFE_PATH_PREFIXES):
+        return "safe_generated_or_test_context", "test/generated context"
+
+    if relative.startswith("tests/"):
+        return "test_fixture", "test fixture"
+
+    if relative.startswith(("src/", "tools/")):
+        return "absolute_path_blocker", (
+            "source/tool files must not contain user-specific absolute paths; "
+            "line-level historical words are not enough to downgrade this"
+        )
+
+    if relative in SAFE_PATHS and any(marker in lowered for marker in HISTORICAL_MARKERS):
+        return "historical_or_example_context", "stable doc with historical/example marker"
+
+    if any(marker in lowered for marker in HISTORICAL_MARKERS):
+        return "historical_or_example_context", "line contains historical/example/evidence marker"
+
+    if match.startswith("/tmp/") or match.startswith("/mnt/data/") or match.startswith("/var/folders/"):
+        return "transient_path_reference", "transient local path should not be current repo contract"
+
+    return "absolute_path_blocker", "absolute local path may break portability"
+
+
+def audit_absolute_path_portability(root: Path = Path(".")) -> AbsolutePathAuditResult:
+    root = root.resolve()
+    references: list[AbsolutePathReference] = []
+
+    for path in _iter_candidate_files(root):
+        relative = path.relative_to(root).as_posix()
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except UnicodeDecodeError:
+            continue
+
+        for number, line in enumerate(lines, start=1):
+            for pattern in ABSOLUTE_PATH_PATTERNS:
+                for match in pattern.finditer(line):
+                    matched = match.group(0)
+                    classification, reason = _classify(relative, line, matched)
+                    references.append(
+                        AbsolutePathReference(
+                            path=relative,
+                            line=number,
+                            text=line.strip(),
+                            match=matched,
+                            classification=classification,
+                            reason=reason,
+                        )
+                    )
+
+    blockers = tuple(
+        ref
+        for ref in references
+        if ref.classification in {"absolute_path_blocker", "transient_path_reference"}
+    )
+    return AbsolutePathAuditResult(
+        root=root.as_posix(),
+        references=tuple(references),
+        blockers=blockers,
+    )
+
+
+def render_absolute_path_portability_audit(result: AbsolutePathAuditResult) -> str:
+    lines = [
+        "ABSOLUTE_PATH_PORTABILITY_AUDIT",
+        f"STATUS={result.status}",
+        f"REFERENCE_COUNT={len(result.references)}",
+        f"BLOCKER_COUNT={len(result.blockers)}",
+    ]
+
+    for ref in result.blockers:
+        lines.append(
+            "BLOCKER="
+            f"{ref.classification}|{ref.path}:{ref.line}|{ref.match}|{ref.text}"
+        )
+
+    for ref in result.references:
+        lines.append(
+            "REFERENCE="
+            f"{ref.classification}|{ref.path}:{ref.line}|{ref.match}|{ref.text}"
+        )
+
+    return "\n".join(lines) + "\n"

agentic_project_kit/access_level_policy.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from agentic_project_kit.access_levels import AccessLevel, meets_min_access
+from agentic_project_kit.cockpit import CockpitAction
+
+
+def can_show_action(action: CockpitAction, level: AccessLevel) -> bool:
+    return meets_min_access(level, action.min_access_level)
+
+
+def visible_actions(actions: Iterable[CockpitAction], level: AccessLevel) -> list[CockpitAction]:
+    return [action for action in actions if can_show_action(action, level)]

agentic_project_kit/access_levels.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Literal
+
+AccessLevel = Literal["basic", "advanced", "maintainer"]
+
+ACCESS_LEVEL_ORDER: tuple[AccessLevel, ...] = ("basic", "advanced", "maintainer")
+DEFAULT_ACCESS_LEVEL: AccessLevel = "basic"
+
+
+def access_level_rank(level: AccessLevel) -> int:
+    return ACCESS_LEVEL_ORDER.index(level)
+
+
+def meets_min_access(current: AccessLevel, required: AccessLevel) -> bool:
+    return access_level_rank(current) >= access_level_rank(required)
+
+
+def normalize_access_level(value: str | None) -> AccessLevel:
+    if value in ACCESS_LEVEL_ORDER:
+        return value
+    return DEFAULT_ACCESS_LEVEL

agentic_project_kit/action_registry.py

@@ -0,0 +1,195 @@
+"""Static action metadata for local workflow and cockpit readiness.
+
+This module is intentionally read-only: it describes known local actions but
+does not execute shell commands, mutate git state, call GitHub, or publish releases.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class SafetyClass(str, Enum):
+    """Coarse safety class for a local action."""
+
+    READ_ONLY = "read-only"
+    LOCAL_ONLY = "local-only"
+    REMOTE_MUTATION = "remote-mutation"
+    RELEASE_TAG_PUBLISH = "release-tag-publish"
+    MERGE_DELETE_CLOSE = "merge-delete-close"
+
+
+@dataclass(frozen=True)
+class ActionMetadata:
+    """Static metadata for one repo-local action."""
+
+    name: str
+    safety_class: SafetyClass
+    mutation_scope: str
+    dry_run_supported: bool
+    outcome_contract: tuple[str, ...]
+    summary: str
+
+
+ACTIONS: tuple[ActionMetadata, ...] = (
+    ActionMetadata(
+        name="dev",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Run local deterministic development gates.",
+    ),
+    ActionMetadata(
+        name="pr-cleanup",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Classify open pull requests without mutating them.",
+    ),
+    ActionMetadata(
+        name="release-verify",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Verify an existing release and metadata state.",
+    ),
+    ActionMetadata(
+        name="clean-evidence",
+        safety_class=SafetyClass.LOCAL_ONLY,
+        mutation_scope="working-tree-files",
+        dry_run_supported=False,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Clean local evidence or generated files according to repo policy.",
+    ),
+    ActionMetadata(
+        name="release-prep",
+        safety_class=SafetyClass.LOCAL_ONLY,
+        mutation_scope="version-and-release-metadata-files",
+        dry_run_supported=False,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Prepare local release metadata before a release PR.",
+    ),
+    ActionMetadata(
+        name="release-gate",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Verify release readiness without tagging or publishing.",
+    ),
+    ActionMetadata(
+        name="finalize-guard",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS_ALREADY_ON_MAIN", "PASS_NOOP_BRANCH", "PASS_SUPERSEDED", "PASS_NEEDS_PR", "FAIL_CONFLICT_RELEVANT", "FAIL_NEEDS_HUMAN_REVIEW"),
+        summary="Classify branch finalization state without merging or deleting.",
+    ),
+    ActionMetadata(
+        name="doctor",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Run compact project health checks without mutating repository state.",
+    ),
+
+    ActionMetadata(
+        name="check-docs",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Run documentation coverage and lifecycle gates without mutating repository state.",
+    ),
+
+    ActionMetadata(
+        name="cockpit-readiness",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS", "FAIL"),
+        summary="Render static cockpit readiness metadata without executing actions.",
+    ),
+
+    ActionMetadata(
+        name="agent-next",
+        safety_class=SafetyClass.REMOTE_MUTATION,
+        mutation_scope="docs/reports/command_runs and docs/reports/terminal",
+        dry_run_supported=False,
+        outcome_contract=(
+            "PASS_EXECUTED",
+            "FAIL_NO_COMMAND",
+            "FAIL_AMBIGUOUS_COMMANDS",
+            "FAIL_PULL",
+            "FAIL_ALREADY_EXECUTED",
+            "FAIL_INVALID_COMMAND",
+            "FAIL_SHELL_SYNTAX",
+            "FAIL_COMMAND",
+            "FAIL_UPLOAD",
+            "FAIL_POSTCONDITION",
+        ),
+        summary="Pull and execute exactly one pending repo-backed agent command.",
+    ),
+
+    ActionMetadata(
+        name="agent-run",
+        safety_class=SafetyClass.REMOTE_MUTATION,
+        mutation_scope="docs/reports/command_runs and docs/reports/terminal",
+        dry_run_supported=False,
+        outcome_contract=("PASS_EXECUTED", "FAIL_NO_COMMAND", "FAIL_ALREADY_EXECUTED", "FAIL_INVALID_COMMAND", "FAIL_SHELL_SYNTAX", "FAIL_COMMAND", "FAIL_UPLOAD"),
+        summary="Pull-safe repo command runner for agent handoff without copy-and-paste terminal blocks.",
+    ),
+    ActionMetadata(
+        name="run-logged",
+        safety_class=SafetyClass.LOCAL_ONLY,
+        mutation_scope="docs/reports/terminal",
+        dry_run_supported=False,
+        outcome_contract=("PASS", "FAIL", "FAIL_NO_COMMAND", "FAIL_MISSING_SEPARATOR"),
+        summary="Run a local command while teeing output to a terminal log.",
+    ),
+    ActionMetadata(
+        name="terminal-status",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS_LOG_READY", "PASS_NO_LOG", "FAIL_INVALID_POINTER"),
+        summary="Inspect the latest terminal log pointer without mutating state.",
+    ),
+    ActionMetadata(
+        name="terminal-clean-check",
+        safety_class=SafetyClass.READ_ONLY,
+        mutation_scope="none",
+        dry_run_supported=True,
+        outcome_contract=("PASS_CLEAN", "PASS_ONLY_TERMINAL_LOG_DIRTY", "FAIL_DIRTY_NON_LOG_FILES"),
+        summary="Check whether only terminal-log artifacts are dirty during logged runs.",
+    ),
+    ActionMetadata(
+        name="terminal-upload",
+        safety_class=SafetyClass.REMOTE_MUTATION,
+        mutation_scope="docs/reports/terminal only",
+        dry_run_supported=False,
+        outcome_contract=("PASS_UPLOADED", "PASS_ALREADY_UPLOADED", "FAIL_NO_LOG", "FAIL_DIRTY_NON_LOG_FILES", "FAIL_PUSH_FAILED"),
+        summary="Commit and push only terminal-log artifacts for failure handoff.",
+    ),
+
+)
+
+
+def list_actions() -> tuple[ActionMetadata, ...]:
+    """Return all known action metadata entries."""
+
+    return ACTIONS
+
+
+def get_action(name: str) -> ActionMetadata | None:
+    """Return metadata for one action name, if known."""
+
+    for action in ACTIONS:
+        if action.name == name:
+            return action
+    return None