Add multi-environment auth with encrypted v2 config

.changeset/multi-environment-auth.md

@@ -0,0 +1,44 @@
+---
+"t3code-cli": minor
+---
+
+Add multi-environment auth with encrypted credential storage.
+
+### Features
+
+- Store multiple named auth environments in `~/.config/t3cli/config.json` (or `$XDG_CONFIG_HOME/t3cli/config.json`).
+- Encrypt tokens at rest with AES-256-GCM; bind ciphertext to environment name, URL, and `local` flag via additional authenticated data.
+- Store the master key in the OS keyring when available (`@napi-rs/keyring`), otherwise in `~/.config/t3cli/key` with `0600` permissions.
+- Migrate legacy v1 flat config (plaintext `url`/`token`) to encrypted v2 on first read; rewrite `config.json` automatically.
+- Add global `--environment <name>` flag and `T3CLI_ENV` for per-command environment selection.
+- Add `T3CODE_URL` + `T3CODE_TOKEN` override when both are set.
+- Add `env list`, `env use`, and `env remove` commands for managing stored environments.
+- Add `--name` and `--replace` flags to `auth pair` and `auth local`.
+- Verify credential decryption before switching the default environment (`env use`).
+
+### Breaking changes
+
+**CLI**
+
+- `auth list`, `auth use`, and `auth unpair` are removed. Use `env list`, `env use`, and `env remove` instead.
+- `auth unpair` is renamed to `env remove` (same behavior: removes local credentials only).
+
+**Library (`t3code-cli/config`)**
+
+- `T3ConfigLive`, `makeT3Config`, `UrlError`, and `StoredConfig` are removed from the public export surface.
+- Import config services via namespace exports instead: `Config`, `Credential`, `Keystore`, `Selection`, `Env`, `Paths`, `Url`, `EnvironmentName`.
+- `ResolvedConfig` remains exported but now includes optional `environment` and a `source` discriminator (`config` | `env`).
+
+**Library (`t3code-cli/connection`)**
+
+- `T3CodeNodeRpcLayer` is no longer exported from `t3code-cli/connection`. Import it from `t3code-cli/node`.
+
+**Library (`t3code-cli/runtime` and `t3code-cli/node`)**
+
+- `NodeEnvironmentLive` is removed. Environment/process snapshot access moved to `CliRuntime` under `t3code-cli/cli`.
+
+### Upgrade notes
+
+- Existing single-environment v1 configs upgrade automatically on the first command that reads config.
+- After upgrade, tokens are encrypted; keep the OS keyring entry or `~/.config/t3cli/key` file backed up if you rely on stored credentials.
+- Scripts using `auth list`, `auth use`, or `auth unpair` must switch to the `env` subcommands.

CONTRIBUTING.md

@@ -28,6 +28,18 @@ pnpm release:check
 
 Use `pnpm format` and `pnpm lint:fix` for mechanical fixes.
 
+## testing
+
+- Prefer pure `it()` tests for logic with no service dependencies.
+- Use `it.layer(ConfigPlatformLayer)` for config/auth tests that need filesystem, path, and crypto only — not full `NodeServices.layer`.
+- Colocate tests as `{module}.test.ts` next to `{module}.ts`; shared fixtures use `{module}.test-utils.ts` in the same directory.
+- Keep feature code grouped under its module (e.g. `config/credential/cipher.ts`, `config/url/error.ts`) with sibling-only `index.ts` barrels — no standalone `error/` directories, but each feature owns an `error.ts` when needed.
+- Top-level module files use the module name (e.g. `config/config.ts` for `T3Config`, `config/error.ts` for shared config errors).
+- Use `it.layer(ConfigPlatformLayer)` for config/auth tests that need filesystem, path, and crypto only — not full `NodeServices.layer`.
+- Use `CliRuntime.layerTest()` for cwd fixtures and `config/env/env.test-utils.ts` for `HOME`.
+- Split tests by module/concern; keep integration files under ~120 lines when possible.
+- Reserve full app-layer smoke tests for CLI routing and end-to-end wiring only.
+
 ## pull requests
 
 Keep changes scoped and small. Include user-facing README updates when command behavior changes.

