Skip to content

BumpyClock/agent-templates / skills/ios-macos-development

ios-macos-development

Unverified

Build, debug, or release iOS and macOS apps with Swift and Apple platform tools.

FileKindSize
SKILL.mdskill md2.1 KB
agents/openai.yamlconfig278 B
app-store-connect-cli/asc-app-create-ui/guide.mdmarkdown6.3 KB
app-store-connect-cli/asc-build-lifecycle/guide.mdmarkdown1.8 KB
app-store-connect-cli/asc-cli-usage/guide.mdmarkdown1.3 KB
app-store-connect-cli/asc-id-resolver/guide.mdmarkdown1.3 KB
app-store-connect-cli/asc-metadata-sync/guide.mdmarkdown4.5 KB
app-store-connect-cli/asc-notarization/guide.mdmarkdown7.2 KB
app-store-connect-cli/asc-ppp-pricing/guide.mdmarkdown4.4 KB
app-store-connect-cli/asc-release-flow/guide.mdmarkdown4.7 KB
app-store-connect-cli/asc-shots-pipeline/guide.mdmarkdown10.7 KB
app-store-connect-cli/asc-signing-setup/guide.mdmarkdown2.6 KB
app-store-connect-cli/asc-submission-health/guide.mdmarkdown6.9 KB
app-store-connect-cli/asc-subscription-localization/guide.mdmarkdown10.2 KB
app-store-connect-cli/asc-testflight-orchestration/guide.mdmarkdown1.7 KB
app-store-connect-cli/asc-workflow/guide.mdmarkdown5.3 KB
app-store-connect-cli/asc-xcode-build/guide.mdmarkdown3.7 KB
app-store-connect-cli/guide.mdmarkdown3.6 KB
instruments-profiling/guide.mdmarkdown3.7 KB
ios-app-intents/guide.mdmarkdown4.8 KB
ios-app-intents/references/code-templates.mdmarkdown7.4 KB
ios-app-intents/references/example-patterns.mdmarkdown3.6 KB
ios-app-intents/references/first-pass-checklist.mdmarkdown1.4 KB
ios-app-intents/references/system-surfaces.mdmarkdown1.0 KB
ios-debugger-agent/guide.mdmarkdown2.7 KB
ios-simulator/guide.mdmarkdown21.0 KB
ios-simulator/references/accessibility_checklist.mdmarkdown1.5 KB
ios-simulator/references/idb_quick.mdmarkdown1.1 KB
ios-simulator/references/simctl_quick.mdmarkdown1.3 KB
ios-simulator/references/test_patterns.mdmarkdown1.6 KB
ios-simulator/references/troubleshooting.mdmarkdown1.3 KB
ios-simulator/scripts/accessibility_audit.pyexecutablescript10.3 KB
ios-simulator/scripts/app_launcher.pyexecutablescript9.7 KB
ios-simulator/scripts/app_state_capture.pyexecutablescript13.2 KB
ios-simulator/scripts/appearance.pyscript11.3 KB
ios-simulator/scripts/build_and_test.pyexecutablescript11.3 KB
ios-simulator/scripts/clipboard.pyscript2.6 KB
ios-simulator/scripts/common/__init__.pyscript1.5 KB
ios-simulator/scripts/common/cache_utils.pyscript9.3 KB
ios-simulator/scripts/common/device_utils.pyscript13.5 KB
ios-simulator/scripts/common/env_config.pyscript1.1 KB
ios-simulator/scripts/common/hang_pipeline.pyscript29.6 KB
ios-simulator/scripts/common/hang_sessions.pyscript17.9 KB
ios-simulator/scripts/common/idb_utils.pyscript5.3 KB
ios-simulator/scripts/common/screenshot_utils.pyscript10.0 KB
ios-simulator/scripts/container.pyscript22.7 KB
ios-simulator/scripts/gesture.pyexecutablescript12.3 KB
ios-simulator/scripts/hang_watcher.pyscript56.5 KB
ios-simulator/scripts/keyboard.pyexecutablescript11.5 KB
ios-simulator/scripts/localization_audit.pyscript16.2 KB
ios-simulator/scripts/location.pyscript15.4 KB
ios-simulator/scripts/log_monitor.pyexecutablescript14.8 KB
ios-simulator/scripts/model_inspector.pyscript21.7 KB
ios-simulator/scripts/navigator.pyexecutablescript14.2 KB
ios-simulator/scripts/privacy_manager.pyscript8.7 KB
ios-simulator/scripts/push_notification.pyscript6.5 KB
ios-simulator/scripts/screen_mapper.pyexecutablescript10.7 KB
ios-simulator/scripts/sim_health_check.shscript8.1 KB
ios-simulator/scripts/sim_list.pyscript8.9 KB
ios-simulator/scripts/simctl_boot.pyexecutablescript9.1 KB
ios-simulator/scripts/simctl_create.pyexecutablescript8.9 KB
ios-simulator/scripts/simctl_delete.pyexecutablescript10.3 KB
ios-simulator/scripts/simctl_erase.pyexecutablescript10.2 KB
ios-simulator/scripts/simctl_shutdown.pyexecutablescript8.4 KB
ios-simulator/scripts/simulator_selector.pyexecutablescript10.3 KB
ios-simulator/scripts/status_bar.pyscript6.6 KB
ios-simulator/scripts/test_recorder.pyexecutablescript10.6 KB
ios-simulator/scripts/visual_diff.pyexecutablescript7.6 KB
ios-simulator/scripts/xcode/__init__.pyscript378 B
ios-simulator/scripts/xcode/builder.pyscript13.2 KB
ios-simulator/scripts/xcode/cache.pyscript5.5 KB
ios-simulator/scripts/xcode/config.pyscript5.4 KB
ios-simulator/scripts/xcode/reporter.pyscript10.7 KB
ios-simulator/scripts/xcode/xcresult.pyscript16.5 KB
native-app-performance/attribution.txtmarkdown349 B
native-app-performance/guide.mdmarkdown2.1 KB
native-app-performance/scripts/extract_time_samples.pyscript1.1 KB
native-app-performance/scripts/record_time_profiler.shscript1.3 KB
native-app-performance/scripts/top_hotspots.pyscript4.0 KB
swift-concurrency-expert/attribution.txtmarkdown353 B
swift-concurrency-expert/guide.mdmarkdown1.9 KB
swift-concurrency-expert/references/swift-6-2-concurrency.mdmarkdown4.3 KB
swift-concurrency-expert/references/swiftui-concurrency-tour-wwdc.mdmarkdown1.6 KB
swift-ui/guide.mdmarkdown1.0 KB
swift-ui/references/index.mdmarkdown4.2 KB
swift-ui/references/liquid-glass/appkit.mdmarkdown3.3 KB
swift-ui/references/liquid-glass/overview.mdmarkdown1.6 KB
swift-ui/references/liquid-glass/patterns.mdmarkdown3.9 KB
swift-ui/references/liquid-glass/swiftui.mdmarkdown4.0 KB
swift-ui/references/logging-private-fix.mdmarkdown8.0 KB
swift-ui/references/modern-swift.mdmarkdown2.9 KB
swift-ui/references/swift-concurrency.mdmarkdown39.6 KB
swift-ui/references/swift-testing-playbook.mdmarkdown35.3 KB
swift-ui/references/swiftui.mdmarkdown1.8 MB
swift-ui/references/toolbar/swiftui-features.mdmarkdown4.7 KB
swiftui-liquid-glass/attribution.txtmarkdown345 B
swiftui-liquid-glass/guide.mdmarkdown4.1 KB
swiftui-liquid-glass/references/liquid-glass.mdmarkdown8.0 KB
swiftui-performance-audit/attribution.txtmarkdown355 B
swiftui-performance-audit/guide.mdmarkdown1.7 KB
swiftui-performance-audit/references/code-smells.mdmarkdown4.8 KB
swiftui-performance-audit/references/demystify-swiftui-performance-wwdc23.mdmarkdown1.8 KB
swiftui-performance-audit/references/optimizing-swiftui-performance-instruments.mdmarkdown1.8 KB
swiftui-performance-audit/references/profiling-intake.mdmarkdown2.4 KB
swiftui-performance-audit/references/report-template.mdmarkdown1.2 KB
swiftui-performance-audit/references/understanding-hangs-in-your-app.mdmarkdown1.2 KB
swiftui-performance-audit/references/understanding-improving-swiftui-performance.mdmarkdown2.2 KB
swiftui-ui-patterns/guide.mdmarkdown2.0 KB
swiftui-ui-patterns/references/app-wiring.mdmarkdown6.5 KB
swiftui-ui-patterns/references/async-state.mdmarkdown3.5 KB
swiftui-ui-patterns/references/components-index.mdmarkdown4.2 KB
swiftui-ui-patterns/references/controls.mdmarkdown1.6 KB
swiftui-ui-patterns/references/deeplinks.mdmarkdown1.7 KB
swiftui-ui-patterns/references/focus.mdmarkdown2.3 KB
swiftui-ui-patterns/references/form.mdmarkdown3.0 KB
swiftui-ui-patterns/references/grids.mdmarkdown1.8 KB
swiftui-ui-patterns/references/haptics.mdmarkdown2.0 KB
swiftui-ui-patterns/references/input-toolbar.mdmarkdown1.4 KB
swiftui-ui-patterns/references/lightweight-clients.mdmarkdown2.5 KB
swiftui-ui-patterns/references/list.mdmarkdown2.7 KB
swiftui-ui-patterns/references/loading-placeholders.mdmarkdown1.2 KB
swiftui-ui-patterns/references/macos-settings.mdmarkdown2.0 KB
swiftui-ui-patterns/references/matched-transitions.mdmarkdown1.6 KB
swiftui-ui-patterns/references/media.mdmarkdown2.0 KB
swiftui-ui-patterns/references/menu-bar.mdmarkdown2.2 KB
swiftui-ui-patterns/references/navigationstack.mdmarkdown4.2 KB
swiftui-ui-patterns/references/overlay.mdmarkdown1.2 KB
swiftui-ui-patterns/references/performance.mdmarkdown1.9 KB
swiftui-ui-patterns/references/previews.mdmarkdown1.6 KB
swiftui-ui-patterns/references/scroll-reveal.mdmarkdown5.2 KB
swiftui-ui-patterns/references/scrollview.mdmarkdown2.3 KB
swiftui-ui-patterns/references/searchable.mdmarkdown1.7 KB
swiftui-ui-patterns/references/sheets.mdmarkdown4.3 KB
swiftui-ui-patterns/references/split-views.mdmarkdown2.0 KB
swiftui-ui-patterns/references/tabview.mdmarkdown3.4 KB
swiftui-ui-patterns/references/theming.mdmarkdown1.7 KB
swiftui-ui-patterns/references/title-menus.mdmarkdown2.1 KB
swiftui-ui-patterns/references/top-bar.mdmarkdown1.3 KB
swiftui-view-refactor/guide.mdmarkdown1.6 KB
swiftui-view-refactor/references/mv-patterns.mdmarkdown2.3 KB

