@visa/cli 4.1.0-rc.229 → 4.1.0-rc.230

package/dist/skills/pair-visa-agent/scripts/setup.mjs

@@ -1,48 +1,328 @@
 #!/usr/bin/env node
 // Portable provisioner for the pair-visa-agent skill.
 //
-// Ensures the `visa` CLI is installed so ANY Agent Skills runtime can pair —
-// not just OpenClaw (whose `metadata.openclaw.install` auto-runs). Hermes,
-// Claude Code, and any other agentskills.io-compatible runtime run this bundled
-// script per the standard's `scripts/` execution stage.
+// Ensures the `visa` CLI is installed and provides the required v4 MCP tools
+// (`agent_handoff_claim`, `agent_connect`, `agent_connect_poll`) so ANY Agent
+// Skills runtime can pair — not just OpenClaw (whose `metadata.openclaw.install`
+// auto-runs). Hermes, Claude Code, and any other agentskills.io-compatible
+// runtime run this bundled script per the standard's `scripts/` execution stage.
 //
-// Safe to run repeatedly: it no-ops when `visa` already resolves. Pinned to @rc
-// because the v4 agent surface is prerelease (the @latest tag predates the
-// `visa agent` commands); drop the tag once 4.1.0 is promoted to latest.
+// Safe to run repeatedly:
+// - Idempotent no-op when a compatible version with required tools is installed.
+// - Upgrades when a stale or incomplete binary (e.g. 4.0.1 without handoff tools) is found.
+// - Installs `@visa/cli@rc` when no binary exists.
 
-import { execSync } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+export const DEFAULT_RELEASE_CHANNEL = 'rc'
+export const MIN_COMPATIBLE_VERSION = '4.1.0-rc.159'
+export const REQUIRED_MCP_TOOLS = Object.freeze([
+  'agent_handoff_claim',
+  'agent_connect',
+  'agent_connect_poll',
+])
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+export function parseSemver(v) {
+  if (typeof v !== 'string') return null
+  const cleaned = v.trim().replace(/^v/, '')
+  const m = cleaned.match(SEMVER_RE)
+  if (!m) return null
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    pre: m[4] ?? null,
+  }
+}
+
+/**
+ * Returns true if `version` satisfies >= `minVersion`.
+ * Rules (semver 2.0.0):
+ * - Release (no prerelease) outranks any prerelease of the same major.minor.patch.
+ * - For identical major.minor.patch with prerelease `rc.N`, compares N numerically.
+ */
+export function isSemverCompatible(version, minVersion = MIN_COMPATIBLE_VERSION) {
+  const cur = parseSemver(version)
+  const min = parseSemver(minVersion)
+  if (!cur || !min) return false
+
+  if (cur.major !== min.major) return cur.major > min.major
+  if (cur.minor !== min.minor) return cur.minor > min.minor
+  if (cur.patch !== min.patch) return cur.patch > min.patch
+
+  // Both main versions are equal.
+  // A release version (no prerelease) outranks any prerelease of the same main version.
+  if (!cur.pre && min.pre) return true
+  if (cur.pre && !min.pre) return false
+  if (!cur.pre && !min.pre) return true
+
+  // Both have prereleases. Compare prerelease identifiers.
+  const curParts = cur.pre.split('.')
+  const minParts = min.pre.split('.')
+  const len = Math.max(curParts.length, minParts.length)
+
+  for (let i = 0; i < len; i++) {
+    if (i >= curParts.length) return false
+    if (i >= minParts.length) return true
+    const a = curParts[i]
+    const b = minParts[i]
+    const aNum = /^\d+$/.test(a)
+    const bNum = /^\d+$/.test(b)
+    if (aNum && bNum) {
+      const numA = Number(a)
+      const numB = Number(b)
+      if (numA !== numB) return numA > numB
+    } else if (aNum && !bNum) {
+      return false
+    } else if (!aNum && bNum) {
+      return true
+    } else if (a !== b) {
+      return a > b
+    }
+  }
+  return true
+}
+
+export function findCliBinary(execFn = execFileSync) {
+  for (const bin of ['visa', 'visa-cli']) {
+    try {
+      execFn(bin, ['--version'], { stdio: 'ignore', timeout: 5000 })
+      return bin
+    } catch {
+      // not resolvable or failed
+    }
+  }
+  return null
+}
+
+export function detectCliVersion(bin, execFn = execFileSync) {
+  if (!bin) return null
+
+  try {
+    const rawCap = execFn(bin, ['capabilities', '--format', 'json'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+    })
+    const cap = JSON.parse(rawCap)
+    const version = cap?.data?.build?.version ?? cap?.build?.version
+    if (typeof version === 'string' && version.trim()) {
+      return version.trim()
+    }
+  } catch {
+    // fallback to --version
+  }
 
-function resolves(cmd) {
   try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' })
-    return true
+    const raw = execFn(bin, ['--version'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+    })
+    const cleaned = raw.trim().replace(/^v/, '')
+    if (cleaned) return cleaned
   } catch {
-    return false
+    // unable to detect version
   }
+
+  return null
 }
 
