@sandbaseai/cli 0.1.6 → 0.1.8

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,357 @@
1
+ import { spawn } from "node:child_process";
2
+ import { createHash } from "node:crypto";
3
+ import { readFile } from "node:fs/promises";
4
+ import { join } from "node:path";
5
+ /** Immutable release identity approved for the native Skills CLI adapter. */
6
+ export const sandbaseSkillRelease = {
7
+ repository: "https://github.com/sandbaseai/sandbase-skills",
8
+ release: "v0.1.0",
9
+ sourceArg: "https://github.com/sandbaseai/sandbase-skills/tree/v0.1.0",
10
+ commit: "03bc2811987db610cd64cbddfaa79b08e46c0e2f",
11
+ skillSha256: "583879aa39368577ebadd270434923969cbdeac0e0be73f5db0c2494019418da",
12
+ minimumCliVersion: "1.5.20",
13
+ };
14
+ /** Only IDs verified by the release owner may be passed to the Skills CLI. */
15
+ export const skillsAgentRegistry = {
16
+ "kiro-cli": { skillsAgentId: "kiro-cli" },
17
+ };
18
+ /** Immutable public identity of the ClawHub Skill adapter. */
19
+ export const openClawSandbaseSkill = {
20
+ slug: "@joeliu926/sandbase",
21
+ name: "sandbase",
22
+ page: "https://clawhub.ai/joeliu926/skills/sandbase",
23
+ };
24
+ const openClawMcpName = "sandbase";
25
+ const openClawManagedEnvironment = { SANDBASE_CLI_MANAGED: "1" };
26
+ export const systemOpenClawRunner = async (args) => new Promise(resolve => {
27
+ const child = spawn("openclaw", [...args], { stdio: ["ignore", "pipe", "pipe"] });
28
+ let stdout = "";
29
+ let stderr = "";
30
+ let settled = false;
31
+ const finish = (result) => { if (settled)
32
+ return; settled = true; clearTimeout(timeout); resolve(result); };
33
+ // The OpenClaw CLI may initialize plugins before executing a local MCP or
34
+ // Skill command. Give that supported command enough time, while still
35
+ // treating a timeout as unavailable rather than as ownership proof.
36
+ const timeout = setTimeout(() => { child.kill(); finish({ code: null, stdout: "", stderr: "" }); }, 45_000);
37
+ child.stdout.on("data", data => { stdout += String(data); });
38
+ child.stderr.on("data", data => { stderr += String(data); });
39
+ child.on("error", () => finish({ code: null, stdout: "", stderr: "" }));
40
+ child.on("close", code => finish({ code, stdout, stderr }));
41
+ });
42
+ /**
43
+ * OpenClaw's documented JSON readback reports an installed workspace Skill's
44
+ * name, loader source, and frontmatter homepage. Those three values are the
45
+ * only supported evidence used here; paths and raw SKILL.md contents are not
46
+ * considered ownership proof.
47
+ */
48
+ export const verifyOpenClawSandbaseReadback = async (json) => {
49
+ try {
50
+ const entry = JSON.parse(json);
51
+ return entry.name === openClawSandbaseSkill.name
52
+ && entry.source === "workspace"
53
+ && entry.homepage === openClawSandbaseSkill.page;
54
+ }
55
+ catch {
56
+ return false;
57
+ }
58
+ };
59
+ function openClawUnavailable() {
60
+ return { status: "failed", code: "skills_cli_unavailable", message: "OpenClaw CLI is unavailable or does not support the required Skill readback; no SandBase Skill was changed." };
61
+ }
62
+ async function invokeOpenClaw(runner, args) {
63
+ try {
64
+ return await runner(args);
65
+ }
66
+ catch {
67
+ return undefined;
68
+ }
69
+ }
70
+ function entryFrom(value) {
71
+ if (!value || typeof value !== "object" || Array.isArray(value))
72
+ return undefined;
73
+ const candidate = value;
74
+ if (typeof candidate.command !== "string" || !Array.isArray(candidate.args) || !candidate.args.every(arg => typeof arg === "string"))
75
+ return undefined;
76
+ const env = candidate.env && typeof candidate.env === "object" && !Array.isArray(candidate.env)
77
+ ? Object.fromEntries(Object.entries(candidate.env).filter((entry) => typeof entry[1] === "string"))
78
+ : {};
79
+ return { command: candidate.command, args: [...candidate.args], env };
80
+ }
81
+ /** Accept only documented JSON envelopes emitted by `openclaw mcp show`. */
82
+ function readMcpEntry(json) {
83
+ try {
84
+ const root = JSON.parse(json);
85
+ return entryFrom(root)
86
+ || entryFrom(root.mcpServers?.[openClawMcpName])
87
+ || entryFrom(root.servers?.[openClawMcpName])
88
+ || entryFrom(root.mcp?.servers?.[openClawMcpName]);
89
+ }
90
+ catch {
91
+ return undefined;
92
+ }
93
+ }
94
+ function isManagedMcpEntry(entry) {
95
+ return entry.command === "node"
96
+ && entry.args.length === 3
97
+ && entry.args[0].endsWith("sandbase-mcp-bridge.mjs")
98
+ && entry.args[1] === "--client"
99
+ && entry.args[2] === "openclaw"
100
+ && entry.env.SANDBASE_CLI_MANAGED === "1";
101
+ }
102
+ function desiredMcpEntry(bridgePath) {
103
+ return { command: "node", args: [bridgePath, "--client", "openclaw"], env: { ...openClawManagedEnvironment } };
104
+ }
105
+ function sameMcpEntry(left, right) {
106
+ return left.command === right.command
107
+ && JSON.stringify(left.args) === JSON.stringify(right.args)
108
+ && JSON.stringify(left.env) === JSON.stringify(right.env);
109
+ }
110
+ async function showOpenClawMcp(runner) {
111
+ const response = await invokeOpenClaw(runner, ["mcp", "show", openClawMcpName, "--json"]);
112
+ if (!response || response.code === null)
113
+ return { missing: false, unavailable: true };
114
+ if (response.code !== 0)
115
+ return { missing: response.code === 1, unavailable: response.code !== 1 };
116
+ const entry = readMcpEntry(response.stdout);
117
+ return entry ? { entry, missing: false, unavailable: false } : { missing: false, unavailable: true };
118
+ }
119
+ /** Read only the managed OpenClaw MCP entry; malformed or foreign entries fail closed. */
120
+ export async function inspectOpenClawMcp(runner = systemOpenClawRunner) {
121
+ const readback = await showOpenClawMcp(runner);
122
+ if (readback.missing)
123
+ return { status: "missing", message: "OpenClaw has no MCP server named sandbase." };
124
+ if (readback.unavailable || !readback.entry)
125
+ return { status: "failed", message: "OpenClaw CLI is unavailable or could not read back the sandbase MCP server." };
126
+ return isManagedMcpEntry(readback.entry)
127
+ ? { status: "already_configured", message: "OpenClaw read back the managed SandBase MCP bridge." }
128
+ : { status: "confirmation_required", message: "An existing non-SandBase OpenClaw MCP server named sandbase was left untouched." };
129
+ }
130
+ async function setOpenClawMcp(runner, entry) {
131
+ const result = await invokeOpenClaw(runner, ["mcp", "set", openClawMcpName, JSON.stringify(entry)]);
132
+ return !!result && result.code === 0;
133
+ }
134
+ async function unsetOpenClawMcp(runner) {
135
+ const result = await invokeOpenClaw(runner, ["mcp", "unset", openClawMcpName]);
136
+ return !!result && result.code === 0;
137
+ }
138
+ async function rollbackOpenClawMcp(runner, previous) {
139
+ if (previous)
140
+ await setOpenClawMcp(runner, previous);
141
+ else
142
+ await unsetOpenClawMcp(runner);
143
+ }
144
+ /**
145
+ * Configure the documented OpenClaw MCP registry. The credential deliberately
146
+ * remains in SandBase's restricted local store and is never included in this
147
+ * JSON value or passed to OpenClaw.
148
+ */
149
+ export async function installOpenClawMcp(bridgePath, runner = systemOpenClawRunner) {
150
+ const previous = await showOpenClawMcp(runner);
151
+ if (previous.unavailable)
152
+ return { status: "failed", message: "OpenClaw CLI is unavailable or does not support MCP readback; no MCP server was changed." };
153
+ if (previous.entry && !isManagedMcpEntry(previous.entry))
154
+ return { status: "confirmation_required", message: "An existing non-SandBase OpenClaw MCP server named sandbase was left untouched." };
155
+ const desired = desiredMcpEntry(bridgePath);
156
+ if (previous.entry && sameMcpEntry(previous.entry, desired))
157
+ return { status: "already_configured", message: "OpenClaw already has the managed SandBase MCP bridge." };
158
+ if (!(await setOpenClawMcp(runner, desired)))
159
+ return { status: "failed", message: "OpenClaw could not register the SandBase MCP server; no success was reported." };
160
+ const readback = await showOpenClawMcp(runner);
161
+ if (!readback.entry || readback.unavailable || !isManagedMcpEntry(readback.entry) || !sameMcpEntry(readback.entry, desired)) {
162
+ await rollbackOpenClawMcp(runner, previous.entry).catch(() => undefined);
163
+ return { status: "failed", message: "OpenClaw could not verify the managed SandBase MCP bridge; the prior MCP state was restored." };
164
+ }
165
+ return { status: "configured", message: "OpenClaw registered and read back the managed SandBase MCP bridge." };
166
+ }
167
+ /** Remove only the exact managed entry, then prove that it is absent. */
168
+ export async function removeOpenClawMcp(runner = systemOpenClawRunner) {
169
+ const before = await showOpenClawMcp(runner);
170
+ if (before.missing)
171
+ return { status: "missing", message: "OpenClaw has no SandBase MCP server to remove." };
172
+ if (before.unavailable || !before.entry)
173
+ return { status: "failed", message: "OpenClaw CLI is unavailable or could not read back the SandBase MCP server; nothing was removed." };
174
+ if (!isManagedMcpEntry(before.entry))
175
+ return { status: "confirmation_required", message: "OpenClaw MCP ownership could not be proven; the existing sandbase server was left untouched." };
176
+ if (!(await unsetOpenClawMcp(runner)))
177
+ return { status: "failed", message: "OpenClaw could not remove the managed SandBase MCP server." };
178
+ const after = await showOpenClawMcp(runner);
179
+ if (!after.missing)
180
+ return { status: "failed", message: "OpenClaw could not verify SandBase MCP removal; no removal success was reported." };
181
+ return { status: "removed", message: "OpenClaw removal of the managed SandBase MCP bridge was verified." };
182
+ }
183
+ async function inspectOpenClawSkillWith(runner, verify) {
184
+ const readback = await invokeOpenClaw(runner, ["skills", "info", openClawSandbaseSkill.name, "--json"]);
185
+ if (!readback || readback.code !== 0)
186
+ return openClawUnavailable();
187
+ return await verify(readback.stdout)
188
+ ? { status: "already_installed", message: "OpenClaw reports the exact SandBase ClawHub Skill identity." }
189
+ : { status: "confirmation_required", message: "OpenClaw cannot prove the exact SandBase ClawHub Skill identity." };
190
+ }
191
+ export async function installOpenClawSkill(runner = systemOpenClawRunner, verify = verifyOpenClawSandbaseReadback) {
192
+ const before = await inspectOpenClawSkillWith(runner, verify);
193
+ if (before.status === "already_installed")
194
+ return before;
195
+ if (before.status === "failed")
196
+ return before;
197
+ const installed = await invokeOpenClaw(runner, ["skills", "install", openClawSandbaseSkill.slug]);
198
+ if (!installed || installed.code !== 0)
199
+ return openClawUnavailable();
200
+ const readback = await inspectOpenClawSkillWith(runner, verify);
201
+ if (readback.status !== "already_installed")
202
+ return { status: "failed", code: "readback_failed", message: "OpenClaw could not prove the exact SandBase ClawHub Skill identity; no success was reported." };
203
+ return { status: "installed", message: "OpenClaw installed and read back the exact SandBase ClawHub Skill identity." };
204
+ }
205
+ export async function inspectOpenClawSkill(runner = systemOpenClawRunner, verify = verifyOpenClawSandbaseReadback) {
206
+ return inspectOpenClawSkillWith(runner, verify);
207
+ }
208
+ export async function removeOpenClawSkill(runner = systemOpenClawRunner, verify = verifyOpenClawSandbaseReadback) {
209
+ const existing = await inspectOpenClawSkillWith(runner, verify);
210
+ if (existing.status !== "already_installed")
211
+ return existing.status === "failed" ? existing : { status: "confirmation_required", message: "OpenClaw cannot prove SandBase Skill ownership; no Skill was removed." };
212
+ // OpenClaw 2026.4.12 documents no `skills remove`/`uninstall` subcommand.
213
+ // Do not delete the workspace directory or infer a removal path ourselves.
214
+ return { status: "confirmation_required", message: "This OpenClaw version has no supported Skill removal command; the verified SandBase Skill was left unchanged." };
215
+ }
216
+ function versionAtLeast(actual, minimum) {
217
+ const parse = (value) => value.match(/\b(\d+)\.(\d+)\.(\d+)\b/)?.slice(1).map(Number);
218
+ const a = parse(actual);
219
+ const b = parse(minimum);
220
+ if (!a || !b)
221
+ return false;
222
+ for (let index = 0; index < 3; index++) {
223
+ if (a[index] !== b[index])
224
+ return a[index] > b[index];
225
+ }
226
+ return true;
227
+ }
228
+ /** Reject every mutable or incomplete source tuple before starting any child process. */
229
+ export function validateSandbaseSkillRelease(release = sandbaseSkillRelease) {
230
+ return release.repository === "https://github.com/sandbaseai/sandbase-skills"
231
+ && release.release === "v0.1.0"
232
+ && release.sourceArg === "https://github.com/sandbaseai/sandbase-skills/tree/v0.1.0"
233
+ && release.commit === "03bc2811987db610cd64cbddfaa79b08e46c0e2f"
234
+ && release.skillSha256 === "583879aa39368577ebadd270434923969cbdeac0e0be73f5db0c2494019418da"
235
+ && release.minimumCliVersion === "1.5.20";
236
+ }
237
+ export const systemSkillsRunner = async (args) => new Promise(resolve => {
238
+ const child = spawn("npx", ["-y", "skills", ...args], { stdio: ["ignore", "pipe", "pipe"] });
239
+ let stdout = "";
240
+ let stderr = "";
241
+ child.stdout.on("data", data => { stdout += String(data); });
242
+ child.stderr.on("data", data => { stderr += String(data); });
243
+ child.on("error", () => resolve({ code: null, stdout: "", stderr: "" }));
244
+ child.on("close", code => resolve({ code, stdout, stderr }));
245
+ });
246
+ function unavailable() { return { status: "failed", code: "skills_cli_unavailable", message: "Skills CLI is unavailable or below the required version; no native Skill was changed." }; }
247
+ function sourceUnavailable() { return { status: "failed", code: "skill_source_unavailable", message: "The verified SandBase Skill source is unavailable; no native Skill was changed." }; }
248
+ // The first-party listing must echo the exact immutable selector. A repository
249
+ // name or a tag alone could refer to a different source and is not ownership proof.
250
+ export const verifySkillsReadback = async (output, agent) => {
251
+ try {
252
+ const entries = JSON.parse(output);
253
+ const candidates = [];
254
+ const visit = (value) => {
255
+ if (Array.isArray(value)) {
256
+ value.forEach(visit);
257
+ return;
258
+ }
259
+ if (!value || typeof value !== "object")
260
+ return;
261
+ const item = value;
262
+ if ("sourceUrl" in item || "agents" in item || "path" in item)
263
+ candidates.push(item);
264
+ Object.values(item).forEach(visit);
265
+ };
266
+ visit(entries);
267
+ const agentLabel = agent === "kiro-cli" ? "Kiro CLI" : "";
268
+ for (const candidate of candidates) {
269
+ if (candidate.sourceUrl !== `${sandbaseSkillRelease.repository}.git` || typeof candidate.path !== "string" || !JSON.stringify(candidate.agents).includes(agentLabel))
270
+ continue;
271
+ const skill = await readFile(join(candidate.path, "SKILL.md"), "utf8");
272
+ if (createHash("sha256").update(skill, "utf8").digest("hex") === sandbaseSkillRelease.skillSha256)
273
+ return true;
274
+ }
275
+ }
276
+ catch { /* malformed/unreadable first-party readback is not proof */ }
277
+ return false;
278
+ };
279
+ async function invoke(runner, args) {
280
+ try {
281
+ return await runner(args);
282
+ }
283
+ catch {
284
+ return undefined;
285
+ }
286
+ }
287
+ async function probe(client, runner) {
288
+ if (!validateSandbaseSkillRelease())
289
+ return sourceUnavailable();
290
+ const registration = skillsAgentRegistry[client];
291
+ if (!registration)
292
+ return { status: "failed", code: "unsupported_by_skills_cli", message: `No verified Skills CLI agent mapping exists for ${client}; no native Skill was changed.` };
293
+ const version = await invoke(runner, ["--version"]);
294
+ if (!version || version.code !== 0 || !versionAtLeast(`${version.stdout}\n${version.stderr}`, sandbaseSkillRelease.minimumCliVersion))
295
+ return unavailable();
296
+ // `skills add <source> --agent <id> --list` is the documented capability
297
+ // probe. It must succeed before an install or lifecycle command is attempted.
298
+ const listed = await invoke(runner, ["add", sandbaseSkillRelease.sourceArg, "--agent", registration.skillsAgentId, "--list"]);
299
+ if (!listed || listed.code !== 0)
300
+ return unavailable();
301
+ return { agent: registration.skillsAgentId, listed };
302
+ }
303
+ export async function installNativeSkill(client, runner = systemSkillsRunner, verify = verifySkillsReadback) {
304
+ const checked = await probe(client, runner);
305
+ if ("status" in checked)
306
+ return checked;
307
+ const before = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
308
+ if (!before || before.code !== 0)
309
+ return unavailable();
310
+ if (await verify(before.stdout, checked.agent))
311
+ return { status: "already_installed", message: "Native SandBase Skill is already installed and verified by Skills CLI readback." };
312
+ const added = await invoke(runner, ["add", sandbaseSkillRelease.sourceArg, "-g", "-a", checked.agent]);
313
+ if (!added || added.code !== 0)
314
+ return unavailable();
315
+ const readback = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
316
+ if (!readback || readback.code !== 0 || !(await verify(readback.stdout, checked.agent)))
317
+ return { status: "failed", code: "readback_failed", message: "Skills CLI could not prove the SandBase source for this agent; no success was reported." };
318
+ return { status: "installed", message: "Native SandBase Skill was installed and verified by Skills CLI readback." };
319
+ }
320
+ export async function inspectNativeSkill(client, runner = systemSkillsRunner, verify = verifySkillsReadback) {
321
+ const checked = await probe(client, runner);
322
+ if ("status" in checked)
323
+ return checked;
324
+ const readback = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
325
+ if (!readback || readback.code !== 0)
326
+ return unavailable();
327
+ return await verify(readback.stdout, checked.agent)
328
+ ? { status: "already_installed", message: "Native SandBase Skill ownership is verified by Skills CLI readback." }
329
+ : { status: "confirmation_required", message: "Native SandBase Skill is not listed for this agent." };
330
+ }
331
+ export async function planNativeSkillRemoval(client, runner = systemSkillsRunner, verify = verifySkillsReadback) {
332
+ const checked = await probe(client, runner);
333
+ if ("status" in checked)
334
+ return { owned: false, result: checked };
335
+ const before = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
336
+ if (!before || before.code !== 0)
337
+ return { owned: false, result: unavailable() };
338
+ if (!(await verify(before.stdout, checked.agent)))
339
+ return { agent: checked.agent, owned: false, result: { status: "confirmation_required", message: "Skills CLI cannot prove SandBase ownership for this agent; no native Skill was removed." } };
340
+ return { agent: checked.agent, owned: true, result: { status: "already_installed", message: "Native SandBase Skill ownership is verified by Skills CLI readback." } };
341
+ }
342
+ export async function executeNativeSkillRemoval(plan, runner = systemSkillsRunner, verify = verifySkillsReadback) {
343
+ if (!plan.owned || !plan.agent)
344
+ return plan.result;
345
+ // Skills CLI removes by its first-party Skill name, never by a URL. This is
346
+ // reached only after source, agent and digest ownership have been proven.
347
+ const removed = await invoke(runner, ["remove", "sandbase", "-g", "-a", plan.agent]);
348
+ if (!removed || removed.code !== 0)
349
+ return unavailable();
350
+ const readback = await invoke(runner, ["list", "-g", "-a", plan.agent, "--json"]);
351
+ if (!readback || readback.code !== 0 || await verify(readback.stdout, plan.agent))
352
+ return { status: "failed", code: "readback_failed", message: "Skills CLI could not prove native Skill removal; no removal success was reported." };
353
+ return { status: "removed", message: "Native SandBase Skill removal was verified by Skills CLI readback." };
354
+ }
355
+ export async function removeNativeSkill(client, runner = systemSkillsRunner, verify = verifySkillsReadback) {
356
+ return executeNativeSkillRemoval(await planNativeSkillRemoval(client, runner, verify), runner, verify);
357
+ }
package/dist/skills.js CHANGED
@@ -8,12 +8,21 @@ import { clientProfiles, skillTiers } from "./clients.js";
8
8
  import { sandbaseHome } from "./paths.js";
