ai-kit-python 1.4.2__py3-none-any.whl

aikit/tests/build_distribution.py

@@ -0,0 +1,73 @@
+"""Build release archives in an isolated copy with synthetic private-file probes."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+import check_distribution
+
+ROOT = Path(__file__).resolve().parents[1]
+PRIVATE_PROBES = ("AGENTS.md", "PROJECT_CONTEXT.md", "WIKI.md", "auth.json",
+                  "ai-kit/.memory/session/private.json", "ai-kit/.metrics/private.json",
+                  "ai-kit/.upstream-cache/private.md", "ai-kit/.design/private.md",
+                  "docs/.private/private.md", "docs/auth.json", "docs/.env.release",
+                  "template/.env", "docs/private.pem", "docs/id_ed25519")
+MARKER = b"SYNTHETIC_PRIVATE_" + b"DISTRIBUTION_PROBE_MUST_NOT_SHIP"
+
+
+def prepare(destination: Path) -> list[dict]:
+    destination = destination.resolve()
+    if destination.is_relative_to(ROOT):
+        raise ValueError("Distribution output must be outside the source checkout")
+    if list(destination.glob("*.whl")) or list(destination.glob("*.tar.gz")):
+        raise ValueError("Choose an output directory without existing distribution archives")
+    destination.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="aikit-source-", dir=destination.parent) as temporary:
+        source = Path(temporary) / "source"
+        source.mkdir()
+        names = {p.name for pattern in ("*.md", "*.py") for p in ROOT.glob(pattern)} - check_distribution.LOCAL_FILES
+        names.update(("VERSION", "LICENSE", "MANIFEST.in", "pyproject.toml", "Makefile", "Dockerfile",
+                      ".dockerignore", ".gitignore", ".gitattributes"))
+        for name in sorted(names):
+            shutil.copy2(ROOT / name, source / name)
+        ignore = shutil.ignore_patterns(".git", "__pycache__", "*.pyc", "*.egg-info", ".memory", ".metrics",
+                                       ".upstream-cache", ".design", ".private", ".env", ".env.*", "auth.json",
+                                       ".aws", ".codex", ".claude", ".secrets", ".netrc", ".pypirc",
+                                       "*.pem", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*")
+        for name in ("scripts", "tests", "docs", "template", "templates", "integrations", "ai-kit", ".agents", ".github", "docker", "deploy"):
+            shutil.copytree(ROOT / name, source / name, ignore=ignore)
+        for name in PRIVATE_PROBES:
+            path = source / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(MARKER + b"\n")
+        subprocess.run([sys.executable, "-m", "build", "--no-isolation", "--outdir", str(destination)],
+                       cwd=source, check=True)
+        version = (ROOT / "VERSION").read_text(encoding="utf-8").strip()
+        result = check_distribution.check_archives(destination, version)
+        for item in result:
+            members = check_distribution._members(destination / item["file"])
+            if any(MARKER in data for data in members.values()):
+                raise ValueError("Synthetic private marker leaked into an archive")
+        return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("destination", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        for item in prepare(args.destination):
+            print(item["file"] + ": metadata/resources/privacy passed; sha256=" + item["sha256"])
+        return 0
+    except (OSError, ValueError, subprocess.SubprocessError) as exc:
+        print("Distribution build refused: " + str(exc))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aikit/tests/docker_smoke.py

@@ -0,0 +1,172 @@
+"""Exercise a local CLI image with isolated fixtures and no runtime network access."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import time
+import uuid
+
+
+def docker(arguments: list[str], *, expected: int = 0, timeout: int = 180) -> str:
+    result = subprocess.run(["docker", *arguments], capture_output=True, text=True,
+                            encoding="utf-8", timeout=timeout)
+    if result.returncode != expected:
+        raise RuntimeError(f"Docker exited {result.returncode}, expected {expected}: "
+                           + result.stdout + result.stderr)
+    return result.stdout
+
+
+def runtime_arguments(image: str, project: Path | None = None, *, readonly: bool = False,
+                      entrypoint: str | None = None, create: bool = False,
+                      name: str | None = None) -> list[str]:
+    arguments = ["create" if create else "run"]
+    if not create:
+        arguments.append("--rm")
+    arguments.extend(["--init", "--network", "none", "--read-only", "--cap-drop", "ALL",
+                      "--security-opt", "no-new-privileges", "--tmpfs", "/tmp:rw,nosuid,nodev,size=256m",
+                      "--label", "ai-kit.disposable=true"])
+    if hasattr(os, "getuid") and os.getuid() != 0:
+        arguments.extend(["--user", f"{os.getuid()}:{os.getgid()}"])
+    if project is not None:
+        source = project.resolve()
+        if not source.is_dir():
+            raise ValueError("Smoke project must be an existing directory")
+        mount = f"type=bind,source={source},target=/workspace" + (",readonly" if readonly else "")
+        arguments.extend(["--mount", mount])
+    if entrypoint:
+        arguments.extend(["--entrypoint", entrypoint])
+    if name:
+        arguments.extend(["--name", name, "--label", "ai-kit.test-run=" + name])
+    if create:
+        arguments.append("--interactive")
+    return [*arguments, image]
+
+
+def context_smoke(source: Path, base: Path, builder: str | None) -> None:
+    """Use Docker's actual ignore engine on synthetic sensitive files, not user secrets."""
+    context = base / "build context"
+    output = base / "context export"
+    context.mkdir()
+    for name in ("Dockerfile", ".dockerignore"):
+        (context / name).write_bytes((source / name).read_bytes())
+    included = ("VERSION", "scripts/install.py", "template/AGENTS.md", "template/PROJECT_CONTEXT.md",
+                "template/WIKI.md", "template/.agents/skills/web-design/SKILL.md",
+                "template/ai-kit/vendor/security-audit/LICENSE", "docker/check_version.py")
+    excluded = ("AGENTS.md", "PROJECT_CONTEXT.md", "WIKI.md", ".env", ".git/config",
+                ".codex/auth.json", ".aws/credentials", "private-helper.py",
+                "docs/.private/brief.txt", "docs/auth.json", "template/.env", "ai-kit/.metrics/tasks.jsonl",
+                "ai-kit/.design/screenshots/private.png", "ai-kit/.memory/session/imports/private.json",
+                "scripts/__pycache__/private.pyc")
+    for name in included + excluded:
+        path = context / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(b"Synthetic build-context probe.\n")
+    arguments = ["buildx", "build"]
+    if builder:
+        arguments.extend(["--builder", builder])
+    arguments.extend(["--target", "context-audit", "--output", "type=local,dest=" + str(output), str(context)])
+    docker(arguments, timeout=300)
+    if not all((output / name).is_file() for name in included):
+        raise RuntimeError("Docker ignored required kit sources")
+    if any((output / name).exists() for name in excluded):
+        raise RuntimeError("Docker exposed a synthetic secret or private state in the build context")
+    print("Build context: required sources included; synthetic secrets/private state excluded.", flush=True)
+
+
+def signal_smoke(image: str, project: Path) -> None:
+    name = "aikit-cli-signal-" + uuid.uuid4().hex[:12]
+    created = False
+    try:
+        docker([*runtime_arguments(image, project, readonly=True, create=True, name=name),
+                "install", "/workspace", "--interactive"])
+        created = True
+        docker(["start", name])
+        deadline = time.monotonic() + 15
+        while "AI-KIT interactive installer" not in docker(["logs", name]):
+            if time.monotonic() >= deadline:
+                raise RuntimeError("Interactive CLI did not reach its input prompt")
+            time.sleep(0.2)
+        docker(["stop", "--time", "5", name])
+        state = json.loads(docker(["inspect", name]))[0]
+        if state["State"]["Running"] or state["State"]["ExitCode"] != 143:
+            raise RuntimeError("SIGTERM did not terminate the CLI without a forced kill")
+        print("SIGTERM reached the foreground CLI; preview terminated with exit 143.", flush=True)
+    finally:
+        if created:
+            record = json.loads(docker(["inspect", name]))[0]
+            if record["Config"]["Labels"].get("ai-kit.test-run") != name:
+                raise RuntimeError("Refusing cleanup of an unrelated container")
+            docker(["rm", "--force", name])
+
+
+def smoke(image: str, *, source: Path | None = None, builder: str | None = None) -> None:
+    inspection = json.loads(docker(["image", "inspect", image]))[0]
+    config = inspection["Config"]
+    if config["User"] != "10001:10001" or config["Entrypoint"] != ["aikit"]:
+        raise RuntimeError("Image must have a non-root user and direct aikit entry point")
+    if config.get("ExposedPorts") or config.get("Healthcheck") or config.get("Volumes"):
+        raise RuntimeError("A one-shot CLI must not introduce ports, a service probe or anonymous volumes")
+    identity_code = ("import json,os,aikit.aikit_cli; "
+                     "print(json.dumps({'uid':os.getuid(),'version':aikit.aikit_cli.__version__}))")
+    identity = json.loads(docker([*runtime_arguments(image, entrypoint="python"), "-c", identity_code]))
+    if identity["uid"] == 0 or identity["version"] != config["Labels"]["org.opencontainers.image.version"]:
+        raise RuntimeError("Runtime UID/version does not match the image contract")
+    docker([*runtime_arguments(image), "--help"])
+    docker([*runtime_arguments(image), "route", "implement a feature"])
+    docker([*runtime_arguments(image), "check"])
+
+    with tempfile.TemporaryDirectory(prefix="aikit-container-") as folder:
+        base = Path(folder).resolve()
+        project = base / "project with spaces"
+        project.mkdir(mode=0o777)
+        project.chmod(0o777)
+        preserved = {"README.md": b"Existing project README.\r\n", ".mcp.json": b'{"mcpServers":{}}\r\n'}
+        for name, data in preserved.items():
+            (project / name).write_bytes(data)
+        preview = json.loads(docker([*runtime_arguments(image, project, readonly=True), "install", "/workspace",
+                                    "--with-web-design"]))
+        if not preview["preview"] or (project / "ai-kit").exists():
+            raise RuntimeError("Preview changed the mounted project")
+        docker([*runtime_arguments(image, project, readonly=True), "install", "/workspace", "--apply"], expected=1)
+        if (project / "ai-kit").exists():
+            raise RuntimeError("Read-only mount refusal left project writes")
+        docker([*runtime_arguments(image, project), "install", "/workspace", "--agent", "codex", "--agent", "claude",
+                "--with-web-design", "--with-context7", "--with-security-audit", "--with-strix", "--apply", "--check"])
+        if preserved != {name: (project / name).read_bytes() for name in preserved}:
+            raise RuntimeError("Installation replaced existing project/client documents")
+        report = json.loads(docker([*runtime_arguments(image, project, readonly=True), "doctor", "/workspace"]))
+        if report["errors"]:
+            raise RuntimeError("Installed project failed doctor: " + str(report["errors"]))
+        selection = json.loads(docker([*runtime_arguments(image, project, readonly=True), "context", "select",
+                                       "/workspace", "--workflow", "web-design"]))
+        if selection["workflow"] != "web-design":
+            raise RuntimeError("Installed design context was not selected")
+        repeated = json.loads(docker([*runtime_arguments(image, project), "install", "/workspace", "--apply"]))
+        if repeated["writes"]:
+            raise RuntimeError("Repeated installation was not stable")
+        signal_smoke(image, project)
+        if source:
+            context_smoke(source, base, builder)
+    print("CLI image smoke passed: offline/read-only runtime, preview, refusal, all extras, preservation and rerun.", flush=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", help="Already built local image; this command does not publish images")
+    parser.add_argument("--context", type=Path, help="Reference checkout for an actual Docker ignore-engine check")
+    parser.add_argument("--builder", help="Optional dedicated builder for the context-export check")
+    args = parser.parse_args(argv)
+    try:
+        smoke(args.image, source=args.context, builder=args.builder)
+        return 0
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as exc:
+        print("Container verification failed: " + str(exc))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aikit/tests/fixtures/create-junction.ps1

@@ -0,0 +1,18 @@
+param(
+    [Parameter(Mandatory = $true)][string]$LinkPath,
+    [Parameter(Mandatory = $true)][string]$TargetPath
+)
+
+$ErrorActionPreference = 'Stop'
+try {
+    New-Item -ItemType Junction -Path $LinkPath -Target $TargetPath | Out-Null
+} catch {
+    $taskError = $_.Exception.GetBaseException()
+    if (($taskError -is [System.UnauthorizedAccessException]) -or
+        (($taskError -is [System.ComponentModel.Win32Exception]) -and
+         ($taskError.NativeErrorCode -in @(5, 1314)))) {
+        Write-Error -Message 'Junction creation unavailable: access or privilege denied.' -ErrorAction Continue
+        exit 77
+    }
+    throw
+}

aikit/tests/fixtures/golden/claude-settings-local.json

@@ -0,0 +1,58 @@
+{
+  "permissions": {
+    "ask": [
+      "Bash(git commit)",
+      "Bash(git commit *)",
+      "Bash(git push)",
+      "Bash(git push *)",
+      "Bash(rm -rf *)",
+      "Bash(rm -fr *)",
+      "Bash(git reset --hard*)",
+      "Bash(git clean *)",
+      "Bash(docker system prune*)",
+      "Bash(docker volume rm *)",
+      "Bash(docker volume prune*)",
+      "Bash(php artisan migrate*)",
+      "Bash(php artisan db:wipe*)",
+      "Bash(php artisan db:seed*)"
+    ],
+    "allow": [
+      "Bash(go test ./... *)",
+      "Bash(go vet ./... *)",
+      "Bash(go build ./... *)",
+      "Bash(php artisan test *)"
+    ],
+    "deny": [
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(!.env.example)",
+      "Read(!.env.*.example)",
+      "Read(!.env.dist)",
+      "Read(!.env.*.dist)",
+      "Read(.envrc)",
+      "Read(.netrc)",
+      "Read(*.pem)",
+      "Read(*.p12)",
+      "Read(*.pfx)",
+      "Read(*.private.key)",
+      "Read(id_rsa*)",
+      "Read(id_ed25519*)",
+      "Read(/secrets/**)",
+      "Read(/.secrets/**)",
+      "Read(auth.json)",
+      "Read(/web/storage/*.key)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tr -d '\\r' < \"$CLAUDE_PROJECT_DIR/.agents/hooks/session-start.sh\" | sh"
+          }
+        ]
+      }
+    ]
+  }
+}

