@sandbaseai/cli 0.1.11 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,179 @@
1
+ export declare const clientCatalog: readonly [{
2
+ readonly id: "codex";
3
+ readonly label: "Codex";
4
+ readonly delivery: "adapter";
5
+ readonly autoEligible: true;
6
+ readonly localAuthorization: true;
7
+ readonly installScriptEligible: true;
8
+ }, {
9
+ readonly id: "claude-code";
10
+ readonly label: "Claude Code";
11
+ readonly delivery: "adapter";
12
+ readonly autoEligible: true;
13
+ readonly localAuthorization: true;
14
+ readonly installScriptEligible: true;
15
+ }, {
16
+ readonly id: "cursor";
17
+ readonly label: "Cursor";
18
+ readonly delivery: "adapter";
19
+ readonly autoEligible: true;
20
+ readonly localAuthorization: true;
21
+ readonly installScriptEligible: true;
22
+ }, {
23
+ readonly id: "windsurf";
24
+ readonly label: "Windsurf";
25
+ readonly delivery: "adapter";
26
+ readonly autoEligible: true;
27
+ readonly localAuthorization: true;
28
+ readonly installScriptEligible: true;
29
+ }, {
30
+ readonly id: "gemini-cli";
31
+ readonly label: "Gemini CLI";
32
+ readonly delivery: "adapter";
33
+ readonly autoEligible: true;
34
+ readonly localAuthorization: true;
35
+ readonly installScriptEligible: true;
36
+ }, {
37
+ readonly id: "opencode";
38
+ readonly label: "OpenCode";
39
+ readonly delivery: "adapter";
40
+ readonly autoEligible: true;
41
+ readonly localAuthorization: true;
42
+ readonly installScriptEligible: true;
43
+ }, {
44
+ readonly id: "hermes";
45
+ readonly label: "Hermes";
46
+ readonly delivery: "adapter";
47
+ readonly autoEligible: true;
48
+ readonly localAuthorization: true;
49
+ readonly installScriptEligible: true;
50
+ }, {
51
+ readonly id: "openclaw";
52
+ readonly label: "OpenClaw";
53
+ readonly delivery: "adapter";
54
+ readonly autoEligible: true;
55
+ readonly localAuthorization: true;
56
+ readonly installScriptEligible: true;
57
+ }, {
58
+ readonly id: "cursor-cli";
59
+ readonly label: "Cursor CLI";
60
+ readonly delivery: "adapter";
61
+ readonly autoEligible: true;
62
+ readonly localAuthorization: true;
63
+ readonly installScriptEligible: true;
64
+ }, {
65
+ readonly id: "warp";
66
+ readonly label: "Warp";
67
+ readonly delivery: "adapter";
68
+ readonly autoEligible: true;
69
+ readonly localAuthorization: true;
70
+ readonly installScriptEligible: true;
71
+ }, {
72
+ readonly id: "kimi-cli";
73
+ readonly label: "Kimi CLI";
74
+ readonly delivery: "adapter";
75
+ readonly autoEligible: true;
76
+ readonly localAuthorization: true;
77
+ readonly installScriptEligible: true;
78
+ }, {
79
+ readonly id: "qwen-code";
80
+ readonly label: "Qwen Code";
81
+ readonly delivery: "adapter";
82
+ readonly autoEligible: true;
83
+ readonly localAuthorization: true;
84
+ readonly installScriptEligible: true;
85
+ }, {
86
+ readonly id: "kiro";
87
+ readonly label: "Kiro IDE";
88
+ readonly delivery: "adapter";
89
+ readonly autoEligible: true;
90
+ readonly localAuthorization: true;
91
+ readonly installScriptEligible: true;
92
+ }, {
93
+ readonly id: "kiro-cli";
94
+ readonly label: "Kiro CLI";
95
+ readonly delivery: "adapter";
96
+ readonly autoEligible: true;
97
+ readonly localAuthorization: true;
98
+ readonly installScriptEligible: true;
99
+ }, {
100
+ readonly id: "amp";
101
+ readonly label: "Amp";
102
+ readonly delivery: "adapter";
103
+ readonly autoEligible: true;
104
+ readonly localAuthorization: true;
105
+ readonly installScriptEligible: true;
106
+ }, {
107
+ readonly id: "crush";
108
+ readonly label: "Crush";
109
+ readonly delivery: "adapter";
110
+ readonly autoEligible: true;
111
+ readonly localAuthorization: true;
112
+ readonly installScriptEligible: true;
113
+ }, {
114
+ readonly id: "iflow-cli";
115
+ readonly label: "iFlow CLI (legacy)";
116
+ readonly delivery: "adapter";
117
+ readonly autoEligible: true;
118
+ readonly localAuthorization: true;
119
+ readonly installScriptEligible: true;
120
+ }, {
121
+ readonly id: "antigravity";
122
+ readonly label: "Antigravity";
123
+ readonly delivery: "prompt";
124
+ readonly autoEligible: false;
125
+ readonly localAuthorization: true;
126
+ readonly installScriptEligible: true;
127
+ }, {
128
+ readonly id: "trae";
129
+ readonly label: "Trae";
130
+ readonly delivery: "prompt";
131
+ readonly autoEligible: false;
132
+ readonly localAuthorization: true;
133
+ readonly installScriptEligible: true;
134
+ }, {
135
+ readonly id: "qoder";
136
+ readonly label: "Qoder";
137
+ readonly delivery: "prompt";
138
+ readonly autoEligible: false;
139
+ readonly localAuthorization: true;
140
+ readonly installScriptEligible: true;
141
+ }, {
142
+ readonly id: "workbuddy";
143
+ readonly label: "WorkBuddy";
144
+ readonly delivery: "prompt";
145
+ readonly autoEligible: false;
146
+ readonly localAuthorization: true;
147
+ readonly installScriptEligible: true;
148
+ }, {
149
+ readonly id: "pi";
150
+ readonly label: "Pi";
151
+ readonly delivery: "prompt";
152
+ readonly autoEligible: false;
153
+ readonly localAuthorization: true;
154
+ readonly installScriptEligible: true;
155
+ }, {
156
+ readonly id: "claude-desktop";
157
+ readonly label: "Claude Desktop";
158
+ readonly delivery: "desktop_import";
159
+ readonly autoEligible: false;
160
+ readonly localAuthorization: true;
161
+ readonly installScriptEligible: true;
162
+ }, {
163
+ readonly id: "cowork";
164
+ readonly label: "Cowork";
165
+ readonly delivery: "desktop_import";
166
+ readonly autoEligible: false;
167
+ readonly localAuthorization: true;
168
+ readonly installScriptEligible: true;
169
+ }, {
170
+ readonly id: "chatgpt";
171
+ readonly label: "ChatGPT";
172
+ readonly delivery: "remote_workspace";
173
+ readonly autoEligible: false;
174
+ readonly localAuthorization: true;
175
+ readonly installScriptEligible: true;
176
+ }];
177
+ export type ClientCatalogEntry = (typeof clientCatalog)[number];
178
+ export type CatalogClient = ClientCatalogEntry["id"];
179
+ export declare function stableCatalog(): string;
@@ -0,0 +1,30 @@
1
+ export const clientCatalog = [
2
+ { id: "codex", label: "Codex", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
3
+ { id: "claude-code", label: "Claude Code", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
4
+ { id: "cursor", label: "Cursor", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
5
+ { id: "windsurf", label: "Windsurf", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
6
+ { id: "gemini-cli", label: "Gemini CLI", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
7
+ { id: "opencode", label: "OpenCode", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
8
+ { id: "hermes", label: "Hermes", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
9
+ { id: "openclaw", label: "OpenClaw", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
10
+ { id: "cursor-cli", label: "Cursor CLI", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
11
+ { id: "warp", label: "Warp", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
12
+ { id: "kimi-cli", label: "Kimi CLI", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
13
+ { id: "qwen-code", label: "Qwen Code", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
14
+ { id: "kiro", label: "Kiro IDE", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
15
+ { id: "kiro-cli", label: "Kiro CLI", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
16
+ { id: "amp", label: "Amp", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
17
+ { id: "crush", label: "Crush", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
18
+ { id: "iflow-cli", label: "iFlow CLI (legacy)", delivery: "adapter", autoEligible: true, localAuthorization: true, installScriptEligible: true },
19
+ { id: "antigravity", label: "Antigravity", delivery: "prompt", autoEligible: false, localAuthorization: true, installScriptEligible: true },
20
+ { id: "trae", label: "Trae", delivery: "prompt", autoEligible: false, localAuthorization: true, installScriptEligible: true },
21
+ { id: "qoder", label: "Qoder", delivery: "prompt", autoEligible: false, localAuthorization: true, installScriptEligible: true },
22
+ { id: "workbuddy", label: "WorkBuddy", delivery: "prompt", autoEligible: false, localAuthorization: true, installScriptEligible: true },
23
+ { id: "pi", label: "Pi", delivery: "prompt", autoEligible: false, localAuthorization: true, installScriptEligible: true },
24
+ { id: "claude-desktop", label: "Claude Desktop", delivery: "desktop_import", autoEligible: false, localAuthorization: true, installScriptEligible: true },
25
+ { id: "cowork", label: "Cowork", delivery: "desktop_import", autoEligible: false, localAuthorization: true, installScriptEligible: true },
26
+ { id: "chatgpt", label: "ChatGPT", delivery: "remote_workspace", autoEligible: false, localAuthorization: true, installScriptEligible: true },
27
+ ];
28
+ export function stableCatalog() {
29
+ return JSON.stringify({ schemaVersion: 1, clients: clientCatalog }, null, 2) + "\n";
30
+ }
package/dist/cli.js CHANGED
@@ -2,6 +2,7 @@
2
2
  import { connect, doctor, unregister } from "./commands.js";
3
3
  import { clientList } from "./clients.js";
4
4
  import { bridgeClients, isBridgeClient, isClient } from "./types.js";
5
+ import { stableCatalog } from "./catalog.js";
5
6
  if (Number(process.versions.node.split(".")[0]) < 20) {
6
7
  console.error("SandBase CLI requires Node.js 20 or newer. Upgrade Node.js and retry.");
7
8
  process.exit(1);
@@ -11,7 +12,13 @@ const at = args.indexOf("--client");
11
12
  const value = at >= 0 ? args[at + 1] : undefined;
12
13
  const client = value === undefined || value === "auto" ? "auto" : isClient(value) ? value : undefined;
13
14
  const bridgeClient = value !== undefined && isBridgeClient(value) ? value : undefined;
14
- if (command === "mcp-bridge") {
15
+ if (command === "catalog") {
16
+ if (args.length !== 1 || args[0] !== "--json") {
17
+ console.error("Usage: sandbase catalog --json");
18
+ process.exit(2);
19
+ }
20
+ }
21
+ else if (command === "mcp-bridge") {
15
22
  if (!bridgeClient || at !== 0 || args.length !== 2) {
16
23
  console.error(`Usage: sandbase mcp-bridge --client <${bridgeClients.join("|")}>`);
17
24
  process.exit(2);
@@ -27,7 +34,9 @@ const abort = () => controller.abort();
27
34
  for (const signal of signals)
28
35
  process.once(signal, abort);
29
36
  try {
30
- if (command === "mcp-bridge") {
37
+ if (command === "catalog")
38
+ process.stdout.write(stableCatalog());
39
+ else if (command === "mcp-bridge") {
31
40
  const runtime = await import(new URL("../assets/mcp-bridge.mjs", import.meta.url).href);
32
41
  await runtime.runMCPBridge({ client: bridgeClient, signal: controller.signal });
33
42
  }
package/dist/clients.js CHANGED
@@ -41,7 +41,7 @@ export const nativeCapabilities = {
41
41
  "qwen-code": { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Qwen Code", "Restart Qwen Code, open /mcp, and inspect SandBase settings/tools.", "The user-scope SandBase server is present in /mcp and settings readback."), uninstall: "managed_only", terminal: "action_required" },
42
42
  windsurf: { mcpMode: "auto", skillMode: "none", invocation: "desktop_ui", verification: "read_only_probe", guide: guide("Windsurf", "Restart Windsurf and inspect Cascade MCP Servers.", "The SandBase remote server and tools are visible."), uninstall: "managed_only", terminal: "action_required" },
43
43
  opencode: { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("OpenCode", "Restart OpenCode and inspect its MCP server list.", "opencode2 mcp list reads back SandBase."), uninstall: "managed_only", terminal: "action_required" },
44
- chatgpt: { mcpMode: "manual", skillMode: "none", invocation: "none", verification: "user_action", guide: guide("ChatGPT", "No verified safe personal/workspace MCP import path is available.", "Do not add unverified configuration."), uninstall: "managed_only", terminal: "unsupported" },
44
+ chatgpt: { mcpMode: "manual", skillMode: "none", invocation: "desktop_ui", verification: "user_action", guide: guide("ChatGPT", "After SandBase authorization and local bridge preparation, use an eligible Business, Enterprise, or Edu workspace: enable Developer Mode, create the SandBase App, Scan Tools, and have an administrator publish it.", "In a fresh ChatGPT conversation, read back the published SandBase tools and complete one safe call; this CLI never writes ChatGPT configuration."), uninstall: "managed_only", terminal: "action_required" },
45
45
  warp: { mcpMode: "auto", skillMode: "none", invocation: "desktop_ui", verification: "read_only_probe", guide: guide("Warp", "Approve the managed server with /agent-add-mcp, then inspect Warp's MCP server and tool readback.", "The owned user entry is present and Warp lists SandBase tools without a project override."), uninstall: "managed_only", terminal: "action_required" },
46
46
  trae: { mcpMode: "none", skillMode: "prompt", invocation: "prompt", verification: "user_action", guide: guide("Trae", "Paste a SandBase MCP usage prompt into the client after configuring its supported integration.", "The client confirms the prompt or tool availability."), uninstall: "managed_only", terminal: "action_required" },
47
47
  "kimi-cli": { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Kimi CLI", "Restart Kimi and inspect its persistent MCP list/test output.", "kimi mcp list/test read back SandBase tools."), uninstall: "managed_only", terminal: "action_required" },
@@ -78,9 +78,15 @@ function v2(client, capability) {
78
78
  crush: { source: "https://github.com/charmbracelet/crush/blob/main/schema.json", retrieved: "2026-07-30", conclusion: "Crush supports a global top-level mcp stdio schema with project precedence; SandBase writes only static argv and never shell expansion.", kind: "first_party" },
79
79
  "iflow-cli": { source: "https://github.com/iflow-ai/iflow-cli/blob/main/docs_en/examples/mcp.md", retrieved: "2026-07-30", conclusion: "The discontinued iFlow CLI exposes user-scope add-json/get/list/remove for existing legacy installations; vendor maintenance and service availability are not claimed.", kind: "first_party" },
80
80
  warp: { source: "https://docs.warp.dev/agent-platform/capabilities/mcp/", retrieved: "2026-07-30", conclusion: "Warp supports user-level ~/.warp/.mcp.json command servers and explicit /agent-add-mcp approval/readback.", kind: "first_party" },
81
+ chatgpt: { source: "https://platform.openai.com/docs/mcp", retrieved: "2026-07-31", conclusion: "ChatGPT remote Apps require product-side Developer Mode, app creation, tool scanning, publication, and verification; SandBase CLI only prepares its owned credential and bridge.", kind: "first_party" },
82
+ antigravity: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
83
+ trae: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
84
+ qoder: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
85
+ workbuddy: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
86
+ pi: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
81
87
  };
82
- const implemented = client === "codex" || client === "claude-code" || client === "cursor" || client === "hermes" || client === "openclaw" || client === "claude-desktop" || client === "cowork" || client === "opencode" || client === "qwen-code" || client === "windsurf" || client === "gemini-cli" || client === "cursor-cli" || client === "kimi-cli" || client === "kiro" || client === "kiro-cli" || client === "amp" || client === "crush" || client === "iflow-cli" || client === "warp";
83
- const blocker = client === "cursor-cli" ? "Cursor CLI MCP installation is blocked until an independent first-party schema is recorded; desktop Cursor configuration must not be reused." : "This client batch has no completed installer and validator in the current iteration.";
88
+ const implemented = true;
89
+ const blocker = "This client batch has no completed installer and validator in the current iteration.";
84
90
  if (!implemented)
85
91
  return {
86
92
  evidence: { source: "docs/design/features/REQ-20260728-e4a8c1b9d2f0-all-agent-native-capabilities/design.md#2.1", retrieved: "2026-07-29", conclusion: blocker, kind: "internal_blocker" },
@@ -91,8 +97,8 @@ function v2(client, capability) {
91
97
  const skillInstaller = !hasSkill ? "none" : desktop ? "confirmation" : client === "claude-code" || client === "hermes" ? "private" : "shared";
92
98
  const skillValidator = !hasSkill ? "none" : desktop || client === "cursor" || client === "claude-code" || client === "hermes" || client === "openclaw" ? "real_client_matrix" : "ownership_checksum";
93
99
  return {
94
- evidence: evidence[client], installer: { mcp: desktop ? "confirmation" : "adapter", skill: skillInstaller },
95
- validator: { mcp: "read_back", skill: skillValidator }, implementation: "implemented", status: "confirmation_required",
100
+ evidence: evidence[client], installer: { mcp: desktop || client === "chatgpt" ? "confirmation" : "adapter", skill: skillInstaller },
101
+ validator: { mcp: client === "chatgpt" ? "confirmation" : "read_back", skill: skillValidator }, implementation: "implemented", status: "confirmation_required",
96
102
  nextStep: capability.guide,
97
103
  };
98
104
  }
package/dist/commands.js CHANGED
@@ -18,6 +18,7 @@ import { desktopIdentityPath, isDesktopClient, readDesktopIdentity, removeDeskto
18
18
  import { claudeDesktopArtifactPath, readClaudeDesktopArtifactState, removeClaudeDesktopArtifacts, rollbackClaudeDesktopArtifacts } from "./claude-desktop.js";
19
19
  import { coworkStatePath, readCoworkState, removeCoworkState, rollbackCoworkState } from "./cowork.js";
20
20
  import { atomicWrite, readOptional, restore } from "./fs-safe.js";
21
+ import { configPath } from "./paths.js";
21
22
  const sleep = (ms, signal) => new Promise((resolve, reject) => { const t = setTimeout(resolve, ms); signal?.addEventListener("abort", () => { clearTimeout(t); reject(new Error("Authorization cancelled")); }, { once: true }); });
22
23
  async function compensate(api, authorizationId, token) { for (const delay of [0, 250, 750]) {
23
24
  if (delay)
@@ -30,14 +31,52 @@ async function compensate(api, authorizationId, token) { for (const delay of [0,
30
31
  } return false; }
31
32
  export async function openBrowser(url) { const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open"; const args = platform() === "win32" ? ["/c", "start", "", url] : [url]; const child = spawn(cmd, args, { detached: true, stdio: "ignore" }); child.unref(); }
32
33
  function mcpServerSnippet(client, bridgePath) { return JSON.stringify({ mcpServers: { sandbase: { command: "node", args: [bridgePath, "--client", client] } } }, null, 2); }
33
- function promptAssistedLauncher(client) { return JSON.stringify({ command: "npx", args: ["-y", "@sandbaseai/cli", "mcp-bridge", "--client", client] }, null, 2); }
34
+ function promptAssistedLauncher(client, bridge) { return JSON.stringify({ command: "node", args: [bridge, "--client", client] }, null, 2); }
35
+ const sharedSlotPairs = [["cursor", "cursor-cli"], ["kiro", "kiro-cli"]];
36
+ async function sharedSlotOwner(client) {
37
+ const pair = sharedSlotPairs.find(item => item.includes(client));
38
+ if (!pair)
39
+ return undefined;
40
+ const raw = await readOptional(configPath(client));
41
+ if (!raw)
42
+ return undefined;
43
+ try {
44
+ const value = JSON.parse(raw).mcpServers?.sandbase;
45
+ if (!value)
46
+ return undefined;
47
+ if (Array.isArray(value.args) && value.args.length === 3 && value.args[1] === "--client" && typeof value.args[2] === "string")
48
+ return pair.includes(value.args[2]) ? value.args[2] : undefined;
49
+ if (typeof value.command === "string") {
50
+ const match = /(?:^|\s)--client\s+(cursor-cli|cursor|kiro-cli|kiro)(?=\s|$)/.exec(value.command);
51
+ return match?.[1] && pair.includes(match[1]) ? match[1] : undefined;
52
+ }
53
+ return undefined;
54
+ }
55
+ catch {
56
+ return undefined;
57
+ }
58
+ }
59
+ async function assertSharedSlotAvailable(client) { const pair = sharedSlotPairs.find(item => item.includes(client)); if (!pair)
60
+ return; const owner = await sharedSlotOwner(client); if (owner && owner !== client)
61
+ throw new Error(`${client} shares one SandBase configuration slot with ${owner}, which currently owns it. Run sandbase unregister --client ${owner}, then retry ${client}; authorization was not started.`); }
62
+ async function resolveAutoSharedSlots(targets, log) { const selected = [...targets]; for (const pair of sharedSlotPairs) {
63
+ if (!pair.every(client => selected.includes(client)))
64
+ continue;
65
+ const owner = await sharedSlotOwner(pair[0]);
66
+ const keep = owner && pair.includes(owner) ? owner : pair[0], skip = pair.find(client => client !== keep);
67
+ selected.splice(selected.indexOf(skip), 1);
68
+ log(`${skip}: status=action_required, authorization=not_started, local_write=none, next_step=${keep} uses the same SandBase configuration slot. Complete or unregister ${keep}, then run sandbase connect --client ${skip}.`);
69
+ } return selected; }
70
+ function safeFailure(error) { let message = error instanceof Error ? error.message : "unknown failure"; for (const value of [process.env.HOME, process.env.SANDBASE_HOME, process.env.PWD])
71
+ if (value)
72
+ message = message.replaceAll(value, "[LOCAL_PATH]"); return message.replace(/(?:sk|cln)-[A-Za-z0-9_-]+/g, "[REDACTED]").replace(/\s+/g, " ").slice(0, 240); }
34
73
  function nextStepPrompts(label) { return [`2. In ${label}, try asking:`, " - List the available SandBase MCP tools.", " - Use SandBase to fetch Elon Musk's latest 10 posts on Twitter."]; }
35
74
  function successMessage(client, bridgePath) {
36
75
  const profile = clientProfiles[client];
37
76
  const label = profile.label;
38
77
  if (client === "warp")
39
- return ["", "SandBase MCP configuration is staged for Warp.", "", "Client: Warp (warp)", "Credential was stored locally with restricted permissions.", "", "Next steps:", "1. Open Warp and use /agent-add-mcp to review and approve the SandBase server.", "2. Read back SandBase in Warp's MCP server list and inspect its tools before treating it as connected.", "3. If a project .warp/.mcp.json defines sandbase, remove or rename that override first; SandBase leaves it untouched.", "", 'Manage access: revoke the "CLI Login" key in SandBase Dashboard when you no longer need it.'].join("\n");
40
- const common = ["", "SandBase MCP is connected.", "", `Client: ${label} (${client})`, "Credential was stored locally with restricted permissions."];
78
+ return ["", "SandBase MCP configuration is staged for Warp.", "", "Client: Warp (warp)", "Credential was stored locally with restricted permissions.", "", "Next steps:", "1. Open Warp and use /agent-add-mcp to review and approve the SandBase server.", "2. Read back SandBase in Warp's MCP server list, inspect its tools, and complete one safe call.", "3. If a project .warp/.mcp.json defines sandbase, remove or rename that override first; SandBase leaves it untouched.", "", 'Manage access: revoke the "CLI Login" key in SandBase Dashboard when you no longer need it.'].join("\n");
79
+ const common = ["", "SandBase local configuration is ready; client verification is still required.", "", `Client: ${label} (${client})`, "Credential was stored locally with restricted permissions."];
41
80
  if (profile.mode === "auto")
42
81
  return [...common, "", "Next steps:", `1. Restart or reload ${label} so it picks up the new MCP configuration.`, ...nextStepPrompts(label), "", 'Manage access: revoke the "CLI Login" key in SandBase Dashboard when you no longer need it.'].join("\n");
43
82
  if (profile.mode === "skill")
@@ -79,12 +118,12 @@ async function configureSkill(client, log) {
79
118
  try {
80
119
  const result = await installSkill(client);
81
120
  const status = result.state === "already_configured" ? "already_configured" : result.state === "configured" ? "configured" : "confirmation_required";
82
- log(`${client}: status=${status}, mcp=configured, skill=${result.state}, invocation=${nativeCapabilities[client].invocation}, next_step=${result.message}`);
121
+ log(`${client}: status=action_required, mcp=local_configured, skill=${result.state}, invocation=${nativeCapabilities[client].invocation}, next_step=${result.message}`);
83
122
  return status;
84
123
  }
85
124
  catch (error) {
86
125
  const message = error instanceof Error ? error.message : "Unknown native Skill failure";
87
- log(`${client}: status=failed, mcp=configured, skill=failed, invocation=${nativeCapabilities[client].invocation}, next_step=${message}`);
126
+ log(`${client}: status=failed, mcp=local_configured, skill=failed, invocation=${nativeCapabilities[client].invocation}, next_step=${message}`);
88
127
  return "failed";
89
128
  }
90
129
  }
@@ -130,7 +169,7 @@ async function connectOpenClaw(deps) {
130
169
  const mcp = await installOpenClawMcp(bridgeResult.path, deps.openClawRunner);
131
170
  if (mcp.status !== "configured" && mcp.status !== "already_configured")
132
171
  throw new Error(mcp.message);
133
- log(`openclaw: status=configured, mcp=${mcp.status}, skill=already_installed, invocation=mcp_chat, next_step=Restart OpenClaw, then make a natural-language request that needs SandBase.`);
172
+ log(`openclaw: status=action_required, mcp=local_configured, skill=already_installed, invocation=mcp_chat, next_step=Restart OpenClaw, read back server/tools, then complete one safe call.`);
134
173
  exchange.cleanup_token = "";
135
174
  }
136
175
  catch (error) {
@@ -155,7 +194,7 @@ async function connectDesktop(client, deps) {
155
194
  await store.save(recordFor(client, exchange));
156
195
  bridgeResult = await installBridge();
157
196
  identityResult = await writeDesktopIdentity(client);
158
- log(`${client}: status=client_confirmation_required, credential=ready, bridge=ready, mcp_artifact=not_read_back, skill_artifact=not_read_back, next_step=${client === "cowork" ? "Download and verify both artifacts, then obtain explicit account/workspace administrator approval before import." : "Download the versioned artifacts from SandBase Dashboard and complete the client-specific import."} MCP and Skill are not yet verified.`);
197
+ log(`${client}: status=action_required, credential=ready, bridge=ready, mcp_artifact=not_read_back, skill_artifact=not_read_back, next_step=${client === "cowork" ? "Download and inspect both artifacts, then obtain explicit account/workspace administrator approval before import." : "Download the versioned artifacts from SandBase Dashboard and complete the client-specific import."} Product verification is pending.`);
159
198
  exchange.cleanup_token = "";
160
199
  }
161
200
  catch (error) {
@@ -180,7 +219,7 @@ async function connectPromptAssisted(client, deps) {
180
219
  try {
181
220
  await store.save(recordFor(client, exchange));
182
221
  bridgeResult = await installBridge();
183
- log(`${client}: status=action_required, authorization=completed, credential=stored, bridge=ready, registration=registration_required, verification=real_client_matrix\nUse these generic stdio launcher fields in ${clientProfiles[client].label}'s existing MCP manager; no client settings were changed:\n${promptAssistedLauncher(client)}\nReload the client, read back the SandBase MCP server and tool list, then make one safe SandBase tool call. Until all three checks pass, status remains action_required.`);
222
+ log(`${client}: status=action_required, authorization=completed, credential=stored, bridge=ready, registration=registration_required, verification=real_client_matrix\nUse these generic stdio launcher fields in ${clientProfiles[client].label}'s existing MCP manager; no client settings were changed:\n${promptAssistedLauncher(client, bridgeResult.path)}\nReload the client, read back the SandBase MCP server and tool list, then make one safe SandBase tool call. Until all three checks pass, status remains action_required.`);
184
223
  exchange.cleanup_token = "";
185
224
  }
186
225
  catch (error) {
@@ -193,6 +232,29 @@ async function connectPromptAssisted(client, deps) {
193
232
  throw error;
194
233
  }
195
234
  }
235
+ async function connectChatGPT(deps) {
236
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
237
+ const store = deps.store || new FileCredentialStore();
238
+ const log = deps.log || console.log;
239
+ const previous = await store.get("chatgpt");
240
+ const { authorizationId, exchange } = await authorize(api, "chatgpt", { open: deps.open || openBrowser, sleep, log, ...(deps.signal ? { signal: deps.signal } : {}) });
241
+ let bridgeResult;
242
+ try {
243
+ await store.save(recordFor("chatgpt", exchange));
244
+ bridgeResult = await installBridge();
245
+ log("chatgpt: status=action_required, authorization=completed, credential=stored, bridge=ready, chatgpt_app=not_configured, verification=not_verified, next_step=Use an eligible ChatGPT Business, Enterprise, or Edu workspace. Enable Developer Mode, open Apps and choose Create, register the SandBase remote MCP endpoint using the approved authentication method, run Scan Tools, have a workspace administrator review and publish the App, then start a fresh conversation and complete one safe SandBase tool call. The CLI did not write or change any ChatGPT configuration.");
246
+ exchange.cleanup_token = "";
247
+ }
248
+ catch (error) {
249
+ if (bridgeResult)
250
+ await rollbackBridge(bridgeResult).catch(() => undefined);
251
+ await restoreCredential(store, "chatgpt", previous).catch(() => undefined);
252
+ if (!(await compensate(api, authorizationId, exchange.cleanup_token)))
253
+ console.error("WARNING: automatic credential cleanup failed. Revoke the new CLI credential in SandBase Dashboard immediately.");
254
+ exchange.cleanup_token = "";
255
+ throw error;
256
+ }
257
+ }
196
258
  async function connectOne(client, deps) {
197
259
  const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
198
260
  const store = deps.store || new FileCredentialStore();
@@ -201,6 +263,11 @@ async function connectOne(client, deps) {
201
263
  const profile = clientProfiles[client];
202
264
  const capability = nativeCapabilities[client];
203
265
  const v2 = capabilityRegistry[client];
266
+ if (client === "chatgpt") {
267
+ await connectChatGPT(deps);
268
+ return;
269
+ }
270
+ await assertSharedSlotAvailable(client);
204
271
  if (isPromptAssistedClient(client)) {
205
272
  await connectPromptAssisted(client, deps);
206
273
  return;
@@ -251,8 +318,8 @@ async function connectOne(client, deps) {
251
318
  if (client === "kiro") {
252
319
  const skill = await installSkill("kiro");
253
320
  if (skill.state !== "configured" && skill.state !== "already_configured")
254
- throw new Error("Kiro IDE Skill installation was not verified");
255
- log(`kiro: status=confirmation_required, mcp=configured, skill=${skill.state}, invocation=desktop_ui, next_step=Reload Kiro IDE, verify the SandBase server and tools, then complete one safe tool call.`);
321
+ throw new Error("Kiro IDE Skill local readback failed");
322
+ log(`kiro: status=action_required, mcp=local_configured, skill=${skill.state}, invocation=desktop_ui, next_step=Reload Kiro IDE, read back the SandBase server and tools, then complete one safe tool call.`);
256
323
  }
257
324
  else {
258
325
  log(successMessage(client, bridgeResult.path));
@@ -278,8 +345,8 @@ async function connectAuto(deps) {
278
345
  const store = deps.store || new FileCredentialStore();
279
346
  const log = deps.log || console.log;
280
347
  const detect = deps.detect || detectClient;
281
- const targets = plannedAutoClients(detect).filter(client => client !== "openclaw");
282
- const nativeSkillTargets = clients.filter(target => !!skillsAgentRegistry[target] && detect(target).installed);
348
+ const targets = await resolveAutoSharedSlots(plannedAutoClients(detect).filter(client => client !== "openclaw"), log);
349
+ const nativeSkillTargets = clients.filter(target => targets.includes(target) && !!skillsAgentRegistry[target] && detect(target).installed);
283
350
  // Native Skills are an independent local lifecycle: do not let their result
284
351
  // change MCP authorization, configuration, or rollback decisions.
285
352
  for (const target of nativeSkillTargets)
@@ -309,7 +376,7 @@ async function connectAuto(deps) {
309
376
  const mcp = await installOpenClawMcp(bridgeResult.path, deps.openClawRunner);
310
377
  if (mcp.status !== "configured" && mcp.status !== "already_configured")
311
378
  throw new Error(mcp.message);
312
- log(`openclaw: status=configured, mcp=${mcp.status}, skill=already_installed, invocation=mcp_chat, next_step=Restart OpenClaw, then make a natural-language request that needs SandBase.`);
379
+ log(`openclaw: status=action_required, mcp=local_configured, skill=already_installed, invocation=mcp_chat, next_step=Restart OpenClaw, read back server/tools, then complete one safe call.`);
313
380
  }
314
381
  else {
315
382
  configured = await configureMCP(client, bridgeResult.path, exchange, deps.a1Runner, deps.bRunner, deps.cRunner);
@@ -318,19 +385,20 @@ async function connectAuto(deps) {
318
385
  if (client === "kiro") {
319
386
  const skill = await installSkill("kiro");
320
387
  if (skill.state !== "configured" && skill.state !== "already_configured")
321
- throw new Error("Kiro IDE Skill installation was not verified");
322
- log(`kiro: status=confirmation_required, mcp=configured, skill=${skill.state}, invocation=desktop_ui, next_step=Reload Kiro IDE and verify server/tools plus one safe call.`);
388
+ throw new Error("Kiro IDE Skill local readback failed");
389
+ log(`kiro: status=action_required, mcp=local_configured, skill=${skill.state}, invocation=desktop_ui, next_step=Reload Kiro IDE and read back server/tools plus one safe call.`);
323
390
  }
324
391
  else if (!skillsAgentRegistry[client])
325
392
  await configureSkill(client, log);
326
393
  }
327
394
  succeeded.push(client);
328
395
  }
329
- catch {
396
+ catch (error) {
330
397
  if (configured)
331
398
  await rollbackMCP(client, configured, deps.cRunner).catch(() => undefined);
332
399
  await restoreCredential(store, client, previous).catch(() => undefined);
333
400
  failed.push(client);
401
+ log(`${client}: status=failed, reason=${safeFailure(error)}, next_step=Run sandbase doctor --client ${client}, resolve the reported ownership, precedence, capability, or readback issue, then retry.`);
334
402
  }
335
403
  }
336
404
  if (!succeeded.length)
@@ -550,6 +618,20 @@ export async function doctor(client = "auto", store = new FileCredentialStore(),
550
618
  }
551
619
  let healthy = true;
552
620
  for (const target of targets) {
621
+ if (target === "chatgpt") {
622
+ const [credential, bridge] = await Promise.all([store.get("chatgpt"), inspectBridge()]);
623
+ const ready = !!credential && validOwnedCredential("chatgpt", credential) && bridge === "ready";
624
+ console.log(`chatgpt: status=${ready ? "action_required" : "failed"}, authorization=${ready ? "completed" : "required"}, credential=${ready ? "present" : credential ? "invalid" : "missing"}, bridge=${bridge}, chatgpt_app=not_observable, verification=not_verified, next_step=${ready ? nativeCapabilities.chatgpt.guide : "Run sandbase connect --client chatgpt again to prepare the SandBase-owned credential and bridge. No ChatGPT configuration was changed."}`);
625
+ healthy = false;
626
+ continue;
627
+ }
628
+ if (isPromptAssistedClient(target)) {
629
+ const [credential, bridge] = await Promise.all([store.get(target), inspectBridge()]);
630
+ const ready = !!credential && validOwnedCredential(target, credential) && bridge === "ready";
631
+ console.log(`${target}: status=${ready ? "action_required" : "failed"}, credential=${ready ? "present" : credential ? "invalid" : "missing"}, bridge=${bridge}, registration=not_observable, verification=real_client_matrix, next_step=${ready ? "Register the displayed local bridge in the client, reload, then read back server/tools and complete one safe call." : `Run sandbase connect --client ${target} again.`}`);
632
+ healthy = false;
633
+ continue;
634
+ }
553
635
  if (isDesktopClient(target)) {
554
636
  const [credential, identity, bridge, artifact] = await Promise.all([store.get(target), readDesktopIdentity(target), inspectBridge(), target === "claude-desktop" ? readClaudeDesktopArtifactState() : readCoworkState()]);
555
637
  const credentialReady = !!credential && validOwnedCredential(target, credential);
@@ -614,7 +696,7 @@ export async function doctor(client = "auto", store = new FileCredentialStore(),
614
696
  }
615
697
  if (target === "warp") {
616
698
  const inspection = await inspectWarp(), credential = inspection.state === "configured" ? await store.get(target) : undefined, staged = inspection.state === "configured" && !!credential;
617
- console.log(`warp: status=${staged ? "confirmation_required" : inspection.state === "confirmation_required" || inspection.state === "conflict" ? "confirmation_required" : "failed"}, credential=${credential ? "present" : "missing"}, mcp=${inspection.state}, approval=not_observable, verification=read_back, next_step=${staged ? "Use /agent-add-mcp in Warp, approve SandBase, then inspect the MCP server and tools before treating it as connected." : inspection.detail}`);
699
+ console.log(`warp: status=${staged ? "action_required" : inspection.state === "confirmation_required" || inspection.state === "conflict" ? "confirmation_required" : "failed"}, credential=${credential ? "present" : "missing"}, mcp=${inspection.state}, approval=not_observable, verification=read_back, next_step=${staged ? "Use /agent-add-mcp in Warp, approve SandBase, then inspect the MCP server/tools and complete one safe call." : inspection.detail}`);
618
700
  healthy = false;
619
701
  continue;
620
702
  }
@@ -645,6 +727,24 @@ export async function unregister(client = "auto", store = new FileCredentialStor
645
727
  return;
646
728
  }
647
729
  for (const target of targets) {
730
+ if (target === "chatgpt") {
731
+ const credential = await store.get("chatgpt");
732
+ if (credential && !validOwnedCredential("chatgpt", credential))
733
+ throw new Error("chatgpt credential ownership is unrecognized; no changes were made");
734
+ if (credential)
735
+ await store.remove("chatgpt");
736
+ console.log(`chatgpt: status=${credential ? "removed" : "missing"}, bridge=retained, third_party_config=preserved, next_step=Only the SandBase-owned local ChatGPT credential was removed. The shared bridge and every ChatGPT App/workspace setting were left untouched; ask a workspace administrator to unpublish or remove the App separately if required.`);
737
+ continue;
738
+ }
739
+ if (isPromptAssistedClient(target)) {
740
+ const credential = await store.get(target);
741
+ if (credential && !validOwnedCredential(target, credential))
742
+ throw new Error(`${target} credential ownership is unrecognized; no changes were made`);
743
+ if (credential)
744
+ await store.remove(target);
745
+ console.log(`${target}: status=${credential ? "removed" : "missing"}, next_step=No client settings were changed; remove any manual MCP registration in the client, then revoke the CLI key in SandBase Dashboard if needed.`);
746
+ continue;
747
+ }
648
748
  if (isDesktopClient(target)) {
649
749
  const removed = target === "claude-desktop" ? await unregisterClaudeDesktop(store) : await unregisterCowork(store);
650
750
  console.log(`Removed local SandBase bridge identity for ${target}.${removed ? "" : " No managed identity was changed."} Desktop product settings were left untouched; revoke the server credential in SandBase Dashboard if it is no longer needed.`);
@@ -8,6 +8,7 @@ export declare class FileCredentialStore implements CredentialStore {
8
8
  readonly path: string;
9
9
  constructor(home?: string);
10
10
  private all;
11
+ private locked;
11
12
  save(record: CredentialRecord): Promise<void>;
12
13
  get(client: Client): Promise<CredentialRecord | undefined>;
13
14
  remove(client: Client): Promise<void>;
@@ -1,13 +1,44 @@
1
1
  import { join } from "node:path";
2
2
  import { atomicWrite, readOptional } from "../fs-safe.js";
3
3
  import { sandbaseHome } from "../paths.js";
4
+ import { mkdir, rm, stat } from "node:fs/promises";
5
+ import { dirname } from "node:path";
4
6
  export class FileCredentialStore {
5
7
  path;
6
8
  constructor(home = sandbaseHome()) { this.path = join(home, "credentials.json"); }
7
9
  async all() { const raw = await readOptional(this.path); if (!raw)
8
10
  return {}; const parsed = JSON.parse(raw); if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
9
11
  throw new Error("SandBase credential store is invalid"); return parsed; }
10
- async save(record) { const all = await this.all(); all[record.client] = record; await atomicWrite(this.path, JSON.stringify(all, null, 2) + "\n"); }
12
+ async locked(operation) {
13
+ const lock = `${this.path}.lock`;
14
+ const deadline = Date.now() + 5000;
15
+ await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
16
+ for (;;) {
17
+ try {
18
+ await mkdir(lock, { mode: 0o700 });
19
+ break;
20
+ }
21
+ catch (error) {
22
+ if (error.code !== "EEXIST")
23
+ throw error;
24
+ try {
25
+ if (Date.now() - (await stat(lock)).mtimeMs > 30_000)
26
+ await rm(lock, { recursive: true, force: true });
27
+ }
28
+ catch { /* another process released it */ }
29
+ if (Date.now() >= deadline)
30
+ throw new Error("SandBase credential store is busy; retry the command.");
31
+ await new Promise(resolve => setTimeout(resolve, 20));
32
+ }
33
+ }
34
+ try {
35
+ return await operation();
36
+ }
37
+ finally {
38
+ await rm(lock, { recursive: true, force: true });
39
+ }
40
+ }
41
+ async save(record) { await this.locked(async () => { const all = await this.all(); all[record.client] = record; await atomicWrite(this.path, JSON.stringify(all, null, 2) + "\n"); }); }
11
42
  async get(client) { return (await this.all())[client]; }
12
- async remove(client) { const all = await this.all(); delete all[client]; await atomicWrite(this.path, JSON.stringify(all, null, 2) + "\n"); }
43
+ async remove(client) { await this.locked(async () => { const all = await this.all(); delete all[client]; await atomicWrite(this.path, JSON.stringify(all, null, 2) + "\n"); }); }
13
44
  }
package/dist/types.d.ts CHANGED
@@ -1,5 +1,6 @@
1
- export declare const clients: readonly ["codex", "claude-code", "cursor", "windsurf", "gemini-cli", "opencode", "chatgpt", "hermes", "openclaw", "antigravity", "claude-desktop", "cursor-cli", "warp", "trae", "kimi-cli", "qwen-code", "kiro", "kiro-cli", "amp", "crush", "iflow-cli", "qoder", "workbuddy", "cowork", "pi"];
2
- export type Client = typeof clients[number];
1
+ import { type CatalogClient } from "./catalog.js";
2
+ export declare const clients: CatalogClient[];
3
+ export type Client = CatalogClient;
3
4
  export declare const promptAssistedClients: readonly ["antigravity", "trae", "qoder", "workbuddy", "pi"];
4
5
  export type PromptAssistedClient = typeof promptAssistedClients[number];
5
6
  export declare const bridgeClients: readonly ["claude-desktop", "cowork", "antigravity", "trae", "qoder", "workbuddy", "pi"];
package/dist/types.js CHANGED
@@ -1,4 +1,5 @@
1
- export const clients = ["codex", "claude-code", "cursor", "windsurf", "gemini-cli", "opencode", "chatgpt", "hermes", "openclaw", "antigravity", "claude-desktop", "cursor-cli", "warp", "trae", "kimi-cli", "qwen-code", "kiro", "kiro-cli", "amp", "crush", "iflow-cli", "qoder", "workbuddy", "cowork", "pi"];
1
+ import { clientCatalog } from "./catalog.js";
2
+ export const clients = clientCatalog.map(entry => entry.id);
2
3
  export const promptAssistedClients = ["antigravity", "trae", "qoder", "workbuddy", "pi"];
3
4
  export const bridgeClients = ["claude-desktop", "cowork", ...promptAssistedClients];
4
5
  export function isPromptAssistedClient(value) { return promptAssistedClients.includes(value); }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sandbaseai/cli",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "description": "Secure SandBase MCP onboarding CLI",
5
5
  "type": "module",
6
6
  "bin": {