@sandbaseai/cli 0.1.5 → 0.1.7
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/dist/adapters/index.js +44 -9
- package/dist/clients.d.ts +25 -0
- package/dist/clients.js +38 -4
- package/dist/commands.d.ts +5 -2
- package/dist/commands.js +71 -17
- package/dist/skills-cli.d.ts +36 -0
- package/dist/skills-cli.js +151 -0
- package/dist/skills.d.ts +2 -0
- package/dist/skills.js +93 -7
- package/package.json +1 -1
package/dist/adapters/index.js
CHANGED
|
@@ -9,12 +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
|
-
|
|
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 }; }
|
|
14
17
|
const start = "# >>> sandbase managed >>>", end = "# <<< sandbase managed <<<";
|
|
15
18
|
function block(client, bridge) {
|
|
16
19
|
if (client === "codex")
|
|
17
|
-
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}`;
|
|
18
21
|
return ` ${start}\n sandbase:\n command: node\n args:\n - ${JSON.stringify(bridge)}\n - --client\n - ${client}\n ${end}`;
|
|
19
22
|
}
|
|
20
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"; }
|
|
@@ -31,12 +34,19 @@ function removeHermesEntry(raw) { const lines = raw.split("\n"); const at = line
|
|
|
31
34
|
} lines.splice(at, end - at); return lines.join("\n"); }
|
|
32
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))
|
|
33
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"; }
|
|
34
41
|
function jsonUpdate(raw, client, bridge, remove = false) { const obj = raw ? JSON.parse(raw) : {}; if (!obj || Array.isArray(obj))
|
|
35
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))
|
|
36
|
-
throw new Error("mcpServers must be an object"); const map = servers; if (
|
|
37
|
-
|
|
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
|
+
}
|
|
38
48
|
else
|
|
39
|
-
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"; }
|
|
40
50
|
function validateText(client, text) { if (!text.trim())
|
|
41
51
|
return; const adapter = clientProfiles[client].adapter; if (adapter === "codex") {
|
|
42
52
|
const value = parseToml(text);
|
|
@@ -64,7 +74,14 @@ export async function configure(client, bridge, env = process.env, io = defaultI
|
|
|
64
74
|
return { path: configPath(client, env), changed: false }; const path = configPath(client, env); const raw = await readOptional(path); let next; try {
|
|
65
75
|
const text = raw || "";
|
|
66
76
|
validateText(client, text);
|
|
67
|
-
|
|
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));
|
|
68
85
|
validateText(client, next);
|
|
69
86
|
}
|
|
70
87
|
catch {
|
|
@@ -83,6 +100,13 @@ export async function unregister(client, env = process.env) { const profile = cl
|
|
|
83
100
|
return false; const path = configPath(client, env); const raw = await readOptional(path); if (!raw)
|
|
84
101
|
return false; let next; try {
|
|
85
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
|
+
}
|
|
86
110
|
next = profile.adapter === "json" ? jsonUpdate(raw, client, "", true) : profile.adapter === "codex" ? removeCodexEntry(removeManaged(raw)) : removeHermesEntry(removeManaged(raw));
|
|
87
111
|
validateText(client, next);
|
|
88
112
|
}
|
|
@@ -101,9 +125,20 @@ export async function isConfigured(client, env = process.env) { const profile =
|
|
|
101
125
|
return false; if (profile.adapter === "json") {
|
|
102
126
|
try {
|
|
103
127
|
const o = JSON.parse(raw);
|
|
104
|
-
return
|
|
128
|
+
return ownedJsonEntry(o.mcpServers?.sandbase, client);
|
|
105
129
|
}
|
|
106
130
|
catch {
|
|
107
131
|
return false;
|
|
108
132
|
}
|
|
109
|
-
}
|
|
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
|
@@ -15,6 +15,30 @@ export interface NativeCapability {
|
|
|
15
15
|
uninstall: "managed_only";
|
|
16
16
|
terminal: Exclude<CapabilityStatus, "configured" | "already_configured" | "failed">;
|
|
17
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
|
+
}
|
|
18
42
|
export interface ClientProfile {
|
|
19
43
|
id: Client;
|
|
20
44
|
label: string;
|
|
@@ -25,6 +49,7 @@ export interface ClientProfile {
|
|
|
25
49
|
export declare const clientProfiles: Record<Client, ClientProfile>;
|
|
26
50
|
export declare const skillTiers: Record<Client, SkillTier>;
|
|
27
51
|
export declare const nativeCapabilities: Record<Client, NativeCapability>;
|
|
52
|
+
export declare const capabilityRegistry: Record<Client, CapabilityV2>;
|
|
28
53
|
export declare function assertNativeCapabilities(): void;
|
|
29
54
|
export declare function clientList(): string;
|
|
30
55
|
export declare function autoClients(): Client[];
|
package/dist/clients.js
CHANGED
|
@@ -25,15 +25,15 @@ export const clientProfiles = {
|
|
|
25
25
|
pi: { id: "pi", label: "Pi", mode: "skill" },
|
|
26
26
|
};
|
|
27
27
|
export const skillTiers = {
|
|
28
|
-
codex: "s3_promotion", "claude-code": "
|
|
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
31
|
const guide = (client, action, check) => `${client}: ${action} Completion check: ${check} Recovery: keep existing settings unchanged and retry after correcting the client setup.`;
|
|
32
32
|
export const nativeCapabilities = {
|
|
33
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: "
|
|
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
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: "
|
|
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
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
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
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" },
|
|
@@ -55,11 +55,45 @@ export const nativeCapabilities = {
|
|
|
55
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
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
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])]));
|
|
58
79
|
export function assertNativeCapabilities() {
|
|
59
80
|
for (const client of Object.keys(clientProfiles)) {
|
|
60
81
|
const capability = nativeCapabilities[client];
|
|
61
82
|
if (!capability || !capability.mcpMode || !capability.skillMode || !capability.invocation || !capability.verification || !capability.guide || !capability.uninstall || !capability.terminal)
|
|
62
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}`);
|
|
63
97
|
}
|
|
64
98
|
}
|
|
65
99
|
assertNativeCapabilities();
|
|
@@ -67,5 +101,5 @@ export function clientList() {
|
|
|
67
101
|
return Object.keys(clientProfiles).join("|");
|
|
68
102
|
}
|
|
69
103
|
export function autoClients() {
|
|
70
|
-
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);
|
|
71
105
|
}
|
package/dist/commands.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
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
|
+
import { type SkillsCommandRunner, type SkillsReadbackVerifier } from "./skills-cli.js";
|
|
4
5
|
type Detection = {
|
|
5
6
|
installed: boolean;
|
|
6
7
|
detail: string;
|
|
@@ -12,9 +13,11 @@ export interface CommandDependencies {
|
|
|
12
13
|
signal?: AbortSignal;
|
|
13
14
|
log?: (s: string) => void;
|
|
14
15
|
detect?: (client: Client) => Detection;
|
|
16
|
+
skillsRunner?: SkillsCommandRunner;
|
|
17
|
+
skillsReadbackVerifier?: SkillsReadbackVerifier;
|
|
15
18
|
}
|
|
16
19
|
export declare function openBrowser(url: string): Promise<void>;
|
|
17
20
|
export declare function connect(client?: ConnectClient, deps?: CommandDependencies): Promise<void>;
|
|
18
|
-
export declare function doctor(client?: ConnectClient, store?: CredentialStore, detect?: (client: Client) => Detection): Promise<boolean>;
|
|
19
|
-
export declare function unregister(client?: ConnectClient, store?: CredentialStore, detect?: (client: Client) => Detection): Promise<void>;
|
|
21
|
+
export declare function doctor(client?: ConnectClient, store?: CredentialStore, detect?: (client: Client) => Detection, skillsRunner?: SkillsCommandRunner, skillsReadbackVerifier?: SkillsReadbackVerifier): Promise<boolean>;
|
|
22
|
+
export declare function unregister(client?: ConnectClient, store?: CredentialStore, detect?: (client: Client) => Detection, skillsRunner?: SkillsCommandRunner, skillsReadbackVerifier?: SkillsReadbackVerifier): Promise<void>;
|
|
20
23
|
export {};
|
package/dist/commands.js
CHANGED
|
@@ -3,10 +3,11 @@ import { platform } from "node:os";
|
|
|
3
3
|
import { clients } from "./types.js";
|
|
4
4
|
import { AuthorizationApi } from "./auth/api.js";
|
|
5
5
|
import { authorize } from "./auth/flow.js";
|
|
6
|
-
import { autoClients, clientProfiles, nativeCapabilities } from "./clients.js";
|
|
6
|
+
import { autoClients, capabilityRegistry, clientProfiles, nativeCapabilities } from "./clients.js";
|
|
7
7
|
import { FileCredentialStore } from "./credentials/store.js";
|
|
8
8
|
import { configure, detectClient, installBridge, isConfigured, rollback, rollbackBridge, unregister as removeAdapter } from "./adapters/index.js";
|
|
9
9
|
import { inspectSkill, installSkill, removeSkill, sharedSkillReferences, skillFallback, skillInvocation } from "./skills.js";
|
|
10
|
+
import { inspectNativeSkill, installNativeSkill, removeNativeSkill, skillsAgentRegistry } from "./skills-cli.js";
|
|
10
11
|
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 }); });
|
|
11
12
|
async function compensate(api, authorizationId, token) { for (const delay of [0, 250, 750]) {
|
|
12
13
|
if (delay)
|
|
@@ -20,12 +21,12 @@ async function compensate(api, authorizationId, token) { for (const delay of [0,
|
|
|
20
21
|
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(); }
|
|
21
22
|
function mcpServerSnippet(client, bridgePath) { return JSON.stringify({ mcpServers: { sandbase: { command: "node", args: [bridgePath, "--client", client] } } }, null, 2); }
|
|
22
23
|
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."]; }
|
|
23
|
-
function successMessage(client,
|
|
24
|
+
function successMessage(client, bridgePath) {
|
|
24
25
|
const profile = clientProfiles[client];
|
|
25
26
|
const label = profile.label;
|
|
26
|
-
const common = ["", "SandBase MCP is connected.", "", `Client: ${label} (${client})`,
|
|
27
|
+
const common = ["", "SandBase MCP is connected.", "", `Client: ${label} (${client})`, "Credential was stored locally with restricted permissions."];
|
|
27
28
|
if (profile.mode === "auto")
|
|
28
|
-
return [...common,
|
|
29
|
+
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");
|
|
29
30
|
if (profile.mode === "skill")
|
|
30
31
|
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");
|
|
31
32
|
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");
|
|
@@ -34,9 +35,12 @@ function plannedAutoClients(detect) { return autoClients().filter(client => dete
|
|
|
34
35
|
function logDetectedActionRequired(detect, log) {
|
|
35
36
|
for (const client of clients) {
|
|
36
37
|
const capability = nativeCapabilities[client];
|
|
37
|
-
|
|
38
|
+
const v2 = capabilityRegistry[client];
|
|
39
|
+
if (skillsAgentRegistry[client])
|
|
38
40
|
continue;
|
|
39
|
-
|
|
41
|
+
if (!detect(client).installed || (v2.implementation === "implemented" && (capability.mcpMode === "auto" || capability.mcpMode === "desktop")))
|
|
42
|
+
continue;
|
|
43
|
+
log(`${client}: status=${v2.status}, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
|
|
40
44
|
}
|
|
41
45
|
}
|
|
42
46
|
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 }; }
|
|
@@ -47,12 +51,26 @@ else
|
|
|
47
51
|
async function configureSkill(client, log) {
|
|
48
52
|
try {
|
|
49
53
|
const result = await installSkill(client);
|
|
50
|
-
|
|
54
|
+
const status = result.state === "already_configured" ? "already_configured" : result.state === "configured" ? "configured" : "confirmation_required";
|
|
55
|
+
log(`${client}: status=${status}, mcp=configured, skill=${result.state}, invocation=${nativeCapabilities[client].invocation}, next_step=${result.message}`);
|
|
56
|
+
return status;
|
|
51
57
|
}
|
|
52
58
|
catch (error) {
|
|
53
59
|
const message = error instanceof Error ? error.message : "Unknown native Skill failure";
|
|
54
|
-
log(
|
|
60
|
+
log(`${client}: status=failed, mcp=configured, skill=failed, invocation=${nativeCapabilities[client].invocation}, next_step=${message}`);
|
|
61
|
+
return "failed";
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
async function configureNativeSkill(client, detected, log, runner, verify) {
|
|
65
|
+
if (!skillsAgentRegistry[client])
|
|
66
|
+
return;
|
|
67
|
+
if (!detected.installed) {
|
|
68
|
+
log(`${client}: status=confirmation_required, mcp=not_configured, skill=confirmation_required, invocation=${nativeCapabilities[client].invocation}, next_step=${clientProfiles[client].label} is not locally detected; no Skills CLI invocation was attempted.`);
|
|
69
|
+
return;
|
|
55
70
|
}
|
|
71
|
+
const result = await installNativeSkill(client, runner, verify);
|
|
72
|
+
const status = result.status === "failed" ? "failed" : "confirmation_required";
|
|
73
|
+
log(`${client}: status=${status}, mcp=not_configured, skill=${result.status}, invocation=${nativeCapabilities[client].invocation}, next_step=${result.message}`);
|
|
56
74
|
}
|
|
57
75
|
async function connectOne(client, deps) {
|
|
58
76
|
const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
|
|
@@ -61,8 +79,23 @@ async function connectOne(client, deps) {
|
|
|
61
79
|
const detect = deps.detect || detectClient;
|
|
62
80
|
const profile = clientProfiles[client];
|
|
63
81
|
const capability = nativeCapabilities[client];
|
|
82
|
+
const v2 = capabilityRegistry[client];
|
|
83
|
+
if (skillsAgentRegistry[client]) {
|
|
84
|
+
await configureNativeSkill(client, detect(client), log, deps.skillsRunner, deps.skillsReadbackVerifier);
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
if (v2.implementation === "blocked") {
|
|
88
|
+
log(`${client}: status=failed, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
|
|
89
|
+
return;
|
|
90
|
+
}
|
|
64
91
|
if (capability.mcpMode === "manual" || capability.mcpMode === "none") {
|
|
65
|
-
|
|
92
|
+
const detected = detect(client);
|
|
93
|
+
if (skillsAgentRegistry[client]) {
|
|
94
|
+
await configureNativeSkill(client, detected, log, deps.skillsRunner, deps.skillsReadbackVerifier);
|
|
95
|
+
return;
|
|
96
|
+
}
|
|
97
|
+
const v2 = capabilityRegistry[client];
|
|
98
|
+
log(`${client}: status=${v2.status}, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
|
|
66
99
|
return;
|
|
67
100
|
}
|
|
68
101
|
const detected = detect(client);
|
|
@@ -79,7 +112,7 @@ async function connectOne(client, deps) {
|
|
|
79
112
|
configured = await configure(client, bridgeResult.path);
|
|
80
113
|
if (profile.mode === "auto" && !(await isConfigured(client)))
|
|
81
114
|
throw new Error("Client configuration verification failed");
|
|
82
|
-
log(successMessage(client,
|
|
115
|
+
log(successMessage(client, bridgeResult.path));
|
|
83
116
|
await configureSkill(client, log);
|
|
84
117
|
exchange.cleanup_token = "";
|
|
85
118
|
}
|
|
@@ -101,8 +134,13 @@ async function connectAuto(deps) {
|
|
|
101
134
|
const log = deps.log || console.log;
|
|
102
135
|
const detect = deps.detect || detectClient;
|
|
103
136
|
const targets = plannedAutoClients(detect);
|
|
137
|
+
const nativeSkillTargets = clients.filter(target => !!skillsAgentRegistry[target] && detect(target).installed);
|
|
138
|
+
// Native Skills are an independent local lifecycle: do not let their result
|
|
139
|
+
// change MCP authorization, configuration, or rollback decisions.
|
|
140
|
+
for (const target of nativeSkillTargets)
|
|
141
|
+
await configureNativeSkill(target, detect(target), log, deps.skillsRunner, deps.skillsReadbackVerifier);
|
|
104
142
|
if (!targets.length) {
|
|
105
|
-
log("No installed compatible clients support automatic configuration. Use --client <client> for manual or skill setup guidance.");
|
|
143
|
+
log("No installed compatible clients support automatic MCP configuration. Use --client <client> for manual or skill setup guidance.");
|
|
106
144
|
logDetectedActionRequired(detect, log);
|
|
107
145
|
return;
|
|
108
146
|
}
|
|
@@ -149,34 +187,50 @@ async function connectAuto(deps) {
|
|
|
149
187
|
}
|
|
150
188
|
export async function connect(client = "auto", deps = {}) { if (client === "auto")
|
|
151
189
|
return connectAuto(deps); return connectOne(client, deps); }
|
|
152
|
-
export async function doctor(client = "auto", store = new FileCredentialStore(), detect = detectClient) {
|
|
153
|
-
const targets = client === "auto" ? plannedAutoClients(detect) : [client];
|
|
190
|
+
export async function doctor(client = "auto", store = new FileCredentialStore(), detect = detectClient, skillsRunner, skillsReadbackVerifier) {
|
|
191
|
+
const targets = client === "auto" ? [...new Set([...plannedAutoClients(detect), ...clients.filter(target => !!skillsAgentRegistry[target] && detect(target).installed)])] : [client];
|
|
154
192
|
if (!targets.length) {
|
|
155
193
|
console.log("No installed compatible clients support automatic configuration.");
|
|
156
194
|
return false;
|
|
157
195
|
}
|
|
158
196
|
let healthy = true;
|
|
159
197
|
for (const target of targets) {
|
|
198
|
+
if (skillsAgentRegistry[target]) {
|
|
199
|
+
const native = await inspectNativeSkill(target, skillsRunner, skillsReadbackVerifier);
|
|
200
|
+
console.log(`${target}: status=${native.status === "failed" ? "failed" : "confirmation_required"}, mcp=not_configured, skill=${native.status}, invocation=${nativeCapabilities[target].invocation}, verification=read_only_probe, next_step=${native.message}`);
|
|
201
|
+
healthy = healthy && native.status === "already_installed";
|
|
202
|
+
continue;
|
|
203
|
+
}
|
|
160
204
|
const credential = await store.get(target);
|
|
161
205
|
const profile = clientProfiles[target];
|
|
162
206
|
const configured = profile.mode === "auto" ? await isConfigured(target) : !!credential;
|
|
163
207
|
const detected = detect(target);
|
|
164
208
|
const skill = await inspectSkill(target);
|
|
165
209
|
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." :
|
|
210
|
+
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;
|
|
167
211
|
const references = await sharedSkillReferences();
|
|
168
|
-
|
|
212
|
+
const status = configured && !!credential && skill === "installed" ? "configured" : "failed";
|
|
213
|
+
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}`);
|
|
169
214
|
healthy = healthy && detected.installed && !!credential && configured && !["missing", "modified"].includes(skill);
|
|
170
215
|
}
|
|
171
216
|
return healthy;
|
|
172
217
|
}
|
|
173
|
-
export async function unregister(client = "auto", store = new FileCredentialStore(), detect = detectClient) {
|
|
174
|
-
const targets = client === "auto" ? plannedAutoClients(detect) : [client];
|
|
218
|
+
export async function unregister(client = "auto", store = new FileCredentialStore(), detect = detectClient, skillsRunner, skillsReadbackVerifier) {
|
|
219
|
+
const targets = client === "auto" ? [...new Set([...plannedAutoClients(detect), ...clients.filter(target => !!skillsAgentRegistry[target] && detect(target).installed)])] : [client];
|
|
175
220
|
if (!targets.length) {
|
|
176
221
|
console.log("No installed compatible clients support automatic configuration.");
|
|
177
222
|
return;
|
|
178
223
|
}
|
|
179
224
|
for (const target of targets) {
|
|
225
|
+
if (skillsAgentRegistry[target]) {
|
|
226
|
+
const result = await removeNativeSkill(target, skillsRunner, skillsReadbackVerifier);
|
|
227
|
+
console.log(`${target}: mcp=not_configured, skill=${result.status}, next_step=${result.message}`);
|
|
228
|
+
continue;
|
|
229
|
+
}
|
|
230
|
+
if (capabilityRegistry[target].implementation === "blocked") {
|
|
231
|
+
console.log(`${target}: status=failed, next_step=${capabilityRegistry[target].nextStep}`);
|
|
232
|
+
continue;
|
|
233
|
+
}
|
|
180
234
|
const removed = await removeAdapter(target);
|
|
181
235
|
const removedSkill = await removeSkill(target);
|
|
182
236
|
await store.remove(target);
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { Client } from "./types.js";
|
|
2
|
+
/** Immutable release identity approved for the native Skills CLI adapter. */
|
|
3
|
+
export declare const sandbaseSkillRelease: {
|
|
4
|
+
readonly repository: "https://github.com/sandbaseai/sandbase-skills";
|
|
5
|
+
readonly release: "v0.1.0";
|
|
6
|
+
readonly sourceArg: "https://github.com/sandbaseai/sandbase-skills/tree/v0.1.0";
|
|
7
|
+
readonly commit: "03bc2811987db610cd64cbddfaa79b08e46c0e2f";
|
|
8
|
+
readonly skillSha256: "583879aa39368577ebadd270434923969cbdeac0e0be73f5db0c2494019418da";
|
|
9
|
+
readonly minimumCliVersion: "1.5.20";
|
|
10
|
+
};
|
|
11
|
+
export interface SkillsAgentRegistration {
|
|
12
|
+
skillsAgentId: string;
|
|
13
|
+
}
|
|
14
|
+
/** Only IDs verified by the release owner may be passed to the Skills CLI. */
|
|
15
|
+
export declare const skillsAgentRegistry: Partial<Record<Client, SkillsAgentRegistration>>;
|
|
16
|
+
export type NativeSkillStatus = "installed" | "already_installed" | "removed" | "confirmation_required" | "failed";
|
|
17
|
+
export type NativeSkillFailure = "skill_source_unavailable" | "skills_cli_unavailable" | "unsupported_by_skills_cli" | "readback_failed";
|
|
18
|
+
export interface NativeSkillResult {
|
|
19
|
+
status: NativeSkillStatus;
|
|
20
|
+
code?: NativeSkillFailure;
|
|
21
|
+
message: string;
|
|
22
|
+
}
|
|
23
|
+
export interface SkillsCommandResult {
|
|
24
|
+
code: number | null;
|
|
25
|
+
stdout: string;
|
|
26
|
+
stderr: string;
|
|
27
|
+
}
|
|
28
|
+
export type SkillsCommandRunner = (args: readonly string[]) => Promise<SkillsCommandResult>;
|
|
29
|
+
export type SkillsReadbackVerifier = (json: string, agent: string) => Promise<boolean>;
|
|
30
|
+
/** Reject every mutable or incomplete source tuple before starting any child process. */
|
|
31
|
+
export declare function validateSandbaseSkillRelease(release?: typeof sandbaseSkillRelease): boolean;
|
|
32
|
+
export declare const systemSkillsRunner: SkillsCommandRunner;
|
|
33
|
+
export declare const verifySkillsReadback: SkillsReadbackVerifier;
|
|
34
|
+
export declare function installNativeSkill(client: Client, runner?: SkillsCommandRunner, verify?: SkillsReadbackVerifier): Promise<NativeSkillResult>;
|
|
35
|
+
export declare function inspectNativeSkill(client: Client, runner?: SkillsCommandRunner, verify?: SkillsReadbackVerifier): Promise<NativeSkillResult>;
|
|
36
|
+
export declare function removeNativeSkill(client: Client, runner?: SkillsCommandRunner, verify?: SkillsReadbackVerifier): Promise<NativeSkillResult>;
|
|
@@ -0,0 +1,151 @@
|
|
|
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
|
+
function versionAtLeast(actual, minimum) {
|
|
19
|
+
const parse = (value) => value.match(/\b(\d+)\.(\d+)\.(\d+)\b/)?.slice(1).map(Number);
|
|
20
|
+
const a = parse(actual);
|
|
21
|
+
const b = parse(minimum);
|
|
22
|
+
if (!a || !b)
|
|
23
|
+
return false;
|
|
24
|
+
for (let index = 0; index < 3; index++) {
|
|
25
|
+
if (a[index] !== b[index])
|
|
26
|
+
return a[index] > b[index];
|
|
27
|
+
}
|
|
28
|
+
return true;
|
|
29
|
+
}
|
|
30
|
+
/** Reject every mutable or incomplete source tuple before starting any child process. */
|
|
31
|
+
export function validateSandbaseSkillRelease(release = sandbaseSkillRelease) {
|
|
32
|
+
return release.repository === "https://github.com/sandbaseai/sandbase-skills"
|
|
33
|
+
&& release.release === "v0.1.0"
|
|
34
|
+
&& release.sourceArg === "https://github.com/sandbaseai/sandbase-skills/tree/v0.1.0"
|
|
35
|
+
&& release.commit === "03bc2811987db610cd64cbddfaa79b08e46c0e2f"
|
|
36
|
+
&& release.skillSha256 === "583879aa39368577ebadd270434923969cbdeac0e0be73f5db0c2494019418da"
|
|
37
|
+
&& release.minimumCliVersion === "1.5.20";
|
|
38
|
+
}
|
|
39
|
+
export const systemSkillsRunner = async (args) => new Promise(resolve => {
|
|
40
|
+
const child = spawn("npx", ["-y", "skills", ...args], { stdio: ["ignore", "pipe", "pipe"] });
|
|
41
|
+
let stdout = "";
|
|
42
|
+
let stderr = "";
|
|
43
|
+
child.stdout.on("data", data => { stdout += String(data); });
|
|
44
|
+
child.stderr.on("data", data => { stderr += String(data); });
|
|
45
|
+
child.on("error", () => resolve({ code: null, stdout: "", stderr: "" }));
|
|
46
|
+
child.on("close", code => resolve({ code, stdout, stderr }));
|
|
47
|
+
});
|
|
48
|
+
function unavailable() { return { status: "failed", code: "skills_cli_unavailable", message: "Skills CLI is unavailable or below the required version; no native Skill was changed." }; }
|
|
49
|
+
function sourceUnavailable() { return { status: "failed", code: "skill_source_unavailable", message: "The verified SandBase Skill source is unavailable; no native Skill was changed." }; }
|
|
50
|
+
// The first-party listing must echo the exact immutable selector. A repository
|
|
51
|
+
// name or a tag alone could refer to a different source and is not ownership proof.
|
|
52
|
+
export const verifySkillsReadback = async (output, agent) => {
|
|
53
|
+
try {
|
|
54
|
+
const entries = JSON.parse(output);
|
|
55
|
+
const candidates = [];
|
|
56
|
+
const visit = (value) => {
|
|
57
|
+
if (Array.isArray(value)) {
|
|
58
|
+
value.forEach(visit);
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
if (!value || typeof value !== "object")
|
|
62
|
+
return;
|
|
63
|
+
const item = value;
|
|
64
|
+
if ("sourceUrl" in item || "agents" in item || "path" in item)
|
|
65
|
+
candidates.push(item);
|
|
66
|
+
Object.values(item).forEach(visit);
|
|
67
|
+
};
|
|
68
|
+
visit(entries);
|
|
69
|
+
const agentLabel = agent === "kiro-cli" ? "Kiro CLI" : "";
|
|
70
|
+
for (const candidate of candidates) {
|
|
71
|
+
if (candidate.sourceUrl !== `${sandbaseSkillRelease.repository}.git` || typeof candidate.path !== "string" || !JSON.stringify(candidate.agents).includes(agentLabel))
|
|
72
|
+
continue;
|
|
73
|
+
const skill = await readFile(join(candidate.path, "SKILL.md"), "utf8");
|
|
74
|
+
if (createHash("sha256").update(skill, "utf8").digest("hex") === sandbaseSkillRelease.skillSha256)
|
|
75
|
+
return true;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
catch { /* malformed/unreadable first-party readback is not proof */ }
|
|
79
|
+
return false;
|
|
80
|
+
};
|
|
81
|
+
async function invoke(runner, args) {
|
|
82
|
+
try {
|
|
83
|
+
return await runner(args);
|
|
84
|
+
}
|
|
85
|
+
catch {
|
|
86
|
+
return undefined;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
async function probe(client, runner) {
|
|
90
|
+
if (!validateSandbaseSkillRelease())
|
|
91
|
+
return sourceUnavailable();
|
|
92
|
+
const registration = skillsAgentRegistry[client];
|
|
93
|
+
if (!registration)
|
|
94
|
+
return { status: "failed", code: "unsupported_by_skills_cli", message: `No verified Skills CLI agent mapping exists for ${client}; no native Skill was changed.` };
|
|
95
|
+
const version = await invoke(runner, ["--version"]);
|
|
96
|
+
if (!version || version.code !== 0 || !versionAtLeast(`${version.stdout}\n${version.stderr}`, sandbaseSkillRelease.minimumCliVersion))
|
|
97
|
+
return unavailable();
|
|
98
|
+
// `skills add <source> --agent <id> --list` is the documented capability
|
|
99
|
+
// probe. It must succeed before an install or lifecycle command is attempted.
|
|
100
|
+
const listed = await invoke(runner, ["add", sandbaseSkillRelease.sourceArg, "--agent", registration.skillsAgentId, "--list"]);
|
|
101
|
+
if (!listed || listed.code !== 0)
|
|
102
|
+
return unavailable();
|
|
103
|
+
return { agent: registration.skillsAgentId, listed };
|
|
104
|
+
}
|
|
105
|
+
export async function installNativeSkill(client, runner = systemSkillsRunner, verify = verifySkillsReadback) {
|
|
106
|
+
const checked = await probe(client, runner);
|
|
107
|
+
if ("status" in checked)
|
|
108
|
+
return checked;
|
|
109
|
+
const before = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
|
|
110
|
+
if (!before || before.code !== 0)
|
|
111
|
+
return unavailable();
|
|
112
|
+
if (await verify(before.stdout, checked.agent))
|
|
113
|
+
return { status: "already_installed", message: "Native SandBase Skill is already installed and verified by Skills CLI readback." };
|
|
114
|
+
const added = await invoke(runner, ["add", sandbaseSkillRelease.sourceArg, "-g", "-a", checked.agent]);
|
|
115
|
+
if (!added || added.code !== 0)
|
|
116
|
+
return unavailable();
|
|
117
|
+
const readback = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
|
|
118
|
+
if (!readback || readback.code !== 0 || !(await verify(readback.stdout, checked.agent)))
|
|
119
|
+
return { status: "failed", code: "readback_failed", message: "Skills CLI could not prove the SandBase source for this agent; no success was reported." };
|
|
120
|
+
return { status: "installed", message: "Native SandBase Skill was installed and verified by Skills CLI readback." };
|
|
121
|
+
}
|
|
122
|
+
export async function inspectNativeSkill(client, runner = systemSkillsRunner, verify = verifySkillsReadback) {
|
|
123
|
+
const checked = await probe(client, runner);
|
|
124
|
+
if ("status" in checked)
|
|
125
|
+
return checked;
|
|
126
|
+
const readback = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
|
|
127
|
+
if (!readback || readback.code !== 0)
|
|
128
|
+
return unavailable();
|
|
129
|
+
return await verify(readback.stdout, checked.agent)
|
|
130
|
+
? { status: "already_installed", message: "Native SandBase Skill ownership is verified by Skills CLI readback." }
|
|
131
|
+
: { status: "confirmation_required", message: "Native SandBase Skill is not listed for this agent." };
|
|
132
|
+
}
|
|
133
|
+
export async function removeNativeSkill(client, runner = systemSkillsRunner, verify = verifySkillsReadback) {
|
|
134
|
+
const checked = await probe(client, runner);
|
|
135
|
+
if ("status" in checked)
|
|
136
|
+
return checked;
|
|
137
|
+
const before = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
|
|
138
|
+
if (!before || before.code !== 0)
|
|
139
|
+
return unavailable();
|
|
140
|
+
if (!(await verify(before.stdout, checked.agent)))
|
|
141
|
+
return { status: "confirmation_required", message: "Skills CLI cannot prove SandBase ownership for this agent; no native Skill was removed." };
|
|
142
|
+
// Skills CLI removes by its first-party Skill name, never by a URL. This is
|
|
143
|
+
// reached only after source, agent and digest ownership have been proven.
|
|
144
|
+
const removed = await invoke(runner, ["remove", "sandbase", "-g", "-a", checked.agent]);
|
|
145
|
+
if (!removed || removed.code !== 0)
|
|
146
|
+
return unavailable();
|
|
147
|
+
const readback = await invoke(runner, ["list", "-g", "-a", checked.agent, "--json"]);
|
|
148
|
+
if (!readback || readback.code !== 0 || await verify(readback.stdout, checked.agent))
|
|
149
|
+
return { status: "failed", code: "readback_failed", message: "Skills CLI could not prove native Skill removal; no removal success was reported." };
|
|
150
|
+
return { status: "removed", message: "Native SandBase Skill removal was verified by Skills CLI readback." };
|
|
151
|
+
}
|
package/dist/skills.d.ts
CHANGED
package/dist/skills.js
CHANGED
|
@@ -8,10 +8,14 @@ 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
12
|
function sha256(content) { return createHash("sha256").update(content, "utf8").digest("hex"); }
|
|
12
13
|
function sharedRoot(env = process.env) { const home = env.HOME || sandbaseHome(env); return join(home, ".agents", "skills", "sandbase"); }
|
|
13
14
|
export function sharedSkillPath(env = process.env) { return join(sharedRoot(env), "SKILL.md"); }
|
|
14
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; }
|
|
15
19
|
function legacySkillPath(client, env = process.env) {
|
|
16
20
|
const home = env.HOME || sandbaseHome(env);
|
|
17
21
|
if (client === "cursor")
|
|
@@ -20,14 +24,14 @@ function legacySkillPath(client, env = process.env) {
|
|
|
20
24
|
return join(env.CODEX_HOME || join(home, ".codex"), "skills", "sandbase", "SKILL.md");
|
|
21
25
|
return undefined;
|
|
22
26
|
}
|
|
23
|
-
export function skillPath(client, env = process.env) { return sharedClients.includes(client) ? sharedSkillPath(env) :
|
|
27
|
+
export function skillPath(client, env = process.env) { return sharedClients.includes(client) ? sharedSkillPath(env) : privateSkillPath(client, env); }
|
|
24
28
|
export function skillFallback(client) {
|
|
25
29
|
if (client === "claude-code" || client === "hermes")
|
|
26
30
|
return `${clientProfiles[client].label} native SandBase Skill is not available yet. Use the configured SandBase MCP tools directly in chat.`;
|
|
27
31
|
return "No native SandBase Skill is available for this client. Use the configured SandBase MCP tools directly.";
|
|
28
32
|
}
|
|
29
|
-
export function skillInvocation(client) { return `${clientProfiles[client].label}
|
|
30
|
-
function nativeTier(client) { return skillTiers[client] === "s3_promotion"; }
|
|
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"; }
|
|
31
35
|
function marked(content) { return content.includes(ownershipMarker) && /^name:\s*sandbase\s*$/m.test(content); }
|
|
32
36
|
async function asset(relative = "../assets/skills/sandbase/SKILL.md") {
|
|
33
37
|
const bundled = fileURLToPath(new URL(relative, import.meta.url));
|
|
@@ -54,6 +58,24 @@ async function sharedOwnership(env = process.env) {
|
|
|
54
58
|
return "ambiguous";
|
|
55
59
|
}
|
|
56
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
|
+
}
|
|
57
79
|
async function withLock(env, work) {
|
|
58
80
|
const lock = join(dirname(sharedRoot(env)), ".sandbase-skill.lock");
|
|
59
81
|
await mkdir(dirname(lock), { recursive: true, mode: 0o700 });
|
|
@@ -77,7 +99,7 @@ async function withLock(env, work) {
|
|
|
77
99
|
}
|
|
78
100
|
async function legacyCopies(env) {
|
|
79
101
|
const copies = [];
|
|
80
|
-
for (const client of
|
|
102
|
+
for (const client of ["cursor", "codex"]) {
|
|
81
103
|
const path = legacySkillPath(client, env);
|
|
82
104
|
const content = await readOptional(path);
|
|
83
105
|
if (content)
|
|
@@ -93,6 +115,11 @@ export async function probeSkill(client, env = process.env) {
|
|
|
93
115
|
if (!nativeTier(client))
|
|
94
116
|
return { compatible: true, message: "No promotion probe is required." };
|
|
95
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
|
+
}
|
|
96
123
|
if ((await sharedOwnership(env)) === "ambiguous")
|
|
97
124
|
return { compatible: false, message: "The shared SandBase Skill ownership or checksum is invalid. It was left untouched; resolve it manually, then retry." };
|
|
98
125
|
const copies = await legacyCopies(env);
|
|
@@ -111,6 +138,10 @@ export async function inspectSkill(client, env = process.env) {
|
|
|
111
138
|
return "fallback";
|
|
112
139
|
if (tier === "s4_none")
|
|
113
140
|
return "unsupported";
|
|
141
|
+
if (privateClients.includes(client)) {
|
|
142
|
+
const ownership = await privateOwnership(client, env);
|
|
143
|
+
return ownership === "owned" ? "installed" : ownership === "missing" ? "missing" : "modified";
|
|
144
|
+
}
|
|
114
145
|
const ownership = await sharedOwnership(env);
|
|
115
146
|
return ownership === "owned" ? "installed" : ownership === "missing" ? "missing" : "modified";
|
|
116
147
|
}
|
|
@@ -119,6 +150,8 @@ export async function installSkill(client, env = process.env) {
|
|
|
119
150
|
const fallback = skillTiers[client] === "s3_fallback";
|
|
120
151
|
return { state: fallback ? "fallback" : "skipped", message: fallback ? skillFallback(client) : "No native SandBase Skill is available for this client.", changed: false };
|
|
121
152
|
}
|
|
153
|
+
if (privateClients.includes(client))
|
|
154
|
+
return installPrivateSkill(client, env);
|
|
122
155
|
return withLock(env, async () => {
|
|
123
156
|
const probe = await probeSkill(client, env);
|
|
124
157
|
if (!probe.compatible)
|
|
@@ -150,14 +183,46 @@ export async function installSkill(client, env = process.env) {
|
|
|
150
183
|
throw error;
|
|
151
184
|
}
|
|
152
185
|
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 };
|
|
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 };
|
|
154
187
|
});
|
|
155
188
|
}
|
|
156
|
-
|
|
157
|
-
|
|
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); }
|
|
158
221
|
export async function removeSkill(client, env = process.env) {
|
|
159
222
|
if (!nativeTier(client))
|
|
160
223
|
return false;
|
|
224
|
+
if (privateClients.includes(client))
|
|
225
|
+
return removePrivateSkill(client, env);
|
|
161
226
|
return withLock(env, async () => {
|
|
162
227
|
if ((await sharedSkillReferences(env)).length)
|
|
163
228
|
return false;
|
|
@@ -182,3 +247,24 @@ export async function removeSkill(client, env = process.env) {
|
|
|
182
247
|
return true;
|
|
183
248
|
});
|
|
184
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")
|
|
255
|
+
return false;
|
|
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);
|
|
260
|
+
try {
|
|
261
|
+
await rm(path);
|
|
262
|
+
await rm(meta);
|
|
263
|
+
}
|
|
264
|
+
catch (error) {
|
|
265
|
+
await restore(path, skillBackup);
|
|
266
|
+
await restore(meta, metaBackup);
|
|
267
|
+
throw error;
|
|
268
|
+
}
|
|
269
|
+
return true;
|
|
270
|
+
}
|