9
9
  const ownershipMarker = "<!-- sandbase-cli-managed: sandbase -->";
10
10
  const sharedClients = ["cursor", "codex"];
11
- const privateClients = ["claude-code"];
11
+ const privateClients = ["claude-code", "hermes", "kiro"];
12
12
  function sha256(content) { return createHash("sha256").update(content, "utf8").digest("hex"); }
13
13
  function sharedRoot(env = process.env) { const home = env.HOME || sandbaseHome(env); return join(home, ".agents", "skills", "sandbase"); }
14
14
  export function sharedSkillPath(env = process.env) { return join(sharedRoot(env), "SKILL.md"); }
15
15
  function metadataPath(env = process.env) { return join(sharedRoot(env), ".sandbase-managed.json"); }
16
- function privateRoot(client, env = process.env) { const home = env.HOME || sandbaseHome(env); return client === "claude-code" ? join(home, ".claude", "skills", "sandbase") : undefined; }
16
+ function privateRoot(client, env = process.env) {
17
+ const home = env.HOME || sandbaseHome(env);
18
+ if (client === "claude-code")
19
+ return join(home, ".claude", "skills", "sandbase");
20
+ if (client === "hermes")
21
+ return join(env.HERMES_HOME || join(home, ".hermes"), "skills", "sandbase");
22
+ if (client === "kiro")
23
+ return join(home, ".kiro", "skills", "sandbase");
24
+ return undefined;
25
+ }
17
26
  function privateSkillPath(client, env = process.env) { const root = privateRoot(client, env); return root ? join(root, "SKILL.md") : undefined; }