aikit/tests/test_adapters.py

@@ -0,0 +1,105 @@
+"""Exercise adapter documentation reporting and conservative retirement."""
+import contextlib
+import io
+import json
+from pathlib import Path
+import shutil
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+import adapters
+import install
+
+
+class AdapterTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory(prefix="ai-kit-adapters-")
+        self.addCleanup(self.temp.cleanup)
+        self.base = Path(self.temp.name).resolve()
+        self.target = self.base / "project"
+        self.source = self.base / "reference"
+        shutil.copytree(install.ROOT, self.source, ignore=shutil.ignore_patterns("__pycache__", ".git"))
+
+    def apply(self, **options):
+        plan = install.build_plan(self.target, root=self.source, **options)
+        self.assertTrue(install.apply_plan(plan))
+        return plan
+
+    def test_report_exposes_documentation_and_runtime_boundaries(self):
+        self.apply(agents=["codex", "cursor"])
+        report = adapters.report(root=self.source, project=self.target)
+        by_name = {item["client"]: item for item in report["clients"]}
+        self.assertEqual(by_name["cursor"]["documentation_status"], "verified")
+        self.assertEqual(by_name["cursor"]["activation"], "unverified")
+        self.assertTrue(by_name["cursor"]["selected"])
+        self.assertIn(".cursor/rules/ai-kit.mdc", by_name["cursor"]["managed_paths"])
+        self.assertEqual(by_name["kimi"]["documentation_status"], "unverified")
+
+    def test_retire_removes_only_unchanged_owned_files_and_updates_state(self):
+        self.apply(agents=["codex", "cursor"])
+        plan = adapters.retirement_plan(self.target, "cursor", root=self.source)
+        paths = {item["path"] for item in plan["removals"]}
+        self.assertIn(".cursor/rules/ai-kit.mdc", paths)
+        self.assertTrue(any("deselected" in warning for warning in plan["warnings"]))
+        self.assertTrue(adapters.apply_retirement(plan))
+        self.assertFalse((self.target / ".cursor/rules/ai-kit.mdc").exists())
+        backup = self.target / next(item["backup"] for item in plan["removals"]
+                                    if item["path"] == ".cursor/rules/ai-kit.mdc")
+        self.assertTrue(backup.is_file())
+        state = json.loads((self.target / "ai-kit/.install-state.json").read_text(encoding="utf-8"))
+        self.assertEqual(state["agents"], ["codex"])
+        rerun = install.build_plan(self.target, root=self.source, agents=["codex"])
+        self.assertFalse(rerun["adapter_conflicts"])
+
+    def test_retire_refuses_modified_adapter_and_preserves_state(self):
+        self.apply(agents=["codex", "cursor"])
+        path = self.target / ".cursor/rules/ai-kit.mdc"
+        path.write_text(path.read_text(encoding="utf-8") + "Local note.\n", encoding="utf-8")
+        plan = adapters.retirement_plan(self.target, "cursor", root=self.source)
+        self.assertIn(".cursor/rules/ai-kit.mdc", plan["conflicts"])
+        self.assertFalse(adapters.apply_retirement(plan))
+        self.assertTrue(path.is_file())
+        state = json.loads((self.target / "ai-kit/.install-state.json").read_text(encoding="utf-8"))
+        self.assertIn("cursor", state["agents"])
+
+    def test_report_and_retire_preserve_a_file_blocking_adapter_directory(self):
+        self.apply(agents=["codex", "cline"])
+        directory = self.target / ".clinerules"
+        (directory / "ai-kit.md").unlink()
+        directory.rmdir()
+        directory.write_text("native data\n", encoding="utf-8")
+        report = adapters.report(root=self.source, project=self.target)
+        cline = next(item for item in report["clients"] if item["client"] == "cline")
+        self.assertEqual(cline["blocked_paths"], [".clinerules/ai-kit.md"])
+        plan = adapters.retirement_plan(self.target, "cline", root=self.source)
+        self.assertEqual(plan["conflicts"], [".clinerules/ai-kit.md"])
+        self.assertEqual(directory.read_text(encoding="utf-8"), "native data\n")
+
+    def test_cli_report_and_retire_preview(self):
+        self.apply(agents=["codex", "cursor"])
+        with contextlib.redirect_stdout(io.StringIO()) as output:
+            self.assertEqual(adapters.main(["report", "--project", str(self.target)]), 0)
+        self.assertIn('"client": "cursor"', output.getvalue())
+        with contextlib.redirect_stdout(io.StringIO()):
+            self.assertEqual(adapters.main(["retire", str(self.target), "--agent", "cursor"]), 0)
+        self.assertTrue((self.target / ".cursor/rules/ai-kit.mdc").is_file())
+
+    def test_audit_obstruction_does_not_hide_a_linked_ancestor(self):
+        self.apply(agents=["codex", "cursor"])
+        path = self.target / ".cursor/rules/ai-kit.mdc"
+        path.unlink()
+        path.parent.rmdir()
+        path.parent.write_text("native data\n", encoding="utf-8")
+        original = install.is_link
+        with mock.patch.object(install, "is_link", side_effect=lambda p: p == self.target / ".cursor" or original(p)):
+            with self.assertRaisesRegex(ValueError, "linked"):
+                adapters.report(root=self.source, project=self.target)
+            with self.assertRaisesRegex(ValueError, "linked"):
+                adapters.retirement_plan(self.target, "cursor", root=self.source)
+
+
+if __name__ == "__main__":
+    unittest.main()

