gitspace 0.2.0-rc.23 → 0.2.0-rc.25

package/README.md

@@ -77,7 +77,7 @@ You can also use traditional CLI commands:
 #### 1. Add Your First Project
 
 ```bash
-gssh add project
+gssh project add
 ```
 
 Select a GitHub repository, and GitSpace will:
@@ -90,20 +90,20 @@ Select a GitHub repository, and GitSpace will:
 
 ```bash
 # Create a workspace from a Linear issue (if configured)
-gssh add
+gssh workspace add --project my-project
 
 # Or create a workspace with a custom name
-gssh add my-feature
+gssh workspace add my-feature --project my-project
 ```
 
-#### 3. Switch Between Workspaces
+#### 3. Target a Workspace
 
 ```bash
-# Interactive selection
-gssh switch
+# List workspaces in a project
+gssh workspace list --project <project-name>
 
-# Switch to a specific workspace
-gssh switch my-feature
+# Show context for a specific workspace
+gssh workspace context --project my-project --workspace my-feature
 ```
 
 ### Workspace Session Mode (`space`)
@@ -112,7 +112,7 @@ When GitSpace opens a workspace-scoped terminal session, it injects a `space` sh
 
 - 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
+- `gssh machine tmux ...` is blocked inside workspace sessions
 
 Examples:
 
@@ -226,8 +226,8 @@ fi
 Bundles can be loaded from:
 
 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`
+2. **Local path**: `gssh project add --bundle-path /path/to/bundle/`
+3. **Remote URL**: `gssh project add --bundle-url https://example.com/bundle.zip`
 
 ## Commands Reference
 
@@ -235,12 +235,12 @@ Bundles can be loaded from:
 
 Launch the interactive terminal UI.
 
-### `gssh add project`
+### `gssh project add`
 
 Add a new project from GitHub.
 
 ```bash
-gssh add project [options]
+gssh project add [options]
 
 Options:
   --bundle-url <url>     Load bundle from remote URL (zip archive)
@@ -251,12 +251,12 @@ Options:
   --linear-key <key>     Provide Linear API key via flag
 ```
 
-### `gssh add [workspace-name]`
+### `gssh workspace add [workspace-name] --project <project-name>`
 
 Create a new workspace in the current project.
 
 ```bash
-gssh add [workspace-name] [options]
+gssh workspace add [workspace-name] --project <project-name> [options]
 
 Options:
   --branch <name>        Specify different branch name from workspace name
@@ -264,70 +264,52 @@ Options:
   --no-setup             Skip setup commands
 ```
 
-### `gssh switch [workspace-name]`
+### `gssh workspace context --project <project-name> --workspace <workspace-name>`
 
-Switch to a workspace in the current project.
+Show the resolved workspace context.
 
 ```bash
-gssh switch [workspace-name]
-# Alias: gssh sw
+gssh workspace context --project <project-name> --workspace <workspace-name>
 ```
 
-### `gssh switch project [project-name]`
+Use `--project` on workspace commands to target a project.
 
-Switch to a different project.
-
-### `gssh list [subcommand]`
+### `gssh project list` / `gssh workspace list --project <project-name>`
 
 List projects or workspaces.
 
 ```bash
-gssh list [subcommand] [options]
-# Alias: gssh ls
-
-Subcommands:
-  projects               List all projects
-  workspaces             List workspaces in current project (default)
+gssh project list [options]
+gssh workspace list --project <project-name> [options]
 
 Options:
   --json                 Output in JSON format
   --verbose              Show additional details
 ```
 
-### `gssh remove workspace [workspace-name]`
+### `gssh workspace remove [workspace-name] --project <project-name>`
 
 Remove a workspace.
 
 ```bash
-gssh remove workspace [workspace-name] [options]
-# Alias: gssh rm workspace
+gssh workspace remove [workspace-name] --project <project-name> [options]
 
 Options:
   --force                Skip confirmation prompts
   --keep-branch          Don't delete git branch when removing workspace
 ```
 
-### `gssh remove project [project-name]`
+### `gssh project remove [project-name]`
 
 Remove a project.
 
 ```bash
-gssh remove project [project-name] [options]
-# Alias: gssh rm project
+gssh project remove [project-name] [options]
 
 Options:
   --force                Skip confirmation prompts
 ```
 
-### `gssh directory`
-
-Print the current project directory path.
-
-```bash
-gssh directory
-# Alias: gssh dir
-```
-
 ## Configuration
 
 ### Global Configuration
@@ -405,9 +387,6 @@ inside each workspace so they can vary by branch:
 ### Environment Variables
 
 ```bash
-# Set the current project (overrides global config)
-export SPACES_CURRENT_PROJECT="my-app"
-
 # Available in scripts (from bundle onboarding):
 # <KEY>                - Value by exact bundle config key name
 # <NORMALIZED_KEY>     - Uppercase snake-case alias (e.g. teamName -> TEAM_NAME)
@@ -444,18 +423,27 @@ GitSpace provides secure remote terminal access with **end-to-end encryption**.
 The easiest way to get remote access is through [gitspace.sh](https://gitspace.sh):
 
 ```bash