ios-simulator/scripts/container.py

View on GitHub
#!/usr/bin/env python3
"""
App sandbox / UserDefaults / Core Data inspector for iOS simulators.

Wraps `xcrun simctl get_app_container` to provide semantic access to an
app's data container — no manual CoreSimulator directory archaeology needed.

Key features:
- List files in the app data container (--ls)
- Read a file from the container (--cat, with progressive cache for large files)
- Inspect UserDefaults as JSON or key=value (--userdefaults)
- Locate Core Data stores (--core-data-path)
- Export the full data container (--export)
- JSON output mode (--json) and auto-UDID detection

Keychain is explicitly out of scope — requires entitlements and is risky.
"""

import argparse
import contextlib
import json
import os
import plistlib
import shutil
import subprocess
import sys
from decimal import Decimal
from pathlib import Path

from common.cache_utils import ProgressiveCache
from common.device_utils import resolve_device_identifier


def _env_int(name: str, default: int, *, min_value: int = 0) -> int:
    """Read an integer from the environment with a minimum clamp."""
    raw = os.environ.get(name)
    if raw is None:
        return default
    try:
        return max(min_value, int(raw))
    except ValueError:
        return default


# Threshold in bytes above which --cat output is cached instead of printed inline
_CAT_CACHE_THRESHOLD_BYTES = _env_int("IOS_SIM_CAT_CACHE_BYTES", 8_192, min_value=512)


