lean-sdd 0.1.0__py3-none-any.whl

lean_sdd/__init__.py

@@ -0,0 +1 @@
+"""Install the Lean-SDD workflow into a development project."""

lean_sdd/__main__.py

@@ -0,0 +1,6 @@
+"""Support invocation with python -m lean_sdd."""
+
+from lean_sdd.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lean_sdd/cli.py

@@ -0,0 +1,65 @@
+"""Command-line interface for installation and local readiness diagnostics."""
+
+import argparse
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from lean_sdd.doctor import diagnose
+from lean_sdd.installer import InstallError, initialize
+from lean_sdd.templates import package_version
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Return 0 on success, 1 on operational failure, or argparse's usage exit 2."""
+    parser = argparse.ArgumentParser(
+        prog="lean-sdd", description="Install the Lean-SDD GitHub workflow."
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {package_version()}"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    init = commands.add_parser(
+        "init", help="Install workflow files without overwriting conflicts."
+    )
+    init.add_argument("directory", nargs="?", type=Path, default=Path("."))
+    init.add_argument(
+        "--dry-run", action="store_true", help="Check and list changes without writing."
+    )
+    doctor = commands.add_parser(
+        "doctor", help="Check local setup without network access."
+    )
+    doctor.add_argument("directory", nargs="?", type=Path, default=Path("."))
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "init":
+            result = initialize(args.directory, dry_run=args.dry_run)
+            for name in result.created:
+                print(f"{'Would create' if args.dry_run else 'Created'} {name}")
+            print(f"{len(result.unchanged)} identical files left unchanged.")
+            if not args.dry_run:
+                print(
+                    "Workflow installed. Read .agents/README.md "
+                    "and run lean-sdd doctor."
+                )
+                print(
+                    "Application scaffolding and GitHub live acceptance "
+                    "remain separate steps."
+                )
+            return 0
+        checks = diagnose(args.directory)
+        for check in checks:
+            print(f"{check.status}: {check.message}")
+        print(
+            "Local checks only: no network access, "
+            "credential verification, or project tests."
+        )
+        print(
+            "Follow .agents/README.md for repository selection "
+            "and live MCP verification."
+        )
+        return 1 if any(check.status == "FAIL" for check in checks) else 0
+    except (InstallError, OSError, ValueError, subprocess.TimeoutExpired) as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1

lean_sdd/doctor.py