-# 1. Authenticate with GitHub
-gssh auth login
+# 1. Initialize machine identity on your control host
+gssh user identity init
+gssh user identity show
+
+# 2. Authenticate with gitspace.sh
+gssh user auth login
 
-# 2. Reserve your subdomain (e.g., yourname.gitspace.sh)
-gssh host reserve yourname
+# 3. Reserve your subdomain (e.g., yourname.gitspace.sh)
+gssh user host reserve yourname
+gssh user host status
 
-# 3. Start serving (creates identity if needed)
-gssh serve
+# 4. Start serving
+gssh machine serve start
+gssh machine serve status
+gssh status
 
-# 4. Access from browser at https://yourname.gitspace.sh
+# 5. Access from browser at https://yourname.gitspace.sh
 ```
 
+In hosted mode, this machine is your control node (owner): it runs the relay path, maintains access state, and is the place cloud-control state/secrets are managed.
+
 ### Self-Hosted Setup
 
 For complete control, run your own relay:
@@ -464,14 +452,13 @@ For complete control, run your own relay:
 # Terminal 1: Start relay server
 gssh relay start --port 4480
 
-# Terminal 2: Initialize identity and start serving
-gssh identity init --label "My MacBook"
-gssh serve --relay ws://localhost:4480/ws
-
-# Terminal 3: Create invite for remote access
-gssh share create
+# Terminal 2: Create relay-machine invite token
+gssh invite relay-machine create --relay ws://localhost:4480/ws --machine-signing-key <BASE64_ED25519_PUB> --machine-key-exchange-key <BASE64_X25519_PUB> --label "My MacBook"
 
-# Share the invite URL with collaborators
+# Terminal 3: Initialize identity, enroll, and start serving
+gssh user identity init
+gssh machine enroll --invite "ws://localhost:4480/ws#<TOKEN>" --label "My MacBook"
+gssh machine serve start --relay ws://localhost:4480/ws
 ```
 
 ### Identity Management
@@ -479,68 +466,67 @@ gssh share create
 Every machine and client has a cryptographic identity (Ed25519 + X25519 keypair):
 
 ```bash
-# Create machine identity (stored in ~/gitspace/.identity/)
-gssh identity init --label "My MacBook"
+# Create machine identity (stored in OS keychain)
+gssh user identity init
 
 # View identity fingerprint
-gssh identity show
+gssh user identity show
 ```
 
-### Access Control
-
-Control who can connect to your machine:
-
-```bash
-# List authorized clients
-gssh access list
+### Owner Access Model
 
-# Add a client by public key
-gssh access add spcs_pk_abc123... --label "Work Laptop"
+Remote access is owner-only at runtime.
 
-# Remove client access
-gssh access remove spcs_pk_abc123...
-```
+- Clients and machines must present device certificates derived from the same owner user root identity.
+- There is no collaborator ACL grant path for relay or machine access.
 
 ### Creating Invites
 
-Share access via signed invite tokens:
+Use root-signed invites for machine enrollment only:
 
 ```bash
-# Create invite (24h default)
-gssh share create
+# Create machine enrollment invite token
+gssh invite relay-machine create --relay ws://localhost:4480/ws --machine-signing-key <BASE64_ED25519_PUB> --machine-key-exchange-key <BASE64_X25519_PUB>
 
-# Custom expiration
-gssh share create --expires 7d
+# List/revoke enrollment invites
+gssh invite list --relay ws://localhost:4480/ws
+gssh invite revoke <invite-id> --relay ws://localhost:4480/ws
 ```
 
 ### Connecting Remotely
 
 ```bash
-# Connect using invite token
-gssh connect <invite-token>
+# On another owner device: recover the same user root identity
+gssh user identity recover
 
-# Connect via TUI with relay
-gssh --relay wss://relay.example.com
+# Connect directly as owner
+gssh client connect <machine-id>
+
+# Browse machines on a relay
+gssh client machines list --relay wss://relay.example.com
 ```
 
 ### Remote Access Commands
 
 | Command | Description |
 |---------|-------------|
