sandling 0.1.0__py3-none-any.whl

sandling/__init__.py

@@ -0,0 +1,3 @@
+"""Sandling: short-lived Git workspaces that know when to leave."""
+
+__version__ = "0.1.0"

sandling/__main__.py

@@ -0,0 +1,3 @@
+from sandling.cli import main
+
+main()

sandling/cli.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from sandling.service import (
+    BootstrapError,
+    SandlingError,
+    destroy_workspace,
+    get_profile,
+    init_profile,
+    load_all_records,
+    load_config,
+    mark_ready,
+    post_push,
+    prune_metadata,
+    record_git_summary,
+    start_workspace,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sandling",
+        description="Safe, disposable Git workspaces. Temporary by design, not by neglect.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    profile = commands.add_parser("profile", help="create a configured project profile")
+    profile_commands = profile.add_subparsers(dest="profile_command", required=True)
+    profile_init = profile_commands.add_parser("init", help="add a minimal project profile")
+    profile_init.add_argument("name")
+    profile_init.add_argument("--repository-url", required=True)
+    profile_init.add_argument("--base-branch", default="main")
+
+    start = commands.add_parser("start", help="clone, select a branch, and bootstrap a workspace")
+    start.add_argument("profile", help="configured profile name")
+    start.add_argument("branch", nargs="?", help="existing remote branch to check out unchanged")
+    start.add_argument(
+        "--new-branch", metavar="BRANCH", help="create BRANCH from the configured base branch"
+    )
+    start.add_argument(
+        "--no-editor", action="store_true", help="do not launch the profile editor command"
+    )
+
+    listed = commands.add_parser("list", help="list known workspaces and their safety state")
+    listed.add_argument("profile", nargs="?", help="show only one profile")
+
+    flag = commands.add_parser("flag", help="mark a workspace ready for later destruction")
+    flag.add_argument("name", nargs="?", help="workspace name; defaults to the current workspace")
+
+    destroy = commands.add_parser("destroy", help="delete one safe, explicitly confirmed workspace")
+    destroy.add_argument("name", help="workspace name from 'sandling list'")
+    destroy.add_argument(
+        "--force", action="store_true", help="bypass Git-state safeguards; still types name"
+    )
+
+    commands.add_parser(
+        "prune-metadata", help="remove destroyed-workspace records older than seven days"
+    )
+
+    hook = commands.add_parser("_post-push", help=argparse.SUPPRESS)
+    hook.add_argument("--workspace", required=True)
+    hook.add_argument("--remote", required=True)
+    return parser
+
+
+def prompt_after_push() -> bool:
+    message = "\nSandling: push accepted. Mark this workspace ready for destruction? [y/N] "
+    try:
+        with Path("/dev/tty").open("r+", encoding="utf-8") as tty:
+            tty.write(message)
+            tty.flush()
+            return tty.readline().strip().lower() in {"y", "yes"}
+    except OSError:
+        print(
+            "Sandling: push accepted. Run 'sandling flag' when the workspace is expendable.",
+            file=sys.stderr,
+        )
+        return False
+
+
+def print_records(profile_name: str | None) -> None:
+    config = load_config()
+    records = [
+        record
+        for record in load_all_records(config)
+        if not profile_name or record.profile == profile_name
+    ]
+    if not records:
+        print("No Sandling workspaces recorded. An empty beach is not a crisis.")
+        return
+    print(f"{'NAME':<42} {'PROFILE':<18} {'STATE':<12} {'BRANCH':<30} PATH")
+    for record in records:
+        state, _ = record_git_summary(record)
+        ready = " ready" if record.ready_for_destruction_at else ""
+        row = f"{record.name:<42} {record.profile:<18} {(state + ready):<12}"
+        print(f"{row} {record.branch:<30} {record.path}")
+
+
+def confirm_destruction(name: str) -> bool:
+    return input(f"Type '{name}' to destroy that workspace directory: ").strip() == name
+
+
+def handle_start(args: argparse.Namespace) -> None:
+    if bool(args.branch) == bool(args.new_branch):
+        raise SandlingError(
+            "Use exactly one: 'sandling start PROFILE BRANCH' or '--new-branch BRANCH'."
+        )
+    config = load_config()
+    profile = get_profile(config, args.profile)
+    branch = args.new_branch or args.branch
+    record = start_workspace(
+        config,
+        profile,
+        branch=branch,
+        create_new_branch=bool(args.new_branch),
+        open_editor=not args.no_editor,
+    )
+    source = (
+        f"{profile.push_remote}/{profile.base_branch}"
+        if args.new_branch
+        else f"{profile.push_remote}/{branch} (unchanged)"
+    )
+    print(f"Sandling workspace ready: {record.path}\nBranch: {branch}\nSource: {source}")
+
+
+def handle_post_push(args: argparse.Namespace) -> None:
+    config = load_config()
+    record = post_push(
+        config,
+        workspace=Path(args.workspace).resolve(),
+        remote=args.remote,
+        pushed_refs=sys.stdin.read(),
+    )
+    if record and prompt_after_push():
+        mark_ready(config, record.name)
+        print(
+            f"Sandling: {record.name} is marked ready for destruction. "
+            "It will not wander off by itself."
+        )
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "profile":
+            path = init_profile(args.name, args.repository_url, args.base_branch)
+            print(f"Sandling profile {args.name!r} added to {path}.")
+        else:
+            config = load_config()
+            if args.command == "start":
+                prune_metadata(config)
+                handle_start(args)
+            elif args.command == "list":
+                prune_metadata(config)
+                print_records(args.profile)
+            elif args.command == "flag":
+                prune_metadata(config)
+                record = mark_ready(config, args.name)
+                print(
+                    f"Sandling: {record.name} is marked ready for destruction. "
+                    "Nothing has been deleted."
+                )
+            elif args.command == "destroy":
+                prune_metadata(config)
+                if not confirm_destruction(args.name):
+                    raise SandlingError("Destruction cancelled: workspace name did not match.")
+                record = destroy_workspace(config, args.name, force=args.force)
+                print(f"Sandling: destroyed {record.path}. Metadata is retained for seven days.")
+            elif args.command == "prune-metadata":
+                removed = prune_metadata(config)
+                print(
+                    f"Sandling: removed {removed} expired destroyed-workspace metadata record(s)."
+                )
+            elif args.command == "_post-push":
+                prune_metadata(config)
+                handle_post_push(args)
+    except BootstrapError as error:
+        print(f"Sandling workspace bootstrap failed: {error.workspace}")
+        print(f"Sandling: {error}", file=sys.stderr)
+        raise SystemExit(2) from error
+    except SandlingError as error:
+        print(f"Sandling: {error}", file=sys.stderr)
+        raise SystemExit(2) from error
+
+
+if __name__ == "__main__":
+    main()

sandling/service.py

@@ -0,0 +1,491 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tomllib
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG_DIR = Path("~/.config/sandling")
+DEFAULT_STATE_ROOT = Path("~/.local/state/sandling")
+DEFAULT_SANDBOX_ROOT = Path("~/.local/share/sandling/sandboxes")
+METADATA_NAME = ".sandling.json"
+PROFILE_NAME = re.compile(r"^[a-z][a-z0-9_-]{0,63}$")
+PLACEHOLDER = re.compile(r"\{([a-z_]+)\}")
+ALLOWED_PLACEHOLDERS = {"sandbox", "profile", "branch"}
+
+
+class SandlingError(RuntimeError):
+    """An expected, actionable Sandling failure."""
+
+
+class BootstrapError(SandlingError):
+    def __init__(self, workspace: Path, error: SandlingError) -> None:
+        self.workspace = workspace
+        super().__init__(f"Bootstrap failed for retained workspace {workspace}.\n{error}")
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    repository_url: str
+    base_branch: str
+    sandbox_root: Path
+    push_remote: str
+    bootstrap: tuple[tuple[str, ...], ...]
+    editor_command: tuple[str, ...] | None
+
+
+@dataclass(frozen=True)
+class Config:
+    state_root: Path
+    profiles: dict[str, Profile]
+
+
+@dataclass
+class WorkspaceRecord:
+    name: str
+    path: str
+    profile: str
+    branch: str
+    sandbox_root: str
+    push_remote: str
+    created_at: str
+    status: str
+    ready_for_destruction_at: str | None = None
+    destroyed_at: str | None = None
+
+    @property
+    def workspace_path(self) -> Path:
+        return Path(self.path)
+
+
+def utc_now() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def expand_path(value: str | Path) -> Path:
+    return Path(value).expanduser().resolve()
+
+
+def config_path() -> Path:
+    configured = os.environ.get("SANDLING_CONFIG")
+    if configured:
+        return expand_path(configured)
+    config_home = Path(os.environ.get("XDG_CONFIG_HOME", DEFAULT_CONFIG_DIR.parent))
+    return expand_path(config_home / "sandling" / "config.toml")
+
+
+def _as_string_list(value: Any, field: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+        raise SandlingError(f"{field} must be a non-empty array of strings.")
+    return tuple(value)
+
+
+def _bootstrap_steps(value: Any, profile_name: str) -> tuple[tuple[str, ...], ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise SandlingError(f"profiles.{profile_name}.bootstrap must be an array of argv arrays.")
+    return tuple(
+        _as_string_list(step, f"profiles.{profile_name}.bootstrap[{index}]")
+        for index, step in enumerate(value)
+    )
+
+
+def load_config() -> Config:
+    path = config_path()
+    if not path.exists():
+        raise SandlingError(
+            f"No Sandling configuration at {path}. "
+            "Run 'sandling profile init NAME --repository-url URL'."
+        )
+    try:
+        with path.open("rb") as handle:
+            raw = tomllib.load(handle)
+    except tomllib.TOMLDecodeError as error:
+        raise SandlingError(f"Invalid Sandling configuration at {path}: {error}") from error
+
+    settings = raw.get("settings", {})
+    if not isinstance(settings, dict):
+        raise SandlingError("settings must be a TOML table.")
+    xdg_state_root = Path(os.environ.get("XDG_STATE_HOME", DEFAULT_STATE_ROOT.parent)) / "sandling"
+    state_root = expand_path(settings.get("state_root", xdg_state_root))
+    default_sandbox_root = expand_path(settings.get("sandbox_root", DEFAULT_SANDBOX_ROOT))
+    raw_profiles = raw.get("profiles", {})
+    if not isinstance(raw_profiles, dict):
+        raise SandlingError("profiles must be a TOML table.")
+
+    profiles: dict[str, Profile] = {}
+    for name, value in raw_profiles.items():
+        if not isinstance(name, str) or not PROFILE_NAME.fullmatch(name):
+            raise SandlingError(
+                "Profile names must start with a lowercase letter and contain letters, "
+                "digits, _ or -."
+            )
+        if not isinstance(value, dict):
+            raise SandlingError(f"profiles.{name} must be a TOML table.")
+        repository_url = value.get("repository_url")
+        if not isinstance(repository_url, str) or not repository_url.strip():
+            raise SandlingError(f"profiles.{name}.repository_url must be a non-empty string.")
+        base_branch = value.get("base_branch", "main")
+        push_remote = value.get("push_remote", "origin")
+        if not isinstance(base_branch, str) or not base_branch:
+            raise SandlingError(f"profiles.{name}.base_branch must be a non-empty string.")
+        if not isinstance(push_remote, str) or not push_remote:
+            raise SandlingError(f"profiles.{name}.push_remote must be a non-empty string.")
+        editor_value = value.get("editor_command")
+        profiles[name] = Profile(
+            name=name,
+            repository_url=repository_url,
+            base_branch=base_branch,
+            sandbox_root=expand_path(value.get("sandbox_root", default_sandbox_root / name)),
+            push_remote=push_remote,
+            bootstrap=_bootstrap_steps(value.get("bootstrap"), name),
+            editor_command=(
+                _as_string_list(editor_value, f"profiles.{name}.editor_command")
+                if editor_value is not None
+                else None
+            ),
+        )
+    return Config(state_root=state_root, profiles=profiles)
+
+
+def init_profile(name: str, repository_url: str, base_branch: str) -> Path:
+    if not PROFILE_NAME.fullmatch(name):
+        raise SandlingError(
+            "Profile names must start with a lowercase letter and contain letters, digits, _ or -."
+        )
+    if not repository_url.strip():
+        raise SandlingError("repository URL must not be empty.")
+    if not base_branch.strip():
+        raise SandlingError("base branch must not be empty.")
+    path = config_path()
+    if path.exists():
+        config = load_config()
+        if name in config.profiles:
+            raise SandlingError(f"Profile {name!r} already exists in {path}.")
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            "# Sandling profiles. Bootstrap commands are argv arrays; no shell is involved.\n",
+            encoding="utf-8",
+        )
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(
+            f"\n[profiles.{name}]\n"
+            f"repository_url = {json.dumps(repository_url)}\n"
+            f"base_branch = {json.dumps(base_branch)}\n"
+        )
+    return path
+
+
+def get_profile(config: Config, name: str) -> Profile:
+    try:
+        return config.profiles[name]
+    except KeyError as error:
+        known = ", ".join(sorted(config.profiles)) or "none"
+        raise SandlingError(f"Unknown profile {name!r}. Configured profiles: {known}.") from error
+
+
+def state_path(config: Config, name: str) -> Path:
+    return config.state_root / "workspaces" / f"{name}.json"
+
+
+def save_record(config: Config, record: WorkspaceRecord) -> None:
+    path = state_path(config, record.name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(asdict(record), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _record_from_path(path: Path) -> WorkspaceRecord:
+    try:
+        return WorkspaceRecord(**json.loads(path.read_text(encoding="utf-8")))
+    except (OSError, TypeError, json.JSONDecodeError) as error:
+        raise SandlingError(f"Invalid Sandling metadata at {path}: {error}") from error
+
+
+def load_record(config: Config, name: str) -> WorkspaceRecord:
+    path = state_path(config, name)
+    if not path.exists():
+        raise SandlingError(
+            f"No Sandling workspace named {name!r}. Run 'sandling list' to see known workspaces."
+        )
+    return _record_from_path(path)
+
+
+def load_all_records(config: Config) -> list[WorkspaceRecord]:
+    records_dir = config.state_root / "workspaces"
+    if not records_dir.exists():
+        return []
+    return [_record_from_path(path) for path in sorted(records_dir.glob("*.json"))]
+
+
+def run(
+    command: list[str], *, cwd: Path | None = None, capture: bool = False
+) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(command, cwd=cwd, check=True, text=True, capture_output=capture)
+    except FileNotFoundError as error:
+        raise SandlingError(f"Required command not found: {command[0]}") from error
+    except subprocess.CalledProcessError as error:
+        detail = (error.stderr or error.stdout or "command failed").strip()
+        raise SandlingError(f"Command failed: {' '.join(command)}\n{detail}") from error
+
+
+def branch_slug(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", value.lower()).strip("_")
+
+
+def workspace_name(branch: str) -> str:
+    slug = branch_slug(branch)
+    if not slug:
+        raise SandlingError("Branch name must contain at least one letter or number.")
+    return f"{slug}-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
+
+
+def metadata_path(workspace: Path) -> Path:
+    return workspace / METADATA_NAME
+
+
+def write_workspace_metadata(workspace: Path, record: WorkspaceRecord) -> None:
+    metadata_path(workspace).write_text(
+        json.dumps(asdict(record), indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+
+
+def install_local_exclude(workspace: Path) -> None:
+    exclude = workspace / ".git" / "info" / "exclude"
+    current = exclude.read_text(encoding="utf-8") if exclude.exists() else ""
+    if METADATA_NAME not in current.splitlines():
+        exclude.parent.mkdir(parents=True, exist_ok=True)
+        with exclude.open("a", encoding="utf-8") as handle:
+            if current and not current.endswith("\n"):
+                handle.write("\n")
+            handle.write(f"{METADATA_NAME}\n")
+
+
+def install_post_push_hook(workspace: Path) -> None:
+    hook = workspace / ".git" / "hooks" / "post-push"
+    python = str(Path(sys.executable).resolve())
+    hook.parent.mkdir(parents=True, exist_ok=True)
+    hook.write_text(
+        "#!/bin/sh\n"
+        "# Installed by Sandling. It reminds; it never deletes.\n"
+        'workspace="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0\n'
+        f'exec "{python}" -m sandling _post-push --workspace "$workspace" --remote "$1"\n',
+        encoding="utf-8",
+    )
+    hook.chmod(0o755)
+
+
+def expand_command(
+    command: tuple[str, ...], *, workspace: Path, profile: Profile, branch: str
+) -> list[str]:
+    variables = {"sandbox": str(workspace), "profile": profile.name, "branch": branch}
+    expanded: list[str] = []
+    for argument in command:
+        unknown = set(PLACEHOLDER.findall(argument)) - ALLOWED_PLACEHOLDERS
+        if unknown:
+            raise SandlingError(f"Unsupported placeholder(s): {', '.join(sorted(unknown))}.")
+        for key, value in variables.items():
+            argument = argument.replace("{" + key + "}", value)
+        expanded.append(argument)
+    return expanded
+
+
+def start_workspace(
+    config: Config,
+    profile: Profile,
+    *,
+    branch: str,
+    create_new_branch: bool,
+    open_editor: bool = True,
+) -> WorkspaceRecord:
+    name = workspace_name(branch)
+    workspace = profile.sandbox_root / name
+    if workspace.exists():
+        raise SandlingError(f"Workspace path already exists: {workspace}")
+    profile.sandbox_root.mkdir(parents=True, exist_ok=True)
+    record = WorkspaceRecord(
+        name=name,
+        path=str(workspace),
+        profile=profile.name,
+        branch=branch,
+        sandbox_root=str(profile.sandbox_root),
+        push_remote=profile.push_remote,
+        created_at=utc_now(),
+        status="creating",
+    )
+    save_record(config, record)
+    try:
+        run(
+            [
+                "git",
+                "clone",
+                "--origin",
+                profile.push_remote,
+                profile.repository_url,
+                str(workspace),
+            ]
+        )
+        run(["git", "fetch", profile.push_remote, "--prune"], cwd=workspace)
+        if create_new_branch:
+            run(
+                [
+                    "git",
+                    "switch",
+                    "--create",
+                    branch,
+                    f"{profile.push_remote}/{profile.base_branch}",
+                ],
+                cwd=workspace,
+            )
+        elif branch == profile.base_branch:
+            run(["git", "switch", branch], cwd=workspace)
+        else:
+            run(
+                ["git", "switch", "--track", "--create", branch, f"{profile.push_remote}/{branch}"],
+                cwd=workspace,
+            )
+        install_local_exclude(workspace)
+        install_post_push_hook(workspace)
+        write_workspace_metadata(workspace, record)
+        for command in profile.bootstrap:
+            try:
+                run(
+                    expand_command(command, workspace=workspace, profile=profile, branch=branch),
+                    cwd=workspace,
+                )
+            except SandlingError as error:
+                raise BootstrapError(workspace, error) from error
+    except SandlingError:
+        record.status = "bootstrap_failed"
+        save_record(config, record)
+        if workspace.exists():
+            write_workspace_metadata(workspace, record)
+        raise
+    record.status = "active"
+    save_record(config, record)
+    write_workspace_metadata(workspace, record)
+    if open_editor and profile.editor_command:
+        command = expand_command(
+            profile.editor_command, workspace=workspace, profile=profile, branch=branch
+        )
+        try:
+            subprocess.Popen(command, cwd=workspace, start_new_session=True)
+        except FileNotFoundError as error:
+            raise SandlingError(
+                f"Workspace is ready, but editor command was not found: {command[0]}"
+            ) from error
+    return record
+
+
+def find_record_for_current_directory(config: Config) -> WorkspaceRecord:
+    current = Path.cwd().resolve()
+    for candidate in [current, *current.parents]:
+        metadata = metadata_path(candidate)
+        if metadata.exists():
+            return load_record(config, _record_from_path(metadata).name)
+    raise SandlingError(
+        "Current directory is not inside a Sandling workspace. Pass a workspace name explicitly."
+    )
+
+
+def mark_ready(config: Config, name: str | None = None) -> WorkspaceRecord:
+    record = load_record(config, name) if name else find_record_for_current_directory(config)
+    if record.status == "destroyed":
+        raise SandlingError(f"Workspace {record.name!r} was already destroyed.")
+    record.ready_for_destruction_at = utc_now()
+    save_record(config, record)
+    if record.workspace_path.exists():
+        write_workspace_metadata(record.workspace_path, record)
+    return record
+
+
+def record_git_summary(record: WorkspaceRecord) -> tuple[str, str]:
+    workspace = record.workspace_path
+    if not workspace.exists():
+        return "missing", ""
+    if record.status == "destroyed":
+        return "destroyed", ""
+    try:
+        dirty = run(["git", "status", "--porcelain"], cwd=workspace, capture=True).stdout.strip()
+        return ("dirty" if dirty else record.status), dirty
+    except SandlingError:
+        return "invalid", ""
+
+
+def require_safe_to_destroy(record: WorkspaceRecord) -> None:
+    workspace = record.workspace_path
+    if not workspace.exists():
+        raise SandlingError(f"Workspace directory no longer exists: {workspace}")
+    status = run(
+        ["git", "status", "--porcelain", "--untracked-files=all"], cwd=workspace, capture=True
+    )
+    if status.stdout.strip():
+        raise SandlingError(
+            "Refusing destruction: working tree contains tracked, staged, or untracked changes."
+        )
+    try:
+        ahead = run(
+            ["git", "rev-list", "--count", "@{upstream}..HEAD"], cwd=workspace, capture=True
+        )
+    except SandlingError as error:
+        raise SandlingError(
+            "Refusing destruction: branch has no usable upstream. Push it first or use --force."
+        ) from error
+    if int(ahead.stdout.strip()) > 0:
+        raise SandlingError(
+            "Refusing destruction: local commits have not been pushed to the upstream branch."
+        )
+
+
+def destroy_workspace(config: Config, name: str, *, force: bool) -> WorkspaceRecord:
+    record = load_record(config, name)
+    if record.status == "destroyed":
+        raise SandlingError(f"Workspace {name!r} was already destroyed on {record.destroyed_at}.")
+    if not force:
+        require_safe_to_destroy(record)
+    workspace = record.workspace_path.resolve()
+    root = expand_path(record.sandbox_root)
+    if workspace.parent != root or not metadata_path(workspace).exists():
+        raise SandlingError(
+            "Refusing destruction: target is not a direct, managed Sandling workspace."
+        )
+    shutil.rmtree(workspace)
+    record.status = "destroyed"
+    record.destroyed_at = utc_now()
+    save_record(config, record)
+    return record
+
+
+def prune_metadata(config: Config, *, retention_days: int = 7) -> int:
+    cutoff = datetime.now(UTC) - timedelta(days=retention_days)
+    removed = 0
+    for record in load_all_records(config):
+        if (
+            record.status == "destroyed"
+            and record.destroyed_at
+            and datetime.fromisoformat(record.destroyed_at) <= cutoff
+        ):
+            state_path(config, record.name).unlink(missing_ok=True)
+            removed += 1
+    return removed
+
+
+def post_push(
+    config: Config, *, workspace: Path, remote: str, pushed_refs: str
+) -> WorkspaceRecord | None:
+    if not pushed_refs.strip() or not metadata_path(workspace).exists():
+        return None
+    record = _record_from_path(metadata_path(workspace))
+    if remote != record.push_remote:
+        return None
+    return load_record(config, record.name)

sandling-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: sandling
+Version: 0.1.0
+Summary: Safe, disposable Git workspaces with fewer abandoned clones.
+Author-email: Camilla Buys <camilla.buys@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: POSIX
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Dynamic: license-file
+
+# Sandling
+
+> **Small, temporary Git workspaces that know when to leave.** A Sandling is for
+> debugging, building, and pushing—not becoming an archaeological layer in your home directory.
+
+Sandling creates an isolated clone for a configured project, selects exactly the branch you ask
+for, runs explicit bootstrap commands, and can remind you when the workspace is ready to retire.
+It never deletes automatically. Sandboxes are disposable; your work is not.
+
+## What it does
+
+- Manages one or more explicit project profiles. A new install has no repository configured.
+- Creates workspaces from a freshly fetched base branch or an existing remote branch unchanged.
+- Runs profile bootstrap steps as argument arrays, never through a shell.
+- Optionally launches your configured editor.
+- Installs a local post-push reminder. It can mark a workspace ready; it cannot delete one.
+- Refuses ordinary destruction when a workspace is dirty, contains untracked files, has unpushed
+  commits, or lacks a usable upstream.
+
+## Install
+
+Sandling supports Linux and macOS with Python 3.11 or later.
+
+```bash
+pipx install sandling
+sandling --help
+```
+
+Upgrade a published installation with `pipx upgrade sandling`. Sandling does not try to update
+itself from a random checkout; that is how tools acquire hobbies.
+
+For local development:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m ruff check src tests
+python -m ruff format --check src tests
+```
+
+## Configure a project
+
+Create a profile for any Git repository:
+
+```bash
+sandling profile init demo --repository-url https://example.test/demo.git --base-branch main
+```
+
+This creates `~/.config/sandling/config.toml` (or `$XDG_CONFIG_HOME/sandling/config.toml`). Add
+optional bootstrap and editor commands as shell-free argument arrays:
+
+```toml
+[profiles.demo]
+repository_url = "https://example.test/demo.git"
+base_branch = "main"
+editor_command = ["code", "."]
+bootstrap = [
+  ["python3", "-m", "venv", ".venv"],
+  ["{sandbox}/.venv/bin/python", "-m", "pip", "install", "-r", "requirements.txt"],
+]
+```
+
+Recognised placeholders are `{sandbox}`, `{profile}`, and `{branch}`. The profile is your
+configuration; review it with the same calm suspicion you reserve for shell aliases copied from
+the internet.
+
+## Start work
+
+Create a new branch from the profile's freshly fetched base branch:
+
+```bash
+sandling start demo --new-branch fix/parse-dates
+```
+
+Or check out an existing remote branch without merging or rebasing it:
+
+```bash
+sandling start demo fix/parse-dates
+```
+
+List known workspaces and mark one after its push is accepted:
+
+```bash
+sandling list
+sandling flag fix_parse_dates-20261110-090000
+```
+
+In an interactive Bash shell, source `scripts/sandling-shell.bash` if you want successful
+`sandling start` calls to enter the newly created workspace. A Python process cannot move its
+parent shell; physics is rude but consistent.
+
+## Safe cleanup
+
+Destroying requires an exact-name confirmation:
+
+```bash
+sandling destroy fix_parse_dates-20261110-090000
+```
+
+Normal destruction refuses dirty, untracked, unpushed, and upstream-less workspaces. `--force`
+bypasses those Git-state checks but still requires the exact workspace name. Use it slowly, after
+checking the path, and ideally after coffee.
+
+Destroyed-workspace metadata remains for seven days. `sandling prune-metadata` removes only those
+expired records; it never removes a workspace directory. There is deliberately no clean-all and no
+remote-branch deletion command.
+
+## Security and scope
+
+Sandling runs only the commands you place in a profile and never invokes a shell for bootstrap
+steps. It does not manage credentials, install system dependencies, configure project services, or
+make remote Git changes other than normal user-initiated pushes from a workspace.
+
+Report vulnerabilities through the process in [SECURITY.md](SECURITY.md). Contributions are
+welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+Created by Camilla Buys. Build fast. Push clean. Leave no clones behind.

sandling-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sandling/__init__.py,sha256=l9fy3KcQGbQYLe0Z4PJ7qUQ-heWpp08LOWYmhq1mF8Y,91
+sandling/__main__.py,sha256=YGs7mu3aWup4dHk27xBlxdsODhyxkLzjQ2KZ35QEM-I,38
+sandling/cli.py,sha256=IlqQcHgGxaH4tYDo7nYizlP6tWpgEIz_LZh1KRJQnXg,7191
+sandling/service.py,sha256=DVw6K9zYpzmx1TiMB3P7NsLX_dcK0IW3ZJqfGxpmI8Y,17900
+sandling-0.1.0.dist-info/licenses/LICENSE,sha256=6ABkA3YA59ExTfToDTR3k2qhjpvDJExAF_XYi58efoo,1069
+sandling-0.1.0.dist-info/METADATA,sha256=Sl8R-zGvnJrndD7a7WRxLcubttJnKbJCYNEN4wGNkMg,4618
+sandling-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sandling-0.1.0.dist-info/entry_points.txt,sha256=0CoQ9QzoH7eT2hCG5rw9IfTNGXi_kOznPsoyGp7eAhQ,47
+sandling-0.1.0.dist-info/top_level.txt,sha256=iWifh5kHdLZ96lfVKX6zR1zOBAPKQrMAh2KqVe7R5mw,9
+sandling-0.1.0.dist-info/RECORD,,

sandling-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sandling-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sandling = sandling.cli:main

sandling-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Camilla Buys
+
+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.

sandling-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sandling