devctk 0.1.0__py3-none-any.whl

devctk-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: devctk
+Version: 0.1.0
+Summary: One-command SSH-accessible rootless Podman dev containers
+Author: y
+License-Expression: MIT
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10

devctk-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+z_ctk/__init__.py,sha256=Te0i8IdN4qfeBZ-YPfEisrLwimd7vsTzbvR2nEhBGEI,80
+z_ctk/__main__.py,sha256=AQOIm9RJ1CpoWEwW4uwQ_QP9zSXueBD9SPohkqONLtc,53
+z_ctk/cli.py,sha256=bm8ZsU8Hx-hBb6S2pjih16Pabb7hSkr10CyC4usXlAk,3057
+z_ctk/commands.py,sha256=RcOWj6Ka6IZ8qX_xV2GBy2hSWx9ozc_krwp-vm77RVM,9395
+z_ctk/helpers.py,sha256=oCH7a2F3nYlRR_K5zTyIdnrd_uLvuFQEPNT67Rssd2E,6087
+z_ctk/paths.py,sha256=5BQFFluP6lZCP99ZCkKz05P3JKCYOB1h-nUYWeLHvgk,1074
+z_ctk/systemd.py,sha256=lrmIpL60emizjUd4lXJGpWVeF59wBRbanWDSSL-lxWQ,935
+z_ctk/util.py,sha256=QQcbskmzYCk0Lj_5B8dUAbqx9axmt22VLyX-TK9qxmM,743
+devctk-0.1.0.dist-info/METADATA,sha256=IpxrQ5XBkS4K530VvsXOrlX1bqDs79BOslu9Kxg0wX8,299
+devctk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+devctk-0.1.0.dist-info/entry_points.txt,sha256=hqtJ6HZRZUHdypiloJeqq4KbrAN3it1jykJe8axXc80,42
+devctk-0.1.0.dist-info/RECORD,,

devctk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

devctk-0.1.0.dist-info/entry_points.txt

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

z_ctk/__init__.py

@@ -0,0 +1,3 @@
+"""z-ctk: one-command rootless Podman dev containers."""
+
+__version__ = "0.1.0"

z_ctk/__main__.py

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

z_ctk/cli.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import argparse
+import os
+import pathlib
+import re
+import sys
+
+NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+COMMANDS = {"init", "ls", "rm"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="z-ctk",
+        description="One-command SSH-accessible rootless Podman dev containers.",
+    )
+    sub = parser.add_subparsers(dest="command")
+    sub.required = True
+
+    # --- init ---
+    p_init = sub.add_parser("init", help="Create and enable a dev container.")
+    p_init.add_argument("--image", required=True)
+    p_init.add_argument("--port", type=int, default=39000)
+    keys = p_init.add_mutually_exclusive_group(required=True)
+    keys.add_argument("--authorized-keys", dest="authorized_keys_text")
+    keys.add_argument("--authorized-keys-file", dest="authorized_keys_file")
+    p_init.add_argument("--container-name")
+    p_init.add_argument("--container-user")
+    p_init.add_argument("--workspace")
+    p_init.add_argument("--no-workspace", action="store_true")
+    p_init.add_argument("--mount", action="append", default=[])
+    p_init.add_argument("--device", action="append", default=[])
+
+    # --- ls ---
+    sub.add_parser("ls", help="List managed containers.")
+
+    # --- rm ---
+    p_rm = sub.add_parser("rm", help="Remove a managed container.")
+    p_rm.add_argument("container_name", nargs="?")
+    p_rm.add_argument("--all", action="store_true")
+
+    return parser
+
+
+def normalize_argv(argv: list[str]) -> list[str]:
+    """Treat bare args (no subcommand) as `init`."""
+    if not argv:
+        return argv
+    if argv[0] in COMMANDS or argv[0] in {"-h", "--help"}:
+        return argv
+    return ["init", *argv]
+
+
+def split_passthrough(argv: list[str]) -> tuple[list[str], list[str]]:
+    if "--" not in argv:
+        return argv, []
+    idx = argv.index("--")
+    return argv[:idx], argv[idx + 1 :]
+
+
+BANNED_PASSTHROUGH = {
+    "--mount", "--volume", "--publish", "--name", "--device", "--user",
+    "--userns", "--restart", "--rm", "--replace", "--entrypoint",
+    "--init", "--stop-timeout",
+}
+
+
+def validate_passthrough(args: list[str]) -> None:
+    for tok in args:
+        if tok in BANNED_PASSTHROUGH or any(tok.startswith(f + "=") for f in BANNED_PASSTHROUGH):
+            raise SystemExit(f"unsupported passthrough flag: {tok}")
+        if tok.startswith(("-p", "-v", "-u")):
+            raise SystemExit(f"unsupported passthrough flag: {tok}")
+
+
+def main() -> int:
+    from z_ctk.commands import cmd_init, cmd_ls, cmd_rm
+
+    if os.geteuid() == 0:
+        raise SystemExit("refuse to run as root")
+
+    argv = normalize_argv(sys.argv[1:])
+    ours, passthrough = split_passthrough(argv)
+    parser = build_parser()
+    args = parser.parse_args(ours)
+
+    if args.command == "init":
+        validate_passthrough(passthrough)
+        return cmd_init(args, passthrough)
+    if args.command == "ls":
+        return cmd_ls()
+    if args.command == "rm":
+        return cmd_rm(args)
+
+    raise SystemExit(f"unknown command: {args.command}")

