@open-dy/vibecoding-cli 0.0.1-beta.1

package/src/commands/turbo.mjs

@@ -0,0 +1,36 @@
+import path from 'node:path'
+import { openCardBuildEnvironment } from '../build/opencard-environment.mjs'
+import { prepareTurboConfig } from '../build/turbo-config.mjs'
+import { UsageError } from '../core/errors.mjs'
+import { resolveProjectBinary, runProcess } from '../core/runner.mjs'
+
+function hasOption(args, option) {
+  return args.some((arg) => arg === option || arg.startsWith(`${option}=`))
+}
+
+/**
+ * @desc 使用 CLI 合并后的工程配置执行 Turbo，并注入 OpenCard 域模式。
+ * @params {{root: string, target: string, taroRoot?: string}} context 工程上下文。
+ * @params {{args?: string[]}} [options] Turbo 参数；`--` 后的参数原样透传。
+ * @return {Promise<unknown>} Turbo 子进程完成后的结果。
+ * @example runTurbo(context, { args: ['run', 'build:raw'] })
+ */
+export async function runTurbo(context, { args = [] } = {}) {
+  if (args.length === 0) {
+    throw new UsageError(
+      'vibecoding turbo requires a Turbo command, for example: run build:raw',
+    )
+  }
+  if (hasOption(args, '--root-turbo-json')) {
+    throw new UsageError('--root-turbo-json is managed by vibecoding turbo and cannot be overridden')
+  }
+
+  const config = prepareTurboConfig({ projectRoot: context.root, target: context.target })
+  const turboArgs = ['--root-turbo-json', path.relative(context.root, config), ...args]
+  const environment = openCardBuildEnvironment(context)
+  return runProcess(resolveProjectBinary(context.root, 'turbo'), turboArgs, {
+    cwd: context.root,
+    env: environment,
+    label: `${context.target} turbo`,
+  })
+}

package/src/commands/validate.mjs

@@ -0,0 +1,26 @@
+import { UsageError } from '../core/errors.mjs'
+import { validateFeedCard } from '../validators/feed-card.mjs'
+import { validateNonEmptyTaro } from '../validators/empty-project.mjs'
+import { validateOpenCardStructure } from '../validators/opencard-structure.mjs'
+import { validateRoutes } from '../validators/routes.mjs'
+
+export async function runValidate(context, validator) {
+  switch (validator) {
+    case 'feed-card':
+      validateFeedCard(context)
+      return
+    case 'routes':
+      validateRoutes(context)
+      return
+    case 'empty':
+      validateNonEmptyTaro(context)
+      return
+    case 'opencard-structure':
+      validateOpenCardStructure(context)
+      return
+    default:
+      throw new UsageError(
+        `Unknown validator: ${validator || '<missing>'}\nAvailable validators: feed-card, routes, empty, opencard-structure`,
+      )
+  }
+}

package/src/commands/verify.mjs

