scc-cli 1.5.0__tar.gz

scc_cli-1.5.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local config (don't commit user-specific settings)
+*.local.json
+
+# Claude Code project instructions (local development only)
+CLAUDE.md
+.serena/
+.claude/
+.specify/
+specs/
+.code/
+
+# Local development directories
+plugindocs/
+safetypluginclone/

scc_cli-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cagri Cimen
+
+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.

scc_cli-1.5.0/PKG-INFO

@@ -0,0 +1,393 @@
+Metadata-Version: 2.4
+Name: scc-cli
+Version: 1.5.0
+Summary: Run Claude Code in Docker sandboxes with team configs and git worktree support
+Project-URL: Homepage, https://github.com/CCimen/scc
+Project-URL: Documentation, https://github.com/CCimen/scc#readme
+Project-URL: Repository, https://github.com/CCimen/scc
+Project-URL: Issues, https://github.com/CCimen/scc/issues
+Author-email: Cagri Cimen <cagricimeenn@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,cli,docker,git,worktree
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.25.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: readchar>=4.0.0
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">SCC - Sandboxed Claude CLI</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/scc-cli/"><img src="https://img.shields.io/pypi/v/scc-cli?style=flat-square&label=PyPI" alt="PyPI"></a>
+  <a href="https://pypi.org/project/scc-cli/"><img src="https://img.shields.io/pypi/pyversions/scc-cli?style=flat-square&label=Python" alt="Python"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" alt="License: MIT"></a>
+  <a href="#contributing"><img src="https://img.shields.io/badge/Contributions-Welcome-brightgreen?style=flat-square" alt="Contributions Welcome"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="docs/CLI-REFERENCE.md">CLI Reference</a> ·
+  <a href="#configuration">Configuration</a> ·
+  <a href="docs/ARCHITECTURE.md">Architecture</a>
+</p>
+
+---
+
+Run [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's AI coding CLI) in Docker sandboxes with organization-managed team profiles and git worktree support.
+
+SCC isolates AI execution in containers, enforces branch safety, and prevents destructive git commands. Organizations distribute plugins through a central config—developers get standardized setups without manual configuration.
+
+> **Plugin Marketplace:** Extend Claude with the [official plugin marketplace](https://github.com/CCimen/sandboxed-code-plugins). Start with [**scc-safety-net**](docs/MARKETPLACE.md#safety-net-plugin) to block destructive git commands like `push --force`.
+
+## 30-Second Guide
+
+**Requires:** Python 3.10+, Docker Desktop 4.50+, Git 2.30+
+
+```bash
+pip install scc-cli      # Install
+scc setup                # Configure (paste your org URL, pick your team)
+cd ~/project && scc      # Auto-detect workspace and launch (or scc start ~/project)
+```
+
+Run `scc doctor` to verify your environment or troubleshoot issues.
+
+### Smart Start Flow
+
+When you run `scc` or `scc start` from inside a git repository:
+- **Auto-detects workspace** from your current directory
+- **Shows Quick Resume** if you have recent sessions for this workspace
+- **Prints brief context** (workspace name, branch, team) before launching
+
+**Keyboard shortcuts in interactive mode:**
+- `Enter` — Select/resume session
+- `n` — Start new session
+- `Esc` — Go back
+- `q` — Quit
+
+---
+
+### Find Your Path
+
+| You are... | Start here |
+|------------|------------|
+| **Developer** joining a team | [Developer Onboarding](#developer-onboarding) — what you get automatically |
+| **Team Lead** setting up your team | [Team Setup](#team-setup) — manage plugins in your own repo |
+| **Org Admin** configuring security | [Organization Setup](#organization-setup) — control what's allowed org-wide |
+| Exploring **plugins** | [Plugin Marketplace](docs/MARKETPLACE.md) — official plugins & safety tools |
+
+---
+
+### Developer Onboarding
+
+**New to a team?** After running `scc setup` and `scc start`, you get:
+
+- **Your team's approved plugins and MCP servers** — pre-configured and ready
+- **Organization security policies** — applied automatically, no action needed
+- **Command guardrails** — block destructive git commands like `push --force` (when scc-safety-net plugin is enabled)
+- **Isolated git worktrees** — your main branch stays clean while Claude experiments
+
+**What you never need to do:**
+- Edit config files manually
+- Download or configure plugins
+- Worry about security settings
+
+Your org admin and team lead handle the configuration. You just code.
+
+---
+
+### Who Controls What
+
+| Setting | Org Admin | Team Lead | Developer |
+|---------|:---------:|:---------:|:---------:|
+| Block dangerous plugins/servers | ✅ **Sets** | ❌ Cannot override | ❌ Cannot override |
+| Default plugins for all teams | ✅ **Sets** | — | — |
+| Team-specific plugins | ✅ Approves | ✅ **Chooses** | — |
+| Project-local config (.scc.yaml) | ✅ Can restrict | ✅ Can restrict | ✅ **Extends** |
+| Safety-net policy (block/warn) | ✅ **Sets** | ❌ Cannot override | ❌ Cannot override |
+
+Organization security blocks cannot be overridden by teams or developers.
+
+*"Approves" = teams can only select from org-allowed marketplaces; blocks always apply. "Extends" = can add plugins/settings, cannot remove org defaults.*
+
+---
+
+### Organization Setup
+
+Org admins create a single JSON config that controls security for all teams:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "organization": { "name": "Acme Corp", "id": "acme" },
+  "marketplaces": {
+    "sandboxed-code-official": {
+      "source": "github",
+      "owner": "CCimen",
+      "repo": "sandboxed-code-plugins"
+    }
+  },
+  "security": {
+    "blocked_plugins": ["*malicious*"],
+    "blocked_mcp_servers": ["*.untrusted.com"],
+    "safety_net": { "action": "block" }
+  },
+  "defaults": {
+    "allowed_plugins": ["*"],
+    "network_policy": "unrestricted"
+  },
+  "profiles": {
+    "backend": { "additional_plugins": ["scc-safety-net@sandboxed-code-official"] },
+    "frontend": { "additional_plugins": ["scc-safety-net@sandboxed-code-official"] }
+  }
+}
+```
+
+Host this anywhere: GitHub, GitLab, S3, or any HTTPS URL. Private repos work with token auth.
+
+See [examples/](examples/) for complete org configs and [GOVERNANCE.md](docs/GOVERNANCE.md) for delegation rules.
+
+---
+
+### Team Setup
+
+Teams can manage their plugins **two ways**:
+
+**Option A: Inline (simple)** — Team config lives in the org config file.
+```json
+"profiles": {
+  "backend": {
+    "additional_plugins": ["scc-safety-net@sandboxed-code-official"]
+  }
+}
+```
+
+**Option B: Team Repo (GitOps)** — Team maintains their own config repo.
+```json
+"profiles": {
+  "backend": {
+    "config_source": {
+      "source": "github",
+      "owner": "acme",
+      "repo": "backend-team-scc-config"
+    }
+  }
+}
+```
+
+With Option B, team leads can update plugins via PRs to their own repo—no org admin approval needed for allowed additions.
+
+**Config precedence:** Org defaults → Team profile → Project `.scc.yaml` (additive merge; blocks apply after merge).
+
+---
+
+## Commands
+
+### Essential Commands
+
+| Command | Description |
+|---------|-------------|
+| `scc` | Smart start: auto-detect workspace, show Quick Resume, or launch |
+| `scc setup` | Configure organization connection |
+| `scc doctor` | Check system health and diagnose issues |
+| `scc stop` | Stop running sandbox(es) |
+
+### Session & Team
+
+| Command | Description |
+|---------|-------------|
+| `scc start --resume` | Resume most recent session |
+| `scc start --select` | Pick from recent sessions |
+| `scc team switch` | Switch to a different team profile |
+| `scc sessions` | List recent sessions |
+
+### Worktrees
+
+| Command | Description |
+|---------|-------------|
+| `scc worktree create <repo> <name>` | Create git worktree for parallel development |
+| `scc worktree enter [target]` | Enter worktree in subshell (no shell config needed) |
+| `scc worktree list -v` | List worktrees with git status |
+
+### Governance & Admin
+
+| Command | Description |
+|---------|-------------|
+| `scc config explain` | Show effective config with sources |
+| `scc exceptions list` | View active exceptions |
+| `scc audit plugins` | Audit installed plugins |
+| `scc support bundle` | Generate support bundle for troubleshooting |
+
+Run `scc <command> --help` for options. See **[CLI Reference](docs/CLI-REFERENCE.md)** for the complete command list (40+ commands).
+
+### Git Worktrees
+
+**Primary method (no shell config needed):**
+
+```bash
+scc worktree enter feature-auth   # Opens a subshell in the worktree
+# Type 'exit' to return to your previous directory
+```
+
+**Power users:** Add this shell wrapper for seamless `cd` switching:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+wt() {
+  local p
+  p="$(scc worktree switch "$@")" || return $?
+  cd "$p" || return 1
+}
+```
+
+**Usage examples (both methods):**
+
+```bash
+scc worktree enter ^        # Enter main branch worktree
+scc worktree enter -        # Enter previous worktree (like cd -)
+wt feature-auth             # Switch with shell wrapper
+wt scc/feature-x            # Match by full branch name
+```
+
+**Note:** Branch names with `/` are sanitized to `-` (e.g., `feature/auth` → `feature-auth`).
+
+**Status indicators in `list -v`:**
+
+| Symbol | Meaning |
+|--------|---------|
+| `+N` | N staged files |
+| `!N` | N modified files |
+| `?N` | N untracked files |
+| `.` | Clean worktree |
+| `…` | Status timed out |
+
+**Cleanup stale entries:**
+
+```bash
+scc worktree prune -n   # Dry-run: show what would be pruned
+scc worktree prune      # Actually prune stale entries
+```
+
+---
+
+## Configuration
+
+### Setup Modes
+
+**Organization mode** (recommended):
+```bash
+scc setup
+# Enter URL when prompted: https://gitlab.example.org/devops/scc-config.json
+```
+
+**Standalone mode** (no org config):
+```bash
+scc setup --standalone
+```
+
+### Project Config
+
+Add `.scc.yaml` to your repository root for project-specific settings:
+
+```yaml
+additional_plugins:
+  - "project-linter@internal"
+
+session:
+  timeout_hours: 4
+```
+
+### File Locations
+
+```
+~/.config/scc/config.json    # Org URL, team, preferences
+~/.cache/scc/                # Cache (safe to delete)
+<repo>/.scc.yaml             # Project-specific config
+```
+
+---
+
+## Troubleshooting
+
+Run `scc doctor` to diagnose issues.
+
+| Problem | Solution |
+|---------|----------|
+| Docker not reachable | Start Docker Desktop |
+| Organization config fetch failed | Check URL and token |
+| Plugin blocked | Check `scc config explain` for security blocks |
+
+See [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more solutions.
+
+---
+
+## Documentation
+
+- [CLI Reference](docs/CLI-REFERENCE.md) — complete command reference (40+ commands)
+- [Architecture](docs/ARCHITECTURE.md) — system design, module structure
+- [Governance](docs/GOVERNANCE.md) — delegation model, security boundaries
+- [Marketplace](docs/MARKETPLACE.md) — plugin distribution and safety-net
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common problems and solutions
+- [Examples](examples/) — ready-to-use organization config templates
+
+---
+
+## Automation & CI
+
+SCC supports non-interactive operation for CI/CD pipelines and scripting.
+
+```bash
+# CI pipeline example
+scc start --non-interactive --team backend ~/project
+
+# Preview configuration as JSON
+scc start --dry-run --json
+
+# Full automation mode
+scc start --dry-run --json --non-interactive ~/project
+```
+
+**Key flags:**
+- `--non-interactive` — Fail fast instead of prompting
+- `--json` — Machine-readable output with standardized envelope
+- `--dry-run` — Preview configuration without launching
+
+**Exit codes:** 0 (success), 2 (usage error), 3 (config error), 4 (tool error), 5 (prerequisites), 6 (governance block), 130 (cancelled)
+
+See [CLI Reference → Exit Codes](docs/CLI-REFERENCE.md#exit-codes) for complete documentation.
+
+---
+
+## Development
+
+```bash
+uv sync              # Install dependencies
+uv run pytest        # Run tests
+uv run ruff check    # Run linter
+```
+
+---
+
+## License
+
+MIT