@@ -0,0 +1,150 @@
+"""Local diagnostics only: do not load credentials or invoke project scripts."""
+
+import json
+import os
+import shutil
+import subprocess
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from lean_sdd.installer import InstallError, check_path
+from lean_sdd.templates import STATE_PATH, installation_state, template_files
+
+
+@dataclass(frozen=True)
+class Check:
+    """A local observation; warnings are not claims of workflow readiness."""
+
+    status: Literal["PASS", "WARN", "FAIL"]
+    message: str
+
+
+def _run(arguments: list[str], target: Path) -> subprocess.CompletedProcess[str]:
+    environment = os.environ.copy()
+    # Noninteractive Bash can otherwise execute arbitrary startup commands.
+    environment.pop("BASH_ENV", None)
+    environment.pop("ENV", None)
+    return subprocess.run(
+        arguments,
+        cwd=target,
+        env=environment,
+        capture_output=True,
+        text=True,
+        timeout=10,
+        check=False,
+    )
+
+
+def _installation_checks(target: Path) -> list[Check]:
+    payload = template_files()
+    expected = json.loads(installation_state(payload))
+    state_path = target / STATE_PATH
+    check_path(state_path)
+    if not state_path.is_file():
+        return [Check("FAIL", "Installation record missing; run lean-sdd init.")]
+    if state_path.stat().st_size > 1_000_000:
+        return [Check("FAIL", "Installation record is too large.")]
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except (ValueError, UnicodeError):
+        return [Check("FAIL", "Installation record is not valid JSON.")]
+    if state != expected:
+        return [
+            Check(
+                "FAIL",
+                "Installation record differs from this installer release. "
+                "Use the matching installer or review the record; no upgrade was made.",
+            )
+        ]
+    checks = [Check("PASS", "Installation version and template record match.")]
+    for name, content in payload.items():
+        path = target / name
+        try:
+            check_path(path)
+        except InstallError:
+            checks.append(Check("FAIL", f"Unsafe installed path: {name}"))
+            continue
+        if not path.is_file():
+            checks.append(Check("FAIL", f"Missing installed file: {name}"))
+        elif path.stat().st_size != len(content) or path.read_bytes() != content:
+            checks.append(Check("WARN", f"Locally modified template: {name}"))
+    if len(checks) == 1:
+        checks.append(Check("PASS", "All installed templates match this release."))
+    return checks
+
+
+def diagnose(target: Path) -> list[Check]:
+    """Check installed files, prerequisites, and configuration without networking."""
+    target = target.expanduser().absolute()
+    check_path(target, directory=True)
+    if not target.is_dir():
+        raise InstallError("Doctor requires an existing project directory.")
+    checks = _installation_checks(target)
+    commands = ("bash", "git", "curl", "jq", "awk", "grep", "mktemp", "uv")
+    for command in commands:
+        checks.append(
+            Check("PASS", f"{command} is available.")
+            if shutil.which(command)
+            else Check("FAIL", f"Required command missing: {command}")
+        )
+    if shutil.which("bash"):
+        bash = _run(
+            ["bash", "--noprofile", "--norc", "-c", 'printf "%s" "$BASH_VERSION"'],
+            target,
+        )
+        major = bash.stdout.partition(".")[0]
+        checks.append(
+            Check("PASS", "Bash 4 or newer is available.")
+            if bash.returncode == 0 and major.isdigit() and int(major) >= 4
+            else Check("FAIL", "Workflow scripts require Bash 4 or newer.")
+        )
+    endpoint = os.environ.get("GITHUB_MCP_URL", "")
+    if not endpoint:
+        checks.append(Check("WARN", "GITHUB_MCP_URL is not exported."))
+    elif endpoint.rstrip("/") != "https://api.githubcopilot.com/mcp":
+        checks.append(
+            Check("FAIL", "GITHUB_MCP_URL is not the supported official endpoint.")
+        )
+    else:
+        checks.append(Check("PASS", "Official GitHub MCP endpoint configured."))
+    token = os.environ.get("GITHUB_TOKEN", "")
+    checks.append(
+        Check("PASS", "GITHUB_TOKEN is exported; validity and permissions not checked.")
+        if token
+        else Check("WARN", "GITHUB_TOKEN is not exported; .env files are not loaded.")
+    )
+    if shutil.which("git"):
+        git = _run(["git", "rev-parse", "--show-toplevel"], target)
+        if git.returncode or Path(git.stdout.strip()).resolve() != target.resolve():
+            checks.append(Check("WARN", "Target is not a Git worktree root."))
+        else:
+            checks.append(Check("PASS", "Target is a Git worktree root."))
+    project = target / "pyproject.toml"
+    check_path(project)
+    if project.is_file():
+        try:
+            with project.open("rb") as stream:
+                config = tomllib.load(stream)
+            checks.append(
+                Check("PASS", "Python project metadata is present.")
+                if isinstance(config.get("project"), dict)
+                else Check("WARN", "pyproject.toml has no [project] metadata.")
+            )
+        except tomllib.TOMLDecodeError:
+            checks.append(Check("FAIL", "pyproject.toml is invalid TOML."))
+    else:
+        checks.append(
+            Check("WARN", "No pyproject.toml; prepare the Python project separately.")
+        )
+    lock = target / "uv.lock"
+    check_path(lock)
+    checks.append(
+        Check("PASS", "uv.lock is present; freshness not checked.")
+        if lock.is_file()
+        else Check(
+            "WARN", "No uv.lock; lock the project dependencies before validation."
+        )
+    )
+    return checks

lean_sdd/installer.py

