kitctl 0.0.1__tar.gz

kitctl-0.0.1/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+node_modules/
+npm/python/
+*.tgz
+.env
+.env.*
+!.env.example
+.pypirc
+inventory.json
+inventory-report.md
+reports/
+.DS_Store

kitctl-0.0.1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.0.1 — 2026-10-11
+
+- Initial Python CLI with version, help, and explicitly scoped read-only inventory.
+- Detect skill folders and config locations; compute hashes without emitting contents.
+- npm launcher bundles the same Python wheel and runs it through uvx.
+- Sandbox tests, Linux/Windows CI, MIT license, and phased implementation plan.
+
+This release does not change native agent configuration.

kitctl-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connor England
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kitctl-0.0.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: kitctl
+Version: 0.0.1
+Summary: Inventory and manage agent skills, MCP connectors, hooks, and loadouts.
+Project-URL: Repository, https://github.com/ConnorBritain/kitctl
+Project-URL: Issues, https://github.com/ConnorBritain/kitctl/issues
+Author: Connor England
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude,codex,mcp,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Kit (`kitctl`)
+
+Kit inventories the skills, MCP configuration, hooks, and plugins used by coding
+agents. The planned compiler manages named **loadouts** from a separate private
+warehouse and writes each harness's native configuration with an ownership ledger.
+The planned default warehouse location is `~/kits`; setup will ask which parent
+directories contain your repositories.
+
+**0.0.1 is an early, read-only release.** It discovers skill folders and known
+configuration files in explicitly selected roots, computes SHA-256 hashes, and
+prints text or JSON. It does not yet parse connectors, count usage, compile
+loadouts, reconcile changes, or modify agent configuration.
+
+## Run
+
+Python 3.11+:
+
+```sh
+# From a checkout (works before the PyPI release):
+uv run kitctl --version
+uv run kitctl inventory --root /path/to/repo --json
+
+# After publication to PyPI:
+uvx kitctl --version
+uv tool install kitctl
+```
+
+Node 20+ with [uv installed](https://docs.astral.sh/uv/getting-started/installation/):
+
+```sh
+# After publication to npm:
+npx kitctl --version
+npx kitctl inventory --root /path/to/repo --json
+```
+
+The npm package is a thin launcher around the bundled Python wheel from the same
+release. It uses `uvx` with that local wheel; it does not require a PyPI release,
+run install scripts, or ship a `kit` binary. uv manages Python if needed.
+
+`inventory` defaults to the current directory. Repeat `--root` to inspect several
+repositories, or explicitly pass your home directory to include user config.
+There is no recursive search through unrelated repositories. Symlinked skills and
+configuration are skipped with warnings. JSON includes file paths and hashes,
+never configuration contents. Exit codes: 0 complete, 1 partial due to skipped
+items, 2 invalid arguments or roots. Reports may reveal private paths; keep them
+out of public source control.
+
+## Develop
+
+```sh
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+uv run python scripts/prepare_npm.py
+npm --prefix npm test
+cd npm
+npm pack --dry-run
+```
+
+Tests use throwaway HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, and repository fixtures.
+CI runs on Linux and Windows with Python 3.11 and 3.14. A local pre-commit
+configuration and CI check reject common token formats and private keys. Install
+the hook with `uvx pre-commit install` if desired; this basic check is not a
+comprehensive secret scanner.
+
+See [PLAN.md](PLAN.md), [design](docs/design.md),
+[harness reference](docs/harness-reference.md), and [publishing](docs/publishing.md).
+
+## Naming
+
+Kit ships only the `kitctl` command. AWS's Kubernetes Iteration Toolkit and
+Gravwell also use a `kitctl` binary; installing those tools alongside Kit can
+cause PATH collisions. This project is independent of those projects and KitOps.
+
+MIT License. The code repository and private warehouse are deliberately separate.

kitctl-0.0.1/README.md

@@ -0,0 +1,78 @@
+# Kit (`kitctl`)
+
+Kit inventories the skills, MCP configuration, hooks, and plugins used by coding
+agents. The planned compiler manages named **loadouts** from a separate private
+warehouse and writes each harness's native configuration with an ownership ledger.
+The planned default warehouse location is `~/kits`; setup will ask which parent
+directories contain your repositories.
+
+**0.0.1 is an early, read-only release.** It discovers skill folders and known
+configuration files in explicitly selected roots, computes SHA-256 hashes, and
+prints text or JSON. It does not yet parse connectors, count usage, compile
+loadouts, reconcile changes, or modify agent configuration.
+
+## Run
+
+Python 3.11+:
+
+```sh
+# From a checkout (works before the PyPI release):
+uv run kitctl --version
+uv run kitctl inventory --root /path/to/repo --json
+
+# After publication to PyPI:
+uvx kitctl --version
+uv tool install kitctl
+```
+
+Node 20+ with [uv installed](https://docs.astral.sh/uv/getting-started/installation/):
+
+```sh
+# After publication to npm:
+npx kitctl --version
+npx kitctl inventory --root /path/to/repo --json
+```
+
+The npm package is a thin launcher around the bundled Python wheel from the same
+release. It uses `uvx` with that local wheel; it does not require a PyPI release,
+run install scripts, or ship a `kit` binary. uv manages Python if needed.
+
+`inventory` defaults to the current directory. Repeat `--root` to inspect several
+repositories, or explicitly pass your home directory to include user config.
+There is no recursive search through unrelated repositories. Symlinked skills and
+configuration are skipped with warnings. JSON includes file paths and hashes,
+never configuration contents. Exit codes: 0 complete, 1 partial due to skipped
+items, 2 invalid arguments or roots. Reports may reveal private paths; keep them
+out of public source control.
+
+## Develop
+
+```sh
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+uv run python scripts/prepare_npm.py
+npm --prefix npm test
+cd npm
+npm pack --dry-run
+```
+
+Tests use throwaway HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, and repository fixtures.
+CI runs on Linux and Windows with Python 3.11 and 3.14. A local pre-commit
+configuration and CI check reject common token formats and private keys. Install
+the hook with `uvx pre-commit install` if desired; this basic check is not a
+comprehensive secret scanner.
+
+See [PLAN.md](PLAN.md), [design](docs/design.md),
+[harness reference](docs/harness-reference.md), and [publishing](docs/publishing.md).
+
+## Naming
+
+Kit ships only the `kitctl` command. AWS's Kubernetes Iteration Toolkit and
+Gravwell also use a `kitctl` binary; installing those tools alongside Kit can
+cause PATH collisions. This project is independent of those projects and KitOps.
+
+MIT License. The code repository and private warehouse are deliberately separate.

kitctl-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kitctl"
+version = "0.0.1"
+description = "Inventory and manage agent skills, MCP connectors, hooks, and loadouts."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Connor England" }]
+keywords = ["agents", "claude", "codex", "skills", "mcp"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = []
+
+[project.scripts]
+kitctl = "kitctl.cli:main"
+
+[project.urls]
+Repository = "https://github.com/ConnorBritain/kitctl"
+Issues = "https://github.com/ConnorBritain/kitctl/issues"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "ruff>=0.11,<1", "mypy>=1.15,<2"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md", "/pyproject.toml"]

kitctl-0.0.1/src/kitctl/__init__.py

@@ -0,0 +1,3 @@
+"""Kit: inventory and manage agent tooling through deterministic loadouts."""
+
+__version__ = "0.0.1"

kitctl-0.0.1/src/kitctl/__main__.py

@@ -0,0 +1,3 @@
+from kitctl.cli import main
+
+raise SystemExit(main())

kitctl-0.0.1/src/kitctl/cli.py

@@ -0,0 +1,44 @@
+"""CLI for Kit's initial read-only release."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from kitctl import __version__
+from kitctl.inventory import inventory
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="kitctl", description="Kit — inventory and manage agent tooling."
+    )
+    parser.add_argument("--version", action="version", version=f"kitctl {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    scan = commands.add_parser("inventory", help="Read-only discovery in explicit roots.")
+    scan.add_argument(
+        "--root",
+        action="append",
+        type=Path,
+        dest="roots",
+        metavar="PATH",
+        help="Repository or home directory to inspect; repeatable. Defaults to current directory.",
+    )
+    scan.add_argument("--json", action="store_true", help="Print metadata and hashes as JSON.")
+    args = parser.parse_args(argv)
+    try:
+        report = inventory(args.roots or [Path.cwd()])
+    except (OSError, ValueError) as error:
+        print(f"kitctl: {error}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        for entry in report["entries"]:
+            print(f"{entry['kind']:6}  {entry['name']}  {entry['path']}")
+        print(f"{len(report['entries'])} items; no files changed.")
+        for warning in report["warnings"]:
+            print(f"warning: {warning}", file=sys.stderr)
+    return 1 if report["warnings"] else 0

kitctl-0.0.1/src/kitctl/inventory.py

@@ -0,0 +1,129 @@
+"""Read-only, explicitly scoped discovery. Never serialize configuration values."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import TypedDict
+
+CONFIG_PATHS = (
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".claude.json",
+    ".mcp.json",
+    ".codex/config.toml",
+    ".codex/hooks.json",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "kit.yaml",
+    "kit.lock",
+)
+SKILL_PATHS = (".claude/skills", ".agents/skills", ".codex/skills")
+
+
+@dataclass(frozen=True)
+class Entry:
+    kind: str
+    name: str
+    root: str
+    path: str
+    content_hash: str
+
+
+class Report(TypedDict):
+    schema_version: int
+    entries: list[dict[str, str]]
+    warnings: list[str]
+
+
+def _safe_file(path: Path, root: Path) -> bool:
+    """Skip links, including a link in a parent directory, and special files."""
+    relative = path.relative_to(root)
+    current = root
+    for part in relative.parts:
+        current /= part
+        if current.is_symlink():
+            return False
+    return path.is_file()
+
+
+def _file_hash(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _skill_hash(directory: Path, root: Path) -> str:
+    """Hash relative names and bytes of all regular skill assets deterministically."""
+    digest = hashlib.sha256()
+
+    def fail(error: OSError) -> None:
+        raise error
+
+    for current, dirs, files in os.walk(directory, followlinks=False, onerror=fail):
+        dirs[:] = sorted(
+            name for name in dirs if name != ".git" and not (Path(current) / name).is_symlink()
+        )
+        for name in sorted(files):
+            path = Path(current) / name
+            if _safe_file(path, root):
+                digest.update(path.relative_to(directory).as_posix().encode("utf-8"))
+                digest.update(b"\0")
+                digest.update(_file_hash(path).encode("ascii"))
+                digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def inventory(roots: list[Path]) -> Report:
+    entries: list[Entry] = []
+    warnings: list[str] = []
+    for root in sorted({path.expanduser().resolve() for path in roots}):
+        if not root.is_dir():
+            raise ValueError(f"Inventory root is not a directory: {root}")
+        for relative in CONFIG_PATHS:
+            path = root / relative
+            try:
+                if _safe_file(path, root):
+                    entries.append(
+                        Entry("config", relative, str(root), str(path), _file_hash(path))
+                    )
+                elif path.exists() or path.is_symlink():
+                    warnings.append(f"Skipped link or non-regular file: {path}")
+            except OSError:
+                warnings.append(f"Cannot read: {path}")
+        for relative in SKILL_PATHS:
+            directory = root / relative
+            try:
+                if directory.is_symlink() or any(
+                    parent.is_symlink() for parent in directory.parents if parent != root
+                ):
+                    warnings.append(f"Skipped linked skill directory: {directory}")
+                    continue
+                if not directory.is_dir():
+                    continue
+                for skill in sorted(directory.iterdir()):
+                    manifest = skill / "SKILL.md"
+                    if skill.is_symlink():
+                        warnings.append(f"Skipped linked skill: {skill}")
+                    elif manifest.is_symlink():
+                        warnings.append(f"Skipped linked skill manifest: {manifest}")
+                    elif _safe_file(manifest, root):
+                        try:
+                            entries.append(
+                                Entry(
+                                    "skill",
+                                    skill.name,
+                                    str(root),
+                                    str(skill),
+                                    _skill_hash(skill, root),
+                                )
+                            )
+                        except OSError:
+                            warnings.append(f"Cannot read complete skill: {skill}")
+            except OSError:
+                warnings.append(f"Cannot read: {directory}")
+    return {"schema_version": 1, "entries": [asdict(e) for e in entries], "warnings": warnings}

kitctl-0.0.1/tests/conftest.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def sandbox(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    home = tmp_path / "home"
+    repo = tmp_path / "repo"
+    home.mkdir()
+    repo.mkdir()
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
+    monkeypatch.setenv("CODEX_HOME", str(home / ".codex"))
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(home / ".claude"))
+    monkeypatch.chdir(repo)
+    return repo

kitctl-0.0.1/tests/test_inventory.py

@@ -0,0 +1,67 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from kitctl.cli import main
+from kitctl.inventory import inventory
+
+
+def snapshot(root: Path) -> dict[str, bytes]:
+    return {str(p.relative_to(root)): p.read_bytes() for p in root.rglob("*") if p.is_file()}
+
+
+def test_inventory_reads_hashes_without_writes_or_secret_values(sandbox: Path) -> None:
+    skill = sandbox / ".agents/skills/writing"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text("---\nname: writing\n---\nWrite clearly.")
+    config = sandbox / ".mcp.json"
+    config.write_text('{"token": "fixture-secret-value"}')
+    before = snapshot(sandbox)
+    report = inventory([sandbox, sandbox])
+    assert len(report["entries"]) == 2
+    assert report["warnings"] == []
+    assert "fixture-secret-value" not in json.dumps(report)
+    assert snapshot(sandbox) == before
+
+
+def test_asset_edits_change_skill_hash(sandbox: Path) -> None:
+    skill = sandbox / ".claude/skills/demo"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text("Demo")
+    asset = skill / "helper.py"
+    asset.write_text("print(1)")
+    first = inventory([sandbox])
+    asset.write_text("print(2)")
+    assert first != inventory([sandbox])
+
+
+def test_symlinks_do_not_read_outside_root(sandbox: Path, tmp_path: Path) -> None:
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    (outside / "SKILL.md").write_text("Private")
+    skills = sandbox / ".agents/skills"
+    skills.mkdir(parents=True)
+    try:
+        (skills / "linked").symlink_to(outside, target_is_directory=True)
+        (sandbox / ".mcp.json").symlink_to(outside / "SKILL.md")
+    except OSError:
+        pytest.skip("Symlink creation unavailable on this platform")
+    report = inventory([sandbox])
+    assert report["entries"] == []
+    assert len(report["warnings"]) == 2
+
+
+def test_cli_explicit_scope_and_missing_root(sandbox: Path, capsys: pytest.CaptureFixture) -> None:
+    (sandbox / "AGENTS.md").write_text("Instructions")
+    assert main(["inventory", "--json"]) == 0
+    assert len(json.loads(capsys.readouterr().out)["entries"]) == 1
+    assert main(["inventory", "--root", str(sandbox / "missing")]) == 2
+    assert "not a directory" in capsys.readouterr().err
+
+
+def test_version(capsys: pytest.CaptureFixture) -> None:
+    with pytest.raises(SystemExit) as result:
+        main(["--version"])
+    assert result.value.code == 0
+    assert capsys.readouterr().out == "kitctl 0.0.1\n"

kitctl-0.0.1/tests/test_secrets.py

@@ -0,0 +1,33 @@
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_staged_secret_check_uses_index_and_withholds_values(sandbox: Path) -> None:
+    checker = Path(__file__).resolve().parents[1] / "scripts/check_secrets.py"
+    subprocess.run(["git", "init", "-q"], cwd=sandbox, check=True)
+    token = "ghp_" + "A" * 36
+    candidate = sandbox / "config.txt"
+    candidate.write_text(token)
+    subprocess.run(["git", "add", "config.txt"], cwd=sandbox, check=True)
+    # Cleaning the working tree must not hide a secret still in the staging area.
+    candidate.write_text("clean")
+    result = subprocess.run(
+        [sys.executable, str(checker), "--staged"],
+        cwd=sandbox,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 1
+    assert "config.txt" in result.stderr
+    assert token not in result.stderr + result.stdout
+    subprocess.run(["git", "add", "config.txt"], cwd=sandbox, check=True)
+    result = subprocess.run(
+        [sys.executable, str(checker), "--staged"],
+        cwd=sandbox,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0