Develop

.claude/CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+See @README.md for project overview.
+
+> **Product:** Ckipper — multi-account Claude Code manager with Docker isolation.
+> **Repo:** Single-package zsh project. Top-level layout in §1.
+
+## Quick Reference
+
+**Core Rules:**
+- @.claude/rules/code-style.md — Naming, complexity limits, documentation
+- @.claude/rules/testing.md — Test structure, what to test, quality gates
+- @.claude/rules/security.md — Security requirements
+- @.claude/rules/file-organization.md — Directory structure, file caps, dependency direction
+
+**Package Rules:** *(add package-specific rule files as needed)*
+<!-- Example:
+- @.claude/rules/backend/api.md — API layer rules
+- @.claude/rules/frontend/webapp.md — Frontend rules
+-->
+
+## How to Use These Instructions
+
+1. **Always follow** the core philosophy and code standards
+2. **Consult package-specific rules** when working in individual packages
+3. **Package rules extend, not override** shared standards (e.g., a backend package adds validation requirements but doesn't remove the 25-line method limit)
+
+## 1. Project Overview
+
+Ckipper is a zsh-based wrapper for the [Claude Code CLI](https://claude.ai/cli) that provides:
+
+- **Multi-account isolation** — separate `~/.claude-<account>/` config dirs per registered account, with macOS Keychain integration for credentials.
+- **Worktree-aware launchers** — `w <project> <branch>` creates a git worktree, syncs settings, and either runs Claude Code locally or launches it inside a hardened Docker container.
+- **Per-account aliases** — auto-generated `<account>` shell functions (e.g., `personal`, `work`) that route to the correct config dir.
+- **Safety hooks** — Claude Code hooks (`bash-guardrails.sh`, `protect-claude-config.sh`) that block destructive commands and protect Ckipper-owned config files from accidental modification.
+- **Docker sandbox** — Dockerfile + entrypoint that isolate Claude Code with an egress firewall, credential injection via tmpfs, and pre-installed MCP server tooling.
+
+**Top-level layout:**
+
+```
+ckipper.zsh                  # ckipper CLI entry (sourced from .zshrc)
+lib/core/                    # shared primitives (registry, keychain, config, prompt, style)
+lib/account/                 # ckipper account subcommands (feature dir)
+lib/worktree/                # ckipper worktree subcommands (feature dir)
+lib/config/                  # ckipper config get/set/unset/list/edit (feature dir)
+lib/setup/                   # ckipper setup wizard (orchestration: delegates to features)
+lib/run/                     # ckipper run shortcut for `worktree run` (orchestration)
+lib/launcher/                # bare `ck` interactive menu (orchestration)
+hooks/                       # Claude Code safety hooks
+docker/                      # Dockerfile + entrypoint + firewall + cleanup
+tests/                       # bats + pytest tests
+install.sh                   # one-shot installer (copies to ~/.ckipper/)
+.claude/                     # rules + project Claude config
+```
+
+`lib/` has two layers (per `.claude/rules/shell-conventions.md`): feature dirs own subcommand functionality and MUST NOT call into each other; orchestration dirs delegate to feature dirs' public entry points.
+
+## 2. Core Engineering Philosophy
+
+1. **KISS** — Keep It Simple, Stupid. The simplest solution that works is the best solution.
+2. **Clarity over cleverness** — No tricks, no golf, no "elegant" one-liners that require a comment to explain.
+3. **Functional decomposition** — Break problems into small, named, single-purpose functions.
+4. **Object-Oriented Design** — Model the domain with clear objects, well-defined boundaries, and explicit contracts.
+5. **Test what matters** — Unit tests are not optional. If logic makes a decision, it gets a test. ALWAYS WRITE TESTS.
+6. **SOLID Principles** — Follow SOLID programming principles.
+
+## 3. Code Review Checklist
+
+Before approving any PR, verify:
+- [ ] **Can I understand every method without reading its callees?** If no, the names need work.
+- [ ] **There are NO MAGIC NUMBERS**
+- [ ] **Is every method <= 25 lines?** NO EXCEPTIONS.
+- [ ] **Is nesting <= 2 levels deep?** Extract if not.
+- [ ] **Does each module/class have a single, obvious responsibility?**
+- [ ] **Are there tests for every decision point in the logic?**
+- [ ] **Is there any cleverness that should be replaced with clarity?**
+- [ ] **Would a new teammate understand this in 5 minutes?**
+- [ ] **Do new entry points (CLI, scripts, API endpoints) validate input at trust boundaries?**
+- [ ] **Do exported functions have clear documentation when behavior isn't obvious from name and signature?**
+- [ ] **Do route handlers and service methods log their outcomes (success, not-found, error)?**
+- [ ] **Do error paths surface to monitoring — never swallowed silently?**
+
+## 4. Infrastructure & Services
+
+CI runs `make lint` + `make test-unit` on `macos-latest` via `.github/workflows/ci.yml`.
+
+## 5. Git Workflow
+
+**Branch naming:** `feature/{ticket-or-slug}-{short-description}` (e.g., `feature/123-user-auth`)
+**Commit messages:** Reference the ticket if applicable (e.g., `#123: Implement user auth flow`)
+**Always use feature branches + PRs.** NEVER commit directly to `main` or `develop`.
+**ALWAYS create PRs as drafts** (`gh pr create --draft`). The author decides when to mark "Ready for review."
+**PR description:** Link to the ticket if applicable, describe what changed and why, list affected files.
+
+## 6. AI-Specific Instructions
+
+- **Read and ingest before you edit.** Always read relevant source files before proposing changes. NEVER speculate about code you haven't inspected.
+- **These rules are authoritative over observed codebase patterns.** If existing code violates a rule in this document or `.claude/rules/`, that is technical debt — not a convention to follow. Never justify bad practices because you see them elsewhere in the repo. When in doubt, follow the rules, not the code.
+- **Follow existing design patterns that comply with these rules.** Study the relevant package and match the established architecture, file placement, and naming. If a convention exists and does not violate these rules, use it. If you have a clear technical reason to deviate, explain the rationale.
+- **Reuse existing utility functions**
+- **Reuse existing UI components**
+- **Verify schema and queries against source files.** Check your ORM schema for table/column structure before writing code that references them.
+- **Check existing types before creating new ones** to avoid duplication. Create new types when genuinely needed for new features.
+- **Flag security concerns proactively** (exposed secrets, SQL injection, missing auth, etc.).
+- **Use parallel tool calls** for independent operations (e.g., reading multiple files, running lint and test simultaneously).
+- **Package context awareness:** When working in a specific package, prioritize that package's rule file.

.claude/rules/code-style.md

@@ -0,0 +1,56 @@
+# Code Style
+
+## Method Size & Complexity
+
+These are **hard limits**, not guidelines:
+- **MAXIMUM 25 lines per method/function** (excluding blank lines and closing braces).
+- **MAXIMUM 2 levels of control flow nesting** per method. If you need a third level, extract a method.
+- **MAXIMUM 3 parameters** per method. Beyond that, introduce a parameter object or rethink the design.
+
+## YOU MUST USE EARLY RETURNS OVER DEEP NESTING
+
+Guard clauses go at the top. The happy path reads straight down.
+
+## Naming Conventions
+
+Names should be **descriptive and unambiguous**. A reader should never have to look at a method body to understand what it does. Avoid abbreviations.
+
+- **Functions/Methods**: language-idiomatic (snake_case in shell/Python, camelCase in JS/TS) — verbs (`getUserById`, `approve_request`, `calculateTotal`)
+- **Types/Classes**: PascalCase — nouns (`InvoiceCalculator`, `ClaimValidator`)
+- **Booleans**: prefix with `is`, `has`, `can`, `should` (`isEligible`, `has_access`)
+- **Collections**: pluralize (`users`, `active_orders`, `pendingItems`)
+- **Constants/env vars**: UPPER_SNAKE_CASE (`ALGORITHM`, `KEY_LENGTH`, `MAX_RETRY_COUNT`)
+- **Files**: match the language's idiomatic convention (PascalCase for classes, kebab-case for shell scripts, snake_case for Python modules)
+
+## General Rules
+
+- **Use the language's strongest type discipline** — explicit over implicit. No escape hatches (`any`, untyped `unknown`, `eval`) without justification.
+- **Prefer async-first APIs** in languages that support them (`async/await` over raw promises/callbacks).
+- **One responsibility per file.**
+- **NO MAGIC NUMBERS EVER** — ALWAYS EXTRACT TO A NAMED CONSTANT.
+
+## Code Documentation & Comments
+
+All code must include clear, human-readable documentation. Comments should be written so that a junior-level developer or higher can understand what is being done and why.
+
+**Public APIs are documented.** In languages with doc tooling (TSDoc/JSDoc, Python docstrings, Rustdoc, etc.), document every exported function, method, class, and interface — IDEs surface these as tooltips and they enable automated API-doc generation.
+
+**Required information** (using the language's doc syntax):
+- Each parameter's purpose and constraints
+- Return value and the conditions producing it
+- Exceptions/errors the function may raise
+- Usage example for non-trivial functions
+- Cross-references to related code or docs
+- Deprecation notice with a migration path
+
+**Inline comments** should explain "why," not "what." Comment business logic, workarounds, edge cases, and non-obvious decisions — not obvious code.
+
+## Linting
+
+Linting is enforced via `make lint` (locally) and `.github/workflows/ci.yml` (CI). Required tools:
+
+- **shellcheck** — all `.zsh` and `.sh` files. Configured via `.shellcheckrc` at repo root: `enable=all`, `disable=SC1090` (dynamic source paths are intentional in this project). Any other disables require a comment justifying the exception.
+- **shfmt** — `shfmt -d -i 4 -ci -s` (4-space indent, indent case, simplify). Diffs MUST be empty in CI.
+- **ruff** — Python files. Configured in `pyproject.toml`. Rules: `E`, `F`, `B`, `D` (docstring checks). Line length 100.
+
+Run `make bootstrap` once to install all linters via Homebrew + pip.

.claude/rules/file-organization.md

@@ -0,0 +1,36 @@
+# File Organization
+
+## Directory Size Limits
+
+These are **hard limits**, not guidelines:
+- **MAXIMUM 10 source files per directory.** Count only source files — colocated test and story files do NOT count toward the cap. If a directory has 10 source files, the next file MUST go in a subdirectory. No exceptions.
+- **Colocate test and story files with their source files.** `parser.py` and `parser_test.py` (and any colocated stories/fixtures) belong together in the same directory.
+
+When a directory approaches the cap, group related files into subdirectories by **domain**, **feature**, or **concern** — not by file type. Colocated tests and stories move with their source files into the subdirectory.
+
+## Directory Grouping
+
+When a directory needs subdirectories, group by **domain or feature**, not by file type. Keep related code together — all claim files in one place, not scattered across `types/`, `validators/`, and `handlers/`.
+
+**Exception:** Top-level `src/` directories MAY be organized by architectural layer (e.g., `api/`, `db/`, `event/`) when they represent distinct system boundaries. Within those layers, group by domain.
+
+## Dependency Direction
+
+Imports flow **downward and inward**, never upward or sideways across features.
+
+- **Parent directories MUST NOT import from child route/feature directories.** Shared code lives at the nearest common ancestor.
+- **Sibling feature directories MUST NOT import from each other.** If two features need the same code, extract it to their shared parent or a `_shared/` directory.
+- **Shared modules are pulled up, never reached into.** If two features both need a utility, it belongs in their common parent — not in one reaching into the other.
+
+## DO NOT MIMIC EXISTING BAD PATTERNS
+
+- **NEVER add files to a directory that already exceeds the 10-file cap.** Flag it to the user and propose a restructuring.
+- **When creating new files, follow these rules from scratch** — do not pattern-match against nearby directories that may be poorly organized.
+
+## Code Review Checklist
+
+Before approving any PR, verify:
+- [ ] **Is every directory under the 10-file cap (source files only)?**
+- [ ] **Are test and story files colocated with their source files?**
+- [ ] **Are subdirectories grouped by domain/feature, not by file type?**
+- [ ] **Do imports flow downward — no parent importing from child, no sibling cross-imports?**

.claude/rules/security.md

@@ -0,0 +1,25 @@
+# Security
+
+## No-Touch Zones
+
+These files require **explicit approval** before any modification:
+
+<!-- Customize per project. Examples: -->
+<!-- - `src/crypto/Cryptographer.ts` — Encryption logic -->
+<!-- - `src/billing/Calculator.ts` — Financial math -->
+<!-- - `prisma/schema.prisma` — Database schema -->
+
+- Any `.env*` files, deployment configs, or CI/CD workflows
+- Database migration files
+- Authentication/authorization configuration
+- Cryptography or encryption modules
+- Financial calculation modules
+- Files handling user secrets or credentials
+
+## Security Rules
+
+- **NEVER hardcode secrets in source code**
+- **NEVER run destructive operations without confirmation** (DROP, TRUNCATE, DELETE without WHERE, `rm -rf`, force-push)
+- **Validate all input at trust boundaries** — NEVER TRUST UNTRUSTED INPUT (CLI args, env vars, files, network requests; use Joi/Zod/equivalent for HTTP)
+- **Flag security concerns proactively** — exposed secrets, injection (SQL, shell, command), missing auth, XSS, CSRF, etc.
+- **Use lossless types for sensitive data** — money in minor units (cents) as integers, never floats; times in epoch ms or ISO 8601

.claude/rules/shell-conventions.md

@@ -0,0 +1,64 @@
+# Shell Conventions
+
+zsh-specific clarifications of `code-style.md`, `file-organization.md`, and `testing.md`. This file only covers what those rules don't already specify; nothing is repeated.
+
+## Function-line counting
+
+The "25 lines per function" cap counts function-body lines, **excluding** blank lines and lines containing only a closing `}`. Comment lines count.
+
+## Doc-header convention
+
+zsh has no native docstrings. Document every public function with a comment block immediately above its definition with these labelled sections (in this order, each as needed):
+
+```
+# <one-line summary, imperative mood, ends with period>
+#
+# Args: $1 — …, $2 — …
+# Returns: 0 on …; non-zero on …
+# Errors (stderr): "<exact message>" — <when>
+```
+
+Omit `Args:` if the function takes none. Omit `Errors:` if it never writes to stderr.
+
+## Function-name prefixes
+
+Used to encode the dependency direction at a glance and let CI verify it:
+
+- `_core_*` — `lib/core/` (shared primitives)
+- `_ckipper_account_*` — `lib/account/` (account subcommands)
+- `_ckipper_worktree_*` — `lib/worktree/` (worktree subcommands)
+- `_ckipper_config_*` — `lib/config/` (config get/set/unset/list/edit)
+- `_ckipper_setup_*` — `lib/setup/` (first-run wizard)
+- `_ckipper_run_*` — `lib/run/` (top-level `ckipper run` shortcut)
+- `_ckipper_launcher_*` — `lib/launcher/` (bare-`ck` interactive menu)
+- `_ckipper_*` — top-level dispatcher in `ckipper.zsh` (and `_ckipper_doctor`, kept un-namespaced because it's exposed as a top-level command, even though its source lives in `lib/account/`)
+- No prefix — public, callable from `.zshrc`: `ckipper`, `ck`
+
+## Booleans
+
+zsh has no native bool. Use string values `"true"`/`"false"` and test with `[[ "$x" = "true" ]]`. (Don't use `0`/`1` integers with `(( x ))`.)
+
+## Module sourcing
+
+Modules under `lib/` are sourced once by `ckipper.zsh` (the single entry script sourced from `~/.zshrc`). Modules MUST NOT source siblings.
+
+The `lib/` tree has two layers:
+
+1. **Feature dirs** — `lib/account/`, `lib/worktree/`, `lib/config/`. Each owns a coherent slice of subcommand functionality. Feature dirs MUST NOT call into each other (account cannot call worktree, worktree cannot call config, etc.). Shared code goes in `lib/core/` per `file-organization.md`.
+
+2. **Orchestration dirs** — `lib/launcher/`, `lib/setup/`, `lib/run/`. Their entire purpose is to delegate to feature dirs (the bare-`ck` menu, the first-run wizard, the `ckipper run` top-level shortcut). Orchestration dirs MAY call public, namespaced entry points from feature dirs (e.g. `_ckipper_worktree_dispatch`, `_ckipper_account_add`, `_ckipper_worktree_run`). They MUST NOT reach into another orchestration dir's internals.
+
+`lib/core/` is callable from any layer.
+
+CI enforces the namespace separation via `make lint-merge-guards`. The grep-based guards catch any *reference* (definition or call) — feature siblings cannot reach into each other, and orchestration-only namespaces (`_ckipper_setup_*`, `_ckipper_run_*`, `_ckipper_launcher_*`) are pinned to their dirs:
+
+- `grep -rE '\b_w_[a-z]' lib/`        — empty (no leftover renames from the merge)
+- `grep -rE '\bW_[A-Z]' lib/`         — empty (no leftover globals from the merge)
+- `grep -rE '\b_ckipper_account_' lib/worktree/ lib/config/`   — empty (sibling features can't call account)
+- `grep -rE '\b_ckipper_worktree_' lib/account/ lib/config/`   — empty (sibling features can't call worktree)
+- `grep -rE '\b_ckipper_config_' lib/account/ lib/worktree/ lib/setup/ lib/run/ lib/core/`   — empty (config namespace is pinned to lib/config/)
+- `grep -rE '\b_ckipper_setup_' lib/account/ lib/worktree/ lib/config/ lib/run/ lib/core/`   — empty (setup namespace is pinned to lib/setup/)
+- `grep -rE '\b_ckipper_run_' lib/account/ lib/worktree/ lib/setup/ lib/config/ lib/core/`   — empty (run namespace is pinned to lib/run/)
+- `grep -rE '\b_ckipper_launcher_' lib/account/ lib/worktree/ lib/setup/ lib/config/ lib/run/ lib/core/`   — empty (launcher namespace is pinned to lib/launcher/)
+
+Orchestration dirs (`lib/launcher/`, `lib/setup/`, `lib/run/`) are *omitted* from the account/worktree/config guards by design — that's the dispatcher exception. Adding them would block the only legal pattern of cross-imports.

.claude/rules/testing.md

@@ -0,0 +1,56 @@
+# Testing
+
+## Philosophy
+
+Tests are **documentation** that happens to be executable. A test should read like a specification of behavior.
+
+## Structure: Arrange -> Act -> Assert
+
+Separate the three phases with blank lines:
+
+```python
+class TestOrderProcessor:
+    def test_creates_order_for_valid_request(self):
+        request = RequestFixture.valid()
+        processor = build_order_processor()
+
+        order = processor.submit(request)
+
+        assert order.status == OrderStatus.PENDING
+        assert order.request_id == request.id
+
+    def test_rejects_invalid_requests(self):
+        request = RequestFixture.invalid()
+        processor = build_order_processor()
+
+        with pytest.raises(InvalidRequestError):
+            processor.submit(request)
+```
+
+## What to Test
+
+- **Processors and business logic** — Always. This is the core of the system.
+- **Utility/helper functions** — Always. They're pure and easy to test.
+- **Financial calculations** — Always. Money math must be bulletproof.
+- **Entry points / handlers** — Integration tests for the happy path and key error cases.
+- **Observable behavior, not implementation** — When testing components or modules with internal state, assert on the externally visible outcomes, not on private structure.
+
+## What NOT to Test
+
+- Simple getters/setters or data classes with no logic.
+- Framework boilerplate (middleware wiring, route config, loader setup).
+- Third-party library behavior.
+
+## Test Doubles
+
+Prefer **hand-written fakes** over mocking libraries. Fakes are simpler, more readable, and catch interface drift at compile time.
+
+## Quality Gates
+
+**Before committing, ALWAYS run** the project's verification commands (build / test / lint / typecheck — whichever apply).
+
+<!-- Add per-package gates as needed. Example:
+**Per-package gates:**
+- **api:** `npm run typecheck && npm run test && npm run lint`
+- **webapp:** `npm run test && npm run lint`
+-->