gitspace 0.2.0-rc.2 → 0.2.0-rc.20

package/.claude/settings.local.json

@@ -1,21 +1,10 @@
 {
   "permissions": {
     "allow": [
-      "Bash(bun test:*)",
-      "Bash(xargs ls:*)",
-      "Bash(bun pm:*)",
-      "Bash(node -e:*)",
-      "Bash(bun run typecheck:*)",
-      "Bash(bun -e:*)",
-      "Bash(bun:*)",
-      "Bash(xargs:*)",
-      "Bash(timeout 2 bash -c 'echo \"\"invalid-base64\"\" | bun src/index.ts access add \"\"not-valid-base64-data\"\" 2>&1')",
-      "Bash(wc:*)",
-      "WebFetch(domain:ghostty.org)",
-      "Bash(xxd:*)",
-      "WebFetch(domain:ast-grep.github.io)",
-      "WebFetch(domain:developers.cloudflare.com)",
-      "WebFetch(domain:gitspace.sh)"
+      "Bash(gh api:*)",
+      "Bash(gh search code:*)",
+      "Bash(curl:*)",
+      "Bash(bun scripts/build.ts:*)"
     ]
   }
 }

package/.gitspace/events.json

@@ -0,0 +1,11 @@
+{
+  "savedFilters": [
+    {
+      "name": "Sample process events",
+      "filter": {
+        "processName": "sample-events"
+      },
+      "sinceMinutes": 60
+    }
+  ]
+}

package/.gitspace/processes.json

@@ -0,0 +1,23 @@
+{
+  "processes": [
+    {
+      "name": "sample-events",
+      "command": "bun",
+      "args": ["scripts/sample-events.ts"],
+      "autostart": false,
+      "events": {
+        "keepRawOutput": false,
+        "correlationField": "requestId",
+        "aggregateMode": "stream",
+        "updateIntervalMs": 200,
+        "maxTimeline": 50
+      },
+      "restart": {
+        "policy": "always",
+        "maxAttempts": 10,
+        "backoffMs": 2000,
+        "maxBackoffMs": 15000
+      }
+    }
+  ]
+}

package/.gitspace/{select → scripts/select}/01-status.sh

@@ -3,9 +3,8 @@
 #
 # This runs every time you switch to an existing workspace.
 #
-# Bundle values are available as environment variables:
-#   SPACE_VALUE_<KEY> - Regular values from input steps
-#   SPACE_SECRET_<KEY> - Secret values from secret steps
+# Bundle values are available using exact keys and uppercase snake-case aliases.
+# Example aliases: DEVELOPER_NAME, EXAMPLE_API_TOKEN
 
 WORKSPACE_NAME=$1
 REPOSITORY=$2
@@ -15,14 +14,14 @@ echo "=== Workspace: $WORKSPACE_NAME ==="
 echo ""
 
 # Show bundle values (proof of concept)
-if [ -n "$SPACE_VALUE_DEVELOPERNAME" ]; then
-  echo "Welcome back, $SPACE_VALUE_DEVELOPERNAME!"
+if [ -n "$DEVELOPER_NAME" ]; then
+  echo "Welcome back, $DEVELOPER_NAME!"
 fi
 
 # Show that we have access to the secret (masked)
-if [ -n "$SPACE_SECRET_EXAMPLEAPITOKEN" ]; then
+if [ -n "$EXAMPLE_API_TOKEN" ]; then
   # Only show first 4 characters to prove we have access
-  TOKEN_PREVIEW="${SPACE_SECRET_EXAMPLEAPITOKEN:0:4}..."
+  TOKEN_PREVIEW="${EXAMPLE_API_TOKEN:0:4}..."
   echo "API Token available: $TOKEN_PREVIEW (stored in OS keychain)"
 fi
 

package/AGENTS.md

@@ -14,7 +14,7 @@ This document provides comprehensive information for AI assistants working on th
 - **X3DH handshake** for forward-secret session encryption
 - Web terminal interface (React + xterm.js)
 - Linear issue integration for workspace creation
-- Convention-based custom scripts (pre, setup, select phases)
+- Convention-based custom scripts in `.gitspace/scripts/` (pre, setup, select, remove phases)
 
 ## Architecture
 
@@ -22,11 +22,12 @@ This document provides comprehensive information for AI assistants working on th
 
 1. **Projects**: Top-level containers for a GitHub repository
    - Located at `~/gitspace/<project-name>/`
