@wangkh/skill-sync-cli 0.2.2 → 0.2.3

package/README.md

@@ -248,9 +248,12 @@ downloaded again. If the update check cannot reach the remote but the previous
 install is still present, the current copy is kept. Use `--force` to reinstall
 regardless.
 
-On networks that cannot reach GitHub directly, pass `--github-mirror <url>`
-(or set `SKILL_SYNC_GITHUB_MIRROR`) to route GitHub clones and update checks
-through a mirror:
+`sync` prefers direct connections and falls back automatically: it probes
+github.com with a 5-second timeout first, and when the probe fails, clones and
+update checks run through `https://gh-proxy.com/` for that run. A direct
+install that fails anyway gets one retry through the fallback mirror. Pass
+`--github-mirror <url>` (or set `SKILL_SYNC_GITHUB_MIRROR`) to force a specific
+mirror instead of the automatic fallback:
 
 ```bash
 npx @wangkh/skill-sync-cli sync --github-mirror https://gh-proxy.com/

package/README.zh-CN.md

@@ -124,7 +124,7 @@ npx --yes skills@1.5.22 add vercel-labs/skills --agent opencode --skill find-ski
 
 `sync` 会把每个分组的已安装版本记录在 `~/.config/skill-sync/state.json`。之后的运行会用 `git ls-remote` 检查远端版本（固定为 commit SHA 的 `ref` 无需检查），版本和已安装文件都没有变化时跳过该组，不再重复下载。检查更新失败但本地文件仍然存在时，会保留现有安装。需要强制重装时使用 `--force`。
 
-如果所在网络无法直接访问 GitHub，可以用 `--github-mirror <url>`（或环境变量 `SKILL_SYNC_GITHUB_MIRROR`）让 clone 和版本检查走镜像：
+`sync` 默认优先直连 GitHub、失败自动回退：先用 5 秒超时探测 github.com，探测失败时本次运行的 clone 和版本检查自动走 `https://gh-proxy.com/`；直连安装失败也会再用镜像重试一次。需要强制指定镜像时用 `--github-mirror <url>`（或环境变量 `SKILL_SYNC_GITHUB_MIRROR`）：
 
 ```bash
 npx @wangkh/skill-sync-cli sync --github-mirror https://gh-proxy.com/

package/bin/skill-sync.mjs

@@ -29,7 +29,7 @@ Options:
   --dry-run               Print commands without downloading anything
   --continue-on-error     Continue after a skill installation fails
   --retries <n>           Retry each failed install up to n times (default 2)
-  --github-mirror <url>   Clone GitHub sources through a mirror (sync only)
+  --github-mirror <url>   Force a GitHub mirror instead of the automatic fallback
   --force                 Replace the selected manifest with init, or reinstall with sync
   -h, --help              Show this help
   -v, --version           Show the version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangkh/skill-sync-cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Sync declared agent skills across machines through the skills CLI",
   "author": "wkh",
   "repository": {

package/skills/skill-sync/SKILL.md

@@ -77,10 +77,11 @@ npx --yes skills@1.5.22 add <owner>/<repo> --list
   overrides the skip.
 - When the update check cannot reach the remote but the installed copy still
   exists, `sync` keeps it instead of failing.
-- GitHub unreachable: `--github-mirror https://gh-proxy.com/` (alternatives:
-  `https://ghproxy.net/`, `https://ghfast.top/`). For the `skills` CLI
-  download itself, configure an npm registry mirror such as
-  `https://registry.npmmirror.com`.
+- GitHub access: `sync` probes github.com with a 5-second timeout and falls
+  back to `https://gh-proxy.com/` automatically; `--github-mirror <url>` forces
+  a specific mirror (alternatives: `https://ghproxy.net/`,
+  `https://ghfast.top/`). For the `skills` CLI download itself, configure an
+  npm registry mirror such as `https://registry.npmmirror.com`.
 
 ## Security
 

package/src/commands.mjs

@@ -15,8 +15,14 @@ import {
   runCommand,
   statusCode,
 } from "./runner.mjs"