18
27
  function privateMetadataPath(client, env = process.env) { const root = privateRoot(client, env); return root ? join(root, ".sandbase-managed.json") : undefined; }
19
28
  function legacySkillPath(client, env = process.env) {
@@ -26,7 +35,7 @@ function legacySkillPath(client, env = process.env) {
26
35
  }
27
36
  export function skillPath(client, env = process.env) { return sharedClients.includes(client) ? sharedSkillPath(env) : privateSkillPath(client, env); }
28
37
  export function skillFallback(client) {
29
- if (client === "claude-code" || client === "hermes")
38
+ if (client === "claude-code")
30
39
  return `${clientProfiles[client].label} native SandBase Skill is not available yet. Use the configured SandBase MCP tools directly in chat.`;
31
40
  return "No native SandBase Skill is available for this client. Use the configured SandBase MCP tools directly.";
32
41
  }
@@ -118,7 +127,7 @@ export async function probeSkill(client, env = process.env) {
118
127
  if (privateClients.includes(client)) {
119
128
  if ((await privateOwnership(client, env)) === "ambiguous")
120
129
  return { compatible: false, message: `The ${clientProfiles[client].label} SandBase Skill ownership or checksum is invalid. It was left untouched; resolve it manually, then retry.` };
121
- return { compatible: true, message: `${clientProfiles[client].label} personal Skills root is available for installation.` };
130
+ return { compatible: true, message: `${clientProfiles[client].label} managed Skills root is available for installation.` };
122
131
  }
123
132
  if ((await sharedOwnership(env)) === "ambiguous")
124
133
  return { compatible: false, message: "The shared SandBase Skill ownership or checksum is invalid. It was left untouched; resolve it manually, then retry." };
@@ -212,7 +221,9 @@ async function installPrivateSkill(client, env) {
212
221
  await restore(meta, metaBackup);
213
222
  throw error;
214
223
  }
215
- return skillBackup ? { state: needsWrite ? "configured" : "already_configured", message: `${clientProfiles[client].label} personal SandBase Skill is installed; /sandbase still requires real-client verification.`, path, backup: skillBackup, metadataPath: meta, metadataBackup: metaBackup, changed: needsWrite } : { state: needsWrite ? "configured" : "already_configured", message: `${clientProfiles[client].label} personal SandBase Skill is installed; /sandbase still requires real-client verification.`, path, metadataPath: meta, metadataBackup: metaBackup, changed: needsWrite };
224
+ const invocation = client === "claude-code" ? "/sandbase" : "the native Skill";
225
+ const message = `${clientProfiles[client].label} managed SandBase Skill is installed; ${invocation} still requires real-client verification.`;
226
+ return skillBackup ? { state: needsWrite ? "configured" : "already_configured", message, path, backup: skillBackup, metadataPath: meta, metadataBackup: metaBackup, changed: needsWrite } : { state: needsWrite ? "configured" : "already_configured", message, path, metadataPath: meta, metadataBackup: metaBackup, changed: needsWrite };
216
227
  });