-   - Contains: base repo clone, workspaces, scripts, config
+   - Contains: base repo clone, workspaces, config
 
 2. **Workspaces**: Individual git worktrees for features/branches
    - Located at `~/gitspace/<project-name>/workspaces/<workspace-name>/`
    - Each workspace has its own branch
+   - Scripts are sourced from `.gitspace/scripts/<phase>/` in the workspace (version-controlled)
 
 3. **Sessions**: PTY terminal sessions managed by tmux-lite
    - Can be attached from multiple clients
@@ -50,7 +51,7 @@ This document provides comprehensive information for AI assistants working on th
 ```
 src/
 ├── index.ts                    # Entry point (TUI or CLI dispatch)
-├── commands/                   # CLI command implementations (16 files)
+├── commands/                   # CLI command implementations (17 files)
 │   ├── access.ts               # Access control list (add/list/remove)
 │   ├── add.ts                  # Add projects/workspaces
 │   ├── auth.ts                 # GitHub OAuth for gitspace.sh
@@ -58,6 +59,7 @@ src/
 │   ├── directory.ts            # Get project directory path
 │   ├── host.ts                 # Subdomain hosting (reserve/release/list)
 │   ├── identity.ts             # Identity management (init/show)
+│   ├── linear.ts               # Linear integration (setup/show/clear)
 │   ├── list.ts                 # List projects/workspaces
 │   ├── machine.ts              # Remote machine management (invite/list)
 │   ├── relay.ts                # Relay server (start/token)
@@ -126,22 +128,21 @@ src/
 │   │   └── ProjectList.tui.tsx
 │   ├── providers/              # Machine access abstraction
 │   │   ├── MachineProvider.ts  # Interface definition
-│   │   ├── LocalMachineProvider.ts  # Direct tmux-lite access
-│   │   └── RemoteMachineProvider.ts # Via relay
+│   │   └── LocalMachineProvider.ts  # Direct tmux-lite access
 │   ├── hooks/
-│   │   └── useNavigation.ts    # Navigation state management
+│   │   └── useUserActivity.ts  # Activity tracking for notifications
 │   └── types.ts                # Shared type definitions
 ├── tui/                        # Terminal UI (OpenTUI)
 │   ├── index.ts                # TUI entry point
 │   ├── app.tsx                 # Main TUI application
-│   ├── state.ts                # State management
-│   ├── adapters.ts             # Local/remote machine adapters
 │   ├── components/
-│   │   └── Terminal.tsx        # Embedded terminal
+│   │   ├── RemoteMachineScreen.tsx # Remote machine browser screen
+│   │   └── RemoteTerminal.tsx  # Embedded session terminal
 │   └── hooks/
-│       ├── useAppState.ts
 │       ├── useRemoteMachines.ts
-│       └── useInboxTUI.ts
+│       ├── useRemoteTerminal.ts
+│       ├── useLocalSession.ts
+│       └── useDaemonStatus.ts
 ├── web/                        # Web application (Vite + React)
 │   └── src/
 │       ├── App.tsx             # Main web app
@@ -215,10 +216,11 @@ src/
 | Command | Description |
 |---------|-------------|
 | `gssh relay start` | Start relay server |
-| `gssh relay token` | Create account JWT (HMAC) |
-| `gssh relay authorize <pubkey>` | Authorize a client on relay |
-| `gssh relay revoke <id>` | Revoke client authorization |
+| `gssh relay authorize <pubkey>` | Authorize a machine on relay |
+| `gssh relay revoke <id>` | Revoke machine authorization |
 | `gssh relay machines` | List authorized machines |
+| `gssh relay trusted` | List trusted relays |
+| `gssh relay untrust <url>` | Remove relay from trusted list |
 
 ### tmux-lite Daemon
 | Command | Description |
@@ -251,6 +253,23 @@ src/
 | `gssh host set-primary <name>` | Set primary subdomain |
 | `gssh host status` | Show hosting status |
 
+### Linear Integration
+| Command | Description |
+|---------|-------------|
+| `gssh linear setup` | Configure Linear integration (API key + teams) |
+| `gssh linear setup --project <name>` | Configure Linear for a specific project |
+| `gssh linear show` | Show user-level Linear configuration |
+| `gssh linear show --project <name>` | Show project-specific Linear configuration |
+| `gssh linear clear` | Clear user-level Linear configuration |
+| `gssh linear clear --project <name>` | Clear project-specific Linear configuration |
+
+### Bundle Management
+| Command | Description |
+|---------|-------------|
+| `gssh bundle status` | Show bundle status for current project |
+| `gssh bundle refresh` | Re-run bundle onboarding (keeps previous values as defaults) |
+| `gssh bundle refresh --force` | Force refresh even if no changes detected |
+
 ## Remote Access Architecture
 
 ```