-import { mirrorGitEnv } from "./mirror.mjs"
-import { gitUrlForSource, isCommitSha, probeRevision } from "./revision.mjs"
+import { DEFAULT_FALLBACK_MIRROR, mirrorGitEnv } from "./mirror.mjs"
+import {
+  checkGithubReachable,
+  gitUrlForSource,
+  isCommitSha,
+  isGithubSource,
+  probeRevision,
+} from "./revision.mjs"
 import {
   allInstalled,
   readState,
@@ -99,17 +105,26 @@ function resolveGroupRevision(skills, probe, probeOptions) {
   return probe(url, ref, probeOptions)
 }
 
-async function runWithRetries(execute, command, { cwd, env, retries, retryDelayMs, label }) {
+async function runWithRetries(execute, command, { cwd, env, fallbackEnv, retries, retryDelayMs, label }) {
+  let result
   for (let attempt = 0; ; attempt += 1) {
-    const result = execute(command, { cwd, env })
+    result = execute(command, { cwd, env })
     const code = statusCode(result)
-    if (code === 0 || result.signal || attempt >= retries) return result
+    if (code === 0 || result.signal || attempt >= retries) break
 
     const delayMs = retryDelayMs * (attempt + 1)
     const delayText = delayMs > 0 ? ` in ${Math.round(delayMs / 1000)}s` : ""
     console.error(`[${label}] attempt ${attempt + 1}/${retries + 1} failed with exit code ${code}; retrying${delayText}`)
     if (delayMs > 0) await sleep(delayMs)
   }
+
+  // Direct connections can work for the reachability probe and still time out
+  // later; one mirror attempt covers that case.
+  if (statusCode(result) !== 0 && !result.signal && fallbackEnv) {
+    console.error(`[${label}] retrying via fallback mirror`)
+    result = execute(command, { cwd, env: fallbackEnv })
+  }
+  return result
 }
 
 export async function planCommand(manifestFilename) {
@@ -140,7 +155,6 @@ export async function syncCommand(manifestFilename, options = {}) {
   const home = options.home ?? os.homedir()
   const cwd = options.cwd ?? process.cwd()
   const probe = options.probe ?? probeRevision
-  const gitEnv = mirrorGitEnv(options.githubMirror)
 
   if (skills.length === 0) {
     console.log("No enabled skills.")
@@ -154,6 +168,30 @@ export async function syncCommand(manifestFilename, options = {}) {
     command: commandForGroup(group, manifest.cli),
   }))
 
+  // Route GitHub traffic for this run: an explicit mirror always wins;
+  // otherwise probe github.com briefly and fall back to the default mirror
+  // when it does not answer.
+  let gitEnv = mirrorGitEnv(options.githubMirror)
+  let fallbackEnv = null
+  if (!options.githubMirror && !options.dryRun && groups.some((group) => isGithubSource(group.skills[0].source))) {
+    const check = options.checkGithub ?? checkGithubReachable
+    if (check()) {
+      console.log("# GitHub reachable; using direct connections")
+      fallbackEnv = mirrorGitEnv(DEFAULT_FALLBACK_MIRROR)
+    } else {
+      gitEnv = mirrorGitEnv(DEFAULT_FALLBACK_MIRROR)
+      console.log(`# GitHub unreachable; using fallback mirror ${DEFAULT_FALLBACK_MIRROR}`)
+    }
+  }
+
+  const resolveRevision = (group) => {
+    let revision = resolveGroupRevision(group.skills, probe, { env: gitEnv })
+    if (revision.status === "error" && fallbackEnv) {
+      revision = resolveGroupRevision(group.skills, probe, { env: fallbackEnv })
+    }
+    return revision
+  }
+
   const stateFilename = options.stateFile ?? statePath(home)
   const state = await readState(stateFilename)
 
@@ -195,7 +233,7 @@ export async function syncCommand(manifestFilename, options = {}) {
     let revision = null
 
     if (!options.force && entry && installedHere) {
-      revision = resolveGroupRevision(group.skills, probe, { env: gitEnv })
+      revision = resolveRevision(group)
       if (revision.status === "known" && entry.revision === revision.revision) {
         console.log(`# unchanged (${revision.revision.slice(0, 7)}); skipping, use --force to reinstall`)
         skipped += 1
@@ -218,6 +256,7 @@ export async function syncCommand(manifestFilename, options = {}) {
       const result = await runWithRetries(executeTolerant, group.command, {
         cwd: options.cwd,
         env: gitEnv,
+        fallbackEnv,
         retries,
         retryDelayMs,
         label: skill.name,
@@ -232,7 +271,11 @@ export async function syncCommand(manifestFilename, options = {}) {
       // A batched command shares one fetch. Since a failure could come from a
       // single bad name or a transient error, retry each entry individually
       // when the batch does not succeed.
-      const batch = executeTolerant(group.command, { cwd: options.cwd, env: gitEnv })
+      let batch = executeTolerant(group.command, { cwd: options.cwd, env: gitEnv })
+      if (statusCode(batch) !== 0 && !batch.signal && fallbackEnv) {
+        console.error(`[${sourceLabel(group.skills)}] batch install failed; retrying via fallback mirror`)
+        batch = executeTolerant(group.command, { cwd: options.cwd, env: fallbackEnv })
+      }
       if (statusCode(batch) !== 0) {
         if (batch.signal) {
           failures += group.skills.length
@@ -245,6 +288,7 @@ export async function syncCommand(manifestFilename, options = {}) {
             const result = await runWithRetries(executeTolerant, commandFor(skill, manifest.cli), {
               cwd: options.cwd,
               env: gitEnv,
+              fallbackEnv,
               retries,
               retryDelayMs,
               label: skill.name,
@@ -264,7 +308,7 @@ export async function syncCommand(manifestFilename, options = {}) {
     }
 
     if (!groupFailed) {
-      if (!revision) revision = resolveGroupRevision(group.skills, probe, { env: gitEnv })
+      if (!revision) revision = resolveRevision(group)
       if (revision.status === "known") {
         setStateEntry(state, filename, key, {
           revision: revision.revision,

package/src/mirror.mjs

@@ -1,4 +1,5 @@
 export const GITHUB_BASE = "https://github.com/"
+export const DEFAULT_FALLBACK_MIRROR = "https://gh-proxy.com/"
 
 export function normalizeMirror(mirror) {
   if (mirror === undefined || mirror === null || mirror === "") return undefined

package/src/revision.mjs

@@ -53,3 +53,21 @@ export function probeRevision(url, ref, { timeoutMs = 10000, env = process.env }
   if (!COMMIT_SHA.test(revision)) return { status: "unknown" }
   return { status: "known", revision: revision.toLowerCase() }
 }
+
+const GITHUB_CHECK_URL = "https://github.com/octocat/Hello-World.git"
+
+export function isGithubSource(source) {
+  if (SHORTHAND.test(source) && !source.split("/").some((part) => part.startsWith("."))) return true
+  if (/^git@github\.com:/i.test(source)) return true
+  try {
+    return /(^|\.)github\.com$/i.test(new URL(source).hostname)
+  } catch {
+    return false
+  }
+}
+
+// A short direct probe decides whether sync runs against github.com or the
+// fallback mirror for this run.
+export function checkGithubReachable({ timeoutMs = 5000 } = {}) {
+  return probeRevision(GITHUB_CHECK_URL, "HEAD", { timeoutMs }).status === "known"
+}