gitspace 0.2.0-rc.12 → 0.2.0-rc.14

package/.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(gh api:*)",
       "Bash(gh search code:*)",
-      "Bash(curl:*)"
+      "Bash(curl:*)",
+      "Bash(bun scripts/build.ts:*)"
     ]
   }
 }

package/.gitspace/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 as environment variables using bundle key names.
+# Example: DEVELOPERNAME, EXAMPLEAPITOKEN
 
 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 "$DEVELOPERNAME" ]; then
+  echo "Welcome back, $DEVELOPERNAME!"
 fi
 
 # Show that we have access to the secret (masked)
-if [ -n "$SPACE_SECRET_EXAMPLEAPITOKEN" ]; then
+if [ -n "$EXAMPLEAPITOKEN" ]; then
   # Only show first 4 characters to prove we have access
-  TOKEN_PREVIEW="${SPACE_SECRET_EXAMPLEAPITOKEN:0:4}..."
+  TOKEN_PREVIEW="${EXAMPLEAPITOKEN: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 in `.gitspace/` (pre, setup, select, remove phases)
+- Convention-based custom scripts in `.gitspace/scripts/` (pre, setup, select, remove phases)
 
 ## Architecture
 
@@ -27,7 +27,7 @@ This document provides comprehensive information for AI assistants working on th
 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/<phase>/` in the workspace (version-controlled)
+   - 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
@@ -128,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
@@ -335,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
 

package/README.md

@@ -117,14 +117,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`)
@@ -179,27 +180,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`
+- Legacy aliases `SPACE_VALUE_<KEY>` / `SPACE_SECRET_<KEY>` are also provided for compatibility
 
 **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 "$TEAMNAME" ]; then
+  echo "Welcome, $TEAMNAME team!"
 fi
 
 # Access secrets (stored securely in OS keychain)
-if [ -n "$SPACE_SECRET_APIKEY" ]; then
+if [ -n "$APIKEY" ]; then
   echo "API Key configured"
 fi
 ```
@@ -361,10 +362,11 @@ inside each workspace so they can vary by branch:
 
 ```
 ~/gitspace/<project-name>/workspaces/<workspace-name>/.gitspace/
-├── pre/           # Run before setup (terminal)
-├── setup/         # Run once on workspace creation
-├── select/        # Run every time workspace is opened
-└── remove/        # Run before workspace deletion
+└── 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
@@ -373,15 +375,15 @@ inside each workspace so they can vary by branch:
 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
@@ -391,8 +393,9 @@ inside each workspace so they can vary by branch:
 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 bundle config key name
+# SPACE_VALUE_<KEY>    - Legacy alias for regular values
+# SPACE_SECRET_<KEY>   - Legacy alias for secret values
 ```
 
 ## Directory Structure
@@ -406,19 +409,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
-│   └── workspaces/
-│       └── <workspace-name>/
-│           └── .gitspace/       # Custom scripts (per worktree)
-│               ├── pre/
-│               ├── setup/
-│               ├── select/
-│               └── remove/
-│       ├── 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
@@ -594,7 +593,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)
 

package/bun.lock

@@ -24,6 +24,7 @@
         "open": "^11.0.0",
         "ora": "^8.2.0",
         "react": "^19.2.4",
+        "react-dom": "^19.2.4",
         "simple-git": "^3.30.0",
         "ws": "^8.19.0",
       },
@@ -38,10 +39,10 @@
         "typescript": "^5.9.3",
       },
       "optionalDependencies": {
-        "@gitspace/darwin-arm64": "0.2.0-rc.11",
-        "@gitspace/darwin-x64": "0.2.0-rc.11",
-        "@gitspace/linux-arm64": "0.2.0-rc.11",
-        "@gitspace/linux-x64": "0.2.0-rc.11",
+        "@gitspace/darwin-arm64": "0.2.0-rc.12",
+        "@gitspace/darwin-x64": "0.2.0-rc.12",
+        "@gitspace/linux-arm64": "0.2.0-rc.12",
+        "@gitspace/linux-x64": "0.2.0-rc.12",
       },
     },
   },