class ContainerInspector:
    """Inspect an app's data sandbox on an iOS simulator."""

    def __init__(self, udid: str | None = None):
        """Initialize inspector with optional device UDID.

        Args:
            udid: Simulator UDID (uses booted device if None)
        """
        self.udid = udid
        self._cache = ProgressiveCache()

    # === PUBLIC API ===

    def get_container_path(self, bundle_id: str) -> tuple[bool, str]:
        """Resolve the data container root for a bundle ID.

        Args:
            bundle_id: App bundle identifier (e.g. com.example.app)

        Returns:
            (success, path_or_error_message)
        """
        device = self.udid or "booted"
        try:
            result = subprocess.run(
                ["xcrun", "simctl", "get_app_container", device, bundle_id, "data"],
                check=False,
                capture_output=True,
                text=True,
                timeout=15,
            )
        except subprocess.TimeoutExpired:
            return False, "get_app_container timed out"
        except Exception as e:
            return False, f"get_app_container error: {e}"

        if result.returncode != 0:
            error = result.stderr.strip() or f"exit code {result.returncode}"
            return False, f"Cannot find container for {bundle_id}: {error}"

        container_path = result.stdout.strip()
        if not container_path:
            return False, f"No data container found for {bundle_id}"

        return True, container_path

    def list_files(
        self,
        bundle_id: str,
        relative_path: str = "",
        max_depth: int = 3,
    ) -> tuple[bool, dict]:
        """List files in the app's data container.

        Args:
            bundle_id: App bundle identifier
            relative_path: Sub-path within container (default: container root)
            max_depth: Recursive listing depth (default: 3)

        Returns:
            (success, result_dict) where result_dict contains 'path', 'entries'
        """
        ok, container = self.get_container_path(bundle_id)
        if not ok:
            return False, {"error": container}

        container_resolved = Path(container).resolve()
        target = container_resolved
        if relative_path:
            target = (container_resolved / relative_path).resolve()
            if not target.is_relative_to(container_resolved):
                return False, {"error": f"Path escapes container boundary: {relative_path}"}

        if not target.exists():
            return False, {"error": f"Path does not exist: {target}"}

        if target.is_file():
            return True, {
                "path": str(target),
                "entries": [_describe_path(target, Path(container))],
                "total_files": 1,
            }

        entries = _walk_directory(target, Path(container), current_depth=0, max_depth=max_depth)
        return True, {
            "bundle_id": bundle_id,
            "container_root": container,
            "listed_path": str(target),
            "max_depth": max_depth,
            "entries": entries,
            "total_entries": len(entries),
        }

    def cat_file(self, bundle_id: str, relative_path: str) -> tuple[bool, dict]:
        """Read a file from the container.

        Large files (> 8 KB) are stored in ProgressiveCache and a cache_id is
        returned instead of the raw content — matching the pattern used by
        build_and_test.py and log_monitor.py.

        Args:
            bundle_id: App bundle identifier
            relative_path: Path relative to container root

        Returns:
            (success, result_dict) with 'content' or 'cache_id' key
        """
        ok, container = self.get_container_path(bundle_id)
        if not ok:
            return False, {"error": container}

        container_resolved = Path(container).resolve()
        file_path = (container_resolved / relative_path).resolve()
        if not file_path.is_relative_to(container_resolved):
            return False, {"error": f"Path escapes container boundary: {relative_path}"}
        if not file_path.exists():
            return False, {"error": f"File not found: {file_path}"}

        if file_path.is_dir():
            return False, {"error": f"Path is a directory — use --ls instead: {relative_path}"}

        if file_path.is_symlink() and not file_path.resolve().exists():
            return False, {"error": f"Broken symlink: {relative_path}"}

        try:
            file_bytes = file_path.read_bytes()
        except OSError as exc:
            return False, {"error": f"Cannot read file: {exc}"}

        size_bytes = len(file_bytes)

        # Attempt plist decode first (handles both binary and XML plists)
        plist_data, is_plist = _try_parse_plist(file_bytes)

        if is_plist:
            content = plist_data
            content_type = "plist"
        else:
            # Try UTF-8 text; fall back to hex summary for binary blobs
            try:
                content = file_bytes.decode("utf-8")
                content_type = "text"
            except UnicodeDecodeError:
                content = f"<binary file: {size_bytes} bytes — use --export to retrieve>"
                content_type = "binary"

        base_result = {
            "bundle_id": bundle_id,
            "path": relative_path,
            "size_bytes": size_bytes,
            "content_type": content_type,
        }

        # Cache large text / plist content
        if size_bytes > _CAT_CACHE_THRESHOLD_BYTES and content_type != "binary":
            cache_data = {**base_result, "content": content}
            cache_id = self._cache.save(cache_data, "container-cat")
            return True, {
                **base_result,
                "cache_id": cache_id,
                "note": (
                    f"File is {size_bytes:,} bytes — full content cached. "
                    f"Retrieve with cache_id '{cache_id}'."
                ),
            }

        return True, {**base_result, "content": content}

    def read_userdefaults(self, bundle_id: str) -> tuple[bool, dict]:
        """Read UserDefaults plist for the app.

        Looks in Library/Preferences/<bundle_id>.plist (both binary and XML
        formats are handled via stdlib plistlib).

        Args:
            bundle_id: App bundle identifier

        Returns:
            (success, result_dict) with 'preferences' key containing decoded data
        """
        ok, container = self.get_container_path(bundle_id)
        if not ok:
            return False, {"error": container}

        plist_path = Path(container) / "Library" / "Preferences" / f"{bundle_id}.plist"

        if not plist_path.exists():
            return False, {
                "error": (
                    f"UserDefaults plist not found: {plist_path}. "
                    "The app may not have written any defaults yet."
                )
            }

        try:
            raw_bytes = plist_path.read_bytes()
        except OSError as exc:
            return False, {"error": f"Cannot read plist: {exc}"}

        plist_data, is_plist = _try_parse_plist(raw_bytes)
        if not is_plist:
            return False, {"error": f"File is not a valid plist: {plist_path}"}

        return True, {
            "bundle_id": bundle_id,
            "plist_path": str(plist_path),
            "preferences": plist_data,
            "total_keys": len(plist_data) if isinstance(plist_data, dict) else None,
        }

    def find_core_data_paths(self, bundle_id: str) -> tuple[bool, dict]:
        """Locate Core Data SQLite stores in the container.

        Searches Library/Application Support/ and Documents/ for *.sqlite,
        *.sqlite-wal, and *.sqlite-shm files. Paths are reported only — no
        file opening occurs.

        Args:
            bundle_id: App bundle identifier

        Returns:
            (success, result_dict) with 'stores' list
        """
        ok, container = self.get_container_path(bundle_id)
        if not ok:
            return False, {"error": container}

        container_path = Path(container)
        search_dirs = [
            container_path / "Library" / "Application Support",
            container_path / "Documents",
        ]

        stores: list[dict] = []
        sqlite_extensions = {".sqlite", ".sqlite-wal", ".sqlite-shm"}

        for search_dir in search_dirs:
            if not search_dir.exists():
                continue
            for file_path in search_dir.rglob("*"):
                if file_path.suffix.lower() in sqlite_extensions and file_path.is_file():
                    relative = str(file_path.relative_to(container_path))
                    size_bytes = file_path.stat().st_size
                    stores.append(
                        {
                            "path": relative,
                            "absolute_path": str(file_path),
                            "size_bytes": size_bytes,
                            "type": _classify_sqlite_file(file_path.name),
                        }
                    )

        return True, {
            "bundle_id": bundle_id,
            "container_root": container,
            "stores": stores,
            "total_stores": len(stores),
        }

    def export_container(self, bundle_id: str, dest_dir: str) -> tuple[bool, dict]:
        """Copy the full data container to dest_dir.

        Uses shutil.copytree with symlinks=True to preserve symlink structure.
        Keychain is not included — it is not part of the data container path.

        Args:
            bundle_id: App bundle identifier
            dest_dir: Destination directory (will be created if absent)

        Returns:
            (success, result_dict) with 'destination' and 'size_bytes'
        """
        ok, container = self.get_container_path(bundle_id)
        if not ok:
            return False, {"error": container}

        dest = Path(dest_dir)
        target = dest / bundle_id

        if target.exists():
            return False, {
                "error": (
                    f"Destination already exists: {target}. "
                    "Remove it or choose a different path."
                )
            }

        dest.mkdir(parents=True, exist_ok=True)

        try:
            shutil.copytree(
                container,
                str(target),
                symlinks=True,
                ignore_dangling_symlinks=True,
            )
        except shutil.Error as exc:
            return False, {"error": f"Export failed: {exc}"}
        except OSError as exc:
            return False, {"error": f"Export OS error: {exc}"}

        total_size = _directory_size_bytes(target)

        return True, {
            "bundle_id": bundle_id,
            "source": container,
            "destination": str(target),
            "size_bytes": total_size,
            "size_human": _human_bytes(total_size),
        }