z_ctk/commands.py

@@ -0,0 +1,249 @@
+"""Command implementations: init, ls, rm."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import stat
+import sys
+
+from z_ctk.paths import ManagedPaths, managed_paths, state_root, STATE_DIR_NAME
+from z_ctk.helpers import render_container_helper, render_sshd_helper
+from z_ctk.systemd import render_unit
+from z_ctk.util import require_binary, run, write_text, unlink_if_exists
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+def resolve_authorized_keys(args: argparse.Namespace) -> tuple[pathlib.Path | None, str | None, str]:
+    """Return (file_path | None, text | None, source_tag)."""
+    if args.authorized_keys_file is not None:
+        p = pathlib.Path(args.authorized_keys_file).expanduser().resolve()
+        if not p.is_file():
+            raise SystemExit(f"authorized_keys file not found: {p}")
+        if p.stat().st_size == 0:
+            raise SystemExit(f"authorized_keys file is empty: {p}")
+        return p, None, "file"
+    text = args.authorized_keys_text
+    if not text or not text.strip():
+        raise SystemExit("authorized_keys text is empty")
+    return None, text, "inline"
+
+
+def build_workspace_mount(workspace: str | None, no_workspace: bool, container_user: str) -> tuple[str | None, str]:
+    home = f"/home/{container_user}"
+    if no_workspace:
+        return None, home
+    if workspace is None:
+        d = pathlib.Path.home() / "dev-container"
+        d.mkdir(parents=True, exist_ok=True)
+        return f"type=bind,src={d},target={home},rw", home
+
+    # Check if it's a full mount spec
+    fields = {k: v for k, _, v in (p.partition("=") for p in workspace.split(",")) if v}
+    if {"type", "src", "source", "target", "destination", "dst"} & fields.keys():
+        target = fields.get("target") or fields.get("destination") or fields.get("dst")
+        if not target:
+            raise SystemExit("--workspace mount spec must include target=...")
+        return workspace, target
+
+    d = pathlib.Path(workspace).expanduser().resolve()
+    d.mkdir(parents=True, exist_ok=True)
+    return f"type=bind,src={d},target={home},rw", home
+
+
+def cmd_init(args: argparse.Namespace, passthrough: list[str]) -> int:
+    from z_ctk.cli import NAME_RE
+
+    user = os.environ.get("USER") or pathlib.Path.home().name
+    container_user = args.container_user or user
+    container_name = args.container_name or f"{user}-dev"
+
+    if not NAME_RE.match(container_user):
+        raise SystemExit(f"invalid container user: {container_user}")
+    if not NAME_RE.match(container_name):
+        raise SystemExit(f"invalid container name: {container_name}")
+    if not 1 <= args.port <= 65535:
+        raise SystemExit(f"invalid port: {args.port}")
+    if args.no_workspace and args.workspace:
+        raise SystemExit("--workspace and --no-workspace conflict")
+
+    ak_file, ak_text, ak_source = resolve_authorized_keys(args)
+    workspace_mount, container_home = build_workspace_mount(args.workspace, args.no_workspace, container_user)
+
+    mounts = list(args.mount)
+    if workspace_mount:
+        mounts.insert(0, workspace_mount)
+
+    podman = require_binary("podman")
+    systemctl = require_binary("systemctl")
+    loginctl = require_binary("loginctl")
+
+    # Conflict checks
+    if run([podman, "container", "exists", container_name], check=False).returncode == 0:
+        raise SystemExit(f"container already exists: {container_name}")
+
+    paths = managed_paths(container_name)
+    for p in [paths.container_unit, paths.sshd_unit, paths.container_helper, paths.sshd_helper, paths.metadata]:
+        if p.exists():
+            raise SystemExit(f"managed files already exist for {container_name}")
+
+    # Write helpers + units
+    write_text(
+        paths.container_helper,
+        render_container_helper(podman, container_name, args.image, args.port, mounts, args.device, passthrough),
+        stat.S_IRWXU,
+    )
+    write_text(
+        paths.sshd_helper,
+        render_sshd_helper(podman, container_name, container_user, os.getuid(), os.getgid(), container_home, ak_file, ak_text),
+        stat.S_IRWXU,
+    )
+    write_text(paths.container_unit, render_unit("container", container_name=container_name, container_helper=str(paths.container_helper)))
+    write_text(paths.sshd_unit, render_unit("sshd", container_name=container_name, container_unit=paths.container_unit.name, sshd_helper=str(paths.sshd_helper)))
+
+    # Metadata
+    write_text(paths.metadata, json.dumps({
+        "container_name": container_name,
+        "container_user": container_user,
+        "image": args.image,
+        "port": args.port,
+        "container_home": container_home,
+        "workspace_mount": workspace_mount or "",
+        "authorized_keys_source": ak_source,
+    }, indent=2, sort_keys=True) + "\n")
+
+    # Enable — rollback on failure
+    try:
+        run([systemctl, "--user", "daemon-reload"])
+        run([systemctl, "--user", "enable", "--now", paths.container_unit.name])
+        run([systemctl, "--user", "enable", "--now", paths.sshd_unit.name])
+    except Exception:
+        print(f"startup failed, cleaning up {container_name}", file=sys.stderr)
+        _cleanup(podman, systemctl, paths, container_name)
+        raise
+
+    print(f"started {container_name}")
+    print(f"  ssh {container_user}@localhost -p {args.port}")
+
+    # Linger check
+    res = run([loginctl, "show-user", user, "-p", "Linger"], check=False, capture=True)
+    if res.returncode == 0 and res.stdout.strip().endswith("no"):
+        print(f"  hint: sudo loginctl enable-linger {user}", file=sys.stderr)
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# ls
+# ---------------------------------------------------------------------------
+
+def cmd_ls() -> int:
+    names = list_names()
+    if not names:
+        print("no z-ctk containers")
+        return 0
+
+    podman = require_binary("podman")
+    systemctl = require_binary("systemctl")
+
+    for name in names:
+        paths = managed_paths(name)
+        meta = _read_meta(paths.metadata)
+        parts = [
+            name,
+            f"user={meta.get('container_user', '-')}",
+            f"podman={_container_status(podman, name)}",
+            f"port={meta.get('port', '-')}",
+            f"image={meta.get('image', '-')}",
+        ]
+        print("  ".join(parts))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# rm
+# ---------------------------------------------------------------------------
+
+def cmd_rm(args: argparse.Namespace) -> int:
+    user = os.environ.get("USER") or pathlib.Path.home().name
+
+    if args.all and args.container_name:
+        raise SystemExit("rm accepts either a name or --all, not both")
+
+    if args.all:
+        names = list_names()
+        if not names:
+            print("no z-ctk containers")
+            return 0
+    else:
+        names = [args.container_name or f"{user}-dev"]
+
+    podman = require_binary("podman")
+    systemctl = require_binary("systemctl")
+
+    for name in names:
+        paths = managed_paths(name)
+        exists = any(p.exists() for p in [paths.metadata, paths.container_helper, paths.sshd_helper, paths.container_unit, paths.sshd_unit])
+        exists = exists or run([podman, "container", "exists", name], check=False).returncode == 0
+
+        if not exists:
+            if args.all:
+                continue
+            raise SystemExit(f"not found: {name}")
+
+        _cleanup(podman, systemctl, paths, name)
+        print(f"removed {name}")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+def _cleanup(podman: str, systemctl: str, paths: ManagedPaths, name: str) -> None:
+    """Stop services, remove container, delete managed files."""
+    run([systemctl, "--user", "disable", "--now", paths.sshd_unit.name], check=False, capture=True)
+    run([systemctl, "--user", "disable", "--now", paths.container_unit.name], check=False, capture=True)
+    res = run([podman, "rm", "-f", "--ignore", name], check=False, capture=True)
+    if res.returncode != 0:
+        print(f"warning: podman rm failed for {name}: {res.stderr.strip()}", file=sys.stderr)
+
+    for p in [paths.container_unit, paths.sshd_unit, paths.container_helper, paths.sshd_helper, paths.metadata]:
+        unlink_if_exists(p)
+
+    if paths.helper_dir.exists() and not any(paths.helper_dir.iterdir()):
+        paths.helper_dir.rmdir()
+
+    run([systemctl, "--user", "daemon-reload"], check=False)
+
+
+def list_names() -> list[str]:
+    d = state_root() / STATE_DIR_NAME
+    if not d.exists():
+        return []
+    names: set[str] = set()
+    for p in d.glob("*.json"):
+        names.add(p.stem)
+    for p in d.glob("*-container.sh"):
+        names.add(p.name.removesuffix("-container.sh"))
+    return sorted(names)
+
+
+def _read_meta(path: pathlib.Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError:
+        return {}
+
+
+def _container_status(podman: str, name: str) -> str:
+    res = run([podman, "inspect", "-f", "{{.State.Status}}", name], check=False, capture=True)
+    return res.stdout.strip() if res.returncode == 0 else "missing"

z_ctk/helpers.py

@@ -0,0 +1,201 @@
+"""Generate the container and sshd helper shell scripts."""
+
+from __future__ import annotations
+
+import pathlib
+import shlex
+
+
+def _sq(s: str) -> str:
+    return shlex.quote(s)
+
+
+def _shell_join(parts: list[str]) -> str:
+    return " ".join(shlex.quote(p) for p in parts)
+
+
+def render_container_helper(
+    podman: str,
+    name: str,
+    image: str,
+    port: int,
+    mounts: list[str],
+    devices: list[str],
+    extra: list[str],
+) -> str:
+    create_cmd = [podman, "create", "--name", name, "--userns", "keep-id", "--init", "--stop-timeout", "5"]
+    for d in devices:
+        create_cmd.extend(["--device", d])
+    for m in mounts:
+        create_cmd.extend(["--mount", m])
+    create_cmd.extend(["--publish", f"127.0.0.1:{port}:22"])
+    create_cmd.extend(extra)
+    create_cmd.extend([image, "sleep", "infinity"])
+
+    return f"""\
+#!/bin/sh
+set -eu
+
+podman={_sq(podman)}
+name={_sq(name)}
+
+create() {{
+    if "$podman" container exists "$name"; then exit 0; fi
+    exec {_shell_join(create_cmd)}
+}}
+
+start() {{
+    running=$("$podman" inspect -f '{{{{.State.Running}}}}' "$name" 2>/dev/null || printf 'false\\n')
+    if [ "$running" = "true" ]; then exec "$podman" attach "$name"; fi
+    exec "$podman" start --attach "$name"
+}}
+
+stop() {{
+    exec "$podman" stop --ignore -t 10 "$name"
+}}
+
+case "${{1:-}}" in
+    create) create ;; start) start ;; stop) stop ;;
+    *) echo "usage: $0 {{create|start|stop}}" >&2; exit 2 ;;
+esac
+"""
+
+
+def render_sshd_helper(
+    podman: str,
+    name: str,
+    container_user: str,
+    uid: int,
+    gid: int,
+    container_home: str,
+    authorized_keys_file: pathlib.Path | None,
+    authorized_keys_text: str | None,
+) -> str:
+    ak_path = f"/etc/ssh/authorized_keys/{container_user}"
+    sudoers = f"/etc/sudoers.d/90-{container_user}"
+
+    # Build the copy-keys command.
+    # Use shell builtins only (no cat/cp) — systemd user services on NixOS
+    # have a minimal PATH that excludes coreutils.
+    if authorized_keys_file is not None:
+        copy_keys = (
+            f'"$podman" exec --user root -i "$name" /bin/sh -c \'cat >{ak_path}\''
+            f' < {_sq(str(authorized_keys_file))}'
+        )
+    else:
+        copy_keys = (
+            f'printf \'%s\\n\' {_sq(authorized_keys_text or "")} | '
+            f'"$podman" exec --user root -i "$name" /bin/sh -c \'cat >{ak_path}\''
+        )
+
+    # The bootstrap script runs entirely inside the container via heredoc.
+    # All variables are hardcoded literals — no host-side expansion.
+    return f"""\
+#!/bin/sh
+set -eu
+# pipefail: catch failures in pipe left-hand side (e.g. missing binary)
+( set -o pipefail 2>/dev/null ) && set -o pipefail
+
+podman={_sq(podman)}
+name={_sq(name)}
+
+exec_root() {{
+    "$podman" exec --user root "$name" /bin/sh -lc "$@"
+}}
+
+stop_sshd() {{
+    exec_root 'if [ -f /run/sshd.pid ]; then kill "$(cat /run/sshd.pid)"; fi' >/dev/null 2>&1 || true
+}}
+
+bootstrap() {{
+    # Check apt-get
+    exec_root 'command -v apt-get >/dev/null 2>&1' >/dev/null 2>&1 || {{
+        echo "apt-get is required inside $name" >&2; exit 1
+    }}
+
+    # Install packages if needed
+    packages=""
+    exec_root 'test -x /usr/sbin/sshd' || packages="$packages openssh-server"
+    exec_root 'command -v sudo >/dev/null 2>&1' || packages="$packages sudo"
+    if [ -n "$packages" ]; then
+        "$podman" exec --user root "$name" /bin/sh -lc \\
+            "export DEBIAN_FRONTEND=noninteractive; apt-get update && apt-get install -y --no-install-recommends $packages"
+    fi
+
+    # Create user and configure sshd — all values are literals, no host expansion
+    "$podman" exec --user root -i "$name" /bin/sh <<'BOOTSTRAP'
+set -eu
+container_user={container_user}
+container_uid={uid}
+container_gid={gid}
+container_home={_sq(container_home)}
+
+# Handle GID — reuse or create
+existing_group=$(getent group "$container_gid" 2>/dev/null | cut -d: -f1 || true)
+if [ -n "$existing_group" ]; then
+    group_name="$existing_group"
+elif getent group "$container_user" >/dev/null 2>&1; then
+    # Group name exists with different GID — rename it
+    groupmod -g "$container_gid" "$(getent group "$container_user" | cut -d: -f1)"
+    group_name="$container_user"
+else
+    groupadd -g "$container_gid" "$container_user"
+    group_name="$container_user"
+fi
+
+# Handle UID — reuse, rename, or create
+uid_owner=$(getent passwd "$container_uid" 2>/dev/null | cut -d: -f1 || true)
+if [ -n "$uid_owner" ] && [ "$uid_owner" != "$container_user" ]; then
+    # UID taken by another user (e.g. 'ubuntu') — rename it
+    usermod -l "$container_user" -d "$container_home" -m -g "$container_gid" -s /bin/bash "$uid_owner"
+elif id -u "$container_user" >/dev/null 2>&1; then
+    usermod -u "$container_uid" -d "$container_home" -g "$container_gid" -s /bin/bash "$container_user"
+else
+    useradd -M -d "$container_home" -s /bin/bash -u "$container_uid" -g "$container_gid" "$container_user"
+fi
+
+mkdir -p "$container_home" /run/sshd /etc/ssh/authorized_keys /etc/ssh/sshd_config.d /etc/sudoers.d
+chown "$container_uid:$container_gid" "$container_home" >/dev/null 2>&1 || true
+
+# Sudoers
+printf '%s ALL=(ALL) NOPASSWD:ALL\\n' "$container_user" >{sudoers}
+chmod 440 {sudoers}
+
+# SSH authorized keys dir
+chmod 755 /etc/ssh/authorized_keys
+ssh-keygen -A
+BOOTSTRAP
+
+    # Copy authorized keys from host
+    {copy_keys}
+    exec_root 'chmod 644 {ak_path} && chown root:root {ak_path}'
+
+    # sshd config
+    "$podman" exec --user root -i "$name" /bin/sh -c 'cat >/etc/ssh/sshd_config.d/10-rootless-dev.conf' <<'SSHDCONF'
+PermitRootLogin no
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+ChallengeResponseAuthentication no
+PubkeyAuthentication yes
+AuthorizedKeysFile /etc/ssh/authorized_keys/%u
+AllowUsers {container_user}
+PidFile /run/sshd.pid
+SSHDCONF
+
+    exec_root '/usr/sbin/sshd -t'
+}}
+
+start() {{
+    stop_sshd
+    exec "$podman" exec --user root "$name" /usr/sbin/sshd -D -e -o PidFile=/run/sshd.pid
+}}
+
+stop() {{
+    stop_sshd
+}}
+
+case "${{1:-}}" in
+    bootstrap) bootstrap ;; start) start ;; stop) stop ;;
+    *) echo "usage: $0 {{bootstrap|start|stop}}" >&2; exit 2 ;;
+esac
+"""

z_ctk/paths.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import os
+import pathlib
+from dataclasses import dataclass
+
+STATE_DIR_NAME = "z-ctk"
+
+
+def state_root() -> pathlib.Path:
+    xdg = os.environ.get("XDG_STATE_HOME")
+    if xdg:
+        return pathlib.Path(xdg).expanduser()
+    return pathlib.Path.home() / ".local" / "state"
+
+
+@dataclass(frozen=True)
+class ManagedPaths:
+    units_dir: pathlib.Path
+    helper_dir: pathlib.Path
+    metadata: pathlib.Path
+    container_unit: pathlib.Path
+    sshd_unit: pathlib.Path
+    container_helper: pathlib.Path
+    sshd_helper: pathlib.Path
+
+
+def managed_paths(name: str) -> ManagedPaths:
+    home = pathlib.Path.home()
+    units = home / ".config" / "systemd" / "user"
+    helpers = state_root() / STATE_DIR_NAME
+    return ManagedPaths(
+        units_dir=units,
+        helper_dir=helpers,
+        metadata=helpers / f"{name}.json",
+        container_unit=units / f"{name}.service",
+        sshd_unit=units / f"{name}-sshd.service",
+        container_helper=helpers / f"{name}-container.sh",
+        sshd_helper=helpers / f"{name}-sshd.sh",
+    )

z_ctk/systemd.py

@@ -0,0 +1,49 @@
+"""Render systemd user unit files from embedded templates."""
+
+from __future__ import annotations
+
+from string import Template
+
+TEMPLATES = {
+    "container": """\
+[Unit]
+Description=z-ctk container $container_name
+
+[Service]
+Type=simple
+TimeoutStartSec=300
+TimeoutStopSec=15
+Restart=on-failure
+RestartSec=5
+ExecStartPre=$container_helper create
+ExecStart=$container_helper start
+ExecStop=$container_helper stop
+
+[Install]
+WantedBy=default.target
+""",
+    "sshd": """\
+[Unit]
+Description=z-ctk OpenSSH server in $container_name
+Requires=$container_unit
+After=$container_unit
+BindsTo=$container_unit
+PartOf=$container_unit
+
+[Service]
+Type=simple
+TimeoutStartSec=300
+Restart=always
+RestartSec=5
+ExecStartPre=$sshd_helper bootstrap
+ExecStart=$sshd_helper start
+ExecStop=$sshd_helper stop
+
+[Install]
+WantedBy=default.target
+""",
+}
+
+
+def render_unit(kind: str, **values: str) -> str:
+    return Template(TEMPLATES[kind]).substitute(values)

z_ctk/util.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import pathlib
+import shutil
+import subprocess
+
+
+def require_binary(name: str) -> str:
+    path = shutil.which(name)
+    if not path:
+        raise SystemExit(f"missing required binary: {name}")
+    return path
+
+
+def run(cmd: list[str], check: bool = True, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(cmd, check=check, text=True, capture_output=capture)
+
+
+def write_text(path: pathlib.Path, content: str, mode: int | None = None) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    if mode is not None:
+        path.chmod(mode)
+
+
+def unlink_if_exists(path: pathlib.Path) -> None:
+    if path.exists():
+        path.unlink()