aepkit 0.6.0__py3-none-any.whl

aepkit/__init__.py

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

aepkit/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m aepkit``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

aepkit/cli.py

@@ -0,0 +1,151 @@
+"""aepkit — mechanical support for the Auditor/Executor protocol.
+
+See SKILL.md in the repo root for the protocol itself. This CLI operationalizes the
+parts of it that are checklist work, not judgment: scaffolding the document set,
+cross-checking it for drift, running a negative control end to end, and reporting
+status.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, install_skill, lint, negcontrol, scaffold, status
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="aepkit", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"aepkit {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser(
+        "init", help="scaffold the document set (three documents and an annexes/ directory)"
+    )
+    p_init.add_argument("target_dir", help="directory to scaffold (created if missing)")
+    p_init.add_argument(
+        "--name",
+        dest="project_name",
+        metavar="NAME",
+        default=None,
+        help="project name written into the documents (default: the directory name)",
+    )
+    p_init.add_argument("--force", action="store_true", help="overwrite existing documents")
+
+    p_lint = sub.add_parser("lint", help="cross-check the document set for drift")
+    p_lint.add_argument("target_dir", help="directory holding the document set")
+    p_lint.add_argument(
+        "--annex-threshold",
+        type=int,
+        metavar="N",
+        default=lint.DEFAULT_ANNEX_THRESHOLD,
+        help="flag more annexes than this, overall or per phase (default: %(default)s)",
+    )
+
+    p_neg = sub.add_parser("negcontrol", help="run a backup/break/test/restore/test cycle")
+    p_neg.add_argument(
+        "--file", dest="file_path", metavar="PATH", default=None, help="file to back up and restore"
+    )
+    p_neg.add_argument(
+        "--break-cmd",
+        dest="break_cmd",
+        metavar="CMD",
+        default=None,
+        help="shell command that removes the protection",
+    )
+    p_neg.add_argument(
+        "--test-cmd",
+        dest="test_cmd",
+        metavar="CMD",
+        required=True,
+        help="shell command that should fail without the protection",
+    )
+    p_neg.add_argument(
+        "--restore-cmd",
+        dest="restore_cmd",
+        metavar="CMD",
+        default=None,
+        help="shell command to restore; with --file, the backup still wins if the file differs",
+    )
+    p_neg.add_argument(
+        "--expect",
+        metavar="REGEX",
+        default=None,
+        help="the failing run's output must match this regular expression to count",
+    )
+    p_neg.add_argument(
+        "--timeout",
+        type=float,
+        metavar="SECONDS",
+        default=None,
+        help="seconds allowed per command (default: no limit)",
+    )
+
+    p_status = sub.add_parser(
+        "status", help="tally verdicts and reports in the compliance log; only APPROVED closes"
+    )
+    p_status.add_argument("target_dir", help="directory holding compliance-log.md")
+
+    p_install = sub.add_parser(
+        "install-skill", help="provision SKILL.md and references/ into an agent skills directory"
+    )
+    p_install.add_argument(
+        "target_dir",
+        nargs="?",
+        default=".",
+        help="target project directory (defaults to current directory)",
+    )
+    p_install.add_argument(
+        "--agent",
+        choices=["antigravity", "claude", "cursor", "auto"],
+        default="auto",
+        help="target agent framework (default: auto-detect)",
+    )
+    p_install.add_argument(
+        "--global",
+        dest="is_global",
+        action="store_true",
+        help="install to user-level global configuration directory",
+    )
+    p_install.add_argument(
+        "--dest",
+        dest="dest_path",
+        metavar="PATH",
+        default=None,
+        help="explicit destination (SKILL.md installs references/ beside it; any other name gets one bundled file)",
+    )
+    p_install.add_argument(
+        "--force", action="store_true", help="overwrite an existing installation"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "init":
+        return scaffold.run(args.target_dir, args.project_name, args.force)
+    if args.command == "lint":
+        return lint.run(args.target_dir, args.annex_threshold)
+    if args.command == "negcontrol":
+        return negcontrol.run(
+            args.test_cmd,
+            break_cmd=args.break_cmd,
+            file_path=args.file_path,
+            restore_cmd=args.restore_cmd,
+            timeout=args.timeout,
+            expect=args.expect,
+        )
+    if args.command == "status":
+        return status.run(args.target_dir)
+    return install_skill.run(
+        target_dir=args.target_dir,
+        agent=args.agent,
+        is_global=args.is_global,
+        dest_path=args.dest_path,
+        force=args.force,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aepkit/install_skill.py

@@ -0,0 +1,126 @@
+"""Provision the protocol skill (SKILL.md and references/) into an agent or workspace."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+REFERENCES_DIR = "references"
+
+
+def _skill_source_dir() -> Path:
+    """Directory holding SKILL.md and references/: the packaged copy, else the repo root."""
+    packaged = Path(__file__).parent / "skill"
+    if (packaged / "SKILL.md").exists():
+        return packaged
+    repo_root = Path(__file__).resolve().parent.parent.parent
+    if (repo_root / "SKILL.md").exists():
+        return repo_root
+    raise FileNotFoundError("SKILL.md could not be found.")
+
+
+def _reference_files(source: Path) -> list[Path]:
+    ref_dir = source / REFERENCES_DIR
+    return sorted(ref_dir.glob("*.md")) if ref_dir.is_dir() else []
+
+
+def _bundle(source: Path) -> str:
+    """Single-file form for destinations that hold one file (Cursor rules, custom paths)."""
+    parts = [(source / "SKILL.md").read_text(encoding="utf-8").rstrip("\n")]
+    for ref in _reference_files(source):
+        body = ref.read_text(encoding="utf-8").rstrip("\n")
+        parts.append(f"<!-- {REFERENCES_DIR}/{ref.name} -->\n\n{body}")
+    return "\n\n---\n\n".join(parts) + "\n"
+
+
+def _install(source: Path, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.name != "SKILL.md":
+        dest.write_text(_bundle(source), encoding="utf-8")
+        return
+    shutil.copyfile(source / "SKILL.md", dest)
+    refs = _reference_files(source)
+    if refs:
+        ref_dest = dest.parent / REFERENCES_DIR
+        ref_dest.mkdir(exist_ok=True)
+        for ref in refs:
+            shutil.copyfile(ref, ref_dest / ref.name)
+
+
+def _detect_agent(target: Path) -> str:
+    # 1. Check workspace marker directories
+    if (target / ".agents").exists() or (target / ".gemini").exists():
+        return "antigravity"
+    if (target / ".claude").exists():
+        return "claude"
+    if (target / ".cursor").exists():
+        return "cursor"
+
+    # 2. Check runtime environment variables
+    if os.environ.get("ANTIGRAVITY_AGENT") or os.environ.get("GEMINI_CLI"):
+        return "antigravity"
+    if os.environ.get("CLAUDE_CODE") or os.environ.get("CLAUDE_PROJECT_DIR"):
+        return "claude"
+    if os.environ.get("CURSOR_PROJECT_DIR"):
+        return "cursor"
+
+    # 3. Default fallback
+    return "antigravity"
+
+
+def resolve_dest_path(
+    target_dir: str = ".",
+    agent: str = "auto",
+    is_global: bool = False,
+    dest_path: str | None = None,
+) -> Path:
+    if dest_path:
+        # A directory (existing, or written with a trailing separator) receives SKILL.md.
+        if Path(dest_path).is_dir() or dest_path.endswith(("/", os.sep)):
+            return Path(dest_path) / "SKILL.md"
+        return Path(dest_path)
+
+    home = Path.home()
+    if is_global:
+        if agent == "claude":
+            return home / ".claude" / "skills" / "auditor-executor-protocol" / "SKILL.md"
+        if agent == "cursor":
+            return home / ".cursor" / "rules" / "auditor-executor-protocol.mdc"
+        return home / ".gemini" / "config" / "skills" / "auditor-executor-protocol" / "SKILL.md"
+
+    target = Path(target_dir).resolve()
+    chosen_agent = _detect_agent(target) if agent == "auto" else agent
+
+    if chosen_agent == "claude":
+        return target / ".claude" / "skills" / "auditor-executor-protocol" / "SKILL.md"
+    if chosen_agent == "cursor":
+        return target / ".cursor" / "rules" / "auditor-executor-protocol.mdc"
+    return target / ".agents" / "skills" / "auditor-executor-protocol" / "SKILL.md"
+
+
+def run(
+    target_dir: str = ".",
+    agent: str = "auto",
+    is_global: bool = False,
+    dest_path: str | None = None,
+    force: bool = False,
+) -> int:
+    try:
+        source = _skill_source_dir()
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    dest = resolve_dest_path(
+        target_dir=target_dir, agent=agent, is_global=is_global, dest_path=dest_path
+    )
+
+    if dest.exists() and not force:
+        print(f"skip: {dest} already exists (use --force to overwrite)")
+        return 0
+
+    _install(source, dest)
+    print(f"installed {dest}")
+    return 0