# === PRIVATE HELPERS ===


def _try_parse_plist(data: bytes) -> tuple[dict | list | None, bool]:
    """Attempt to parse bytes as a plist (binary or XML).

    Args:
        data: Raw file bytes

    Returns:
        (parsed_data, is_plist) — parsed_data is None if not a valid plist
    """
    try:
        parsed = plistlib.loads(data)
        return _make_json_serializable(parsed), True
    except Exception:
        return None, False


def _make_json_serializable(obj):
    """Recursively convert plist types to JSON-serializable equivalents.

    Handles bytes (→ hex string), sets (→ list), and datetime (→ ISO string).
    """
    if isinstance(obj, dict):
        return {k: _make_json_serializable(v) for k, v in obj.items()}
    if isinstance(obj, list):
        return [_make_json_serializable(i) for i in obj]
    if isinstance(obj, bytes):
        return obj.hex()
    if isinstance(obj, set):
        return sorted(_make_json_serializable(i) for i in obj)
    if isinstance(obj, Decimal):
        return float(obj)
    # datetime — plistlib returns datetime.datetime for plist dates
    if hasattr(obj, "isoformat"):
        return obj.isoformat()
    return obj


def _describe_path(path: Path, container_root: Path) -> dict:
    """Build a metadata dict for a single filesystem path."""
    try:
        stat = path.stat()
        size_bytes = stat.st_size if path.is_file() else None
    except OSError:
        size_bytes = None

    relative = str(path.relative_to(container_root))
    kind = "symlink" if path.is_symlink() else ("dir" if path.is_dir() else "file")

    entry: dict = {"path": relative, "kind": kind}
    if size_bytes is not None:
        entry["size_bytes"] = size_bytes
    if path.is_symlink():
        try:
            entry["symlink_target"] = str(path.readlink())
        except OSError:
            entry["symlink_target"] = "<unreadable>"

    return entry


