@tangle-network/sandbox-cli 0.2.9 → 0.2.11

package/hub-reference.md

@@ -0,0 +1,401 @@
+# Tangle Hub Reference
+
+## Response Shapes
+
+The CLI `--json` flag prints raw response data. The SDK internally uses envelopes (`{ success: true, data: ... }` / `{ success: false, error: ... }`), but the CLI unwraps the envelope and prints only the `data` or formats the `error`.
+
+**Success output:** raw data object directly (no envelope wrapper).
+**Error output:** `{ error: { code, message, status?, details? } }`.
+
+### Status
+
+```bash
+tangle hub status --json
+```
+
+```json
+{
+  "principal": {
+    "kind": "user_session",
+    "userId": "usr_xxx",
+    "apiKeyId": "key_xxx",
+    "sandboxId": null
+  },
+  "connections": {
+    "connectedProviderCount": 2,
+    "unhealthyProviderCount": 0
+  }
+}
+```
+
+`kind` values: `user_session`, `api_key`, `sandbox_runtime`.
+
+### Connections
+
+```bash
+tangle hub connections --json
+```
+
+```json
+{
+  "connections": [
+    {
+      "id": "conn_abc123",
+      "providerId": "github",
+      "displayName": "GitHub",
+      "accountDisplay": "octocat",
+      "scopes": ["repo", "user:email"],
+      "status": "active",
+      "health": "healthy",
+      "createdAt": "2026-01-15T10:00:00Z",
+      "updatedAt": "2026-01-15T10:00:00Z",
+      "lastUsedAt": "2026-06-10T08:00:00Z"
+    }
+  ]
+}
+```
+
+Connection `status`: `active`, `revoked`, `unhealthy`, `reconnect_required`.
+
+Connection `health`: `unknown`, `healthy`, `unhealthy`, `rate_limited`.
+
+### OAuth Connect
+
+```bash
+tangle hub connect github --json
+```
+
+```json
+{
+  "provider": "github",
+  "redirectUrl": "https://github.com/login/oauth/authorize?client_id=...&scope=repo&state=...",
+  "expiresAt": "2026-06-10T12:30:00Z",
+  "scopes": ["repo", "user:email"],
+  "cli": true
+}
+```
+
+The `state` field is redacted from `--json` output (CSRF protection). The CLI prints the raw redirect URL directly.
+
+### Tool Sources
+
+```bash
+tangle hub tools sources --json
+```
+
+```json
+{
+  "sources": [
+    {
+      "sourceId": "github",
+      "providerId": "github",
+      "displayName": "GitHub",
+      "toolCount": 47,
+      "connectionStatus": "connected",
+      "health": "healthy",
+      "configured": true
+    }
+  ]
+}
+```
+
+Source `connectionStatus`: `connected`, `missing`, `unknown`.
+
+Source `health`: `healthy`, `unhealthy`, `rate_limited`, `unknown`.
+
+### Tool Search
+
+```bash
+tangle hub tools search "github issues" --provider github --json
+```
+
+```json
+{
+  "tools": [
+    {
+      "path": "github.issues.listIssues",
+      "providerId": "github",
+      "title": "List GitHub Issues",
+      "description": "List issues in a repository",
+      "connectionRequired": true,
+      "connectionStatus": "connected",
+      "requiredConnectionProviderId": "github",
+      "policyState": "ask"
+    }
+  ]
+}
+```
+
+Tool `policyState`: `allow`, `ask`, `deny`, `unknown`.
+
+### Tool Describe
+
+```bash
+tangle hub tools describe github.issues.listIssues --json
+```
+
+```json
+{
+  "tool": {
+    "path": "github.issues.listIssues",
+    "providerId": "github",
+    "title": "List GitHub Issues",
+    "description": "List issues in a repository",
+    "connectionRequired": true,
+    "connectionStatus": "connected",
+    "requiredConnectionProviderId": "github",
+    "policyState": "ask",
+    "inputSchema": {
+      "type": "object",
+      "required": ["owner", "repo"],
+      "properties": {
+        "owner": { "type": "string" },
+        "repo": { "type": "string" },
+        "state": { "type": "string", "enum": ["open", "closed", "all"] },
+        "labels": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "outputSchema": {
+      "type": "array",
+      "items": { "$ref": "#/components/schemas/Issue" }
+    }
+  }
+}
+```
+
+### Tool Call / Exec
+
+```bash
+tangle hub call github issues listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}'
+tangle hub exec github.issues.listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}'
+```
+
+```json
+{
+  "result": [
+    {
+      "number": 42,
+      "title": "Fix auth middleware",
+      "state": "open",
+      "createdAt": "2026-06-01T10:00:00Z"
+    }
+  ]
+}
+```
+
+The `result` shape depends on the tool. Always inspect the `outputSchema` first.
+
+### Approvals
+
+```bash
+tangle hub approvals list --json
+```
+
+```json
+{
+  "approvals": [
+    {
+      "id": "app_xxx",
+      "connectionId": "conn_abc123",
+      "providerId": "github",
+      "actionPath": "github.issues.create",
+      "inputHash": "sha256:...",
+      "requesterPrincipal": { "userId": "usr_xxx", "kind": "api_key" },
+      "status": "pending",
+      "requestedAt": "2026-06-10T08:00:00Z",
+      "expiresAt": "2026-06-10T09:00:00Z",
+      "resolvedAt": null
+    }
+  ]
+}
+```
+
+Approval `status`: `pending`, `approved`, `denied`, `expired`, `consumed`.
+
+### Approve / Deny
+
+```bash
+tangle hub approvals approve app_xxx --json
+tangle hub approvals deny app_xxx --json
+```
+
+```json
+{
+  "approval": {
+    "id": "app_xxx",
+    "status": "approved",
+    "connectionId": "conn_abc123",
+    "actionPath": "github.issues.create"
+  },
+  "capabilityToken": {
+    "tokenId": "tok_xxx",
+    "expiresAt": "2026-06-10T08:30:00Z"
+  }
+}
+```
+
+`capabilityToken` is present only on approve. The actual token value is redacted from `--json` output.
+
+### Permissions
+
+```bash
+tangle hub permissions list --connection conn_xxx --json
+```
+
+```json
+{
+  "policies": [
+    {
+      "id": "pol_xxx",
+      "connectionId": "conn_xxx",
+      "providerId": "github",
+      "actionPath": "github.issues.create",
+      "decision": "ask",
+      "createdAt": "2026-06-01T00:00:00Z",
+      "updatedAt": "2026-06-10T00:00:00Z"
+    }
+  ]
+}
+```
+
+`decision` values: `allow`, `ask`, `deny`.
+
+### Permission Set
+
+```bash
+tangle hub permissions set --connection conn_xxx --action github.issues.create --decision allow --json
+```
+
+```json
+{
+  "policy": {
+    "id": "pol_xxx",
+    "connectionId": "conn_xxx",
+    "providerId": "github",
+    "actionPath": "github.issues.create",
+    "decision": "allow",
+    "createdAt": "2026-06-01T00:00:00Z",
+    "updatedAt": "2026-06-10T00:00:00Z"
+  }
+}
+```
+
+## Error Format
+
+```bash
+# Any failing hub command with --json
+tangle hub tools sources --json  # when not authenticated
+```
+
+```json
+{
+  "error": {
+    "code": "HUB_UNAUTHENTICATED",
+    "message": "Authentication required for Hub endpoints",
+    "status": 401
+  }
+}
+```
+
+Error fields:
+- `code`: Hub error code string
+- `message`: Human-readable description
+- `status`: HTTP status code (optional)
+- `details`: Additional context (optional)
+
+## Error Codes
+
+| Code | When it occurs | Recovery |
+|------|----------------|----------|
+| `HUB_UNAUTHENTICATED` | Missing or invalid API key | Check `TANGLE_API_KEY` |
+| `HUB_FORBIDDEN` | Valid auth but no permission | Check connection or team membership |
+| `HUB_INVALID_INPUT` | JSON schema violation | Check `inputSchema` with `tools describe` |
+| `HUB_PROVIDER_MISSING` | Provider not configured | `tangle hub connect <provider>` |
+| `HUB_CONNECTION_MISSING` | No connection for this provider | `tangle hub connect <provider>` |
+| `HUB_CONNECTION_REVOKED` | Connection was revoked | Reconnect via `tangle hub connect` |
+| `HUB_TOKEN_EXPIRED` | Capability token expired | Re-run with `--approve` or mint new token |
+| `HUB_TOKEN_REPLAYED` | Token already consumed | Re-run with `--approve` |
+| `HUB_TOKEN_REVOKED` | Token explicitly revoked | Re-run with `--approve` |
+| `HUB_TOKEN_ACTION_MISMATCH` | Token for different action | Use `--approve` with correct action |
+| `HUB_POLICY_DENIED` | Permission set to `deny` | Change policy via `permissions set` |
+| `HUB_APPROVAL_REQUIRED` | Policy is `ask` and first use | Use `--approve` or `approvals approve` |
+| `HUB_EXECUTOR_FAILURE` | Hub executor error | Retry; check tool health |
+| `HUB_PROVIDER_FAILURE` | Provider API error | Check provider status |
+| `HUB_NOT_FOUND` | Tool or resource not found | Check path spelling |
+| `HUB_NOT_IMPLEMENTED` | Route not yet implemented | Use a different endpoint |
+
+## Workflow Examples
+
+### Connect → Call → Approve
+
+```bash
+# 1. Connect
+tangle hub connect github
+# (follow browser flow)
+
+# 2. Verify
+tangle hub status --json
+
+# 3. Discover
+tangle hub tools sources --json
+tangle hub tools search "issues" --provider github --json
+tangle hub tools describe github.issues.listIssues --json
+
+# 4. Call with auto-approve
+tangle hub exec github.issues.listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}' --approve
+
+# 5. Set permanent policy
+tangle hub permissions set --connection conn_xxx --action github.issues.listIssues --decision allow
+```
+
+### Batch Approvals
+
+```bash
+# List all pending
+tangle hub approvals list --json | jq '.approvals[] | .id'
+
+# Bulk approve
+for id in $(tangle hub approvals list --json | jq -r '.approvals[].id'); do
+  tangle hub approvals approve "$id"
+done
+```
+
+### Policy Audit
+
+```bash
+# Show all policies for one connection
+tangle hub permissions list --connection conn_xxx --json
+
+# Set all read actions to allow, write actions to ask
+tangle hub permissions set --connection conn_xxx --action github.issues.listIssues --decision allow
+tangle hub permissions set --connection conn_xxx --action github.issues.create --decision ask
+```
+
+## GitHub App Primitives
+
+```bash
+# Mint a repo-scoped token (requires GitHub App installation)
+tangle hub github-app mint-installation-token --repo-url https://github.com/owner/repo
+
+# Check if repo is installed
+tangle hub github-app is-repo-installed --owner owner --repo repo
+
+# List installations
+tangle hub github-app installations
+
+# List repos for an installation
+tangle hub github-app repos --installation-id 123456
+```
+
+## Token Management
+
+```bash
+# List minted capability tokens
+tangle hub tokens list --json
+
+# List including expired
+tangle hub tokens list --include-expired --json
+
+# Revoke a token
+tangle hub tokens revoke tok_xxx --json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox-cli",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "CLI for Tangle Sandbox operations",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
   "files": [
     "dist",
     "bin",
-    "SKILL.md"
+    "SKILL.md",
+    "hub-reference.md"
   ],
   "dependencies": {
     "chalk": "^5.4.1",
@@ -19,8 +20,8 @@
     "dotenv": "17.2.3",
     "ora": "^9.4.0",
     "ws": "^8.20.0",
-    "@tangle-network/sandbox": "0.4.4",
-    "@tangle-network/hub-sdk": "0.2.2"
+    "@tangle-network/hub-sdk": "0.2.2",
+    "@tangle-network/sandbox": "0.6.1"
   },
   "devDependencies": {
     "@types/node": "25.6.0",