217
228
  }
218
229
  export async function rollbackSkill(result) { if (!result.changed || !result.path)
package/dist/types.d.ts CHANGED
@@ -1,5 +1,11 @@
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-cli", "amp", "crush", "iflow-cli", "qoder", "workbuddy", "cowork", "pi"];
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
2
  export type Client = typeof clients[number];
3
+ export declare const promptAssistedClients: readonly ["antigravity", "trae", "qoder", "workbuddy", "pi"];
4
+ export type PromptAssistedClient = typeof promptAssistedClients[number];
5
+ export declare const bridgeClients: readonly ["claude-desktop", "cowork", "antigravity", "trae", "qoder", "workbuddy", "pi"];
6
+ export type BridgeClient = typeof bridgeClients[number];
7
+ export declare function isPromptAssistedClient(value: string): value is PromptAssistedClient;
8
+ export declare function isBridgeClient(value: string): value is BridgeClient;
3
9
  export type ConnectClient = Client | "auto";
4
10
  export declare function isClient(value: string): value is Client;
5
11
  export interface CredentialRecord {
package/dist/types.js CHANGED
@@ -1,2 +1,6 @@
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-cli", "amp", "crush", "iflow-cli", "qoder", "workbuddy", "cowork", "pi"];
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"];
2
+ export const promptAssistedClients = ["antigravity", "trae", "qoder", "workbuddy", "pi"];
3
+ export const bridgeClients = ["claude-desktop", "cowork", ...promptAssistedClients];
4
+ export function isPromptAssistedClient(value) { return promptAssistedClients.includes(value); }
5
+ export function isBridgeClient(value) { return bridgeClients.includes(value); }
2
6
  export function isClient(value) { return clients.includes(value); }
@@ -0,0 +1,26 @@
1
+ export type WarpInspectionState = "missing" | "configured" | "confirmation_required" | "conflict" | "invalid";
2
+ export interface WarpInspection {
3
+ state: WarpInspectionState;
4
+ detail: string;
5
+ }
6
+ export interface WarpAdapterResult {
7
+ path: string;
8
+ changed: boolean;
9
+ backup?: string;
10
+ identityPath: string;
11
+ identityChanged: boolean;
12
+ identityPrevious?: string;
13
+ }
14
+ export interface WarpUnregisterSnapshot {
15
+ path: string;
16
+ config: string;
17
+ identityPath: string;
18
+ identity: string;
19
+ }
20
+ export declare function findWarpProjectOverride(env?: NodeJS.ProcessEnv): Promise<string | undefined>;
21
+ export declare function inspectWarp(env?: NodeJS.ProcessEnv, expectedBridge?: string): Promise<WarpInspection>;
22
+ export declare function installWarp(bridge: string, env?: NodeJS.ProcessEnv): Promise<WarpAdapterResult>;
23
+ export declare function rollbackWarp(result: WarpAdapterResult): Promise<void>;
24
+ export declare function snapshotWarpUnregister(env?: NodeJS.ProcessEnv): Promise<WarpUnregisterSnapshot | undefined>;
25
+ export declare function restoreWarpUnregister(snapshot: WarpUnregisterSnapshot): Promise<void>;
26
+ export declare function unregisterWarp(env?: NodeJS.ProcessEnv): Promise<boolean>;
@@ -0,0 +1,154 @@
1
+ import { dirname, isAbsolute, join } from "node:path";
2
+ import { rm } from "node:fs/promises";
3
+ import { atomicWrite, backup, readOptional, restore } from "./fs-safe.js";
4
+ import { configPath, sandbaseHome } from "./paths.js";
5
+ const marker = "sandbase-cli-warp-v1";
6
+ const identityPath = (env = process.env) => join(sandbaseHome(env), "adapters", "warp.json");
7
+ function object(value, label) {
8
+ if (!value || typeof value !== "object" || Array.isArray(value))
9
+ throw new Error(`${label} must be an object`);
10
+ return value;
11
+ }
12
+ function parseRoot(raw, label) { return object(JSON.parse(raw), label); }
13
+ function expected(bridge) { return { command: "node", args: [bridge, "--client", "warp"] }; }
14
+ function owned(value, bridge) {
15
+ if (!value || typeof value !== "object" || Array.isArray(value))
16
+ return false;
17
+ const entry = value;
18
+ return entry.command === "node" && Array.isArray(entry.args) && entry.args.length === 3 && entry.args[0] === bridge && entry.args[1] === "--client" && entry.args[2] === "warp";
19
+ }
20
+ async function identity(env = process.env) {
21
+ const raw = await readOptional(identityPath(env));
22
+ if (raw === undefined)
23
+ return undefined;
24
+ try {
25
+ const value = parseRoot(raw, "Warp identity");
26
+ return value.marker === marker && value.client === "warp" && typeof value.bridge === "string" && isAbsolute(value.bridge) ? { bridge: value.bridge } : undefined;
27
+ }
28
+ catch {
29
+ return undefined;
30
+ }
31
+ }
32
+ function parentDirectories(start) {
33
+ const result = [];
34
+ let current = start;
35
+ for (;;) {
36
+ result.push(current);
37
+ const parent = dirname(current);
38
+ if (parent === current)
39
+ return result;
40
+ current = parent;
41
+ }
42
+ }
43
+ export async function findWarpProjectOverride(env = process.env) {
44
+ const cwd = env.PWD || process.cwd(), globalPath = configPath("warp", env);
45
+ for (const directory of parentDirectories(cwd)) {
46
+ const path = join(directory, ".warp", ".mcp.json");
47
+ const raw = await readOptional(path);
48
+ if (raw === undefined)
49
+ continue;
50
+ if (path === globalPath)
51
+ continue;
52
+ const root = parseRoot(raw, "Warp project configuration");
53
+ const servers = root.mcpServers === undefined ? {} : object(root.mcpServers, "Warp project mcpServers");
54
+ if (servers.sandbase !== undefined)
55
+ return path;
56
+ }
57
+ return undefined;
58
+ }
59
+ export async function inspectWarp(env = process.env, expectedBridge) {
60
+ try {
61
+ const override = await findWarpProjectOverride(env);
62
+ if (override)
63
+ return { state: "confirmation_required", detail: `higher-priority project SandBase entry at ${override} was left untouched` };
64
+ const raw = await readOptional(configPath("warp", env));
65
+ if (raw === undefined)
66
+ return { state: "missing", detail: "Warp user configuration is missing" };
67
+ const root = parseRoot(raw, "Warp user configuration");
68
+ const servers = root.mcpServers === undefined ? {} : object(root.mcpServers, "Warp user mcpServers");
69
+ if (servers.sandbase === undefined)
70
+ return { state: "missing", detail: "SandBase is not registered in the Warp user configuration" };
71
+ const id = await identity(env);
72
+ const bridge = expectedBridge || id?.bridge;
73
+ if (!bridge || !owned(servers.sandbase, bridge))
74
+ return { state: "conflict", detail: "the sandbase entry is not SandBase-owned" };
75
+ return { state: "configured", detail: "user configuration ownership verified; approve with /agent-add-mcp and read back tools in Warp" };
76
+ }
77
+ catch (error) {
78
+ return { state: "invalid", detail: error instanceof Error ? error.message : "Warp configuration is invalid" };
79
+ }
80
+ }
81
+ export async function installWarp(bridge, env = process.env) {
82
+ if (!isAbsolute(bridge))
83
+ throw new Error("warp: managed bridge path must be absolute; no changes were made");
84
+ const before = await inspectWarp(env, bridge);
85
+ if (["confirmation_required", "conflict", "invalid"].includes(before.state))
86
+ throw new Error(`warp: ${before.detail}; no changes were made`);
87
+ const path = configPath("warp", env), raw = await readOptional(path), text = raw === undefined || !raw.trim() ? "{}\n" : raw;
88
+ const root = parseRoot(text, "Warp user configuration"), servers = root.mcpServers === undefined ? {} : object(root.mcpServers, "Warp user mcpServers");
89
+ const nextEntry = expected(bridge), nextIdentity = JSON.stringify({ marker, client: "warp", bridge }, null, 2) + "\n", idPath = identityPath(env), oldIdentity = await readOptional(idPath);
90
+ const changed = !owned(servers.sandbase, bridge), identityChanged = oldIdentity !== nextIdentity;
91
+ const result = { path, changed, identityPath: idPath, identityChanged, ...(oldIdentity === undefined ? {} : { identityPrevious: oldIdentity }) };
92
+ try {
93
+ if (identityChanged)
94
+ await atomicWrite(idPath, nextIdentity);
95
+ if (changed) {
96
+ servers.sandbase = nextEntry;
97
+ root.mcpServers = servers;
98
+ const backupPath = await backup(path);
99
+ if (backupPath !== undefined)
100
+ result.backup = backupPath;
101
+ await atomicWrite(path, JSON.stringify(root, null, 2) + "\n");
102
+ }
103
+ const after = await inspectWarp(env, bridge);
104
+ if (after.state !== "configured")
105
+ throw new Error(`Warp readback failed: ${after.detail}`);
106
+ return result;
107
+ }
108
+ catch (error) {
109
+ await rollbackWarp(result);
110
+ throw error;
111
+ }
112
+ }
113
+ export async function rollbackWarp(result) {
114
+ const operations = [];
115
+ if (result.changed)
116
+ operations.push(restore(result.path, result.backup));
117
+ if (result.identityChanged)
118
+ operations.push(result.identityPrevious === undefined ? rm(result.identityPath, { force: true }) : atomicWrite(result.identityPath, result.identityPrevious));
119
+ const settled = await Promise.allSettled(operations);
120
+ if (settled.some(item => item.status === "rejected"))
121
+ throw new Error("Warp rollback was incomplete");
122
+ }
123
+ export async function snapshotWarpUnregister(env = process.env) {
124
+ const inspection = await inspectWarp(env);
125
+ if (inspection.state === "missing")
126
+ return undefined;
127
+ if (inspection.state !== "configured")
128
+ throw new Error(`warp: ${inspection.detail}; no changes were made`);
129
+ const [config, identityRaw] = await Promise.all([readOptional(configPath("warp", env)), readOptional(identityPath(env))]);
130
+ if (config === undefined || identityRaw === undefined)
131
+ throw new Error("warp: managed ownership state is incomplete; no changes were made");
132
+ return { path: configPath("warp", env), config, identityPath: identityPath(env), identity: identityRaw };
133
+ }
134
+ export async function restoreWarpUnregister(snapshot) { await Promise.all([atomicWrite(snapshot.path, snapshot.config), atomicWrite(snapshot.identityPath, snapshot.identity)]); }
135
+ export async function unregisterWarp(env = process.env) {
136
+ const snapshot = await snapshotWarpUnregister(env);
137
+ if (!snapshot)
138
+ return false;
139
+ try {
140
+ const root = parseRoot(snapshot.config, "Warp user configuration"), servers = object(root.mcpServers, "Warp user mcpServers");
141
+ delete servers.sandbase;
142
+ root.mcpServers = servers;
143
+ await atomicWrite(snapshot.path, JSON.stringify(root, null, 2) + "\n");
144
+ await rm(snapshot.identityPath, { force: true });
145
+ const after = await inspectWarp(env);
146
+ if (after.state !== "missing")
147
+ throw new Error(`Warp removal readback failed: ${after.detail}`);
148
+ return true;
149
+ }
150
+ catch (error) {
151
+ await restoreWarpUnregister(snapshot);
152
+ throw error;
153
+ }
154
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sandbaseai/cli",
3
- "version": "0.1.6",
3
+ "version": "0.1.8",
4
4
  "description": "Secure SandBase MCP onboarding CLI",
5
5
  "type": "module",
6
6
  "bin": {
@@ -37,6 +37,7 @@
37
37
  "provenance": true
38
38
  },
39
39
  "dependencies": {
40
+ "jsonc-parser": "3.3.1",
40
41
  "smol-toml": "1.7.0",
41
42
  "yaml": "2.9.0"
42
43
  }