@sandbaseai/cli 0.1.4 → 0.1.5

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.
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: sandbase
3
3
  description: Use the already configured SandBase MCP tools for relevant requests.
4
+ disable-model-invocation: true
4
5
  ---
5
6
 
6
7
  # SandBase
@@ -9,9 +9,8 @@ import { atomicWrite, backup, readOptional, restore } from "../fs-safe.js";
9
9
  import { clientProfiles } from "../clients.js";
10
10
  import { configPath, sandbaseHome } from "../paths.js";
11
11
  const defaultIO = { backup, write: atomicWrite, restore };
12
- export function detectClient(client) { const profile = clientProfiles[client]; if (profile.mode !== "auto")
13
- return { installed: true, detail: "manual setup" }; if (!profile.executable)
14
- return existsSync(configPath(client)) ? { installed: true, detail: "existing configuration" } : { installed: false, detail: "configuration not found" }; const result = spawnSync(profile.executable, ["--version"], { encoding: "utf8", timeout: 5000 }); const detail = (result.stdout || result.stderr || "").trim().split("\n")[0] || "not found"; return { installed: result.status === 0, detail }; }
12
+ export function detectClient(client) { const profile = clientProfiles[client]; if (!profile.executable)
13
+ return profile.mode === "auto" && existsSync(configPath(client)) ? { installed: true, detail: "existing configuration" } : { installed: false, detail: "not detected" }; const result = spawnSync(profile.executable, ["--version"], { encoding: "utf8", timeout: 5000 }); const detail = (result.stdout || result.stderr || "").trim().split("\n")[0] || "not found"; return { installed: result.status === 0, detail }; }
15
14
  const start = "# >>> sandbase managed >>>", end = "# <<< sandbase managed <<<";