aikit/tests/test_aikit.py

@@ -0,0 +1,79 @@
+"""Exercise the unified aikit CLI dispatcher."""
+import contextlib
+import io
+from pathlib import Path
+import sys
+import unittest
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import aikit_cli
+
+
+class AikitCliTests(unittest.TestCase):
+    def test_no_command_prints_help(self):
+        with contextlib.redirect_stdout(io.StringIO()):
+            self.assertEqual(aikit_cli.main([]), 2)
+
+    def test_route_dispatches_to_router(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            self.assertEqual(aikit_cli.main(["route", "implement a feature"]), 0)
+        self.assertIn('"level"', output.getvalue())
+
+    def test_install_help_forwards_arguments(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output), self.assertRaises(SystemExit) as context:
+            aikit_cli.main(["install", "--help"])
+        self.assertEqual(context.exception.code, 0)
+        self.assertIn("--preset", output.getvalue())
+
+    def test_benchmark_help_reaches_worker_commands(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output), self.assertRaises(SystemExit) as context:
+            aikit_cli.main(["benchmark", "--help"])
+        self.assertEqual(context.exception.code, 0)
+        self.assertIn("{run,report,review,export}", output.getvalue())
+
+    def test_version_reads_from_version_file(self):
+        self.assertEqual(aikit_cli.__version__, (Path(__file__).resolve().parents[1] / "VERSION")
+                         .read_text(encoding="utf-8").strip())
+
+    def test_version_flag_reports_bundle_without_loading_or_running_a_command(self):
+        output = io.StringIO()
+        with mock.patch.object(aikit_cli, "_load") as load, contextlib.redirect_stdout(output), self.assertRaises(SystemExit) as context:
+            aikit_cli.main(["--version"])
+        self.assertEqual(context.exception.code, 0)
+        self.assertEqual(output.getvalue().strip(), "aikit " + aikit_cli.__version__)
+        load.assert_not_called()
+
+    def test_memory_help_reaches_offline_commands(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output), self.assertRaises(SystemExit) as context:
+            aikit_cli.main(["memory", "--help"])
+        self.assertEqual(context.exception.code, 0)
+        self.assertIn("{import,merge,export}", output.getvalue())
+
+    def test_providers_dispatches_to_router(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            self.assertEqual(aikit_cli.main(["providers"]), 0)
+        self.assertIn('"provider": "gemini"', output.getvalue())
+
+    def test_adapters_dispatches_to_client_report(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            self.assertEqual(aikit_cli.main(["adapters", "report"]), 0)
+        self.assertIn('"client": "codex"', output.getvalue())
+
+    def test_loader_prefers_installed_package_module(self):
+        import types
+        package_module = types.ModuleType("aikit.scripts.install")
+        package_module.main = lambda argv=None: 0
+        with mock.patch.dict(sys.modules, {"aikit.scripts.install": package_module}):
+            self.assertIs(aikit_cli._load("install"), package_module)
+        self.assertTrue(callable(aikit_cli._load("install").main))
+
+
+if __name__ == "__main__":
+    unittest.main()