@sandbaseai/cli 0.1.6 → 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.
@@ -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
@@ -7,6 +7,7 @@ import { autoClients, capabilityRegistry, clientProfiles, nativeCapabilities } f
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)
@@ -35,6 +36,8 @@ 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])
40
+ continue;
38
41
  if (!detect(client).installed || (v2.implementation === "implemented" && (capability.mcpMode === "auto" || capability.mcpMode === "desktop")))
39
42
  continue;
40
43
  log(`${client}: status=${v2.status}, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
@@ -58,6 +61,17 @@ async function configureSkill(client, log) {
58
61
  return "failed";
59
62
  }
60
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;
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}`);
74
+ }
61
75
  async function connectOne(client, deps) {
62
76
  const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
63
77
  const store = deps.store || new FileCredentialStore();
@@ -66,11 +80,20 @@ async function connectOne(client, deps) {
66
80
  const profile = clientProfiles[client];
67
81
  const capability = nativeCapabilities[client];
68
82
  const v2 = capabilityRegistry[client];
83
+ if (skillsAgentRegistry[client]) {
84
+ await configureNativeSkill(client, detect(client), log, deps.skillsRunner, deps.skillsReadbackVerifier);
85
+ return;
86
+ }
69
87
  if (v2.implementation === "blocked") {
70
88
  log(`${client}: status=failed, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
71
89
  return;
72
90
  }
73
91
  if (capability.mcpMode === "manual" || capability.mcpMode === "none") {
92
+ const detected = detect(client);
93
+ if (skillsAgentRegistry[client]) {
94
+ await configureNativeSkill(client, detected, log, deps.skillsRunner, deps.skillsReadbackVerifier);
95
+ return;
96
+ }
74
97
  const v2 = capabilityRegistry[client];
75
98
  log(`${client}: status=${v2.status}, mcp=not_configured, skill=not_configured, invocation=${capability.invocation}, next_step=${v2.nextStep}`);
76
99
  return;
@@ -111,8 +134,13 @@ async function connectAuto(deps) {
111
134
  const log = deps.log || console.log;
112
135
  const detect = deps.detect || detectClient;
113
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);
114
142
  if (!targets.length) {
115
- 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.");
116
144
  logDetectedActionRequired(detect, log);
117
145
  return;
118
146
  }
@@ -159,14 +187,20 @@ async function connectAuto(deps) {
159
187
  }
160
188
  export async function connect(client = "auto", deps = {}) { if (client === "auto")
161
189
  return connectAuto(deps); return connectOne(client, deps); }
162
- export async function doctor(client = "auto", store = new FileCredentialStore(), detect = detectClient) {
163
- 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];
164
192
  if (!targets.length) {
165
193
  console.log("No installed compatible clients support automatic configuration.");
166
194
  return false;
167
195
  }
168
196
  let healthy = true;
169
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
+ }
170
204
  const credential = await store.get(target);
171
205
  const profile = clientProfiles[target];
172
206
  const configured = profile.mode === "auto" ? await isConfigured(target) : !!credential;
@@ -181,13 +215,18 @@ export async function doctor(client = "auto", store = new FileCredentialStore(),
181
215
  }
182
216
  return healthy;
183
217
  }
184
- export async function unregister(client = "auto", store = new FileCredentialStore(), detect = detectClient) {
185
- 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];
186
220
  if (!targets.length) {
187
221
  console.log("No installed compatible clients support automatic configuration.");
188
222
  return;
189
223
  }
190
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
+ }
191
230
  if (capabilityRegistry[target].implementation === "blocked") {
192
231
  console.log(`${target}: status=failed, next_step=${capabilityRegistry[target].nextStep}`);
193
232
  continue;
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sandbaseai/cli",
3
- "version": "0.1.6",
3
+ "version": "0.1.7",
4
4
  "description": "Secure SandBase MCP onboarding CLI",
5
5
  "type": "module",
6
6
  "bin": {