16
15
  function block(client, bridge) {
17
16
  if (client === "codex")
package/dist/clients.d.ts CHANGED
@@ -1,6 +1,20 @@
1
1
  import type { Client } from "./types.js";
2
2
  export type InstallMode = "auto" | "manual" | "skill";
3
- export type SkillTier = "s1_slash" | "s2_skill" | "s3_fallback" | "s4_none";
3
+ export type SkillTier = "s1_slash" | "s3_promotion" | "s3_fallback" | "s4_none";
4
+ export type MCPMode = "auto" | "desktop" | "manual" | "none";
5
+ export type SkillMode = "shared_skill" | "client_skill" | "prompt" | "none";
6
+ export type Invocation = "slash" | "skill_picker" | "mcp_chat" | "desktop_ui" | "prompt" | "none";
7
+ export type Verification = "fixture" | "read_only_probe" | "user_action" | "real_client_matrix";
8
+ export type CapabilityStatus = "configured" | "already_configured" | "action_required" | "unsupported" | "failed";
9
+ export interface NativeCapability {
10
+ mcpMode: MCPMode;
11
+ skillMode: SkillMode;
12
+ invocation: Invocation;
13
+ verification: Verification;
14
+ guide: string;
15
+ uninstall: "managed_only";
16
+ terminal: Exclude<CapabilityStatus, "configured" | "already_configured" | "failed">;
17
+ }
4
18
  export interface ClientProfile {
5
19
  id: Client;
6
20
  label: string;
@@ -10,5 +24,7 @@ export interface ClientProfile {
10
24
  }
11
25
  export declare const clientProfiles: Record<Client, ClientProfile>;
12
26
  export declare const skillTiers: Record<Client, SkillTier>;
27
+ export declare const nativeCapabilities: Record<Client, NativeCapability>;
28
+ export declare function assertNativeCapabilities(): void;
13
29
  export declare function clientList(): string;
14
30
  export declare function autoClients(): Client[];
package/dist/clients.js CHANGED
@@ -25,9 +25,44 @@ export const clientProfiles = {
25
25
  pi: { id: "pi", label: "Pi", mode: "skill" },
26
26
  };
27
27
  export const skillTiers = {
28
- codex: "s2_skill", "claude-code": "s1_slash", cursor: "s3_fallback", hermes: "s3_fallback",
28
+ codex: "s3_promotion", "claude-code": "s3_fallback", cursor: "s3_promotion", hermes: "s3_fallback",
29
29
  windsurf: "s4_none", "gemini-cli": "s4_none", opencode: "s4_none", chatgpt: "s4_none", openclaw: "s4_none", antigravity: "s4_none", "claude-desktop": "s4_none", "cursor-cli": "s4_none", warp: "s4_none", trae: "s4_none", "kimi-cli": "s4_none", "qwen-code": "s4_none", "kiro-cli": "s4_none", amp: "s4_none", crush: "s4_none", "iflow-cli": "s4_none", qoder: "s4_none", workbuddy: "s4_none", cowork: "s4_none", pi: "s4_none",
30
30
  };
31
+ const guide = (client, action, check) => `${client}: ${action} Completion check: ${check} Recovery: keep existing settings unchanged and retry after correcting the client setup.`;
32
+ export const nativeCapabilities = {
33
+ codex: { mcpMode: "auto", skillMode: "shared_skill", invocation: "skill_picker", verification: "read_only_probe", guide: guide("Codex", "Restart Codex and use its Skill picker to select SandBase; do not assume a slash command.", "SandBase MCP tools are visible in the session."), uninstall: "managed_only", terminal: "action_required" },
34
+ "claude-code": { mcpMode: "auto", skillMode: "shared_skill", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Claude Code", "Restart Claude Code and use its configured MCP tools; native Skill discovery is not claimed.", "SandBase MCP tools are visible in chat."), uninstall: "managed_only", terminal: "action_required" },
35
+ cursor: { mcpMode: "auto", skillMode: "shared_skill", invocation: "slash", verification: "real_client_matrix", guide: guide("Cursor", "Restart Cursor, type /, and look for /sandbase.", "A real-client matrix confirms /sandbase discovery and invocation."), uninstall: "managed_only", terminal: "action_required" },
36
+ "cursor-cli": { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Cursor CLI", "Restart the CLI session and use the configured SandBase MCP tools.", "SandBase tools are listed by the client."), uninstall: "managed_only", terminal: "action_required" },
37
+ "gemini-cli": { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Gemini CLI", "Restart the CLI session and use the configured SandBase MCP tools.", "SandBase tools are listed by the client."), uninstall: "managed_only", terminal: "action_required" },
38
+ hermes: { mcpMode: "auto", skillMode: "prompt", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Hermes", "Restart Hermes, then ask it to use the configured SandBase MCP tools.", "Hermes lists or calls SandBase tools."), uninstall: "managed_only", terminal: "action_required" },
39
+ "claude-desktop": { mcpMode: "desktop", skillMode: "none", invocation: "desktop_ui", verification: "read_only_probe", guide: guide("Claude Desktop", "Restart the desktop app and inspect its MCP tools panel.", "SandBase tools appear in the desktop UI."), uninstall: "managed_only", terminal: "action_required" },
40
+ "qwen-code": { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Qwen Code", "Restart Qwen Code and use the configured SandBase MCP tools.", "SandBase tools are listed by the client."), uninstall: "managed_only", terminal: "action_required" },
41
+ windsurf: { mcpMode: "manual", skillMode: "none", invocation: "desktop_ui", verification: "user_action", guide: guide("Windsurf", "Open its MCP settings and import the SandBase MCP server using your locally stored credential.", "The MCP settings page lists SandBase."), uninstall: "managed_only", terminal: "action_required" },
42
+ opencode: { mcpMode: "manual", skillMode: "none", invocation: "mcp_chat", verification: "user_action", guide: guide("OpenCode", "Use its documented MCP import flow and add the SandBase server.", "OpenCode lists SandBase tools."), uninstall: "managed_only", terminal: "action_required" },
43
+ 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
+ warp: { mcpMode: "manual", skillMode: "none", invocation: "desktop_ui", verification: "user_action", guide: guide("Warp", "Open Warp's MCP settings and follow its documented server import flow.", "SandBase is visible in Warp's MCP settings."), uninstall: "managed_only", terminal: "action_required" },
45
+ 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" },
46
+ "kimi-cli": { mcpMode: "manual", skillMode: "none", invocation: "mcp_chat", verification: "user_action", guide: guide("Kimi CLI", "Use Kimi CLI's documented MCP import flow.", "SandBase tools are visible in Kimi CLI."), uninstall: "managed_only", terminal: "action_required" },
47
+ "kiro-cli": { mcpMode: "manual", skillMode: "none", invocation: "mcp_chat", verification: "user_action", guide: guide("Kiro CLI", "Use Kiro CLI's documented MCP import flow.", "SandBase tools are visible in Kiro CLI."), uninstall: "managed_only", terminal: "action_required" },
48
+ amp: { mcpMode: "manual", skillMode: "none", invocation: "mcp_chat", verification: "user_action", guide: guide("Amp", "Use Amp's documented MCP import flow.", "SandBase tools are visible in Amp."), uninstall: "managed_only", terminal: "action_required" },
49
+ crush: { mcpMode: "manual", skillMode: "none", invocation: "mcp_chat", verification: "user_action", guide: guide("Crush", "Use Crush's documented MCP import flow.", "SandBase tools are visible in Crush."), uninstall: "managed_only", terminal: "action_required" },
50
+ "iflow-cli": { mcpMode: "manual", skillMode: "none", invocation: "mcp_chat", verification: "user_action", guide: guide("iFlow CLI", "Use iFlow CLI's documented MCP import flow.", "SandBase tools are visible in iFlow CLI."), uninstall: "managed_only", terminal: "action_required" },
51
+ qoder: { mcpMode: "none", skillMode: "prompt", invocation: "prompt", verification: "user_action", guide: guide("Qoder", "Paste the SandBase MCP usage prompt into Qoder.", "Qoder confirms the prompt or tool availability."), uninstall: "managed_only", terminal: "action_required" },
52
+ workbuddy: { mcpMode: "none", skillMode: "prompt", invocation: "prompt", verification: "user_action", guide: guide("WorkBuddy", "Paste the SandBase MCP usage prompt into WorkBuddy.", "WorkBuddy confirms the prompt or tool availability."), uninstall: "managed_only", terminal: "action_required" },
53
+ cowork: { mcpMode: "manual", skillMode: "none", invocation: "desktop_ui", verification: "user_action", guide: guide("Cowork", "Open Cowork's MCP settings and use its documented import flow.", "SandBase appears in Cowork's MCP settings."), uninstall: "managed_only", terminal: "action_required" },
54
+ pi: { mcpMode: "none", skillMode: "prompt", invocation: "prompt", verification: "user_action", guide: guide("Pi", "Paste the SandBase MCP usage prompt into Pi.", "Pi confirms the prompt or tool availability."), uninstall: "managed_only", terminal: "action_required" },
55
+ openclaw: { mcpMode: "none", skillMode: "prompt", invocation: "prompt", verification: "user_action", guide: guide("OpenClaw", "Paste the SandBase MCP usage prompt into OpenClaw.", "OpenClaw confirms the prompt or tool availability."), uninstall: "managed_only", terminal: "action_required" },
56
+ antigravity: { mcpMode: "none", skillMode: "prompt", invocation: "prompt", verification: "user_action", guide: guide("Antigravity", "Paste the SandBase MCP usage prompt into Antigravity.", "Antigravity confirms the prompt or tool availability."), uninstall: "managed_only", terminal: "action_required" },
57
+ };
58
+ export function assertNativeCapabilities() {
59
+ for (const client of Object.keys(clientProfiles)) {
60
+ const capability = nativeCapabilities[client];
61
+ if (!capability || !capability.mcpMode || !capability.skillMode || !capability.invocation || !capability.verification || !capability.guide || !capability.uninstall || !capability.terminal)
62
+ throw new Error(`Invalid native capability for ${client}`);
63
+ }
64
+ }
65
+ assertNativeCapabilities();
31
66
  export function clientList() {
32
67
  return Object.keys(clientProfiles).join("|");
33
68
  }
@@ -1,4 +1,4 @@
1
- import type { Client, ConnectClient } from "./types.js";
1
+ import { type Client, type ConnectClient } from "./types.js";
2
2
  import { AuthorizationApi } from "./auth/api.js";
3
3
  import { type CredentialStore } from "./credentials/store.js";
4
4
  type Detection = {
package/dist/commands.js CHANGED
@@ -1,11 +1,12 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { platform } from "node:os";
3
+ import { clients } from "./types.js";
3
4
  import { AuthorizationApi } from "./auth/api.js";
4
5
  import { authorize } from "./auth/flow.js";
5
- import { autoClients, clientProfiles } from "./clients.js";
6
+ import { autoClients, clientProfiles, nativeCapabilities } from "./clients.js";
6
7
  import { FileCredentialStore } from "./credentials/store.js";
7
8
  import { configure, detectClient, installBridge, isConfigured, rollback, rollbackBridge, unregister as removeAdapter } from "./adapters/index.js";
8
- import { inspectSkill, installSkill, removeSkill, skillFallback, skillInvocation } from "./skills.js";
9
+ import { inspectSkill, installSkill, removeSkill, sharedSkillReferences, skillFallback, skillInvocation } from "./skills.js";
9
10
  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 }); });
10
11
  async function compensate(api, authorizationId, token) { for (const delay of [0, 250, 750]) {
11
12
  if (delay)
@@ -30,6 +31,14 @@ function successMessage(client, record, bridgePath, configuredPath) {
30
31
  return [...common, "", "Manual MCP configuration required.", `Add this MCP server configuration to ${label}:`, "", mcpServerSnippet(client, bridgePath), "", "Next steps:", `1. Save the configuration and restart or reload ${label}.`, ...nextStepPrompts(label), "", 'Manage access: revoke the "CLI Login" key in SandBase Dashboard when you no longer need it.'].join("\n");
31
32
  }
32
33
  function plannedAutoClients(detect) { return autoClients().filter(client => detect(client).installed); }
34
+ function logDetectedActionRequired(detect, log) {
35
+ for (const client of clients) {
36
+ const capability = nativeCapabilities[client];
37
+ if (capability.mcpMode === "auto" || capability.mcpMode === "desktop" || !detect(client).installed)
38
+ continue;
39
+ log(`${client}: status=${capability.terminal}, mcp=not_configured, skill=${capability.skillMode}, invocation=${capability.invocation}. ${capability.guide}`);
40
+ }
41
+ }
33
42
  function recordFor(client, exchange) { return { credential: exchange.credential, credentialId: exchange.credential_id, keyPrefix: exchange.key_prefix, client, scope: exchange.scope, mcpUrl: exchange.mcp_url, createdAt: exchange.created_at }; }
34
43
  async function restoreCredential(store, client, previous) { if (previous)
35
44
  await store.save(previous);
@@ -51,6 +60,11 @@ async function connectOne(client, deps) {
51
60
  const log = deps.log || console.log;
52
61
  const detect = deps.detect || detectClient;
53
62
  const profile = clientProfiles[client];
63
+ const capability = nativeCapabilities[client];
64
+ if (capability.mcpMode === "manual" || capability.mcpMode === "none") {
65
+ log(`${client}: status=${capability.terminal}, mcp=not_configured, skill=${capability.skillMode}, invocation=${capability.invocation}. ${capability.guide}`);
66
+ return;
67
+ }
54
68
  const detected = detect(client);
55
69
  if (!detected.installed)
56
70
  throw new Error(`${profile.label} is not installed or is incompatible. Install a supported version, then retry.`);
@@ -89,6 +103,7 @@ async function connectAuto(deps) {
89
103
  const targets = plannedAutoClients(detect);
90
104
  if (!targets.length) {
91
105
  log("No installed compatible clients support automatic configuration. Use --client <client> for manual or skill setup guidance.");
106
+ logDetectedActionRequired(detect, log);
92
107
  return;
93
108
  }
94
109
  const { authorizationId, exchange } = await authorize(api, "auto", { open: deps.open || openBrowser, sleep, log, ...(deps.signal ? { signal: deps.signal } : {}) });
@@ -120,6 +135,7 @@ async function connectAuto(deps) {
120
135
  log(`Configured clients: ${succeeded.join(", ")}.`);
121
136
  if (failed.length)
122
137
  log(`Partial success: failed clients were rolled back: ${failed.join(", ")}.`);
138
+ logDetectedActionRequired(detect, log);
123
139
  exchange.cleanup_token = "";
124
140
  }
125
141
  catch (e) {
@@ -146,8 +162,10 @@ export async function doctor(client = "auto", store = new FileCredentialStore(),
146
162
  const configured = profile.mode === "auto" ? await isConfigured(target) : !!credential;
147
163
  const detected = detect(target);
148
164
  const skill = await inspectSkill(target);
149
- const skillDetail = skill === "installed" ? skillInvocation(target) : skill === "fallback" ? skillFallback(target) : skill === "unsupported" ? "No native SandBase Skill is available for this client." : skill === "modified" ? "Managed native Skill is missing or modified; it was left untouched." : "Native SandBase Skill is not installed.";
150
- console.log(`${target}: mode=${profile.mode}, installed=${detected.installed ? "yes" : "no"}, config=${configured ? profile.mode === "auto" ? "ok" : "manual" : "missing"}, skill=${skill}, credential=${credential ? credential.keyPrefix + "…" : "missing"}, url=${credential?.mcpUrl || "unknown"}, scope=${credential?.scope.join(",") || "unknown"}. ${skillDetail}`);
165
+ const capability = nativeCapabilities[target];
166
+ const skillDetail = skill === "installed" ? skillInvocation(target) : skill === "fallback" ? skillFallback(target) : skill === "unsupported" ? "No native SandBase Skill is available for this client." : skill === "modified" ? "Managed native Skill is missing or modified; it was left untouched." : capability.guide;
167
+ const references = await sharedSkillReferences();
168
+ console.log(`${target}: status=${capability.terminal}, mode=${profile.mode}, installed=${detected.installed ? "yes" : "no"}, config=${configured ? profile.mode === "auto" ? "ok" : "manual" : "missing"}, skill=${skill}, invocation=${capability.invocation}, verification=${capability.verification}, shared_skill_references=${references.join(",") || "none"}, credential=${credential ? credential.keyPrefix + "…" : "missing"}, url=${credential?.mcpUrl || "unknown"}, scope=${credential?.scope.join(",") || "unknown"}. ${skillDetail}`);
151
169
  healthy = healthy && detected.installed && !!credential && configured && !["missing", "modified"].includes(skill);
152
170
  }
153
171
  return healthy;
package/dist/skills.d.ts CHANGED
@@ -7,9 +7,16 @@ export interface SkillInstallResult {
7
7
  backup?: string;
8
8
  changed: boolean;
9
9
  }
10
+ export interface SkillProbe {
11
+ compatible: boolean;
12
+ message: string;
13
+ }
14
+ export declare function sharedSkillPath(env?: NodeJS.ProcessEnv): string;
10
15
  export declare function skillPath(client: Client, env?: NodeJS.ProcessEnv): string | undefined;
11
16
  export declare function skillFallback(client: Client): string;
12
17
  export declare function skillInvocation(client: Client): string;
18
+ export declare function sharedSkillReferences(env?: NodeJS.ProcessEnv): Promise<Client[]>;
19
+ export declare function probeSkill(client: Client, env?: NodeJS.ProcessEnv): Promise<SkillProbe>;
13
20
  export declare function inspectSkill(client: Client, env?: NodeJS.ProcessEnv): Promise<SkillState>;
14
21
  export declare function installSkill(client: Client, env?: NodeJS.ProcessEnv): Promise<SkillInstallResult>;
15
22
  export declare function rollbackSkill(result: SkillInstallResult): Promise<void>;
package/dist/skills.js CHANGED
@@ -1,28 +1,36 @@
1
+ import { createHash } from "node:crypto";
1
2
  import { mkdir, readFile, rm } from "node:fs/promises";
2
3
  import { dirname, join } from "node:path";
3
4
  import { fileURLToPath } from "node:url";
5
+ import { isConfigured } from "./adapters/index.js";
4
6
  import { atomicWrite, backup, readOptional, restore } from "./fs-safe.js";
5
7
  import { clientProfiles, skillTiers } from "./clients.js";
6
8
  import { sandbaseHome } from "./paths.js";
7
9
  const ownershipMarker = "<!-- sandbase-cli-managed: sandbase -->";
8
- export function skillPath(client, env = process.env) {
10
+ const sharedClients = ["cursor", "codex"];
11
+ function sha256(content) { return createHash("sha256").update(content, "utf8").digest("hex"); }
12
+ function sharedRoot(env = process.env) { const home = env.HOME || sandbaseHome(env); return join(home, ".agents", "skills", "sandbase"); }
13
+ export function sharedSkillPath(env = process.env) { return join(sharedRoot(env), "SKILL.md"); }
14
+ function metadataPath(env = process.env) { return join(sharedRoot(env), ".sandbase-managed.json"); }
15
+ function legacySkillPath(client, env = process.env) {
9
16
  const home = env.HOME || sandbaseHome(env);
10
- if (client === "claude-code")
11
- return join(home, ".claude", "skills", "sandbase", "SKILL.md");
17
+ if (client === "cursor")
18
+ return join(home, ".cursor", "skills", "sandbase", "SKILL.md");
12
19
  if (client === "codex")
13
20
  return join(env.CODEX_HOME || join(home, ".codex"), "skills", "sandbase", "SKILL.md");
14
21
  return undefined;
15
22
  }
23
+ export function skillPath(client, env = process.env) { return sharedClients.includes(client) ? sharedSkillPath(env) : undefined; }
16
24
  export function skillFallback(client) {
17
- if (client === "cursor" || client === "hermes")
25
+ if (client === "claude-code" || client === "hermes")
18
26
  return `${clientProfiles[client].label} native SandBase Skill is not available yet. Use the configured SandBase MCP tools directly in chat.`;
19
27
  return "No native SandBase Skill is available for this client. Use the configured SandBase MCP tools directly.";
20
28
  }
21
- export function skillInvocation(client) { return client === "claude-code" ? "Type / and select /sandbase to get SandBase MCP tool guidance." : "Open Codex's Skill picker and select SandBase, or reference $sandbase where that native affordance is available."; }
22
- function nativeTier(client) { const tier = skillTiers[client]; return tier === "s1_slash" || tier === "s2_skill"; }
23
- function isOwned(content) { return content.includes(ownershipMarker) && /^name:\s*sandbase\s*$/m.test(content); }
24
- async function asset() {
25
- const bundled = fileURLToPath(new URL("../assets/skills/sandbase/SKILL.md", import.meta.url));
29
+ export function skillInvocation(client) { return `${clientProfiles[client].label} uses the shared SandBase Skill. Restart the client, type /, and look for /sandbase; real-client verification is pending.`; }
30
+ function nativeTier(client) { return skillTiers[client] === "s3_promotion"; }
31
+ function marked(content) { return content.includes(ownershipMarker) && /^name:\s*sandbase\s*$/m.test(content); }
32
+ async function asset(relative = "../assets/skills/sandbase/SKILL.md") {
33
+ const bundled = fileURLToPath(new URL(relative, import.meta.url));
26
34
  try {
27
35
  return await readFile(bundled, "utf8");
28
36
  }
@@ -32,58 +40,145 @@ async function asset() {
32
40
  return readFile(join(process.cwd(), "assets", "skills", "sandbase", "SKILL.md"), "utf8");
33
41
  }
34
42
  }
43
+ async function sharedOwnership(env = process.env) {
44
+ const [skill, metadata] = await Promise.all([readOptional(sharedSkillPath(env)), readOptional(metadataPath(env))]);
45
+ if (!skill && !metadata)
46
+ return "missing";
47
+ if (!skill || !metadata || !marked(skill))
48
+ return "ambiguous";
49
+ try {
50
+ const parsed = JSON.parse(metadata);
51
+ return parsed.owner === "sandbase-cli" && parsed.sha256 === sha256(skill) ? "owned" : "ambiguous";
52
+ }
53
+ catch {
54
+ return "ambiguous";
55
+ }
56
+ }
57
+ async function withLock(env, work) {
58
+ const lock = join(dirname(sharedRoot(env)), ".sandbase-skill.lock");
59
+ await mkdir(dirname(lock), { recursive: true, mode: 0o700 });
60
+ for (let attempt = 0; attempt < 100; attempt++) {
61
+ try {
62
+ await mkdir(lock, { mode: 0o700 });
63
+ try {
64
+ return await work();
65
+ }
66
+ finally {
67
+ await rm(lock, { recursive: true, force: true });
68
+ }
69
+ }
70
+ catch (error) {
71
+ if (error.code !== "EEXIST")
72
+ throw error;
73
+ await new Promise(resolve => setTimeout(resolve, 20));
74
+ }
75
+ }
76
+ throw new Error("Another SandBase Skill installation is still running. Retry after it finishes.");
77
+ }
78
+ async function legacyCopies(env) {
79
+ const copies = [];
80
+ for (const client of sharedClients) {
81
+ const path = legacySkillPath(client, env);
82
+ const content = await readOptional(path);
83
+ if (content)
84
+ copies.push({ client, path, content });
85
+ }
86
+ return copies;
87
+ }
88
+ function verifiedLegacy(content) { return marked(content); }
89
+ export async function sharedSkillReferences(env = process.env) { const refs = []; for (const client of sharedClients)
90
+ if (await isConfigured(client, env))
91
+ refs.push(client); return refs; }
92
+ export async function probeSkill(client, env = process.env) {
93
+ if (!nativeTier(client))
94
+ return { compatible: true, message: "No promotion probe is required." };
95
+ try {
96
+ if ((await sharedOwnership(env)) === "ambiguous")
97
+ return { compatible: false, message: "The shared SandBase Skill ownership or checksum is invalid. It was left untouched; resolve it manually, then retry." };
98
+ const copies = await legacyCopies(env);
99
+ const unknown = copies.find(copy => !verifiedLegacy(copy.content));
100
+ if (unknown)
101
+ return { compatible: false, message: `An unmanaged legacy ${clientProfiles[unknown.client].label} SandBase Skill was left untouched. Resolve it manually, then retry.` };
102
+ return { compatible: true, message: "Shared Agent Skills root is available for installation." };
103
+ }
104
+ catch {
105
+ return { compatible: false, message: "The shared Agent Skills root is not readable. Check its local configuration and retry." };
106
+ }
107
+ }
35
108
  export async function inspectSkill(client, env = process.env) {
36
109
  const tier = skillTiers[client];
37
110
  if (tier === "s3_fallback")
38
111
  return "fallback";
39
112
  if (tier === "s4_none")
40
113
  return "unsupported";
41
- const current = await readOptional(skillPath(client, env));
42
- return !current ? "missing" : isOwned(current) ? "installed" : "modified";
114
+ const ownership = await sharedOwnership(env);
115
+ return ownership === "owned" ? "installed" : ownership === "missing" ? "missing" : "modified";
43
116
  }
44
117
  export async function installSkill(client, env = process.env) {
45
118
  if (!nativeTier(client)) {
46
119
  const fallback = skillTiers[client] === "s3_fallback";
47
120
  return { state: fallback ? "fallback" : "skipped", message: fallback ? skillFallback(client) : "No native SandBase Skill is available for this client.", changed: false };
48
121
  }
49
- const path = skillPath(client, env);
50
- const desired = await asset();
51
- const current = await readOptional(path);
52
- if (current && !isOwned(current))
53
- throw new Error(`Refusing to overwrite an unmanaged ${clientProfiles[client].label} SandBase Skill artifact. Resolve it manually, then retry.`);
54
- if (current === desired)
55
- return { state: "already_configured", message: skillInvocation(client), path, changed: false };
56
- await mkdir(dirname(path), { recursive: true, mode: 0o700 });
57
- const backupPath = await backup(path);
58
- try {
59
- await atomicWrite(path, desired, 0o600);
60
- if ((await readOptional(path)) !== desired || !isOwned(desired))
61
- throw new Error("Native Skill verification failed");
62
- }
63
- catch (error) {
64
- await restore(path, backupPath);
65
- throw error;
66
- }
67
- return backupPath ? { state: "configured", message: skillInvocation(client), path, backup: backupPath, changed: true } : { state: "configured", message: skillInvocation(client), path, changed: true };
122
+ return withLock(env, async () => {
123
+ const probe = await probeSkill(client, env);
124
+ if (!probe.compatible)
125
+ throw new Error(probe.message);
126
+ const desired = await asset();
127
+ const skillPath = sharedSkillPath(env);
128
+ const metaPath = metadataPath(env);
129
+ const metadata = JSON.stringify({ owner: "sandbase-cli", sha256: sha256(desired) }) + "\n";
130
+ const current = await readOptional(skillPath);
131
+ const copies = await legacyCopies(env);
132
+ const needsWrite = current !== desired || await sharedOwnership(env) !== "owned";
133
+ const skillBackup = await backup(skillPath);
134
+ const metaBackup = await backup(metaPath);
135
+ const legacyBackups = await Promise.all(copies.map(async (copy) => ({ ...copy, backup: await backup(copy.path) })));
136
+ try {
137
+ if (needsWrite) {
138
+ await atomicWrite(skillPath, desired, 0o600);
139
+ await atomicWrite(metaPath, metadata, 0o600);
140
+ }
141
+ if (await sharedOwnership(env) !== "owned")
142
+ throw new Error("Shared native Skill verification failed");
143
+ for (const copy of copies)
144
+ await rm(copy.path);
145
+ }
146
+ catch (error) {
147
+ await restore(skillPath, skillBackup);
148
+ await restore(metaPath, metaBackup);
149
+ await Promise.all(legacyBackups.map(copy => restore(copy.path, copy.backup)));
150
+ throw error;
151
+ }
152
+ const changed = needsWrite || copies.length > 0;
153
+ return skillBackup ? { state: changed ? "configured" : "already_configured", message: skillInvocation(client), path: skillPath, backup: skillBackup, changed } : { state: changed ? "configured" : "already_configured", message: skillInvocation(client), path: skillPath, changed };
154
+ });
68
155
  }
69
156
  export async function rollbackSkill(result) { if (result.changed && result.path)
70
157
  await restore(result.path, result.backup); }
71
158
  export async function removeSkill(client, env = process.env) {
72
159
  if (!nativeTier(client))
73
160
  return false;
74
- const path = skillPath(client, env);
75
- const current = await readOptional(path);
76
- if (!current)
77
- return false;
78
- if (!isOwned(current))
79
- throw new Error(`Refusing to remove an unmanaged ${clientProfiles[client].label} SandBase Skill artifact. Remove it manually if intended.`);
80
- const backupPath = await backup(path);
81
- try {
82
- await rm(path);
83
- }
84
- catch (error) {
85
- await restore(path, backupPath);
86
- throw error;
87
- }
88
- return true;
161
+ return withLock(env, async () => {
162
+ if ((await sharedSkillReferences(env)).length)
163
+ return false;
164
+ const ownership = await sharedOwnership(env);
165
+ if (ownership === "missing")
166
+ return false;
167
+ if (ownership !== "owned")
168
+ throw new Error("The shared SandBase Skill ownership or checksum is invalid. It was left untouched; remove it manually if intended.");
169
+ const skillPath = sharedSkillPath(env);
170
+ const metaPath = metadataPath(env);
171
+ const skillBackup = await backup(skillPath);
172
+ const metaBackup = await backup(metaPath);
173
+ try {
174
+ await rm(skillPath);
175
+ await rm(metaPath);
176
+ }
177
+ catch (error) {
178
+ await restore(skillPath, skillBackup);
179
+ await restore(metaPath, metaBackup);
180
+ throw error;
181
+ }
182
+ return true;
183
+ });
89
184
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sandbaseai/cli",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Secure SandBase MCP onboarding CLI",
5
5
  "type": "module",
6
6
  "bin": {