@@ -0,0 +1,108 @@
+"""Conservative installation: preflight every file and never overwrite one."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from lean_sdd.templates import STATE_PATH, installation_state, template_files
+
+
+class InstallError(Exception):
+    """A target cannot be initialized without risking existing content."""
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    """Report the planned or completed changes relative to the target."""
+
+    created: tuple[str, ...]
+    unchanged: tuple[str, ...]
+
+
+def check_path(path: Path, *, directory: bool = False) -> None:
+    """Reject symlinks and non-directory ancestors before accessing a target."""
+    for parent in reversed(path.parents):
+        if parent.is_symlink() or (parent.exists() and not parent.is_dir()):
+            raise InstallError(f"Unsafe parent directory: {parent}")
+    if path.is_symlink():
+        raise InstallError(f"Refusing symbolic link: {path}")
+    if path.exists() and (not path.is_dir() if directory else not path.is_file()):
+        raise InstallError(f"Unexpected file type: {path}")
+
+
+def _matches(path: Path, content: bytes) -> bool:
+    return path.stat().st_size == len(content) and path.read_bytes() == content
+
+
+def _make_directories(path: Path, created: list[Path]) -> None:
+    missing = []
+    while not path.exists():
+        missing.append(path)
+        path = path.parent
+    for directory in reversed(missing):
+        directory.mkdir()
+        created.append(directory)
+
+
+def initialize(target: Path, *, dry_run: bool = False) -> InstallResult:
+    """Install missing files, failing before writes on any content conflict.
+
+    Existing identical files are left untouched. On a write failure, remove
+    only newly created files and empty directories from this invocation. The
+    target must not be concurrently modified while initialization is running.
+    """
+    target = target.expanduser().absolute()
+    check_path(target, directory=True)
+    payload = template_files()
+    payload[STATE_PATH] = installation_state(payload)
+    missing: list[str] = []
+    unchanged: list[str] = []
+    conflicts: list[str] = []
+    for name, content in payload.items():
+        destination = target / name
+        check_path(destination)
+        if destination.exists():
+            if _matches(destination, content):
+                unchanged.append(name)
+            else:
+                conflicts.append(name)
+        else:
+            missing.append(name)
+    if conflicts:
+        raise InstallError(
+            "Conflicting files; nothing was written:\n  "
+            + "\n  ".join(conflicts)
+            + "\nReview differences using a separate empty directory. "
+            "Existing rules and installation versions are never overwritten."
+        )
+    if not dry_run:
+        written: list[Path] = []
+        directories: list[Path] = []
+        try:
+            for name in missing:
+                destination = target / name
+                check_path(destination)
+                _make_directories(destination.parent, directories)
+                with destination.open("xb") as stream:
+                    written.append(destination)
+                    stream.write(payload[name])
+                if destination.suffix == ".sh":
+                    destination.chmod(0o755)
+        except (OSError, InstallError) as error:
+            cleanup_failures: list[str] = []
+            for path in reversed(written):
+                try:
+                    path.unlink()
+                except OSError:
+                    cleanup_failures.append(str(path))
+            for path in reversed(directories):
+                try:
+                    path.rmdir()
+                except OSError:
+                    cleanup_failures.append(str(path))
+            detail = (
+                " Review leftover paths: " + ", ".join(cleanup_failures)
+                if cleanup_failures
+                else " Newly created files were removed."
+            )
+            raise InstallError(f"Installation failed: {error}.{detail}") from error
+    return InstallResult(tuple(missing), tuple(unchanged))

lean_sdd/templates.py

@@ -0,0 +1,52 @@
+"""Read the explicitly bundled, versioned workflow resources."""
+
+import hashlib
+import json
+from importlib.metadata import version
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import PurePosixPath
+
+STATE_PATH = ".agents/lean-sdd-install.json"
+
+
+def package_version() -> str:
+    """Return the version of the installed distribution."""
+    return version("lean-sdd-cli")
+
+
+def _read_tree(root: Traversable, prefix: str = "") -> dict[str, bytes]:
+    result: dict[str, bytes] = {}
+    for entry in sorted(root.iterdir(), key=lambda child: child.name):
+        name = f"{prefix}{entry.name}"
+        if entry.is_dir():
+            result.update(_read_tree(entry, f"{name}/"))
+        elif entry.is_file():
+            result[name] = entry.read_bytes()
+    return result
+
+
+def template_files() -> dict[str, bytes]:
+    """Read installed resources, including dotfiles, without locating a checkout."""
+    payload = _read_tree(files("lean_sdd_templates"))
+    required = {"AGENTS.md", "CONSTITUTION.md", "CODING_STANDARDS.md"}
+    if not required.issubset(payload) or STATE_PATH in payload:
+        raise ValueError("Installed template bundle is incomplete or invalid.")
+    for name in payload:
+        path = PurePosixPath(name)
+        if path.is_absolute() or ".." in path.parts or "\\" in name:
+            raise ValueError("Installed template bundle contains an unsafe path.")
+    return payload
+
+
+def installation_state(payload: dict[str, bytes]) -> bytes:
+    """Describe the original installed templates, without machine-local values."""
+    state = {
+        "schema_version": 1,
+        "template_version": package_version(),
+        "files": {
+            name: hashlib.sha256(content).hexdigest()
+            for name, content in sorted(payload.items())
+        },
+    }
+    return (json.dumps(state, indent=2, sort_keys=True) + "\n").encode("utf-8")