-if (resolves('visa') || resolves('visa-cli')) {
-  console.log('✓ visa CLI already installed — nothing to do. Run the pairing flow in SKILL.md.')
-  process.exit(0)
+function defaultLocalMcpBundlePath() {
+  try {
+    const req = createRequire(import.meta.url)
+    const pkgJson = req.resolve('@visa/cli/package.json')
+    return join(dirname(pkgJson), 'dist', 'mcp-server', 'index.js')
+  } catch {
+    return null
+  }
 }
 
-console.log('Installing @visa/cli@rc (the v4 agent surface is prerelease)…')
-try {
-  execSync('npm install -g @visa/cli@rc', { stdio: 'inherit' })
-} catch {
-  console.error(
-    'Global install failed. Try `npm install -g @visa/cli@rc` manually (may need sudo, or set a\n' +
-      'user-writable npm prefix: `npm config set prefix ~/.npm-global` and add its `bin` to PATH).'
-  )
-  process.exit(1)
+export function resolveMcpBundlePath(
+  npmRootFn = () => execFileSync('npm', ['root', '-g'], { encoding: 'utf-8' }),
+  localBundleFn = defaultLocalMcpBundlePath
+) {
+  const candidates = []
+
+  try {
+    const globalRoot = npmRootFn().trim()
+    if (globalRoot) {
+      candidates.push(join(globalRoot, '@visa', 'cli', 'dist', 'mcp-server', 'index.js'))
+    }
+  } catch {
+    // npm root -g failed
+  }
+
+  const local = localBundleFn()
+  if (local) candidates.push(local)
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+export function probeMcpTools(mcpPath, requiredTools = REQUIRED_MCP_TOOLS) {
+  if (!mcpPath || !existsSync(mcpPath)) {
+    return { ok: false, missingTools: [...requiredTools] }
+  }
+
+  try {
+    const content = readFileSync(mcpPath, 'utf-8')
+    const missing = requiredTools.filter((tool) => {
+      const exact = new RegExp(`(?:^|[^A-Za-z0-9_])${tool}(?:[^A-Za-z0-9_]|$)`)
+      return !exact.test(content)
+    })
+    return {
+      ok: missing.length === 0,
+      missingTools: missing,
+    }
+  } catch {
+    return { ok: false, missingTools: [...requiredTools] }
+  }
 }
 
-if (!resolves('visa') && !resolves('visa-cli')) {
-  console.error(
-    'Installed, but `visa` is not on PATH. Ensure your npm global bin dir is on PATH\n' +
-      '(`npm bin -g` shows it), then re-run this script.'
+export function verifyCliReadiness(
+  execFn = execFileSync,
+  npmRootFn = () => execFileSync('npm', ['root', '-g'], { encoding: 'utf-8' }),
+  localBundleFn
+) {
+  const bin = findCliBinary(execFn)
+  if (!bin) {
+    return {
+      ready: false,
+      reason: 'not_installed',
+      bin: null,
+      version: null,
+      missingTools: [...REQUIRED_MCP_TOOLS],
+    }
+  }
+
+  const version = detectCliVersion(bin, execFn)
+  const isVersionOk = Boolean(version && isSemverCompatible(version, MIN_COMPATIBLE_VERSION))
+
+  const mcpPath =
+    localBundleFn === undefined
+      ? resolveMcpBundlePath(npmRootFn)
+      : resolveMcpBundlePath(npmRootFn, localBundleFn)
+  const toolProbe = mcpPath
+    ? probeMcpTools(mcpPath, REQUIRED_MCP_TOOLS)
+    : { ok: false, missingTools: [...REQUIRED_MCP_TOOLS] }
+
+  if (isVersionOk && toolProbe.ok) {
+    return {
+      ready: true,
+      bin,
+      version: version || 'unknown',
+      missingTools: [],
+    }
+  }
+
+  return {
+    ready: false,
+    reason: 'stale_or_incomplete',
+    bin,
+    version,
+    missingTools:
+      toolProbe.missingTools.length > 0
+        ? toolProbe.missingTools
+        : isVersionOk
+          ? []
+          : [...REQUIRED_MCP_TOOLS],
+  }
+}
+
+export function performInstallOrUpgrade(pkgName, execFn = execFileSync) {
+  execFn('npm', ['install', '-g', pkgName], {
+    stdio: 'inherit',
+    timeout: 120_000,
+  })
+}
+
+export async function runSetup(env = process.env, execs = {}) {
+  const execFn = execs.execFileSync ?? execFileSync
+  const npmRootFn = execs.npmRootFn ?? (() => execFn('npm', ['root', '-g'], { encoding: 'utf-8' }))
+
+  const channel = env.VISA_RELEASE_CHANNEL || DEFAULT_RELEASE_CHANNEL
+  const pkgName = `@visa/cli@${channel}`
+
+  const initial = verifyCliReadiness(execFn, npmRootFn)
+
+  if (initial.ready) {
+    console.log(
+      `✓ visa CLI v${initial.version} already installed and verified (${REQUIRED_MCP_TOOLS.join(', ')} present) — nothing to do. Run the pairing flow in SKILL.md.`
+    )
+    return {
+      status: 'already_ready',
+      version: initial.version,
+      bin: initial.bin,
+    }
+  }
+
+  if (initial.reason === 'stale_or_incomplete') {
+    const missingStr =
+      initial.missingTools.length > 0 ? initial.missingTools.join(', ') : 'v4 tool generation'
+    console.log(
+      `Detected stale or incomplete CLI (v${initial.version || 'unknown'} lacks required tools: ${missingStr}). Upgrading to ${pkgName}…`
+    )
+  } else {
+    console.log(`Installing ${pkgName} (the v4 agent surface is prerelease)…`)
+  }
+
+  try {
+    performInstallOrUpgrade(pkgName, execFn)
+  } catch (err) {
+    console.error(
+      `Global install failed. Try \`npm install -g ${pkgName}\` manually (may need sudo, or set a\n` +
+        'user-writable npm prefix: `npm config set prefix ~/.npm-global` and add its `bin` to PATH).'
+    )
+    process.exit(1)
+  }
+
+  const post = verifyCliReadiness(execFn, npmRootFn)
+
+  if (!post.bin) {
+    console.error(
+      'Installed, but `visa` is not on PATH. Ensure your npm global bin dir is on PATH\n' +
+        '(`npm bin -g` shows it), then re-run this script.'
+    )
+    process.exit(1)
+  }
+
+  if (!post.ready) {
+    const missingStr =
+      post.missingTools.length > 0 ? post.missingTools.join(', ') : 'v4 tool generation'
+    console.error(
+      `Readiness check failed: installed CLI v${post.version || 'unknown'} is missing required tools (${missingStr}).\n` +
+        `Explicit upgrade action:\n` +
+        `  npm install -g ${pkgName}`
+    )
+    process.exit(1)
+  }
+
+  const status = initial.reason === 'not_installed' ? 'installed' : 'upgraded'
+  console.log(
+    `✓ visa CLI ready (v${post.version}, ${REQUIRED_MCP_TOOLS.join(', ')} present). Now run the pairing flow in SKILL.md.`
   )
-  process.exit(1)
+  return {
+    status,
+    version: post.version,
+    bin: post.bin,
+  }
 }
 
-console.log('✓ visa CLI ready. Now run the pairing flow in SKILL.md.')
+const isMain =
+  typeof process !== 'undefined' &&
+  process.argv[1] &&
+  (import.meta.url === pathToFileURL(process.argv[1]).href || process.argv[1].endsWith('setup.mjs'))
+
+if (isMain) {
+  runSetup().catch((err) => {
+    console.error(`Provisioning error: ${err && err.message ? err.message : String(err)}`)
+    process.exit(1)
+  })
+}

package/install.ps1

@@ -137,8 +137,9 @@ try {
 }
 
 # Install via npm
-Write-Host "  Running: npm install -g @visa/cli" -ForegroundColor Gray
-$npmOutput = & npm install -g @visa/cli 2>&1
+$Package = '@visa/cli@rc'
+Write-Host "  Running: npm install -g $Package" -ForegroundColor Gray
+$npmOutput = & npm install -g $Package 2>&1
 $npmExitCode = $LASTEXITCODE
 $npmText = ($npmOutput | Out-String)
 $npmOutput | Out-Host
@@ -158,7 +159,7 @@ if ($npmExitCode -ne 0) {
         Write-Host "  Do not disable TLS verification globally." -ForegroundColor Yellow
     } else {
         Write-Host "  Run manually for the full error, then retry:" -ForegroundColor Yellow
-        Write-Host "    npm install -g @visa/cli" -ForegroundColor Yellow
+        Write-Host "    npm install -g $Package" -ForegroundColor Yellow
     }
 
     Wait-BeforeExit
@@ -188,7 +189,7 @@ Write-Host ""
 if ($verifiedCommand) {
     Write-Host "  Visa CLI $visaVersion installed." -ForegroundColor Green
     Write-Host "  Connect an AI client with: $verifiedCommand connect <client>" -ForegroundColor Cyan
-    Write-Host "  Then ask your agent to call enroll_agent." -ForegroundColor Cyan
+    Write-Host "  Then ask your agent to call setup_start." -ForegroundColor Cyan
     Write-Host ""
 } else {
     $primaryCommand = $cliCommandNames | Select-Object -First 1

package/install.sh

@@ -109,7 +109,7 @@ echo ""
 if [ -n "$VISA_VERSION" ]; then
   ok "Visa CLI ${VISA_VERSION} installed."
   info "Connect an AI client with: visa-cli connect <client>"
-  info "Then ask your agent to call enroll_agent."
+  info "Then ask your agent to call setup_start."
 else
   warn "Installed, but 'visa-cli' was not found on PATH."
   warn "Restart your shell, then run: visa-cli connect <client>"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "4.1.0-rc.229",
+  "version": "4.1.0-rc.230",
   "description": "Visa CLI runtime for stable agent identity and separately authorized payment capabilities",
   "bin": {
     "visa-cli": "./bin/visa-cli.js",
@@ -42,32 +42,31 @@
   "author": "Visa Crypto Labs",
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@modelcontextprotocol/core": "2.0.0",
     "@modelcontextprotocol/ext-apps": "1.7.5",
     "@modelcontextprotocol/server": "2.0.0",
     "@ucp-js/sdk": "0.4.4",
     "commander": "^12.1.0",
     "punycode": "^2.3.1",
+    "toml": "^4.3.0",
+    "yaml": "^2.9.0",
     "zod": "^3.25.76"
   },
   "optionalDependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
     "@chainsafe/libp2p-yamux": "^8.0.1",
-    "@libp2p/crypto": "^5.1.22",
+    "@libp2p/crypto": "^5.1.23",
     "@libp2p/tcp": "^11.0.26",
     "@multiformats/multiaddr": "^13.0.3",
-    "libp2p": "^3.3.8",
-    "playwright-core": "^1.48.2",
+    "libp2p": "^3.3.9",
+    "playwright-core": "^1.62.1",
     "uint8arrays": "^6.1.1"
   },
   "devDependencies": {
-    "@changesets/changelog-git": "^0.2.1",
     "@types/express": "^5.0.0",
-    "@changesets/cli": "^2.31.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^26.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.65.0",
-    "@typescript-eslint/parser": "^8.65.0",
+    "@typescript-eslint/eslint-plugin": "^8.68.0",
+    "@typescript-eslint/parser": "^8.68.0",
     "@visa-cli/tools": "workspace:*",
     "@visa/agent-mail": "workspace:*",
     "@visa/checkout-engine": "workspace:*",
@@ -80,7 +79,6 @@
     "@visa/wallet-tools": "workspace:*",
     "esbuild": "^0.28.1",
     "eslint": "^10.0.2",
-    "eslint-config-prettier": "^10.1.8",
     "express": "^4.21.0",
     "jest": "^29.7.0",
     "prettier": "^3.9.6",

package/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.visa-crypto-labs/visa-cli",
-  "version": "4.1.0-rc.229",
+  "version": "4.1.0-rc.230",
   "title": "Visa CLI",
   "description": "Pair a human-approved agent identity, configure payment capabilities separately, and discover and pay x402 services from your AI coding assistant.",
   "websiteUrl": "https://github.com/Visa-Crypto-Labs/Visa-mono/tree/main/packages/cli#readme",
@@ -9,7 +9,7 @@
     {
       "registryType": "npm",
       "identifier": "@visa/cli",
-      "version": "4.1.0-rc.229",
+      "version": "4.1.0-rc.230",
       "transport": {
         "type": "stdio"
       },