def _walk_directory(
    directory: Path,
    container_root: Path,
    current_depth: int,
    max_depth: int,
) -> list[dict]:
    """Recursively walk a directory up to max_depth, returning metadata entries."""
    entries: list[dict] = []
    try:
        children = sorted(directory.iterdir())
    except PermissionError:
        return entries

    for child in children:
        entries.append(_describe_path(child, container_root))
        if child.is_dir() and not child.is_symlink() and current_depth < max_depth:
            entries.extend(_walk_directory(child, container_root, current_depth + 1, max_depth))

    return entries


def _classify_sqlite_file(filename: str) -> str:
    """Return a human-readable type label for a SQLite-related file."""
    lower = filename.lower()
    if lower.endswith(".sqlite-wal"):
        return "write-ahead-log"
    if lower.endswith(".sqlite-shm"):
        return "shared-memory"
    return "database"


def _directory_size_bytes(path: Path) -> int:
    """Return the total size of all files under a directory."""
    total = 0
    for dirpath, _, filenames in os.walk(path, followlinks=False):
        for fname in filenames:
            fpath = Path(dirpath) / fname
            with contextlib.suppress(OSError):
                total += fpath.stat().st_size
    return total


def _human_bytes(num: int) -> str:
    """Format byte count as a human-readable string (KB / MB / GB)."""
    for unit in ("B", "KB", "MB", "GB"):
        if num < 1024:
            return f"{num:.1f} {unit}"
        num /= 1024
    return f"{num:.1f} TB"