@@ -0,0 +1,602 @@
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { CliError } from '../core/errors.mjs'
+import { readRuntimeEnvironment } from '../core/environment.mjs'
+import { waitForPorts } from '../core/ports.mjs'
+import { runCaptured, runTasks } from '../core/runner.mjs'
+import { packageUses, validateDependencies } from '../validators/dependencies.mjs'
+import { validateFeedCard } from '../validators/feed-card.mjs'
+import { runBuild } from './build.mjs'
+import { runDatabaseInit } from './db.mjs'
+import { runLint } from './lint.mjs'
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const devLauncher = fileURLToPath(new URL('../../bin/vibecoding', import.meta.url))
+
+export function targetPorts(context, frontendUrl, full = true) {
+  if (context.target === 'opencard') {
+    return [{ label: 'opencard-h5', port: Number(new URL(frontendUrl).port || 10087) }]
+  }
+  return [
+    { label: 'backend', port: 3000 },
+    ...(context.hasClosedDomainServer ? [{ label: 'closed-domain-backend', port: 3001 }] : []),
+    { label: 'main-h5', port: full ? Number(new URL(frontendUrl).port || 10086) : 10086 },
+    ...(full && context.hasOpenCard ? [{ label: 'opencard-h5', port: 10087 }] : []),
+  ]
+}
+
+async function runStatic(context) {
+  validateDependencies(context)
+  const env = await readRuntimeEnvironment(context.root)
+  const tasks = [
+    { name: 'lint', run: () => runLint(context) },
+    { name: 'build', run: () => runBuild(context, { frontendTarget: 'tt' }) },
+  ]
+  if (context.target === 'taro') {
+    tasks.push(
+      { name: 'database', run: () => runDatabaseInit(context, { env }) },
+      { name: 'feed-card', run: async () => validateFeedCard(context) },
+    )
+  }
+  await runTasks(tasks, { label: 'static verification' })
+}
+
+export function startDevDetached(context, spawnProcess = spawn) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('bash', [
+      devLauncher, 'dev', '--target', context.target, '--cwd', context.root,
+    ], { cwd: context.root, env: process.env, detached: true, stdio: 'ignore' })
+
+    child.once('error', (error) => {
+      reject(new CliError(`dev supervisor failed to start: ${error.message}`))
+    })
+    child.once('spawn', () => {
+      child.unref()
+      resolve(child.pid)
+    })
+  })
+}
+
+export function resolveDevLogPath(context, env = process.env) {
+  if (env.LOG_FILE) return env.LOG_FILE
+  const runtimeRoot = env.VIBECODING_RUNTIME_ROOT || (
+    process.platform === 'linux'
+      ? '/workspace/tmp'
+      : path.join(context.root, '.tmp/microapp-dev')
+  )
+  return path.join(runtimeRoot, 'microapp-logs/dev.log')
+}
+
+function printLastRunErrors(logFile, log) {
+  if (log === undefined) {
+    try { log = readFileSync(logFile, 'utf8') } catch { log = '' }
+  }
+  const section = log.split('--- DEV_RUN_START ---').at(-1) || ''
+  const errors = section.split('\n').filter((line) => line.includes('[error]'))
+  if (errors.length > 0) {
+    console.log(`[vibecoding:verify] Last dev run errors (${logFile}):\n${errors.join('\n')}`)
+  }
+}
+
+export async function waitForDevInstall(context, timeoutSeconds, options = {}) {
+  const logFile = options.logFile ?? resolveDevLogPath(context, options.env)
+  const readLog = options.readLog ?? (() => {
+    try { return readFileSync(logFile, 'utf8') } catch { return '' }
+  })
+  const sleepFn = options.sleepFn ?? sleep
+  const deadline = Date.now() + timeoutSeconds * 1000
+  while (Date.now() < deadline) {
+    if (readLog().includes('Dependencies installed successfully')) return
+    await sleepFn(options.pollMs ?? 1_000)
+  }
+  printLastRunErrors(logFile, readLog())
+  throw new CliError(
+    `Timed out waiting for dev dependency installation after ${timeoutSeconds}s. ` +
+    `Full log: ${logFile}`,
+  )
+}
+
+async function verifyPorts(context, options, frontendUrl) {
+  const ports = targetPorts(context, frontendUrl, options.full)
+  let status = await waitForPorts(ports, 1)
+  if (status.every((entry) => entry.listening)) return
+  if (!options.autoStart) {
+    throw new CliError(`Ports not listening: ${status.filter((entry) => !entry.listening).map((entry) => `${entry.label}:${entry.port}`).join(', ')}`)
+  }
+  const pid = await startDevDetached(context)
+  console.log(`[vibecoding:verify] started dev (PID ${pid}); waiting for ports`)
+  await waitForDevInstall(context, options.timeoutSeconds)
+  status = await waitForPorts(ports, options.timeoutSeconds)
+  const missing = status.filter((entry) => !entry.listening)
+  if (missing.length > 0) {
+    printLastRunErrors(resolveDevLogPath(context))
+    throw new CliError(`Ports not ready after ${options.timeoutSeconds}s: ${missing.map((entry) => `${entry.label}:${entry.port}`).join(', ')}`)
+  }
+}
+
+export async function verifyFeedApi(context, options = {}) {
+  if (!existsSync(path.join(context.root, 'feed/feed-card.json'))) {
+    return { skipped: true }
+  }
+  const routingFile = path.join(context.root, 'config/card-routing.json')
+  let routing = null
+  try {
+    routing = existsSync(routingFile) ? JSON.parse(readFileSync(routingFile, 'utf8')) : null
+  } catch {
+    console.warn(`[verify] Cannot read or parse ${routingFile}; using backend port ${options.backendPort ?? 3000}.`)
+  }
+  const backendPort = options.backendPort ?? (routing?.cardData?.serviceDomain === 'closed' ? 3001 : 3000)
+  const url = `http://127.0.0.1:${backendPort}/api/dy_card/data`
+  let response
+  try {
+    response = await (options.fetchFn ?? fetch)(url)
+  } catch (error) {
+    throw new CliError(`Failed to probe ${url}: ${error.message}`)
+  }
+  const body = await response.text()
+  if (!response.ok) throw new CliError(`${url} returned ${response.status}: ${body.slice(0, 500)}`)
+  let data
+  try { data = JSON.parse(body) } catch { throw new CliError(`${url} did not return JSON`) }
+  if (data.success !== true) {
+    throw new CliError(`${url} returned success=${JSON.stringify(data.success)}: ${body.slice(0, 500)}`)
+  }
+  if (typeof data.data !== 'string' || data.data.trim() === '') {
+    throw new CliError(`${url} returned success=true but data is not a non-empty JSON string`)
+  }
+  let payload
+  try { payload = JSON.parse(data.data) } catch {
+    throw new CliError(`${url} data is not valid JSON: ${data.data.slice(0, 500)}`)
+  }
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new CliError(`${url} data must decode to a JSON object`)
+  }
+  return { skipped: false }
+}
+
+function flatten(value) {
+  if (value == null) return ''
+  if (typeof value === 'string') return value
+  try { return JSON.stringify(value) } catch { return String(value) }
+}
+
+// Keep preview finding classification aligned with the master template verifier.
+const textOf = (value) => (value == null ? "" : String(value));
+
+const BENIGN_RUNTIME_URL_HOSTS = new Set(["developer.toutiao.com"]);
+const BENIGN_RUNTIME_URL_SUFFIXES = [".snssdk.com", ".zijieapi.com"];
+
+const hostnameIsBenignRuntime = (hostname) => {
+  if (!hostname) return false;
+  if (BENIGN_RUNTIME_URL_HOSTS.has(hostname)) return true;
+  return BENIGN_RUNTIME_URL_SUFFIXES.some(
+    (suffix) => hostname === suffix.slice(1) || hostname.endsWith(suffix),
+  );
+};
+
+const LOCAL_PREVIEW_PROXY_MARKER = "/__proxy__/";
+
+const extractPreviewProxyTargetUrl = (url) => {
+  const text = textOf(url);
+  const markerIndex = text.indexOf(LOCAL_PREVIEW_PROXY_MARKER);
+  if (markerIndex === -1) return null;
+  try {
+    return new URL(
+      decodeURIComponent(text.slice(markerIndex + LOCAL_PREVIEW_PROXY_MARKER.length)),
+    );
+  } catch {
+    return null;
+  }
+};
+
+const isLocalPreviewProxyRequest = (url) =>
+  textOf(url).includes(LOCAL_PREVIEW_PROXY_MARKER);
+
+const flattenRuntimePayload = (value, depth = 0, seen = new Set()) => {
+  if (value == null || depth > 8) return "";
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return String(value);
+  }
+  if (typeof value !== "object") return String(value);
+  if (seen.has(value)) return "";
+  seen.add(value);
+
+  if (depth === 0) {
+    try {
+      const json = JSON.stringify(value);
+      if (json && json !== "{}" && json !== "[]") return json;
+    } catch {
+      // fall through
+    }
+  }
+
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => flattenRuntimePayload(item, depth + 1, seen))
+      .filter(Boolean)
+      .join(" ");
+  }
+
+  const parts = [];
+  for (const key of Object.keys(value)) {
+    parts.push(String(key));
+    parts.push(flattenRuntimePayload(value[key], depth + 1, seen));
+  }
+  return parts.filter(Boolean).join(" ");
+};
+
+const BENIGN_RUNTIME_TEXT_PATTERNS = [
+  /request:fail.*url not in domain list/i,
+  /url not in domain list/i,
+  /errNo["']?\s*[:=]\s*21100/i,
+  /errorCode["']?\s*[:=]\s*100001/i,
+  /mcs\.zijieapi\.com/i,
+  /snssdk\.com/i,
+  /\[TMA\].*unhandledRejection/i,
+  // Taro H5 preview optional hot-reload config; often 404, not an app bug
+  /hot-reload-config\.json/i,
+];
+
+const matchesBenignRuntimeText = (text) =>
+  BENIGN_RUNTIME_TEXT_PATTERNS.some((pattern) => pattern.test(textOf(text)));
+
+const buildRuntimeSessionContext = (consoleMessages, pageErrors) =>
+  [...consoleMessages, ...pageErrors]
+    .map((item) => flattenRuntimePayload(item))
+    .filter(Boolean)
+    .join(" ");
+
+const isLocalPreviewOrigin = (url) => {
+  try {
+    const { hostname } = new URL(url);
+    return (
+      hostname === "localhost" ||
+      hostname === "127.0.0.1" ||
+      hostname === "[::1]" ||
+      hostname === "0.0.0.0"
+    );
+  } catch {
+    return false;
+  }
+};
+
+const runtimeMessageText = (payload) => {
+  if (payload == null) return "";
+  if (typeof payload !== "object") return textOf(payload);
+
+  const candidate =
+    payload.text ?? payload.message ?? payload.description ?? payload.error;
+  if (candidate == null) return "";
+  if (typeof candidate === "object") {
+    const flattened = flattenRuntimePayload(candidate);
+    if (flattened) return flattened;
+    try {
+      return JSON.stringify(candidate);
+    } catch {
+      return "[object Object]";
+    }
+  }
+  return textOf(candidate);
+};
+
+const runtimeFindingText = (payload) => {
+  if (payload == null) return "";
+  if (typeof payload !== "object") return textOf(payload);
+
+  const parts = [
+    payload.text,
+    payload.message,
+    payload.description,
+    payload.error,
+    payload.reason,
+    payload.args,
+    payload.value,
+    payload.stack,
+    payload.detail,
+  ];
+
+  const texts = [];
+  for (const part of parts) {
+    if (part == null) continue;
+    if (typeof part === "string") {
+      texts.push(part);
+      continue;
+    }
+    const flattened = flattenRuntimePayload(part);
+    if (flattened) texts.push(flattened);
+  }
+
+  if (texts.length > 0) return texts.join(" ").trim();
+  return flattenRuntimePayload(payload);
+};
+
+const isOpaqueObjectLabel = (message) =>
+  /^(Object|\[object Object\])$/i.test(textOf(message).trim());
+
+const isOpaquePromiseRejectionMessage = (message) => {
+  const text = textOf(message).trim();
+  if (!text) return false;
+  if (isOpaqueObjectLabel(text)) return true;
+  if (/^Uncaught \(in promise\)/i.test(text)) return true;
+  if (/\[TMA\].*unhandledRejection/i.test(text)) return true;
+  return false;
+};
+
+export const isBenignRuntimeFinding = (payload, sessionContext = "") => {
+  const flattened = flattenRuntimePayload(payload);
+  const haystack = [flattened, sessionContext].filter(Boolean).join(" ");
+  if (matchesBenignRuntimeText(haystack)) return true;
+  if (matchesBenignRuntimeText(flattened)) return true;
+
+  const message = runtimeMessageText(payload);
+  const url =
+    payload && typeof payload === "object"
+      ? textOf(payload.url || payload.source || payload.filename)
+      : "";
+  const detail =
+    payload && typeof payload === "object"
+      ? textOf(payload.detail || payload.stack)
+      : "";
+
+  if (isOpaqueObjectLabel(message) && /^blob:/i.test(url)) return true;
+  if (
+    isOpaqueObjectLabel(message) &&
+    (/^blob:/i.test(detail) ||
+      /blob:|localhost|127\.0\.0\.1/i.test(`${url} ${detail}`))
+  ) {
+    return true;
+  }
+
+  if (
+    isOpaquePromiseRejectionMessage(message) &&
+    matchesBenignRuntimeText(sessionContext)
+  ) {
+    return true;
+  }
+
+  return matchesBenignRuntimeText(message);
+};
+
+export const isBenignPreviewRuntimeFinding = (payload, sessionContext, previewUrl) => {
+  const findingText = runtimeFindingText(payload);
+  if (isBenignRuntimeFinding(payload, sessionContext)) return true;
+  if (matchesBenignRuntimeText(findingText)) return true;
+  if (!isLocalPreviewOrigin(previewUrl)) return false;
+
+  const message = runtimeMessageText(payload);
+  if (isOpaqueObjectLabel(message)) return true;
+  if (isOpaquePromiseRejectionMessage(message)) return true;
+  if (isOpaquePromiseRejectionMessage(findingText)) return true;
+
+  return false;
+};
+
+const isBenignRuntimeUrl = (url) => {
+  const text = textOf(url);
+  // Taro H5 optional file; missing in local preview is expected noise
+  if (/hot-reload-config\.json/i.test(text)) return true;
+  try {
+    if (hostnameIsBenignRuntime(new URL(text).hostname)) return true;
+  } catch {
+    // fall through
+  }
+
+  const proxyTarget = extractPreviewProxyTargetUrl(text);
+  if (proxyTarget && hostnameIsBenignRuntime(proxyTarget.hostname)) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * agent-browser 经 CDP 采集网络请求时，Fetch/XHR 常拿不到 status，
+ * 不能据此判失败。仅对明确 >=400，或同域 Document/Script 缺 status 报错；
+ * 已成功重定向的初始 Document 在浏览器检查中单独排除。
+ */
+export const isActionableNetworkRequestFailure = (request, pageOrigin) => {
+  const requestUrl = textOf(request.url);
+  if (isBenignRuntimeUrl(requestUrl)) return false;
+
+  const status =
+    typeof request.status === "number" ? request.status : Number(request.status);
+  const hasStatus = Number.isFinite(status);
+  if (hasStatus) return status >= 400;
+
+  if (isLocalPreviewProxyRequest(requestUrl)) return false;
+  if (["Fetch", "XHR"].includes(request.resourceType)) return false;
+  if (!["Document", "Script"].includes(request.resourceType)) return false;
+
+  try {
+    return new URL(requestUrl).origin === pageOrigin;
+  } catch {
+    return false;
+  }
+};
+
+/** The preview runner may redirect the initial document to the same path with card_appids. */
+const isCompletedSamePageRedirect = (request, requestedUrl, requests) => {
+  if (request.resourceType !== 'Document' || Number.isFinite(Number(request.status))) return false
+  let initialUrl
+  try {
+    initialUrl = new URL(request.url)
+    if (initialUrl.href !== new URL(requestedUrl).href) return false
+  } catch {
+    return false
+  }
+  return requests.some((candidate) => {
+    if (candidate.resourceType !== 'Document') return false
+    const status = Number(candidate.status)
+    if (!Number.isFinite(status) || status < 200 || status >= 300) return false
+    try {
+      const completedUrl = new URL(candidate.url)
+      return completedUrl.origin === initialUrl.origin &&
+        completedUrl.pathname === initialUrl.pathname &&
+        completedUrl.search !== initialUrl.search
+    } catch {
+      return false
+    }
+  })
+}
+
+const parseHttpUrl = (value, label) => {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`Invalid ${label} runtime check URL: ${value}`);
+  }
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    throw new Error(`Unsupported ${label} URL protocol: ${parsed.protocol}`);
+  }
+  return parsed;
+};
+
+/**
+ * 仅为失败请求补充路径语义，不参与错误过滤。
+ * URL 拆分得到的是预期业务路由，不代表已观察到代理实际转发结果。
+ */
+const printRuntimeApiPathHint = (findings, previewUrl) => {
+  // PROJECT_DOMAIN 是前端构建期常量；根据错误里的实际 URL 识别模板路径。
+  for (const finding of findings) {
+    const urls = runtimeFindingText(finding)
+      .replace(/\\+\//g, "/")
+      .match(/https?:\/\/[^\s"'<>\\)\]}]+/g) || [];
+
+    for (const candidate of urls) {
+      let url;
+      try {
+        url = extractPreviewProxyTargetUrl(candidate) || new URL(candidate);
+      } catch {
+        continue;
+      }
+
+      let prefix;
+      const cloudPrefix = url.pathname.match(
+        /^(\/api\/apps\/open_ai_coding_chat_server\/aio_server\/[^/]+\/api)(?=\/api\/)/,
+      );
+      if (cloudPrefix) {
+        prefix = cloudPrefix[1];
+      } else if (
+        isLocalPreviewOrigin(url.href) &&
+        url.origin === new URL(previewUrl).origin &&
+        url.pathname.startsWith("/api/api/")
+      ) {
+        prefix = "/api";
+      }
+      if (!prefix) continue;
+
+      const serviceRoute = url.pathname.slice(prefix.length);
+      console.log([
+        "[verify] API 路径说明（网关前缀 + 业务路由）：",
+        `[verify] 网关前缀：${url.origin}${prefix}`,
+        `[verify] 预期业务路由：${serviceRoute}（按 URL 拆分，实际转发结果需核对）`,
+        "[verify] 本模板默认 PROJECT_DOMAIN 是以 /api 结尾的网关 baseURL；与 /api/... 业务路由拼接后，连续 /api/api/... 可以是预期格式。",
+        "[verify] 不要仅凭重复 /api 删除业务路由的 /api，或修改 PROJECT_DOMAIN、网络拼接函数、SDK 构建配置或 devServer 的代理推导。",
+        "[verify] 请求失败仍需排查：核对实际转发路径、服务端路由和 HTTP 方法，再结合状态码、响应内容及服务端日志定位。",
+      ].join("\n"));
+      return;
+    }
+  }
+};
+
+export function isIgnorableOpenCardConsoleFinding(value, options) {
+  if (!String(options.label ?? '').includes('opencard')) return false
+  let isLocalPreview = false
+  try {
+    const hostname = new URL(options.previewUrl).hostname
+    isLocalPreview = ['localhost', '127.0.0.1', '[::1]', '0.0.0.0'].includes(hostname)
+  } catch {}
+  if (!isLocalPreview) return false
+  const text = value && typeof value === 'object' && typeof value.text === 'string'
+    ? value.text
+    : flatten(value)
+  if (/Refused to set unsafe header ["']user-agent["']/i.test(text)) return true
+  return !options.hasActionableNetworkFailure &&
+    /Failed to load resource: the server responded with a status of 404/i.test(text)
+}
+
+async function browserCheck(root, url, label) {
+  if (packageUses(root, '@open-dy/threejs')) {
+    console.log(`[vibecoding:verify] ${label}: skipping browser runtime check for @open-dy/threejs`)
+    return
+  }
+  parseHttpUrl(url, label)
+  const session = process.env.AGENT_BROWSER_SESSION || `vibecoding-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  const call = (args, allowFailure = false) => runCaptured('agent-browser', ['--session', session, ...args], { allowFailure })
+  try {
+    await call(['network', 'requests'], true)
+    await call(['open', url])
+    await call(['wait', '--load', 'networkidle'], true)
+    await sleep(1500)
+    const [errorsResult, consoleResult, networkResult] = await Promise.all([
+      call(['errors', '--json']), call(['console', '--json']), call(['network', 'requests', '--json']),
+    ])
+    const parse = (result) => JSON.parse(result.stdout).data ?? {}
+    const pageErrors = parse(errorsResult).errors ?? []
+    const consoleErrors = (parse(consoleResult).messages ?? []).filter((item) => ['error', 'assert'].includes(item.type))
+    const origin = new URL(url).origin
+    const sessionContext = buildRuntimeSessionContext(parse(consoleResult).messages ?? [], pageErrors)
+    const requests = parse(networkResult).requests ?? []
+    const networkErrors = requests
+      .filter((item) => isActionableNetworkRequestFailure(item, origin) &&
+        !isCompletedSamePageRedirect(item, url, requests))
+    const actionableNetworkFailure = networkErrors.length > 0
+    const actionableConsoleErrors = consoleErrors.filter((item) =>
+      !isIgnorableOpenCardConsoleFinding(item, {
+        label,
+        previewUrl: url,
+        hasActionableNetworkFailure: actionableNetworkFailure,
+      }),
+    )
+    const findings = [
+      ...[...pageErrors, ...actionableConsoleErrors]
+        .filter((item) => !isBenignPreviewRuntimeFinding(item, sessionContext, url)),
+      ...networkErrors,
+    ]
+    if (findings.length > 0) {
+      printRuntimeApiPathHint(findings, url)
+      throw new CliError(`${label} runtime check found ${findings.length} issue(s):\n${findings.map((item) => `- ${flatten(item)}`).join('\n')}`)
+    }
+  } finally {
+    await call(['close'], true)
+  }
+}
+
+export function resolveFrontendUrl(context, options = {}, env = process.env) {
+  return options.frontendUrl || (context.target === 'opencard'
+    ? 'http://localhost:10087/'
+    : env.RUNTIME_CHECK_URL || 'http://localhost:10086/')
+}
+
+export async function runVerify(context, options = {}) {
+  if (options.staticOnly && options.portsOnly) {
+    throw new CliError('--static-only cannot be combined with --ports-only')
+  }
+  const full = Boolean(options.full || options.autoStart || options.staticOnly ||
+    (context.target === 'taro' && process.env.npm_lifecycle_event === 'verify'))
+  options = { timeoutSeconds: 90, ...options, full }
+  const frontendUrl = resolveFrontendUrl(context, options)
+  parseHttpUrl(frontendUrl, 'frontend')
+  if (full) await waitForDevInstall(context, options.timeoutSeconds)
+  if (full || options.staticOnly) await runStatic(context)
+  if (options.staticOnly) return
+
+  await verifyPorts(context, options, frontendUrl)
+  if (options.portsOnly) return
+  if (full && context.target === 'taro') await verifyFeedApi(context)
+  if (context.target === 'taro' &&
+      existsSync(path.resolve(context.root, '../sar_game/package.json'))) {
+    console.log('[vibecoding:verify] SAR game project detected; skipping browser runtime checks')
+    return
+  }
+  await browserCheck(context.root, frontendUrl, context.target)
+  if (context.target === 'taro' && context.hasOpenCard) {
+    await browserCheck(context.opencardRoot, 'http://localhost:10087/', 'opencard')
+  }
+}