@@ -62,7 +63,7 @@
 
     "@eslint/js": ["@eslint/js@8.57.1", "", {}, "sha512-d9zaMRSTIKDLhctzH12MtXvJKSSUhaHcjV+2Z+GK+EEY7XKpP5yR4x+N3TAcHTcu963nIr+TMcCb4DBCYX1z6Q=="],
 
-    "@gitspace/darwin-arm64": ["@gitspace/darwin-arm64@0.2.0-rc.11", "", { "os": "darwin", "cpu": "arm64", "bin": { "gssh-darwin-arm64": "bin/gssh" } }, "sha512-MCApLGdB9iScZ/IW1TiUlt+HwdYACfTJxw3m8tShb15IjhrNxn06GvKlTIIq5fR13XkPlPZNuX6/IxO00TVa5A=="],
+    "@gitspace/darwin-arm64": ["@gitspace/darwin-arm64@0.2.0-rc.12", "", { "os": "darwin", "cpu": "arm64", "bin": { "gssh-darwin-arm64": "bin/gssh" } }, "sha512-FUCz7f6EThB1/epRZ+X3SV7wDq/m4mFRDy2AVXGurVK6OWAA+D8tddUYeGmxvYT9+PXEZDATu5ukBh2RKpr5OQ=="],
 
     "@graphql-typed-document-node/core": ["@graphql-typed-document-node/core@3.2.0", "", { "peerDependencies": { "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0" } }, "sha512-mB9oAsNCm9aM3/SOv4YtBMqZbYj10R7dkq8byBqxGY/ncFwhf2oQzMV+LCRlWoDSEBJ3COiR1yeDvMtsoOsuFQ=="],
 
@@ -578,7 +579,7 @@
 
     "react-devtools-core": ["react-devtools-core@7.0.1", "", { "dependencies": { "shell-quote": "^1.6.1", "ws": "^7" } }, "sha512-C3yNvRHaizlpiASzy7b9vbnBGLrhvdhl1CbdU6EnZgxPNbai60szdLtl+VL76UNOt5bOoVTOz5rNWZxgGt+Gsw=="],
 