def _format_userdefaults(preferences: dict, bundle_id: str, verbose: bool) -> str:
    """Format UserDefaults output as key=value lines."""
    lines = [f"UserDefaults: {bundle_id}"]
    if not preferences:
        lines.append("  (no keys found)")
        return "\n".join(lines)

    for key, value in sorted(preferences.items()):
        if isinstance(value, dict):
            lines.append(f"  {key} = <dict with {len(value)} keys>")
            if verbose:
                for sub_key, sub_value in sorted(value.items()):
                    lines.append(f"    {sub_key} = {sub_value!r}")
        elif isinstance(value, list):
            lines.append(f"  {key} = <list with {len(value)} items>")
            if verbose:
                for item in value:
                    lines.append(f"    - {item!r}")
        else:
            lines.append(f"  {key} = {value!r}")

    return "\n".join(lines)


# === CLI ===


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="App sandbox / UserDefaults / Core Data inspector for iOS simulators",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python container.py --ls com.example.app
  python container.py --ls com.example.app Library/Preferences
  python container.py --cat com.example.app Library/Preferences/com.example.app.plist
  python container.py --userdefaults com.example.app
  python container.py --core-data-path com.example.app
  python container.py --export com.example.app ./snapshot/
  python container.py --ls com.example.app --udid <DEVICE_UDID> --json
        """,
    )

    # Operation flags — mutually exclusive
    ops = parser.add_mutually_exclusive_group(required=True)
    ops.add_argument(
        "--ls",
        metavar="BUNDLE_ID",
        help="List files in the data container. Optionally pass a sub-path as second argument.",
    )
    ops.add_argument(
        "--cat",
        nargs=2,
        metavar=("BUNDLE_ID", "PATH"),
        help="Print a file from the container. Large files are cached.",
    )
    ops.add_argument(
        "--userdefaults",
        metavar="BUNDLE_ID",
        help="Read and display UserDefaults (Library/Preferences/<bundle>.plist).",
    )
    ops.add_argument(
        "--core-data-path",
        metavar="BUNDLE_ID",
        help="List Core Data SQLite store paths inside the container.",
    )
    ops.add_argument(
        "--export",
        nargs=2,
        metavar=("BUNDLE_ID", "DEST_DIR"),
        help="Copy the full data container to DEST_DIR/BUNDLE_ID.",
    )

    # Sub-path for --ls
    parser.add_argument(
        "path",
        nargs="?",
        default="",
        help="Sub-path for --ls (optional)",
    )

    # Common flags
    parser.add_argument("--udid", help="Simulator UDID (uses booted device if omitted)")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--verbose", action="store_true", help="Show extended detail")
    parser.add_argument(
        "--depth",
        type=int,
        default=3,
        help="Recursive depth for --ls (default: 3)",
    )

    args = parser.parse_args()

    # Resolve device
    try:
        udid = resolve_device_identifier(args.udid)
    except RuntimeError as exc:
        print(f"Error: {exc}", file=sys.stderr)
        sys.exit(1)

    inspector = ContainerInspector(udid=udid)

    # === --ls ===
    if args.ls:
        success, result = inspector.list_files(
            args.ls, relative_path=args.path, max_depth=args.depth
        )
        if args.json:
            print(json.dumps({"action": "ls", "success": success, **result}, indent=2))
        elif not success:
            print(f"Error: {result.get('error', result)}", file=sys.stderr)
        else:
            print(f"Container: {result['container_root']}")
            print(f"Listed: {result['listed_path']}  ({result['total_entries']} entries)")
            listing_root = args.path or ""
            root_depth = listing_root.count("/") + 1 if listing_root else 0
            for entry in result["entries"]:
                relative_depth = entry["path"].count("/") - root_depth
                prefix = "  " * max(0, relative_depth)
                size = f"  [{_human_bytes(entry['size_bytes'])}]" if entry.get("size_bytes") else ""
                print(f"  {prefix}{entry['path']}  ({entry['kind']}){size}")
        sys.exit(0 if success else 1)

    # === --cat ===
    if args.cat:
        bundle_id, rel_path = args.cat
        success, result = inspector.cat_file(bundle_id, rel_path)
        if args.json:
            print(json.dumps({"action": "cat", "success": success, **result}, indent=2))
        elif not success:
            print(f"Error: {result.get('error', result)}", file=sys.stderr)
        elif "cache_id" in result:
            print(f"[{result['path']}]  {_human_bytes(result['size_bytes'])}  (cached)")
            print(result["note"])
        else:
            content = result.get("content", "")
            if isinstance(content, dict | list):
                print(json.dumps(content, indent=2))
            else:
                print(content)
        sys.exit(0 if success else 1)

    # === --userdefaults ===
    if args.userdefaults:
        success, result = inspector.read_userdefaults(args.userdefaults)
        if args.json:
            print(json.dumps({"action": "userdefaults", "success": success, **result}, indent=2))
        elif not success:
            print(f"Error: {result.get('error', result)}", file=sys.stderr)
        else:
            prefs = result.get("preferences", {})
            print(_format_userdefaults(prefs, args.userdefaults, verbose=args.verbose))
            print(f"\n({result['total_keys']} keys  •  {result['plist_path']})")
        sys.exit(0 if success else 1)

    # === --core-data-path ===
    if args.core_data_path:
        success, result = inspector.find_core_data_paths(args.core_data_path)
        if args.json:
            print(json.dumps({"action": "core-data-path", "success": success, **result}, indent=2))
        elif not success:
            print(f"Error: {result.get('error', result)}", file=sys.stderr)
        else:
            stores = result.get("stores", [])
            if not stores:
                print(f"No Core Data stores found for {args.core_data_path}")
            else:
                print(f"Core Data stores for {args.core_data_path}:")
                for store in stores:
                    size = _human_bytes(store["size_bytes"])
                    print(f"  {store['path']}  [{size}]  ({store['type']})")
        sys.exit(0 if success else 1)

    # === --export ===
    if args.export:
        bundle_id, dest_dir = args.export
        success, result = inspector.export_container(bundle_id, dest_dir)
        if args.json:
            print(json.dumps({"action": "export", "success": success, **result}, indent=2))
        elif not success:
            print(f"Error: {result.get('error', result)}", file=sys.stderr)
        else:
            print(
                f"Exported: {result['bundle_id']} → {result['destination']}  "
                f"[{result['size_human']}]"
            )
        sys.exit(0 if success else 1)


if __name__ == "__main__":
    main()
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall