@safeskill/cli 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.2
+
+- Added cross-region hub resolve fallback when the selected SafeSkill hub returns a server error.
+
 ## 0.2.1
 
 - Added Flocks agent support with `.flocks/plugins/skills` install paths.

package/README.md

@@ -76,9 +76,18 @@ npx @safeskill/cli add safeskill://official/acme/code-review@1.2.0
 | `-y, --yes`               | Skip all confirmation prompts                                                                                                                      |
 | `--all`                   | Install all skills to all agents without prompts                                                                                                   |
 
+### Global Options
+
+| Option                 | Description                                                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `--region <cn|global>` | Use a specific SafeSkill service region for this run. Overrides `SAFESKILL_REGION`; otherwise auto-detected. |
+
 ### Examples
 
 ```bash
+# Force the China service region for this run
+npx @safeskill/cli --region cn add safeskill://official/acme/code-review
+
 # List skills in a repository
 npx @safeskill/cli add example-org/agent-skills --list
 
@@ -441,6 +450,7 @@ Ensure you have write access to the target directory.
 | Variable                  | Description                                                                |
 | ------------------------- | -------------------------------------------------------------------------- |
 | `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
+| `SAFESKILL_REGION`        | Optional fallback service region (`cn` or `global`) when `--region` is not specified |
 | `DISABLE_TELEMETRY`       | Set to disable anonymous usage telemetry                                   |
 | `DO_NOT_TRACK`            | Alternative way to disable telemetry                                       |
 

package/dist/cli.mjs

@@ -408,13 +408,18 @@ const STATUS_TIMEOUT_MS = 2500;
 const DETECT_TIMEOUT_MS = 1500;
 let resolvedRegionPromise = null;
 let regionAvailabilityCache = /* @__PURE__ */ new Map();
-function normalizeRegion(region) {
+let safeSkillRegionOverride = null;
+function normalizeSafeSkillRegion(region) {
 	const value = region?.trim().toLowerCase();
 	if (!value) return null;
 	if (value === "cn" || value === "china") return "cn";
 	if (value === "global" || value === "io" || value === "intl" || value === "international") return "global";
 	return null;
 }
+function setSafeSkillRegionOverride(region) {
+	safeSkillRegionOverride = region;
+	resolvedRegionPromise = null;
+}
 function withTimeout(timeoutMs) {
 	return AbortSignal.timeout(timeoutMs);
 }
@@ -496,7 +501,8 @@ async function ensureRegionAvailable(region, hubBaseUrl) {
 async function resolveSafeSkillRegion() {
 	if (resolvedRegionPromise) return resolvedRegionPromise;
 	resolvedRegionPromise = (async () => {
-		const configuredRegion = normalizeRegion(process.env.SAFESKILL_REGION);
+		if (safeSkillRegionOverride) return safeSkillRegionOverride;
+		const configuredRegion = normalizeSafeSkillRegion(process.env.SAFESKILL_REGION);
 		if (configuredRegion) return configuredRegion;
 		return detectRegionByPublicIP();
 	})();
@@ -530,6 +536,19 @@ function normalizeApiBase(baseUrl) {
 function buildApiUrl(baseUrl, path) {
 	return `${normalizeApiBase(baseUrl)}${path.startsWith("/") ? path : `/${path}`}`;
 }
+function getAlternateHubBaseUrl(baseUrl) {
+	if (process.env.SAFESKILL_HUB_URL) return null;
+	const parsed = new URL(baseUrl);
+	if (parsed.hostname === "hubapi.safeskill.io") {
+		parsed.hostname = "hubapi.safeskill.cn";
+		return parsed.toString().replace(/\/$/, "");
+	}
+	if (parsed.hostname === "hubapi.safeskill.cn") {
+		parsed.hostname = "hubapi.safeskill.io";
+		return parsed.toString().replace(/\/$/, "");
+	}
+	return null;
+}
 async function readEnvelope(response) {
 	const payload = await response.json();
 	if (payload && typeof payload === "object" && "data" in payload) return payload.data;
@@ -724,26 +743,41 @@ async function searchSkillsCatalog(query, limit = 10) {
 	}
 }
 async function resolveHubSkill(source, agent) {
-	const resolveUrl = buildApiUrl(await getSafeSkillHubBaseUrl(), "/resolve");
-	const resolveWithAgent = agent ? await fetch(resolveUrl, {
-		method: "POST",
-		headers: getHeaders({ "content-type": "application/json" }),
-		body: JSON.stringify({
-			source,
-			agent
-		})
-	}) : null;
-	const response = resolveWithAgent && resolveWithAgent.ok ? resolveWithAgent : await fetch(resolveUrl, {
-		method: "POST",
-		headers: getHeaders({ "content-type": "application/json" }),
-		body: JSON.stringify({ source })
-	});
+	const baseUrl = await getSafeSkillHubBaseUrl();
+	const resolveFromBaseUrl = async (hubBaseUrl) => {
+		const resolveUrl = buildApiUrl(hubBaseUrl, "/resolve");
+		const resolveWithAgent = agent ? await fetch(resolveUrl, {
+			method: "POST",
+			headers: getHeaders({ "content-type": "application/json" }),
+			body: JSON.stringify({
+				source,
+				agent
+			})
+		}) : null;
+		return resolveWithAgent && resolveWithAgent.ok ? resolveWithAgent : fetch(resolveUrl, {
+			method: "POST",
+			headers: getHeaders({ "content-type": "application/json" }),
+			body: JSON.stringify({ source })
+		});
+	};
+	let resolvedBaseUrl = baseUrl;
+	let response = await resolveFromBaseUrl(baseUrl);
+	const alternateBaseUrl = response.status >= 500 ? getAlternateHubBaseUrl(baseUrl) : null;
+	if (alternateBaseUrl) {
+		const alternateResponse = await resolveFromBaseUrl(alternateBaseUrl);
+		if (alternateResponse.ok || !response.ok) {
+			response = alternateResponse;
+			resolvedBaseUrl = alternateBaseUrl;
+		}
+	}
 	if (!response.ok) throw new Error(`hub resolve failed: ${response.status}`);
-	return readEnvelope(response);
+	const resolved = await readEnvelope(response);
+	resolved.hubBaseUrl = resolvedBaseUrl;
+	return resolved;
 }
 async function downloadHubSource(source, agent) {
-	const baseUrl = await getSafeSkillHubBaseUrl();
 	const resolved = await resolveHubSkill(source, agent);
+	const baseUrl = resolved.hubBaseUrl || await getSafeSkillHubBaseUrl();
 	const downloadUrl = resolved.download_uri || (resolved.artifact_digest ? buildApiUrl(baseUrl, `/artifacts/${encodeURIComponent(resolved.artifact_digest)}/download`) : "");
 	if (!downloadUrl) throw new Error("hub resolve did not return a downloadable artifact");
 	let response;
@@ -901,6 +935,8 @@ async function parseSkillMd(skillMdPath, options) {
 				...metaData
 			};
 		} catch (metaError) {}
+		if (!skillData.name && options?.fallbackName) skillData.name = options.fallbackName;
+		if (!skillData.description && options?.fallbackDescription) skillData.description = options.fallbackDescription;
 		if (!skillData.name || !skillData.description) return null;
 		if (typeof skillData.name !== "string" || typeof skillData.description !== "string") return null;
 		if (skillData.metadata?.internal === true && !shouldInstallInternalSkills() && !options?.includeInternal) return null;
@@ -910,7 +946,8 @@ async function parseSkillMd(skillMdPath, options) {
 			path: dirname(skillMdPath),
 			rawContent: content,
 			metadata: skillData.metadata,
-			slug: skillData.slug
+			slug: skillData.slug || options?.fallbackSlug,
+			installName: options?.fallbackInstallName
 		};
 	} catch {
 		return null;
@@ -2278,7 +2315,7 @@ function createEmptyLocalLock() {
 		skills: {}
 	};
 }
-var version$1 = "0.2.1";
+var version$1 = "0.2.3";
 const isCancelled$1 = (value) => typeof value === "symbol";
 async function isSourcePrivate(source) {
 	const ownerRepo = parseOwnerRepo(source);
@@ -2793,10 +2830,24 @@ async function runAdd(args, options = {}) {
 		}
 		const includeInternal = !!(options.skill && options.skill.length > 0);
 		spinner.start("Discovering skills...");
-		const skills = await discoverSkills(skillsDir, parsed.subpath, {
+		let skills = await discoverSkills(skillsDir, parsed.subpath, {
 			includeInternal,
 			fullDepth: options.fullDepth
 		});
+		let usedHubMetadataFallback = false;
+		if (skills.length === 0 && parsed.type === "hub" && !parsed.subpath && hubResolved?.skill) {
+			const fallbackSkill = await parseSkillMd(join(skillsDir, "SKILL.md"), {
+				includeInternal,
+				fallbackName: hubResolved.skill.display_name || hubResolved.skill.name,
+				fallbackDescription: hubResolved.skill.summary || hubResolved.skill.name,
+				fallbackSlug: hubResolved.skill.name,
+				fallbackInstallName: hubResolved.skill.name
+			});
+			if (fallbackSkill) {
+				skills = [fallbackSkill];
+				usedHubMetadataFallback = true;
+			}
+		}
 		if (skills.length === 0) {
 			spinner.stop(import_picocolors.default.red("No skills found"));
 			Se(import_picocolors.default.red("No valid skills found. Skills require a SKILL.md with name and description."));
@@ -2804,6 +2855,7 @@ async function runAdd(args, options = {}) {
 			process.exit(1);
 		}
 		spinner.stop(`Found ${import_picocolors.default.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
+		if (usedHubMetadataFallback) M.warn("Warning: this hub artifact is missing SKILL.md frontmatter. Some agents may not recognize this skill until name and description are added to SKILL.md.");
 		if (options.list) {
 			console.log();
 			M.step(import_picocolors.default.bold("Available Skills"));
@@ -4369,6 +4421,8 @@ ${BOLD}List Options:${RESET}
 ${BOLD}Options:${RESET}
   --help, -h        Show this help message
   --version, -v     Show version number
+  --region <cn|global>
+                   Use a specific SafeSkill service region for this run
 
 ${BOLD}Examples:${RESET}
   ${DIM}$${RESET} safeskill add example-org/agent-skills
@@ -4655,7 +4709,7 @@ async function runCheck(args = []) {
 	});
 	console.log();
 }
-async function runUpdate() {
+async function runUpdate(region) {
 	console.log(`${TEXT}Checking for skill updates...${RESET}`);
 	console.log();
 	const lock = readSkillLock();
@@ -4751,13 +4805,22 @@ async function runUpdate() {
 			console.log(`  ${DIM}✗ Failed to update ${update.name}: CLI entrypoint not found at ${cliEntry}${RESET}`);
 			continue;
 		}
-		if (spawnSync(process.execPath, [
+		const addArgs = region ? [
 			cliEntry,
+			"--region",
+			region,
 			"add",
 			installUrl,
 			"-g",
 			"-y"
-		], {
+		] : [
+			cliEntry,
+			"add",
+			installUrl,
+			"-g",
+			"-y"
+		];
+		if (spawnSync(process.execPath, addArgs, {
 			stdio: [
 				"inherit",
 				"pipe",
@@ -4784,8 +4847,53 @@ async function runUpdate() {
 	});
 	console.log();
 }
+function parseGlobalOptions(args) {
+	const parsedArgs = [];
+	let region;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === void 0) continue;
+		if (arg === "--region") {
+			const value = args[i + 1];
+			if (typeof value !== "string" || value.startsWith("-")) return {
+				args: parsedArgs,
+				error: "Missing value for --region. Expected one of: cn, global"
+			};
+			const normalized = normalizeSafeSkillRegion(value);
+			if (!normalized) return {
+				args: parsedArgs,
+				error: `Invalid region: ${value}\nExpected one of: cn, global`
+			};
+			region = normalized;
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--region=")) {
+			const value = arg.slice(9);
+			const normalized = normalizeSafeSkillRegion(value);
+			if (!normalized) return {
+				args: parsedArgs,
+				error: `Invalid region: ${value}\nExpected one of: cn, global`
+			};
+			region = normalized;
+			continue;
+		}
+		parsedArgs.push(arg);
+	}
+	return {
+		args: parsedArgs,
+		region
+	};
+}
 async function main() {
-	const args = process.argv.slice(2);
+	const parsedGlobalOptions = parseGlobalOptions(process.argv.slice(2));
+	if (parsedGlobalOptions.error) {
+		console.log(parsedGlobalOptions.error);
+		process.exitCode = 1;
+		return;
+	}
+	if (parsedGlobalOptions.region) setSafeSkillRegionOverride(parsedGlobalOptions.region);
+	const args = parsedGlobalOptions.args;
 	if (args.length === 0) {
 		showBanner();
 		return;
@@ -4844,7 +4952,7 @@ async function main() {
 			break;
 		case "update":
 		case "upgrade":
-			runUpdate();
+			runUpdate(parsedGlobalOptions.region);
 			break;
 		case "--help":
 		case "-h":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safeskill/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "SafeSkill CLI, for safe your skills",
   "type": "module",
   "bin": {