sandling 0.1.0__tar.gz

sandling-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,119 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sandling"
+version = "0.1.0"
+description = "Safe, disposable Git workspaces with fewer abandoned clones."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Camilla Buys", email = "camilla.buys@gmail.com" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: POSIX",
+]
+
+[project.scripts]
+sandling = "sandling.cli:main"
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8.0", "ruff>=0.9"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

sandling-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sandling-0.1.0/src/sandling/__init__.py

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

sandling-0.1.0/src/sandling/__main__.py

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

sandling-0.1.0/src/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()