@@ -263,10 +282,19 @@ src/
 └─────────────────┘       └─────────────────┘       └─────────────────┘
 ```
 
-### Connection Flow
+### Connection Flow (gitspace.sh Hosting)
 
-1. Machine runs `gssh serve --relay <url> --token <jwt>`
-2. Machine registers with relay (sends public keys)
+1. User logs in: `gssh auth login` (GitHub OAuth)
+2. User reserves subdomain: `gssh host reserve <name>`
+3. Machine runs `gssh serve start` (auto-starts local relay + cloudflared tunnel)
+4. Client connects via web: `https://<name>.gitspace.sh`
+5. X3DH handshake establishes session keys
+6. All terminal I/O is E2E encrypted
+
+### Connection Flow (Self-Hosted Relay)
+
+1. Machine runs `gssh serve start --relay ws://relay:4480/ws`
+2. Machine registers with relay (Ed25519 challenge-response auth)
 3. Machine creates invite: `gssh share create`
 4. Client connects with invite: `gssh connect <token>`
 5. X3DH handshake establishes session keys
@@ -280,7 +308,7 @@ src/
 | Key exchange | X25519 |
 | Symmetric encryption | AES-256-GCM |
 | Key derivation | HKDF-SHA256 |
-| JWT signing | HMAC-SHA256 |
+| Relay authentication | Ed25519 challenge-response |
 
 ## TUI/Web Shared Component Pattern
 