-| `gssh auth login` | Authenticate with gitspace.sh (GitHub OAuth) |
-| `gssh auth logout` | Sign out of gitspace.sh |
-| `gssh host reserve <name>` | Reserve a subdomain on gitspace.sh |
-| `gssh host status` | Show hosting status |
-| `gssh identity init` | Create machine/client identity |
-| `gssh identity show` | Display identity fingerprint |
-| `gssh access add <key>` | Authorize a client |
-| `gssh access list` | List authorized clients |
-| `gssh access remove <key>` | Revoke client access |
-| `gssh serve` | Start machine daemon |
-| `gssh serve start` | Start serve as background daemon |
-| `gssh serve stop` | Stop background serve daemon |
-| `gssh share create` | Create invite token |
-| `gssh connect <token>` | Connect to remote machine |
+| `gssh user auth login` | Authenticate with gitspace.sh (GitHub OAuth) |
+| `gssh user auth logout` | Sign out of gitspace.sh |
+| `gssh user host reserve <name>` | Reserve a subdomain on gitspace.sh |
+| `gssh user host status` | Show hosting status |
+| `gssh user identity init` | Create user root identity |
+| `gssh user identity recover` | Recover identity from mnemonic |
+| `gssh user identity show` | Display identity fingerprint |
+| `gssh machine serve start --foreground` | Start machine daemon |
+| `gssh machine serve start` | Start serve as background daemon |
+| `gssh machine serve stop` | Stop background serve daemon |
+| `gssh cloud status` | Show cloud control status on current control node |
+| `gssh cloud list` | List cloud workspaces from control store |
+| `gssh invite relay-machine create --relay <url> --machine-signing-key <k> --machine-key-exchange-key <k>` | Create machine enrollment invite |
+| `gssh invite list --relay <url>` | List root-signed invites |
+| `gssh invite revoke <invite-id> --relay <url>` | Revoke root-signed invite |
+| `gssh client connect <target>` | Connect to remote machine |
+| `gssh client machines list --relay <url>` | List accessible remote machines |
 | `gssh status` | Show all daemon statuses |
 
 ### Relay Server Commands
@@ -550,11 +536,9 @@ For self-hosted relay servers:
 | Command | Description |
 |---------|-------------|
 | `gssh relay start` | Start relay server |
-| `gssh relay authorize <key>` | Authorize a machine |
-| `gssh relay revoke <key>` | Revoke machine authorization |
-| `gssh relay machines` | List registered machines |
-| `gssh relay trusted` | List trusted relays |
-| `gssh relay untrust <url>` | Remove relay trust |
+| `gssh invite relay-machine create --relay <url> --machine-signing-key <k> --machine-key-exchange-key <k>` | Create machine enrollment invite |
+| `gssh relay machines list` | List registered machines |
+| `gssh relay machines revoke <machine-id>` | Revoke machine registration |
 
 ### Terminal Multiplexer (tmux-lite)
 
@@ -562,12 +546,12 @@ Manage terminal sessions:
 
 | Command | Description |
 |---------|-------------|
-| `gssh tmux start` | Start tmux-lite daemon |
-| `gssh tmux stop` | Stop tmux-lite daemon |
-| `gssh tmux list` | List sessions |
-| `gssh tmux attach <id>` | Attach to session |
-| `gssh tmux new` | Create new session |
-| `gssh tmux kill <id>` | Kill session |
+| `gssh machine tmux start` | Start tmux-lite daemon |
+| `gssh machine tmux stop` | Stop tmux-lite daemon |
+| `gssh machine tmux list` | List sessions |
+| `gssh machine tmux attach <id>` | Attach to session |
+| `gssh machine tmux new` | Create new session |
+| `gssh machine tmux kill <id>` | Kill session |
 
 ### Environment Variables
 
@@ -576,9 +560,6 @@ Manage terminal sessions:
 RELAY_PORT=4480              # Default relay port
 RELAY_BIND=0.0.0.0           # Bind address
 
-# Machine identity
-GSSH_IDENTITY_PATH=~/gitspace/.identity/  # Identity storage
-
 # gitspace.sh
 GITSPACE_API_URL=https://api.gitspace.sh   # API endpoint
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitspace",
-  "version": "0.2.0-rc.23",
+  "version": "0.2.0-rc.25",
   "description": "CLI for managing GitHub workspaces with git worktrees and secure remote terminal access",
   "bin": {
     "gssh": "./bin/gssh"
@@ -19,13 +19,14 @@
     "build": "bun scripts/build.ts",
     "build:all": "bun scripts/build.ts --all",
     "build:npm": "bun scripts/build.ts --npm",
-    "relay": "bun src/relay/index.ts"
+    "relay": "bun src/relay/index.ts",
+    "e2e:on-demand": "bash scripts/e2e/run-on-demand.sh"
   },
   "optionalDependencies": {
-    "@gitspace/darwin-arm64": "0.2.0-rc.23",
-    "@gitspace/darwin-x64": "0.2.0-rc.23",
-    "@gitspace/linux-x64": "0.2.0-rc.23",
-    "@gitspace/linux-arm64": "0.2.0-rc.23"
+    "@gitspace/darwin-arm64": "0.2.0-rc.25",
+    "@gitspace/darwin-x64": "0.2.0-rc.25",
+    "@gitspace/linux-x64": "0.2.0-rc.25",
+    "@gitspace/linux-arm64": "0.2.0-rc.25"
   },
   "keywords": [
     "cli",
@@ -45,6 +46,7 @@
   "author": "inKibra, Inc.",
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
+    "@fly/sprites": "0.0.1-rc37",
     "@inquirer/prompts": "^7.10.1",
     "@linear/sdk": "^29.0.0",
     "@noble/curves": "^2.0.1",
@@ -52,6 +54,7 @@
     "@opentui-ui/toast": "^0.0.5",
     "@opentui/core": "^0.1.77",
     "@opentui/react": "^0.1.77",
+    "@scure/bip39": "^2.0.1",
     "@types/ws": "^8.18.1",
     "@xterm/addon-serialize": "^0.13.0",
     "@xterm/headless": "^5.5.0",