README.md

@@ -41,15 +41,27 @@ npx skills add tarik02/t3cli
 
 ## Authentication
 
+`t3cli` stores multiple named auth environments in `~/.config/t3cli/config.json` (or `$XDG_CONFIG_HOME/t3cli/config.json`). Tokens are encrypted at rest with AES-256-GCM; the master key is stored in the OS keyring when available, otherwise in `~/.config/t3cli/key`.
+
 ```sh
-t3cli auth pair --url <url> [--local]     # Pair with a remote server
-t3cli auth local                          # Local t3code installation
-t3cli auth status                         # Check current auth
+t3cli auth pair --url <url> [--name <name>] [--replace] [--local]   # Pair with a remote server
+t3cli auth local [--name <name>] [--replace]                        # Local t3code installation
+t3cli auth status [--format json]                                   # Check current auth
+t3cli env list [--format json]                                      # List stored environments
+t3cli env use <name> [--format json]                                # Set default environment
+t3cli env remove [--name <name>] [--yes]                            # Remove local credentials
+t3cli --environment <name> ...                                      # Use a specific environment once
 ```
 
 - Use `auth pair` with a pairing URL from a running t3code server
-- Use `auth local` to authenticate against a local t3code installation
+- Default environment names: hostname slug from the paired URL, or `local` for `auth local`
+- `auth pair` / `auth local` set the default environment only when creating the first stored environment; use `env use` to switch afterward
+- `--replace` overwrites an existing environment and makes it the default
+- `env remove` removes local CLI credentials only; any remote token can remain valid until natural expiry
+- Use `auth local` or `auth pair --local` to authenticate against a local t3code installation
 - Local auth enables automatic project resolution from the current directory
+- Set `T3CLI_ENV=<name>` to select an environment when `--environment` is omitted
+- `T3CODE_URL` and `T3CODE_TOKEN` override the selected environment only when both are set
 
 ## Project Management
 