@@ -306,7 +334,7 @@ interface MachineProvider {
 ```
 
 - `LocalMachineProvider`: Direct filesystem + tmux-lite CLI
-- `RemoteMachineProvider`: Via relay WebSocket
+- Remote machine access in UI now uses shared relay/session hooks + backend adapters (`shared/relay/*`, `shared/session/*`)
 
 ## Development Workflow
 
@@ -322,11 +350,14 @@ bun run build
 # Run TUI
 bun src/index.ts
 
-# Run relay
-RELAY_SIGNING_SECRET=secret bun src/index.ts relay start
+# Run relay (uses Ed25519 identity from keychain)
+bun src/index.ts relay start
+
+# Run serve with gitspace.sh hosting (requires auth login + host reserve)
+bun src/index.ts serve start
 
-# Run serve
-bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
+# Run serve with self-hosted relay
+bun src/index.ts serve start --relay ws://localhost:4480/ws
 ```
 
 ### Code Style
@@ -409,6 +440,7 @@ bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
 | Access list | `~/gitspace/.access.json` | Authorized client public keys |
 | Machine info | `~/gitspace/.machine.json` | Machine registration |
 | Relay config | `~/gitspace/.relay.json` | Relay configuration cache |
+| Host config | `~/gitspace/host.json` | gitspace.sh subdomain config |
 | Daemon state | `~/gitspace/.serve/` | PID files, status sockets |
 | tmux-lite state | `/tmp/` | Session data (configurable via `TMUX_LITE_SESSION_DIR`) |
 
@@ -418,9 +450,8 @@ bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
 |----------|-------------|---------|
 | `RELAY_PORT` | Relay server port | `4480` |
 | `RELAY_BIND` | Relay bind address | `0.0.0.0` |
-| `RELAY_SIGNING_SECRET` | Secret for HMAC JWT signing | Required |
 | `RELAY_PRIVATE_KEY` | Base64 Ed25519 private key | Uses keychain |
-| `SPACES_CURRENT_PROJECT` | Override current project | From config |
+| `RELAY_LABEL` | Label for relay identity | None |
 | `GITSPACE_API_URL` | gitspace.sh API URL | `https://api.gitspace.sh` |
 
 ### Default Values
@@ -431,9 +462,8 @@ bun src/index.ts serve --relay ws://localhost:8080/ws --token <jwt>
 | Base branch | `main` | Global/project config |
 | Stale workspace days | `30` | Global config |
 | Relay port | `4480` | CLI/env |
-| Default relay URL | `wss://relay.gitspace.sh` | CLI |
 
 ---
 
-**Last Updated**: 2025-01
-**Runtime**: Bun / Node.js 18+
+**Last Updated**: 2026-01
+**Runtime**: Bun 1.3+

package/README.md

@@ -20,7 +20,6 @@ The following tools must be installed and available in your PATH:
 - [GitHub CLI (`gh`)](https://cli.github.com/) - for listing repositories
 - [Git](https://git-scm.com/) - for worktree management
 - [jq](https://stedolan.github.io/jq/) - for JSON processing
-- [Bun](https://bun.sh) - runtime for the CLI
 
 **GitHub Authentication**: You must authenticate the GitHub CLI before using GitSpace:
 
@@ -31,7 +30,17 @@ gh auth login
 ## Installation
 
 ```bash
-bun install -g https://github.com/inkibra/gitspace.sh
+# npm
+npm install -g gitspace
+
+# bun
+bun install -g gitspace
+
+# pnpm
+pnpm install -g gitspace
+
+# yarn
+yarn global add gitspace
 
 # Verify installation
 gssh --version
@@ -97,6 +106,22 @@ gssh switch
 gssh switch my-feature
 ```
 
+### Workspace Session Mode (`space`)
+
+When GitSpace opens a workspace-scoped terminal session, it injects a `space` shell function (bash/zsh).
+
+- Use `space ...` for workspace operations without repeating `--project` and `--workspace`
+- `gssh` commands are restricted in this mode to avoid cross-workspace mistakes
+- `gssh tmux ...` is blocked inside workspace sessions
+
+Examples:
+
+```bash
+space context --json
+space review hunks src/app.ts --format json
+space review add-hunk src/app.ts --index 1 --approve --body "Looks good"
+```
+
 ## Repo Config Bundles
 
 Repo config bundles allow repository owners to share onboarding configurations with their team. When someone clones a project that contains a bundle, they'll be guided through setup steps and have scripts automatically installed.
@@ -108,14 +133,15 @@ A bundle is a directory (typically `.gitspace/`) containing:
 ```
 .gitspace/
 ├── bundle.json           # Bundle manifest with onboarding steps
-├── pre/                  # Scripts to run before setup
-│   └── 01-copy-env.sh
-├── setup/                # Scripts to run on first workspace creation
-│   └── 01-install-deps.sh
-├── select/               # Scripts to run every time workspace is opened
-│   └── 01-status.sh
-└── remove/               # Scripts to run before workspace deletion
-    └── 01-cleanup.sh
+└── scripts/
+    ├── pre/              # Deprecated: migrate scripts into ordered setup/
+    │   └── 01-copy-env.sh
+    ├── setup/            # Scripts for setup runs (when bundle/value state changes)
+    │   └── 01-install-deps.sh
+    ├── select/           # Scripts to run on each new terminal attach
+    │   └── 01-status.sh
+    └── remove/           # Scripts to run before workspace deletion
+        └── 01-cleanup.sh
 ```
 
 ### Bundle Manifest (`bundle.json`)
@@ -170,27 +196,27 @@ A bundle is a directory (typically `.gitspace/`) containing:
 
 ### Using Bundle Values in Scripts
 
-Bundle values are passed to scripts as environment variables:
+Bundle values are passed to scripts as environment variables using the configured bundle keys:
 
-- `SPACE_VALUE_<KEY>` - Regular values from input steps
-- `SPACE_SECRET_<KEY>` - Secret values from secret steps (fetched from OS keychain)
+- `<KEY>` - Regular or secret value using the exact `configKey` from `bundle.json`
+- `<NORMALIZED_KEY>` - Uppercase snake-case alias (for example, `teamName` -> `TEAM_NAME`)
 
 **Example script:**
 
 ```bash
 #!/bin/bash
-# .gitspace/select/01-status.sh
+# .gitspace/scripts/select/01-status.sh
 
 WORKSPACE_NAME=$1
 REPOSITORY=$2
 
 # Access bundle values
-if [ -n "$SPACE_VALUE_TEAMNAME" ]; then
-  echo "Welcome, $SPACE_VALUE_TEAMNAME team!"
+if [ -n "$TEAM_NAME" ]; then
+  echo "Welcome, $TEAM_NAME team!"
 fi
 
 # Access secrets (stored securely in OS keychain)
-if [ -n "$SPACE_SECRET_APIKEY" ]; then
+if [ -n "$API_KEY" ]; then
   echo "API Key configured"
 fi
 ```
@@ -199,7 +225,7 @@ fi
 
 Bundles can be loaded from:
 
-1. **In-repo** (automatic): `.gitspace/`, `.gitspace-config/`, `.spaces-config/`, or `.spaces/` in the cloned repository
+1. **In-repo** (automatic): `.gitspace/` directory in the cloned repository
 2. **Local path**: `gssh add project --bundle-path /path/to/bundle/`
 3. **Remote URL**: `gssh add project --bundle-url https://example.com/bundle.zip`
 
@@ -347,14 +373,16 @@ Located at `~/gitspace/<project-name>/.config.json`:
 
 ### Custom Scripts
 
-GitSpace uses **convention over configuration** for custom scripts:
+GitSpace uses **convention over configuration** for custom scripts. Scripts live
+inside each workspace so they can vary by branch:
 
 ```
-~/gitspace/<project-name>/scripts/
-├── pre/           # Run before setup (terminal)
-├── setup/         # Run once on workspace creation
-├── select/        # Run every time workspace is opened
-└── remove/        # Run before workspace deletion
+~/gitspace/<project-name>/workspaces/<workspace-name>/.gitspace/
+└── scripts/
+    ├── pre/       # Deprecated: run before setup (migrate to setup/)
+    ├── setup/     # Run when setup state requires refresh
+    ├── select/    # Run on each new terminal attach
+    └── remove/    # Run before workspace deletion
 ```
 
 #### Script Execution Rules
@@ -363,15 +391,15 @@ GitSpace uses **convention over configuration** for custom scripts:
 2. Scripts run **alphabetically** (use `01-`, `02-` prefixes)
 3. **Working directory**: The workspace directory
 4. **Arguments**: `$1` = workspace name, `$2` = repository name
-5. **Environment**: Bundle values available as `SPACE_VALUE_*` and `SPACE_SECRET_*`
+5. **Environment**: Bundle values available by key name (for example `REGION`, `PULUMI_ACCESS_TOKEN`)
 
 #### Script Phases
 
 | Phase | When | Use Case |
 |-------|------|----------|
-| `pre/` | Once, before setup | Copy .env files, create directories |
-| `setup/` | Once, on workspace creation | Install dependencies, initial build |
-| `select/` | Every workspace open | Git fetch, status checks |
+| `pre/` | Deprecated | Move scripts into ordered `setup/` files |
+| `setup/` | When setup state changes | Install dependencies, initial build |
+| `select/` | Every new terminal attach | Git fetch, status checks |
 | `remove/` | Before deletion | Cleanup, notifications |
 
 ### Environment Variables
@@ -381,8 +409,8 @@ GitSpace uses **convention over configuration** for custom scripts:
 export SPACES_CURRENT_PROJECT="my-app"
 
 # Available in scripts (from bundle onboarding):
-# SPACE_VALUE_<KEY>    - Regular values
-# SPACE_SECRET_<KEY>   - Secret values (from OS keychain)
+# <KEY>                - Value by exact bundle config key name
+# <NORMALIZED_KEY>     - Uppercase snake-case alias (e.g. teamName -> TEAM_NAME)
 ```
 
 ## Directory Structure
@@ -396,13 +424,15 @@ export SPACES_CURRENT_PROJECT="my-app"
 │   ├── workspaces/              # Git worktrees
 │   │   └── <workspace-name>/
 │   │       ├── gitspace.lock    # Setup completion marker
-│   │       └── .prompt/         # Linear issue details (if applicable)
-│   │           └── issue.md
-│   └── scripts/                 # Custom scripts
-│       ├── pre/
-│       ├── setup/
-│       ├── select/
-│       └── remove/
+│   │       ├── .prompt/         # Linear issue details (if applicable)
+│   │       │   └── issue.md
+│   │       └── .gitspace/
+│   │           ├── bundle.json
+│   │           └── scripts/     # Custom scripts (per worktree)
+│   │               ├── pre/
+│   │               ├── setup/
+│   │               ├── select/
+│   │               └── remove/
 ```
 
 ## Remote Access
@@ -578,7 +608,7 @@ Error: GitHub CLI is not authenticated
 
 ### Bundle secrets not available
 
-If `SPACE_SECRET_*` variables are empty, ensure:
+If expected bundle key environment variables are empty, ensure:
 1. You completed the onboarding secret steps
 2. Your OS keychain service is running (libsecret on Linux, Keychain on macOS)