@sandbaseai/cli 0.1.4 → 0.1.6
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.
- package/assets/skills/sandbase/SKILL.md +1 -0
- package/dist/adapters/index.js +44 -10
- package/dist/clients.d.ts +42 -1
- package/dist/clients.js +71 -2
- package/dist/commands.d.ts +1 -1
- package/dist/commands.js +43 -10
- package/dist/skills.d.ts +9 -0
- package/dist/skills.js +220 -39
- package/package.json +1 -1
package/dist/adapters/index.js
CHANGED
|
@@ -9,13 +9,15 @@ 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
|
-
|
|
13
|
-
|
|
14
|
-
return existsSync(
|
|
12
|
+
const ownershipEnvironment = "SANDBASE_CLI_MANAGED";
|
|
13
|
+
export function detectClient(client) { const profile = clientProfiles[client]; const path = configPath(client); if (!profile.executable)
|
|
14
|
+
return profile.mode === "auto" && existsSync(path) ? { 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"; if (result.status === 0)
|
|
15
|
+
return { installed: true, detail }; if (client === "codex" && existsSync(path))
|
|
16
|
+
return { installed: true, detail: "Codex CLI probe failed; existing Codex configuration detected" }; return { installed: false, detail }; }
|
|
15
17
|
const start = "# >>> sandbase managed >>>", end = "# <<< sandbase managed <<<";
|
|
16
18
|
function block(client, bridge) {
|
|
17
19
|
if (client === "codex")
|
|
18
|
-
return `${start}\n[mcp_servers.sandbase]\ncommand = "node"\nargs = ["${bridge.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}", "--client", "codex"]\n${end}`;
|
|
20
|
+
return `${start}\n[mcp_servers.sandbase]\ncommand = "node"\nargs = ["${bridge.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}", "--client", "codex"]\nenv = { SANDBASE_CLI_MANAGED = "1" }\n${end}`;
|
|
19
21
|
return ` ${start}\n sandbase:\n command: node\n args:\n - ${JSON.stringify(bridge)}\n - --client\n - ${client}\n ${end}`;
|
|
20
22
|
}
|
|
21
23
|
function managedText(raw, value) { const re = new RegExp(`${start.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "m"); return re.test(raw) ? raw.replace(re, value) : raw.replace(/\s*$/, "") + (raw.trim() ? "\n\n" : "") + value + "\n"; }
|
|
@@ -32,12 +34,19 @@ function removeHermesEntry(raw) { const lines = raw.split("\n"); const at = line
|
|
|
32
34
|
} lines.splice(at, end - at); return lines.join("\n"); }
|
|
33
35
|
function hermesUpdate(raw, bridge, client) { const own = block(client, bridge); const cleaned = removeHermesEntry(removeManaged(raw)).replace(/^(mcp_servers:[ \t]*)\n+/m, "$1\n"); if (/^mcp_servers:[ \t]*$/m.test(cleaned))
|
|
34
36
|
return cleaned.replace(/^mcp_servers:[ \t]*$/m, match => `${match}\n${own}`); return cleaned.replace(/\s*$/, "") + (cleaned.trim() ? "\n" : "") + `mcp_servers:\n${own}\n`; }
|
|
37
|
+
function ownedJsonEntry(value, client) { if (!value || typeof value !== "object" || Array.isArray(value))
|
|
38
|
+
return false; const entry = value; return entry.command === "node" && Array.isArray(entry.args) && (client === undefined || entry.args.includes(client)) && entry.env?.[ownershipEnvironment] === "1"; }
|
|
39
|
+
function ownedCodexEntry(value) { if (!value || typeof value !== "object" || Array.isArray(value))
|
|
40
|
+
return false; const entry = value; return entry.command === "node" && Array.isArray(entry.args) && entry.args.length === 3 && typeof entry.args[0] === "string" && entry.args[0].endsWith("sandbase-mcp-bridge.mjs") && entry.args[1] === "--client" && entry.args[2] === "codex" && entry.env?.[ownershipEnvironment] === "1"; }
|
|
35
41
|
function jsonUpdate(raw, client, bridge, remove = false) { const obj = raw ? JSON.parse(raw) : {}; if (!obj || Array.isArray(obj))
|
|
36
42
|
throw new Error("Client configuration root must be an object"); const servers = obj.mcpServers === undefined ? {} : obj.mcpServers; if (!servers || typeof servers !== "object" || Array.isArray(servers))
|
|
37
|
-
throw new Error("mcpServers must be an object"); const map = servers; if (
|
|
38
|
-
|
|
43
|
+
throw new Error("mcpServers must be an object"); const map = servers; const existing = map.sandbase; if (existing !== undefined && !ownedJsonEntry(existing, client))
|
|
44
|
+
throw new Error("A non-SandBase MCP entry named sandbase was left untouched"); if (remove) {
|
|
45
|
+
if (existing !== undefined)
|
|
46
|
+
delete map.sandbase;
|
|
47
|
+
}
|
|
39
48
|
else
|
|
40
|
-
map.sandbase = { command: "node", args: [bridge, "--client", client] }; obj.mcpServers = map; return JSON.stringify(obj, null, 2) + "\n"; }
|
|
49
|
+
map.sandbase = { command: "node", args: [bridge, "--client", client], env: { [ownershipEnvironment]: "1" } }; obj.mcpServers = map; return JSON.stringify(obj, null, 2) + "\n"; }
|
|
41
50
|
function validateText(client, text) { if (!text.trim())
|
|
42
51
|
return; const adapter = clientProfiles[client].adapter; if (adapter === "codex") {
|
|
43
52
|
const value = parseToml(text);
|
|
@@ -65,7 +74,14 @@ export async function configure(client, bridge, env = process.env, io = defaultI
|
|
|
65
74
|
return { path: configPath(client, env), changed: false }; const path = configPath(client, env); const raw = await readOptional(path); let next; try {
|
|
66
75
|
const text = raw || "";
|
|
67
76
|
validateText(client, text);
|
|
68
|
-
|
|
77
|
+
if (profile.adapter === "codex" && /\[mcp_servers\.sandbase\]/.test(text)) {
|
|
78
|
+
const parsed = parseToml(text);
|
|
79
|
+
if (!text.includes(start) || !ownedCodexEntry(parsed.mcp_servers?.sandbase))
|
|
80
|
+
throw new Error("A non-SandBase MCP entry named sandbase was left untouched");
|
|
81
|
+
}
|
|
82
|
+
if (profile.adapter === "yaml" && /^ sandbase:[ \t]*$/m.test(text) && !text.includes(start))
|
|
83
|
+
throw new Error("A non-SandBase MCP entry named sandbase was left untouched");
|
|
84
|
+
next = profile.adapter === "json" ? jsonUpdate(raw, client, bridge) : profile.adapter === "yaml" ? hermesUpdate(text, bridge, client) : managedText(text.includes(start) ? text : text, block(client, bridge));
|
|
69
85
|
validateText(client, next);
|
|
70
86
|
}
|
|
71
87
|
catch {
|
|
@@ -84,6 +100,13 @@ export async function unregister(client, env = process.env) { const profile = cl
|
|
|
84
100
|
return false; const path = configPath(client, env); const raw = await readOptional(path); if (!raw)
|
|
85
101
|
return false; let next; try {
|
|
86
102
|
validateText(client, raw);
|
|
103
|
+
if (profile.adapter !== "json" && !raw.includes(start))
|
|
104
|
+
return false;
|
|
105
|
+
if (profile.adapter === "codex") {
|
|
106
|
+
const parsed = parseToml(raw);
|
|
107
|
+
if (!ownedCodexEntry(parsed.mcp_servers?.sandbase))
|
|
108
|
+
return false;
|
|
109
|
+
}
|
|
87
110
|
next = profile.adapter === "json" ? jsonUpdate(raw, client, "", true) : profile.adapter === "codex" ? removeCodexEntry(removeManaged(raw)) : removeHermesEntry(removeManaged(raw));
|
|
88
111
|
validateText(client, next);
|
|
89
112
|
}
|
|
@@ -102,9 +125,20 @@ export async function isConfigured(client, env = process.env) { const profile =
|
|
|
102
125
|
return false; if (profile.adapter === "json") {
|
|
103
126
|
try {
|
|
104
127
|
const o = JSON.parse(raw);
|
|
105
|
-
return
|
|
128
|
+
return ownedJsonEntry(o.mcpServers?.sandbase, client);
|
|
106
129
|
}
|
|
107
130
|
catch {
|
|
108
131
|
return false;
|
|
109
132
|
}
|
|
110
|
-
}
|
|
133
|
+
} if (!raw.includes(start) || !raw.includes(end))
|
|
134
|
+
return false; try {
|
|
135
|
+
if (profile.adapter === "codex") {
|
|
136
|
+
const parsed = parseToml(raw);
|
|
137
|
+
return ownedCodexEntry(parsed.mcp_servers?.sandbase);
|
|
138
|
+
}
|
|
139
|
+
const parsed = parseDocument(raw).toJS();
|
|
140
|
+
return !!parsed?.mcp_servers?.sandbase;
|
|
141
|
+
}
|
|
142
|
+
catch {
|
|
143
|
+
return false;
|
|
144
|
+
} }
|
package/dist/clients.d.ts
CHANGED
|
@@ -1,6 +1,44 @@
|
|
|
1
1
|
import type { Client } from "./types.js";
|
|
2
2
|
export type InstallMode = "auto" | "manual" | "skill";
|
|
3
|
-
export type SkillTier = "s1_slash" | "
|
|
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
|
+
}
|
|
18
|
+
export type RuntimeStatus = "configured" | "already_configured" | "confirmation_required" | "unsupported" | "failed";
|
|
19
|
+
export type ImplementationState = "implemented" | "blocked";
|
|
20
|
+
export interface Evidence {
|
|
21
|
+
source: string;
|
|
22
|
+
retrieved: string;
|
|
23
|
+
conclusion: string;
|
|
24
|
+
kind: "first_party" | "internal_blocker";
|
|
25
|
+
}
|
|
26
|
+
export interface InstallerDescriptor {
|
|
27
|
+
mcp: "adapter" | "confirmation" | "none";
|
|
28
|
+
skill: "shared" | "private" | "confirmation" | "none";
|
|
29
|
+
}
|
|
30
|
+
export interface ValidatorDescriptor {
|
|
31
|
+
mcp: "read_back" | "confirmation" | "none";
|
|
32
|
+
skill: "ownership_checksum" | "real_client_matrix" | "confirmation" | "none";
|
|
33
|
+
}
|
|
34
|
+
export interface CapabilityV2 {
|
|
35
|
+
evidence: Evidence;
|
|
36
|
+
installer: InstallerDescriptor;
|
|
37
|
+
validator: ValidatorDescriptor;
|
|
38
|
+
implementation: ImplementationState;
|
|
39
|
+
status: RuntimeStatus;
|
|
40
|
+
nextStep: string;
|
|
41
|
+
}
|
|
4
42
|
export interface ClientProfile {
|
|
5
43
|
id: Client;
|
|
6
44
|
label: string;
|
|
@@ -10,5 +48,8 @@ export interface ClientProfile {
|
|
|
10
48
|
}
|
|
11
49
|
export declare const clientProfiles: Record<Client, ClientProfile>;
|
|
12
50
|
export declare const skillTiers: Record<Client, SkillTier>;
|
|
51
|
+
export declare const nativeCapabilities: Record<Client, NativeCapability>;
|
|
52
|
+
export declare const capabilityRegistry: Record<Client, CapabilityV2>;
|
|
53
|
+
export declare function assertNativeCapabilities(): void;
|
|
13
54
|
export declare function clientList(): string;
|
|
14
55
|
export declare function autoClients(): Client[];
|
package/dist/clients.js
CHANGED
|
@@ -25,12 +25,81 @@ export const clientProfiles = {
|
|
|
25
25
|
pi: { id: "pi", label: "Pi", mode: "skill" },
|
|
26
26
|
};
|
|
27
27
|
export const skillTiers = {
|
|
28
|
-
codex: "
|
|
28
|
+
codex: "s3_promotion", "claude-code": "s1_slash", 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: "client_skill", invocation: "slash", verification: "real_client_matrix", guide: guide("Claude Code", "Restart Claude Code; native Skill discovery remains unverified until the real-client matrix is complete.", "SandBase MCP tools and the private Skill are installed."), 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: "none", skillMode: "none", invocation: "none", verification: "user_action", guide: guide("Cursor CLI", "No independent MCP configuration schema is available yet.", "Do not reuse desktop Cursor configuration."), 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
|
+
function v2(client, capability) {
|
|
59
|
+
const evidence = {
|
|
60
|
+
codex: { source: "https://developers.openai.com/codex/skills/", retrieved: "2026-07-29", conclusion: "Codex supports SKILL.md; the existing B-063 adapter provides the MCP transaction.", kind: "first_party" },
|
|
61
|
+
"claude-code": { source: "https://docs.anthropic.com/en/docs/claude-code/skills", retrieved: "2026-07-29", conclusion: "Personal Skills use ~/.claude/skills/<skill-name>/SKILL.md and the directory name maps to its command.", kind: "first_party" },
|
|
62
|
+
cursor: { source: "https://docs.cursor.com/context/skills", retrieved: "2026-07-28", conclusion: "The user-level ~/.agents/skills root is discovered by Cursor; UI discovery remains subject to the real-client matrix.", kind: "first_party" },
|
|
63
|
+
};
|
|
64
|
+
const implemented = client === "codex" || client === "claude-code" || client === "cursor";
|
|
65
|
+
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.";
|
|
66
|
+
if (!implemented)
|
|
67
|
+
return {
|
|
68
|
+
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" },
|
|
69
|
+
installer: { mcp: "none", skill: "none" }, validator: { mcp: "none", skill: "none" }, implementation: "blocked", status: "failed", nextStep: blocker,
|
|
70
|
+
};
|
|
71
|
+
const hasSkill = capability.skillMode === "shared_skill" || capability.skillMode === "client_skill";
|
|
72
|
+
return {
|
|
73
|
+
evidence: evidence[client], installer: { mcp: "adapter", skill: client === "claude-code" ? "private" : "shared" },
|
|
74
|
+
validator: { mcp: "read_back", skill: client === "cursor" || client === "claude-code" ? "real_client_matrix" : "ownership_checksum" }, implementation: "implemented", status: "confirmation_required",
|
|
75
|
+
nextStep: capability.guide,
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
export const capabilityRegistry = Object.fromEntries(Object.keys(clientProfiles).map(client => [client, v2(client, nativeCapabilities[client])]));
|
|
79
|
+
export function assertNativeCapabilities() {
|
|
80
|
+
for (const client of Object.keys(clientProfiles)) {
|
|
81
|
+
const capability = nativeCapabilities[client];
|
|
82
|
+
if (!capability || !capability.mcpMode || !capability.skillMode || !capability.invocation || !capability.verification || !capability.guide || !capability.uninstall || !capability.terminal)
|
|
83
|
+
throw new Error(`Invalid native capability for ${client}`);
|
|
84
|
+
const v2 = capabilityRegistry[client];
|
|
85
|
+
if (!v2?.evidence.source || !v2.evidence.retrieved || !v2.evidence.conclusion || !v2.evidence.kind || !v2.installer || !v2.validator || !v2.implementation || !v2.status || !v2.nextStep)
|
|
86
|
+
throw new Error(`Invalid capability v2 for ${client}`);
|
|
87
|
+
if (v2.implementation === "blocked" && (v2.status !== "failed" || v2.installer.mcp !== "none" || v2.installer.skill !== "none" || v2.validator.mcp !== "none" || v2.validator.skill !== "none"))
|
|
88
|
+
throw new Error(`Blocked capability must not be exposed as implemented for ${client}`);
|
|
89
|
+
if (v2.implementation === "implemented" && v2.evidence.kind !== "first_party")
|
|
90
|
+
throw new Error(`Implemented capability lacks first-party evidence for ${client}`);
|
|
91
|
+
if (v2.status === "unsupported" || v2.status === "confirmation_required") {
|
|
92
|
+
if (v2.status === "unsupported" && !v2.evidence.conclusion)
|
|
93
|
+
throw new Error(`Unsupported capability lacks evidence for ${client}`);
|
|
94
|
+
}
|
|
95
|
+
if (v2.status === "confirmation_required" && v2.installer.mcp === "none" && v2.installer.skill === "none")
|
|
96
|
+
throw new Error(`Confirmation cannot replace an installer for ${client}`);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
assertNativeCapabilities();
|
|
31
100
|
export function clientList() {
|
|
32
101
|
return Object.keys(clientProfiles).join("|");
|
|
33
102
|
}
|
|
34
103
|
export function autoClients() {
|
|
35
|
-
return Object.values(clientProfiles).filter(profile => profile.mode === "auto" && !!profile.adapter).map(profile => profile.id);
|
|
104
|
+
return Object.values(clientProfiles).filter(profile => profile.mode === "auto" && !!profile.adapter && capabilityRegistry[profile.id].implementation === "implemented").map(profile => profile.id);
|
|
36
105
|
}
|
package/dist/commands.d.ts
CHANGED
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, capabilityRegistry, 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)
|
|
@@ -19,17 +20,26 @@ async function compensate(api, authorizationId, token) { for (const delay of [0,
|
|
|
19
20
|
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(); }
|
|
20
21
|
function mcpServerSnippet(client, bridgePath) { return JSON.stringify({ mcpServers: { sandbase: { command: "node", args: [bridgePath, "--client", client] } } }, null, 2); }
|
|
21
22
|
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."]; }
|
|
22
|
-
function successMessage(client,
|
|
23
|
+
function successMessage(client, bridgePath) {
|
|
23
24
|
const profile = clientProfiles[client];
|
|
24
25
|
const label = profile.label;
|
|
25
|
-
const common = ["", "SandBase MCP is connected.", "", `Client: ${label} (${client})`,
|
|
26
|
+
const common = ["", "SandBase MCP is connected.", "", `Client: ${label} (${client})`, "Credential was stored locally with restricted permissions."];
|
|
26
27
|
if (profile.mode === "auto")
|
|
27
|
-
return [...common,
|
|
28
|
+
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");
|
|
28
29
|
if (profile.mode === "skill")
|
|
29
30
|
return [...common, "", "Skill/prompt setup required.", `Copy the following instruction into ${label}:`, "", `Install the SandBase MCP bridge for ${label}. Use this local MCP server configuration and keep the scope limited to SandBase:`, mcpServerSnippet(client, bridgePath), `After setup, reload ${label} if needed.`, "", "Next steps:", "1. Finish the skill/prompt setup in ${label}.", ...nextStepPrompts(label), "", 'Manage access: revoke the "CLI Login" key in SandBase Dashboard when you no longer need it.'].join("\n");
|
|
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
|
+
const v2 = capabilityRegistry[client];
|
|
38
|
+
if (!detect(client).installed || (v2.implementation === "implemented" && (capability.mcpMode === "auto" || capability.mcpMode === "desktop")))
|
|
39
|
+
continue;
|
|
40
|
+
log(`${client}: status=${v2.status}, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
|
|
41
|
+
}
|
|
42
|
+
}
|
|
33
43
|
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
44
|
async function restoreCredential(store, client, previous) { if (previous)
|
|
35
45
|
await store.save(previous);
|
|
@@ -38,11 +48,14 @@ else
|
|
|
38
48
|
async function configureSkill(client, log) {
|
|
39
49
|
try {
|
|
40
50
|
const result = await installSkill(client);
|
|
41
|
-
|
|
51
|
+
const status = result.state === "already_configured" ? "already_configured" : result.state === "configured" ? "configured" : "confirmation_required";
|
|
52
|
+
log(`${client}: status=${status}, mcp=configured, skill=${result.state}, invocation=${nativeCapabilities[client].invocation}, next_step=${result.message}`);
|
|
53
|
+
return status;
|
|
42
54
|
}
|
|
43
55
|
catch (error) {
|
|
44
56
|
const message = error instanceof Error ? error.message : "Unknown native Skill failure";
|
|
45
|
-
log(
|
|
57
|
+
log(`${client}: status=failed, mcp=configured, skill=failed, invocation=${nativeCapabilities[client].invocation}, next_step=${message}`);
|
|
58
|
+
return "failed";
|
|
46
59
|
}
|
|
47
60
|
}
|
|
48
61
|
async function connectOne(client, deps) {
|
|
@@ -51,6 +64,17 @@ async function connectOne(client, deps) {
|
|
|
51
64
|
const log = deps.log || console.log;
|
|
52
65
|
const detect = deps.detect || detectClient;
|
|
53
66
|
const profile = clientProfiles[client];
|
|
67
|
+
const capability = nativeCapabilities[client];
|
|
68
|
+
const v2 = capabilityRegistry[client];
|
|
69
|
+
if (v2.implementation === "blocked") {
|
|
70
|
+
log(`${client}: status=failed, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
|
|
71
|
+
return;
|
|
72
|
+
}
|
|
73
|
+
if (capability.mcpMode === "manual" || capability.mcpMode === "none") {
|
|
74
|
+
const v2 = capabilityRegistry[client];
|
|
75
|
+
log(`${client}: status=${v2.status}, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
54
78
|
const detected = detect(client);
|
|
55
79
|
if (!detected.installed)
|
|
56
80
|
throw new Error(`${profile.label} is not installed or is incompatible. Install a supported version, then retry.`);
|
|
@@ -65,7 +89,7 @@ async function connectOne(client, deps) {
|
|
|
65
89
|
configured = await configure(client, bridgeResult.path);
|
|
66
90
|
if (profile.mode === "auto" && !(await isConfigured(client)))
|
|
67
91
|
throw new Error("Client configuration verification failed");
|
|
68
|
-
log(successMessage(client,
|
|
92
|
+
log(successMessage(client, bridgeResult.path));
|
|
69
93
|
await configureSkill(client, log);
|
|
70
94
|
exchange.cleanup_token = "";
|
|
71
95
|
}
|
|
@@ -89,6 +113,7 @@ async function connectAuto(deps) {
|
|
|
89
113
|
const targets = plannedAutoClients(detect);
|
|
90
114
|
if (!targets.length) {
|
|
91
115
|
log("No installed compatible clients support automatic configuration. Use --client <client> for manual or skill setup guidance.");
|
|
116
|
+
logDetectedActionRequired(detect, log);
|
|
92
117
|
return;
|
|
93
118
|
}
|
|
94
119
|
const { authorizationId, exchange } = await authorize(api, "auto", { open: deps.open || openBrowser, sleep, log, ...(deps.signal ? { signal: deps.signal } : {}) });
|
|
@@ -120,6 +145,7 @@ async function connectAuto(deps) {
|
|
|
120
145
|
log(`Configured clients: ${succeeded.join(", ")}.`);
|
|
121
146
|
if (failed.length)
|
|
122
147
|
log(`Partial success: failed clients were rolled back: ${failed.join(", ")}.`);
|
|
148
|
+
logDetectedActionRequired(detect, log);
|
|
123
149
|
exchange.cleanup_token = "";
|
|
124
150
|
}
|
|
125
151
|
catch (e) {
|
|
@@ -146,8 +172,11 @@ export async function doctor(client = "auto", store = new FileCredentialStore(),
|
|
|
146
172
|
const configured = profile.mode === "auto" ? await isConfigured(target) : !!credential;
|
|
147
173
|
const detected = detect(target);
|
|
148
174
|
const skill = await inspectSkill(target);
|
|
149
|
-
const
|
|
150
|
-
|
|
175
|
+
const capability = nativeCapabilities[target];
|
|
176
|
+
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." : capabilityRegistry[target].nextStep;
|
|
177
|
+
const references = await sharedSkillReferences();
|
|
178
|
+
const status = configured && !!credential && skill === "installed" ? "configured" : "failed";
|
|
179
|
+
console.log(`${target}: status=${status}, mcp=${configured ? "configured" : "not_configured"}, skill=${skill}, invocation=${capability.invocation}, verification=${capability.verification}, shared_skill_references=${references.join(",") || "none"}, next_step=${skillDetail}`);
|
|
151
180
|
healthy = healthy && detected.installed && !!credential && configured && !["missing", "modified"].includes(skill);
|
|
152
181
|
}
|
|
153
182
|
return healthy;
|
|
@@ -159,6 +188,10 @@ export async function unregister(client = "auto", store = new FileCredentialStor
|
|
|
159
188
|
return;
|
|
160
189
|
}
|
|
161
190
|
for (const target of targets) {
|
|
191
|
+
if (capabilityRegistry[target].implementation === "blocked") {
|
|
192
|
+
console.log(`${target}: status=failed, next_step=${capabilityRegistry[target].nextStep}`);
|
|
193
|
+
continue;
|
|
194
|
+
}
|
|
162
195
|
const removed = await removeAdapter(target);
|
|
163
196
|
const removedSkill = await removeSkill(target);
|
|
164
197
|
await store.remove(target);
|
package/dist/skills.d.ts
CHANGED
|
@@ -5,11 +5,20 @@ export interface SkillInstallResult {
|
|
|
5
5
|
message: string;
|
|
6
6
|
path?: string;
|
|
7
7
|
backup?: string;
|
|
8
|
+
metadataPath?: string;
|
|
9
|
+
metadataBackup?: string | undefined;
|
|
8
10
|
changed: boolean;
|
|
9
11
|
}
|
|
12
|
+
export interface SkillProbe {
|
|
13
|
+
compatible: boolean;
|
|
14
|
+
message: string;
|
|
15
|
+
}
|
|
16
|
+
export declare function sharedSkillPath(env?: NodeJS.ProcessEnv): string;
|
|
10
17
|
export declare function skillPath(client: Client, env?: NodeJS.ProcessEnv): string | undefined;
|
|
11
18
|
export declare function skillFallback(client: Client): string;
|
|
12
19
|
export declare function skillInvocation(client: Client): string;
|
|
20
|
+
export declare function sharedSkillReferences(env?: NodeJS.ProcessEnv): Promise<Client[]>;
|
|
21
|
+
export declare function probeSkill(client: Client, env?: NodeJS.ProcessEnv): Promise<SkillProbe>;
|
|
13
22
|
export declare function inspectSkill(client: Client, env?: NodeJS.ProcessEnv): Promise<SkillState>;
|
|
14
23
|
export declare function installSkill(client: Client, env?: NodeJS.ProcessEnv): Promise<SkillInstallResult>;
|
|
15
24
|
export declare function rollbackSkill(result: SkillInstallResult): Promise<void>;
|
package/dist/skills.js
CHANGED
|
@@ -1,28 +1,40 @@
|
|
|
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
|
-
|
|
10
|
+
const sharedClients = ["cursor", "codex"];
|
|
11
|
+
const privateClients = ["claude-code"];
|
|
12
|
+
function sha256(content) { return createHash("sha256").update(content, "utf8").digest("hex"); }
|
|
13
|
+
function sharedRoot(env = process.env) { const home = env.HOME || sandbaseHome(env); return join(home, ".agents", "skills", "sandbase"); }
|
|
14
|
+
export function sharedSkillPath(env = process.env) { return join(sharedRoot(env), "SKILL.md"); }
|
|
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; }
|
|
17
|
+
function privateSkillPath(client, env = process.env) { const root = privateRoot(client, env); return root ? join(root, "SKILL.md") : undefined; }
|
|
18
|
+
function privateMetadataPath(client, env = process.env) { const root = privateRoot(client, env); return root ? join(root, ".sandbase-managed.json") : undefined; }
|
|
19
|
+
function legacySkillPath(client, env = process.env) {
|
|
9
20
|
const home = env.HOME || sandbaseHome(env);
|
|
10
|
-
if (client === "
|
|
11
|
-
return join(home, ".
|
|
21
|
+
if (client === "cursor")
|
|
22
|
+
return join(home, ".cursor", "skills", "sandbase", "SKILL.md");
|
|
12
23
|
if (client === "codex")
|
|
13
24
|
return join(env.CODEX_HOME || join(home, ".codex"), "skills", "sandbase", "SKILL.md");
|
|
14
25
|
return undefined;
|
|
15
26
|
}
|
|
27
|
+
export function skillPath(client, env = process.env) { return sharedClients.includes(client) ? sharedSkillPath(env) : privateSkillPath(client, env); }
|
|
16
28
|
export function skillFallback(client) {
|
|
17
|
-
if (client === "
|
|
29
|
+
if (client === "claude-code" || client === "hermes")
|
|
18
30
|
return `${clientProfiles[client].label} native SandBase Skill is not available yet. Use the configured SandBase MCP tools directly in chat.`;
|
|
19
31
|
return "No native SandBase Skill is available for this client. Use the configured SandBase MCP tools directly.";
|
|
20
32
|
}
|
|
21
|
-
export function skillInvocation(client) { return client
|
|
22
|
-
function nativeTier(client) {
|
|
23
|
-
function
|
|
24
|
-
async function asset() {
|
|
25
|
-
const bundled = fileURLToPath(new URL(
|
|
33
|
+
export function skillInvocation(client) { return `${clientProfiles[client].label} has a SandBase Skill artifact installed. Native discovery remains unverified until the real-client matrix is complete.`; }
|
|
34
|
+
function nativeTier(client) { return skillTiers[client] === "s3_promotion" || skillTiers[client] === "s1_slash"; }
|
|
35
|
+
function marked(content) { return content.includes(ownershipMarker) && /^name:\s*sandbase\s*$/m.test(content); }
|
|
36
|
+
async function asset(relative = "../assets/skills/sandbase/SKILL.md") {
|
|
37
|
+
const bundled = fileURLToPath(new URL(relative, import.meta.url));
|
|
26
38
|
try {
|
|
27
39
|
return await readFile(bundled, "utf8");
|
|
28
40
|
}
|
|
@@ -32,57 +44,226 @@ async function asset() {
|
|
|
32
44
|
return readFile(join(process.cwd(), "assets", "skills", "sandbase", "SKILL.md"), "utf8");
|
|
33
45
|
}
|
|
34
46
|
}
|
|
47
|
+
async function sharedOwnership(env = process.env) {
|
|
48
|
+
const [skill, metadata] = await Promise.all([readOptional(sharedSkillPath(env)), readOptional(metadataPath(env))]);
|
|
49
|
+
if (!skill && !metadata)
|
|
50
|
+
return "missing";
|
|
51
|
+
if (!skill || !metadata || !marked(skill))
|
|
52
|
+
return "ambiguous";
|
|
53
|
+
try {
|
|
54
|
+
const parsed = JSON.parse(metadata);
|
|
55
|
+
return parsed.owner === "sandbase-cli" && parsed.sha256 === sha256(skill) ? "owned" : "ambiguous";
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
return "ambiguous";
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
async function privateOwnership(client, env = process.env) {
|
|
62
|
+
const skill = privateSkillPath(client, env);
|
|
63
|
+
const metadata = privateMetadataPath(client, env);
|
|
64
|
+
if (!skill || !metadata)
|
|
65
|
+
return "missing";
|
|
66
|
+
const [content, meta] = await Promise.all([readOptional(skill), readOptional(metadata)]);
|
|
67
|
+
if (!content && !meta)
|
|
68
|
+
return "missing";
|
|
69
|
+
if (!content || !meta || !marked(content))
|
|
70
|
+
return "ambiguous";
|
|
71
|
+
try {
|
|
72
|
+
const parsed = JSON.parse(meta);
|
|
73
|
+
return parsed.owner === "sandbase-cli" && parsed.client === client && parsed.sha256 === sha256(content) ? "owned" : "ambiguous";
|
|
74
|
+
}
|
|
75
|
+
catch {
|
|
76
|
+
return "ambiguous";
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
async function withLock(env, work) {
|
|
80
|
+
const lock = join(dirname(sharedRoot(env)), ".sandbase-skill.lock");
|
|
81
|
+
await mkdir(dirname(lock), { recursive: true, mode: 0o700 });
|
|
82
|
+
for (let attempt = 0; attempt < 100; attempt++) {
|
|
83
|
+
try {
|
|
84
|
+
await mkdir(lock, { mode: 0o700 });
|
|
85
|
+
try {
|
|
86
|
+
return await work();
|
|
87
|
+
}
|
|
88
|
+
finally {
|
|
89
|
+
await rm(lock, { recursive: true, force: true });
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
catch (error) {
|
|
93
|
+
if (error.code !== "EEXIST")
|
|
94
|
+
throw error;
|
|
95
|
+
await new Promise(resolve => setTimeout(resolve, 20));
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
throw new Error("Another SandBase Skill installation is still running. Retry after it finishes.");
|
|
99
|
+
}
|
|
100
|
+
async function legacyCopies(env) {
|
|
101
|
+
const copies = [];
|
|
102
|
+
for (const client of ["cursor", "codex"]) {
|
|
103
|
+
const path = legacySkillPath(client, env);
|
|
104
|
+
const content = await readOptional(path);
|
|
105
|
+
if (content)
|
|
106
|
+
copies.push({ client, path, content });
|
|
107
|
+
}
|
|
108
|
+
return copies;
|
|
109
|
+
}
|
|
110
|
+
function verifiedLegacy(content) { return marked(content); }
|
|
111
|
+
export async function sharedSkillReferences(env = process.env) { const refs = []; for (const client of sharedClients)
|
|
112
|
+
if (await isConfigured(client, env))
|
|
113
|
+
refs.push(client); return refs; }
|
|
114
|
+
export async function probeSkill(client, env = process.env) {
|
|
115
|
+
if (!nativeTier(client))
|
|
116
|
+
return { compatible: true, message: "No promotion probe is required." };
|
|
117
|
+
try {
|
|
118
|
+
if (privateClients.includes(client)) {
|
|
119
|
+
if ((await privateOwnership(client, env)) === "ambiguous")
|
|
120
|
+
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.` };
|
|
122
|
+
}
|
|
123
|
+
if ((await sharedOwnership(env)) === "ambiguous")
|
|
124
|
+
return { compatible: false, message: "The shared SandBase Skill ownership or checksum is invalid. It was left untouched; resolve it manually, then retry." };
|
|
125
|
+
const copies = await legacyCopies(env);
|
|
126
|
+
const unknown = copies.find(copy => !verifiedLegacy(copy.content));
|
|
127
|
+
if (unknown)
|
|
128
|
+
return { compatible: false, message: `An unmanaged legacy ${clientProfiles[unknown.client].label} SandBase Skill was left untouched. Resolve it manually, then retry.` };
|
|
129
|
+
return { compatible: true, message: "Shared Agent Skills root is available for installation." };
|
|
130
|
+
}
|
|
131
|
+
catch {
|
|
132
|
+
return { compatible: false, message: "The shared Agent Skills root is not readable. Check its local configuration and retry." };
|
|
133
|
+
}
|
|
134
|
+
}
|
|
35
135
|
export async function inspectSkill(client, env = process.env) {
|
|
36
136
|
const tier = skillTiers[client];
|
|
37
137
|
if (tier === "s3_fallback")
|
|
38
138
|
return "fallback";
|
|
39
139
|
if (tier === "s4_none")
|
|
40
140
|
return "unsupported";
|
|
41
|
-
|
|
42
|
-
|
|
141
|
+
if (privateClients.includes(client)) {
|
|
142
|
+
const ownership = await privateOwnership(client, env);
|
|
143
|
+
return ownership === "owned" ? "installed" : ownership === "missing" ? "missing" : "modified";
|
|
144
|
+
}
|
|
145
|
+
const ownership = await sharedOwnership(env);
|
|
146
|
+
return ownership === "owned" ? "installed" : ownership === "missing" ? "missing" : "modified";
|
|
43
147
|
}
|
|
44
148
|
export async function installSkill(client, env = process.env) {
|
|
45
149
|
if (!nativeTier(client)) {
|
|
46
150
|
const fallback = skillTiers[client] === "s3_fallback";
|
|
47
151
|
return { state: fallback ? "fallback" : "skipped", message: fallback ? skillFallback(client) : "No native SandBase Skill is available for this client.", changed: false };
|
|
48
152
|
}
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
await
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
await
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
153
|
+
if (privateClients.includes(client))
|
|
154
|
+
return installPrivateSkill(client, env);
|
|
155
|
+
return withLock(env, async () => {
|
|
156
|
+
const probe = await probeSkill(client, env);
|
|
157
|
+
if (!probe.compatible)
|
|
158
|
+
throw new Error(probe.message);
|
|
159
|
+
const desired = await asset();
|
|
160
|
+
const skillPath = sharedSkillPath(env);
|
|
161
|
+
const metaPath = metadataPath(env);
|
|
162
|
+
const metadata = JSON.stringify({ owner: "sandbase-cli", sha256: sha256(desired) }) + "\n";
|
|
163
|
+
const current = await readOptional(skillPath);
|
|
164
|
+
const copies = await legacyCopies(env);
|
|
165
|
+
const needsWrite = current !== desired || await sharedOwnership(env) !== "owned";
|
|
166
|
+
const skillBackup = await backup(skillPath);
|
|
167
|
+
const metaBackup = await backup(metaPath);
|
|
168
|
+
const legacyBackups = await Promise.all(copies.map(async (copy) => ({ ...copy, backup: await backup(copy.path) })));
|
|
169
|
+
try {
|
|
170
|
+
if (needsWrite) {
|
|
171
|
+
await atomicWrite(skillPath, desired, 0o600);
|
|
172
|
+
await atomicWrite(metaPath, metadata, 0o600);
|
|
173
|
+
}
|
|
174
|
+
if (await sharedOwnership(env) !== "owned")
|
|
175
|
+
throw new Error("Shared native Skill verification failed");
|
|
176
|
+
for (const copy of copies)
|
|
177
|
+
await rm(copy.path);
|
|
178
|
+
}
|
|
179
|
+
catch (error) {
|
|
180
|
+
await restore(skillPath, skillBackup);
|
|
181
|
+
await restore(metaPath, metaBackup);
|
|
182
|
+
await Promise.all(legacyBackups.map(copy => restore(copy.path, copy.backup)));
|
|
183
|
+
throw error;
|
|
184
|
+
}
|
|
185
|
+
const changed = needsWrite || copies.length > 0;
|
|
186
|
+
return skillBackup ? { state: changed ? "configured" : "already_configured", message: skillInvocation(client), path: skillPath, backup: skillBackup, metadataPath: metaPath, metadataBackup: metaBackup, changed } : { state: changed ? "configured" : "already_configured", message: skillInvocation(client), path: skillPath, metadataPath: metaPath, metadataBackup: metaBackup, changed };
|
|
187
|
+
});
|
|
68
188
|
}
|
|
69
|
-
|
|
70
|
-
|
|
189
|
+
async function installPrivateSkill(client, env) {
|
|
190
|
+
const path = privateSkillPath(client, env);
|
|
191
|
+
const meta = privateMetadataPath(client, env);
|
|
192
|
+
return withLock(env, async () => {
|
|
193
|
+
const probe = await probeSkill(client, env);
|
|
194
|
+
if (!probe.compatible)
|
|
195
|
+
throw new Error(probe.message);
|
|
196
|
+
const desired = await asset();
|
|
197
|
+
const desiredMeta = JSON.stringify({ owner: "sandbase-cli", client, sha256: sha256(desired) }) + "\n";
|
|
198
|
+
const current = await readOptional(path);
|
|
199
|
+
const needsWrite = current !== desired || await privateOwnership(client, env) !== "owned";
|
|
200
|
+
const skillBackup = await backup(path);
|
|
201
|
+
const metaBackup = await backup(meta);
|
|
202
|
+
try {
|
|
203
|
+
if (needsWrite) {
|
|
204
|
+
await atomicWrite(path, desired, 0o600);
|
|
205
|
+
await atomicWrite(meta, desiredMeta, 0o600);
|
|
206
|
+
}
|
|
207
|
+
if (await privateOwnership(client, env) !== "owned")
|
|
208
|
+
throw new Error(`${clientProfiles[client].label} native Skill verification failed`);
|
|
209
|
+
}
|
|
210
|
+
catch (error) {
|
|
211
|
+
await restore(path, skillBackup);
|
|
212
|
+
await restore(meta, metaBackup);
|
|
213
|
+
throw error;
|
|
214
|
+
}
|
|
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 };
|
|
216
|
+
});
|
|
217
|
+
}
|
|
218
|
+
export async function rollbackSkill(result) { if (!result.changed || !result.path)
|
|
219
|
+
return; await restore(result.path, result.backup); if (result.metadataPath)
|
|
220
|
+
await restore(result.metadataPath, result.metadataBackup); }
|
|
71
221
|
export async function removeSkill(client, env = process.env) {
|
|
72
222
|
if (!nativeTier(client))
|
|
73
223
|
return false;
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
224
|
+
if (privateClients.includes(client))
|
|
225
|
+
return removePrivateSkill(client, env);
|
|
226
|
+
return withLock(env, async () => {
|
|
227
|
+
if ((await sharedSkillReferences(env)).length)
|
|
228
|
+
return false;
|
|
229
|
+
const ownership = await sharedOwnership(env);
|
|
230
|
+
if (ownership === "missing")
|
|
231
|
+
return false;
|
|
232
|
+
if (ownership !== "owned")
|
|
233
|
+
throw new Error("The shared SandBase Skill ownership or checksum is invalid. It was left untouched; remove it manually if intended.");
|
|
234
|
+
const skillPath = sharedSkillPath(env);
|
|
235
|
+
const metaPath = metadataPath(env);
|
|
236
|
+
const skillBackup = await backup(skillPath);
|
|
237
|
+
const metaBackup = await backup(metaPath);
|
|
238
|
+
try {
|
|
239
|
+
await rm(skillPath);
|
|
240
|
+
await rm(metaPath);
|
|
241
|
+
}
|
|
242
|
+
catch (error) {
|
|
243
|
+
await restore(skillPath, skillBackup);
|
|
244
|
+
await restore(metaPath, metaBackup);
|
|
245
|
+
throw error;
|
|
246
|
+
}
|
|
247
|
+
return true;
|
|
248
|
+
});
|
|
249
|
+
}
|
|
250
|
+
async function removePrivateSkill(client, env) {
|
|
251
|
+
const path = privateSkillPath(client, env);
|
|
252
|
+
const meta = privateMetadataPath(client, env);
|
|
253
|
+
const ownership = await privateOwnership(client, env);
|
|
254
|
+
if (ownership === "missing")
|
|
77
255
|
return false;
|
|
78
|
-
if (
|
|
79
|
-
throw new Error(`
|
|
80
|
-
const
|
|
256
|
+
if (ownership !== "owned")
|
|
257
|
+
throw new Error(`The ${clientProfiles[client].label} SandBase Skill ownership or checksum is invalid. It was left untouched; remove it manually if intended.`);
|
|
258
|
+
const skillBackup = await backup(path);
|
|
259
|
+
const metaBackup = await backup(meta);
|
|
81
260
|
try {
|
|
82
261
|
await rm(path);
|
|
262
|
+
await rm(meta);
|
|
83
263
|
}
|
|
84
264
|
catch (error) {
|
|
85
|
-
await restore(path,
|
|
265
|
+
await restore(path, skillBackup);
|
|
266
|
+
await restore(meta, metaBackup);
|
|
86
267
|
throw error;
|
|
87
268
|
}
|
|
88
269
|
return true;
|