-    "react-dom": ["react-dom@19.2.3", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.3" } }, "sha512-yELu4WmLPw5Mr/lmeEpox5rw3RETacE++JgHqQzd2dg+YbJuat3jH4ingc+WPZhxaoFzdv9y33G+F7Nl5O0GBg=="],
+    "react-dom": ["react-dom@19.2.4", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.4" } }, "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ=="],
 
     "react-is": ["react-is@17.0.2", "", {}, "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w=="],
 

package/docs/CONNECTION.md

@@ -4,7 +4,7 @@ This document describes how GitSpace handles WebSocket connections, disconnectio
 
 > **Related:** See [PROTOCOL.md](./PROTOCOL.md) for message/frame format, [REMOTE-DESIGN.md](./REMOTE-DESIGN.md) for security model.
 
-> **Implementation Note:** The web client (`src/web/`) currently lacks the
+> **Implementation Note:** The web client tooling (`web/`) currently lacks the
 > auto-reconnection logic described below. While the relay connection has a
 > 15-second heartbeat, neither the relay nor terminal connections implement
 > exponential backoff reconnection. This is a known gap - disconnections

package/docs/REMOTE-DESIGN.md

@@ -293,14 +293,18 @@ Key responsibilities:
 **Role:** User interface, decryption endpoint
 
 ```
-src/web/src/
-├── App.tsx                     # Main application
+web/
+├── index.html                  # Vite entry document
+└── main.tsx                    # Lightweight web entrypoint
+
+src/
+├── app.web.tsx                 # Main web application
 ├── hooks/
-│   ├── useRelayConnection.ts   # WebSocket + machine list
-│   └── useTerminal.ts          # Terminal session management
+│   ├── useRelayConnection.web.ts
+│   └── useTerminal.web.ts
 ├── components/
-│   └── Terminal.tsx            # xterm.js wrapper
-└── lib/crypto/                 # Client-side X3DH + encryption
+│   └── SessionTerminal.web.tsx
+└── session/crypto/             # Client-side X3DH + encryption
 ```
 
 Key responsibilities:
@@ -319,10 +323,11 @@ src/
 ├── commands/connect.ts         # CLI connect command
 ├── tui/
 │   ├── app.tsx                 # TUI application
-│   ├── adapters.ts             # Machine provider adapters
-│   └── hooks/useRemoteMachines.ts
-└── shared/providers/
-    └── RemoteMachineProvider.ts
+│   ├── hooks/useRemoteMachines.ts
+│   └── hooks/useRemoteTerminal.ts
+└── shared/
+    ├── relay/                  # Shared relay directory client/hooks
+    └── session/                # Shared session backends + engine
 ```
 
 ---

package/docs/ROADMAP.md

@@ -159,7 +159,7 @@ VM-per-workspace isolation using Lima. Works on all Apple Silicon (M1/M2/M3+).
 - `src/core/lima/manager.ts` - VM lifecycle (start/stop/status)
 - `src/core/lima/config.ts` - Generate Lima YAML from workspace config
 - `src/core/lima/connection.ts` - Connect to tmux-lite inside VM
-- `src/shared/providers/LimaMachineProvider.ts` - MachineProvider implementation
+- `src/session/backends/lima-session-backend.ts` - Session backend implementation
 
 **Session Lifecycle:**
 1. User selects workspace in TUI

package/docs/SITE_DOCS_FIGMA_MAKE.md

@@ -281,14 +281,15 @@ D) CUSTOM SCRIPTS & BUNDLES
 
 ### Custom Scripts
 
-GitSpace uses convention-based scripts stored per workspace in `.gitspace/`:
+GitSpace uses convention-based scripts stored per workspace in `.gitspace/scripts/`:
 
 ```
 ~/gitspace/<project>/workspaces/<workspace>/.gitspace/
-├── pre/      # Run before setup (once, in terminal)
-├── setup/    # Run on workspace creation (once)
-├── select/   # Run every time workspace is opened
-└── remove/   # Run before workspace deletion
+└── scripts/
+    ├── pre/      # Run before setup (once, in terminal)
+    ├── setup/    # Run on workspace creation (once)
+    ├── select/   # Run every time workspace is opened
+    └── remove/   # Run before workspace deletion
 ```
 
 Script execution rules:
@@ -296,9 +297,9 @@ Script execution rules:
 - Scripts run alphabetically (use `01-`, `02-` prefixes)
 - Working directory: The workspace directory
 - Arguments: `$1` = workspace name, `$2` = repository name
-- Environment: Bundle values available as `SPACE_VALUE_*` and `SPACE_SECRET_*`
+- Environment: Bundle values available by key name (for example `REGION`, `PULUMI_ACCESS_TOKEN`)
 
-Example script (`.gitspace/select/01-status.sh`):
+Example script (`.gitspace/scripts/select/01-status.sh`):
 ```bash
 #!/bin/bash
 WORKSPACE_NAME=$1
@@ -316,10 +317,11 @@ Bundles allow repository owners to share onboarding configurations. Place in `.g
 ```
 .gitspace/
 ├── bundle.json           # Bundle manifest with onboarding steps
-├── pre/                  # Scripts to run before setup
-├── setup/                # Scripts to run on first workspace creation
-├── select/               # Scripts to run every time workspace is opened
-└── remove/               # Scripts to run before workspace deletion
+└── scripts/
+    ├── pre/              # Scripts to run before setup
+    ├── setup/            # Scripts to run on first workspace creation
+    ├── select/           # Scripts to run every time workspace is opened
+    └── remove/           # Scripts to run before workspace deletion
 ```
 
 Bundle manifest example (`bundle.json`):
@@ -375,14 +377,15 @@ Using bundle values in scripts:
 ```bash
 #!/bin/bash
 # Values available as environment variables:
-# SPACE_VALUE_<KEY>   - Regular values from input steps
-# SPACE_SECRET_<KEY>  - Secret values from secret steps (from OS keychain)
+# <KEY>               - Value by bundle config key name
+# SPACE_VALUE_<KEY>   - Legacy alias for regular values
+# SPACE_SECRET_<KEY>  - Legacy alias for secret values
 
-if [ -n "$SPACE_VALUE_TEAMNAME" ]; then
-  echo "Welcome, $SPACE_VALUE_TEAMNAME team!"
+if [ -n "$TEAMNAME" ]; then
+  echo "Welcome, $TEAMNAME team!"
 fi
 
-if [ -n "$SPACE_SECRET_APIKEY" ]; then
+if [ -n "$APIKEY" ]; then
   echo "API Key configured"
 fi
 ```
@@ -465,15 +468,15 @@ Location: `~/gitspace/.identity/`
 │   ├── workspaces/              # Git worktrees
 │   │   └── <workspace-name>/
 │   │       ├── gitspace.lock       # Setup completion marker
-│   │       └── .prompt/         # Linear issue details (if applicable)
-│   │           └── issue.md
-│   └── workspaces/
-│       └── <workspace-name>/
-│           └── .gitspace/       # Custom scripts (per worktree)
-│               ├── pre/
-│               ├── setup/
-│               ├── select/
-│               └── remove/
+│   │       ├── .prompt/         # Linear issue details (if applicable)
+│   │       │   └── issue.md
+│   │       └── .gitspace/
+│   │           ├── bundle.json
+│   │           └── scripts/     # Custom scripts (per worktree)
+│   │               ├── pre/
+│   │               ├── setup/
+│   │               ├── select/
+│   │               └── remove/
 ```
 
 ============================================================
@@ -621,13 +624,13 @@ gssh identity init --label "My Device"
 - Try: `git fetch origin` first
 
 **"Setup scripts failed"**
-- Check script is executable: `chmod +x .gitspace/setup/*.sh`
-- Run manually to see error: `./.gitspace/setup/01-script.sh`
+- Check script is executable: `chmod +x .gitspace/scripts/setup/*.sh`
+- Run manually to see error: `./.gitspace/scripts/setup/01-script.sh`
 - Check environment variables are set
 
 ### Bundle/Secrets Issues
 
-**"SPACE_SECRET_* variables are empty"**
+**"Bundle key variables are empty"**
 1. Ensure you completed onboarding secret steps
 2. Check OS keychain is accessible:
    - macOS: Keychain Access should be running
@@ -893,14 +896,15 @@ gssh status      # Show daemon statuses
 
 SECTION: Local Workflow - Custom Scripts
 
-GitSpace uses convention-based scripts stored per workspace in `.gitspace/`:
+GitSpace uses convention-based scripts stored per workspace in `.gitspace/scripts/`:
 
 ```
 ~/gitspace/<project>/workspaces/<workspace>/.gitspace/
-├── pre/      # Run before setup (once)
-├── setup/    # Run on workspace creation (once)
-├── select/   # Run every time workspace is opened
-└── remove/   # Run before workspace deletion
+└── scripts/
+    ├── pre/      # Run before setup (once)
+    ├── setup/    # Run on workspace creation (once)
+    ├── select/   # Run every time workspace is opened
+    └── remove/   # Run before workspace deletion
 ```
 
 **Rules:**
@@ -912,7 +916,7 @@ GitSpace uses convention-based scripts stored per workspace in `.gitspace/`:
 **Example:**
 ```bash
 #!/bin/bash
-# .gitspace/select/01-status.sh
+# .gitspace/scripts/select/01-status.sh
 echo "Switching to: $1"
 git fetch origin
 git status
@@ -927,9 +931,11 @@ Bundles allow teams to share onboarding configurations. Place in `.gitspace/`:
 ```
 .gitspace/
 ├── bundle.json           # Manifest
-├── pre/                  # Pre-setup scripts
-├── setup/                # Setup scripts
-└── select/               # Select scripts
+└── scripts/
+    ├── pre/              # Pre-setup scripts
+    ├── setup/            # Setup scripts
+    ├── select/           # Select scripts
+    └── remove/           # Remove scripts
 ```
 
 **Manifest example:**
@@ -954,8 +960,8 @@ Bundles allow teams to share onboarding configurations. Place in `.gitspace/`:
 
 **Using values in scripts:**
 ```bash
-echo "Team: $SPACE_VALUE_TEAMNAME"
-echo "Has API key: $SPACE_SECRET_APIKEY"
+echo "Team: $TEAMNAME"
+echo "Has API key: $APIKEY"
 ```
 
 ---