@@ -143,12 +155,15 @@ t3cli terminal destroy [--thread <id>] <terminal-id> [--yes] [--format auto|huma
 
 When flags are omitted, the CLI reads these environment variables (first match wins):
 
-| Variable               | Used by                                   |
-| ---------------------- | ----------------------------------------- |
-| `T3CODE_PROJECT_ROOT`  | `--project`                               |
-| `T3CODE_PROJECT_ID`    | `--project` (after `T3CODE_PROJECT_ROOT`) |
-| `T3CODE_WORKTREE_PATH` | `--worktree`                              |
-| `T3CODE_THREAD_ID`     | `--thread`                                |
+| Variable               | Used by                                       |
+| ---------------------- | --------------------------------------------- |
+| `T3CODE_PROJECT_ROOT`  | `--project`                                   |
+| `T3CODE_PROJECT_ID`    | `--project` (after `T3CODE_PROJECT_ROOT`)     |
+| `T3CODE_WORKTREE_PATH` | `--worktree`                                  |
+| `T3CODE_THREAD_ID`     | `--thread`                                    |
+| `T3CLI_ENV`            | `--environment`                               |
+| `T3CODE_URL`           | server URL override (requires `T3CODE_TOKEN`) |
+| `T3CODE_TOKEN`         | auth token override (requires `T3CODE_URL`)   |
 
 ### Project Resolution
 
@@ -177,6 +192,7 @@ t3cli wait --format ndjson
 ```sh
 --help                    # Show help
 --version                 # Show version
+--environment <name>      # Auth environment for this command
 --completions <shell>     # Generate shell completions (bash|zsh|fish|sh)
 --log-level <level>        # Set log level
 ```

package.json

@@ -36,60 +36,65 @@
   "exports": {
     ".": {
       "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./application": {
       "types": "./dist/src/application/index.d.ts",
+      "import": "./dist/application.js",
       "default": "./dist/application.js"
     },
     "./auth": {
       "types": "./dist/src/auth/index.d.ts",
+      "import": "./dist/auth.js",
       "default": "./dist/auth.js"
     },
     "./cli": {
       "types": "./dist/src/cli/index.d.ts",
+      "import": "./dist/cli.js",
       "default": "./dist/cli.js"
     },
     "./config": {
       "types": "./dist/src/config/index.d.ts",
+      "import": "./dist/config.js",
       "default": "./dist/config.js"
     },
     "./connection": {
       "types": "./dist/src/connection/index.d.ts",
+      "import": "./dist/connection.js",
       "default": "./dist/connection.js"
     },
     "./contracts": {
       "types": "./dist/src/contracts/index.d.ts",
+      "import": "./dist/contracts.js",
       "default": "./dist/contracts.js"
     },
-    "./t3tools": {
-      "types": "./dist/upstream-t3code/packages/contracts/src/index.d.ts",
-      "default": "./dist/t3tools.js"
-    },
-    "./layout": {
-      "types": "./dist/src/layout/index.d.ts",
-      "default": "./dist/layout.js"
-    },
     "./node": {
       "types": "./dist/src/node/index.d.ts",
+      "import": "./dist/node.js",
       "default": "./dist/node.js"
     },
     "./orchestration": {
       "types": "./dist/src/orchestration/index.d.ts",
+      "import": "./dist/orchestration.js",
       "default": "./dist/orchestration.js"
     },
     "./rpc": {
       "types": "./dist/src/rpc/index.d.ts",
+      "import": "./dist/rpc.js",
       "default": "./dist/rpc.js"
     },
     "./runtime": {
       "types": "./dist/src/runtime/index.d.ts",
+      "import": "./dist/runtime.js",
       "default": "./dist/runtime.js"
     },
-    "./scope": {
-      "types": "./dist/src/scope/index.d.ts",
-      "default": "./dist/scope.js"
-    }
+    "./t3tools": {
+      "types": "./dist/upstream-t3code/packages/contracts/src/index.d.ts",
+      "import": "./dist/t3tools.js",
+      "default": "./dist/t3tools.js"
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "build": "vp pack && tsc -p tsconfig.dts.json",
@@ -108,6 +113,7 @@
   },
   "dependencies": {
     "@effect/platform-node": "4.0.0-beta.78",
+    "@napi-rs/keyring": "^1.3.0",
     "effect": "4.0.0-beta.78"
   },
   "devDependencies": {

skills/t3code-cli/SKILL.md

@@ -49,11 +49,12 @@ t3cli start "task description" --provider "$PROVIDER" --model "$MODEL" --wait
 
 ## Scope resolution
 
-| Target   | Flag         | Env (first match wins)                                              |
-| -------- | ------------ | ------------------------------------------------------------------- |
-| Project  | `--project`  | `T3CODE_PROJECT_ROOT` → `T3CODE_PROJECT_ID` → cwd (local auth only) |
-| Worktree | `--worktree` | `T3CODE_WORKTREE_PATH` → inferred from cwd                          |
-| Thread   | `--thread`   | `T3CODE_THREAD_ID`                                                  |
+| Target      | Flag            | Env (first match wins)                                              |
+| ----------- | --------------- | ------------------------------------------------------------------- |
+| Environment | `--environment` | `T3CLI_ENV` → config default                                        |
+| Project     | `--project`     | `T3CODE_PROJECT_ROOT` → `T3CODE_PROJECT_ID` → cwd (local auth only) |
+| Worktree    | `--worktree`    | `T3CODE_WORKTREE_PATH` → inferred from cwd                          |
+| Thread      | `--thread`      | `T3CODE_THREAD_ID`                                                  |
 
 Project matching: id → `workspaceRoot` → ancestor under workspace → known thread `worktreePath`. Remote pairing without `--local` requires explicit `--project` or `T3CODE_PROJECT_*`.