@open-dy/vibecoding-cli 0.0.1-beta.2 → 0.0.1-beta.3

package/README.md

@@ -16,7 +16,11 @@ vibecoding verify --target taro --auto-start --full
 - `taro`：Taro 主应用、Server，以及项目中存在时的 OpenCard。
 - `opencard`：独立 OpenCard 项目。
 
-主要命令：`dev`、`build`、`lint`、`verify`、`pack`、`turbo`、`init-mysql-db`，以及 `validate feed-card|routes|empty|opencard-structure`。
+主要命令：`dev`、`build`、`lint`、`verify`、`pack`、`docs`、`turbo`、`init-mysql-db`，以及 `validate feed-card|routes|empty|opencard-structure`。
+
+`verify --full --auto-start` 在等待依赖安装日志前启动 dev；已有 dev 正在启动或运行时复用，一次校验最多启动一次。安装就绪只认最近一次启动的日志，安装失败直接报错；之后仍按静态检查、端口检查、API 与浏览器检查执行。`--static-only` 不启动 dev，也不等待 dev 日志。
+
+`vibecoding docs --target taro`（OpenCard 使用 `--target opencard`，可指定 `--cwd <工程目录>`）只读定位实际安装的 SDK，输出 JSON：依赖键、版本、包位置、文档索引及公开类型路径。`ready` 时沿 `index` 查阅；`docs-missing` 表示已安装的旧包没有索引，按 `exports` / `types` 查公开入口。业务导入使用 `imports`，npm 别名以依赖键为前缀，不能换成包的 `name`。包尚不可用时最多等待 `--timeout` 秒（默认 90），超时返回 `SDK_NOT_INSTALLED`，应检查工程安装结果。命令不会安装、重建 SDK 或启动服务。
 
 Turbo 构建应通过 CLI 包装命令执行，例如 `vibecoding turbo --target opencard run build:raw`。CLI 会读取项目的 `turbo.json`，合并版本化默认配置，并将结果写入项目内的 `.vibecoding/cache/turbo.json`；封闭域状态和 `config/card-routing.json` 也会参与构建环境与缓存输入。`--root-turbo-json` 由 CLI 管理，不能由业务命令覆盖；需要传递其他 Turbo 参数时，放在 `--` 后面。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-dy/vibecoding-cli",
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.3",
   "description": "Command orchestration, validation and packaging for Douyin vibecoding Taro and OpenCard projects.",
   "type": "module",
   "bin": {
@@ -34,14 +34,16 @@
     "pack:ppe": "node ./scripts/pack-ppe.mjs",
     "test:release": "node ../scripts/run-release-contracts.mjs",
     "publish:bnpm:ppe": "node ../scripts/ppe-release/cli.mjs vibecoding-cli",
-    "publish:bnpm:ppe:dry-run": "node ../scripts/ppe-release/cli.mjs vibecoding-cli --dry-run"
+    "publish:bnpm:ppe:dry-run": "node ../scripts/ppe-release/cli.mjs vibecoding-cli --dry-run",
+    "publish:npm:beta": "node ../scripts/npm-beta-release/cli.ts vibecoding-cli",
+    "publish:npm:beta:dry-run": "node ../scripts/npm-beta-release/cli.ts vibecoding-cli --dry-run"
   },
   "dependencies": {
     "ajv": "^8.18.0"
   },
   "peerDependencies": {
-    "@open-dy/vibecoding-sdk-taro": "0.0.1-beta.2",
-    "@open-dy/vibecoding-sdk-opencard": "0.0.1-beta.2"
+    "@open-dy/vibecoding-sdk-taro": "0.0.1-beta.3",
+    "@open-dy/vibecoding-sdk-opencard": "0.0.1-beta.3"
   },
   "peerDependenciesMeta": {
     "@open-dy/vibecoding-sdk-taro": {

package/src/build/opencard-environment.mjs

@@ -17,8 +17,9 @@ function findRoutingPath(cardRoot) {
 
 /** Read the host configuration; missing routing retains the legacy open-domain default. */
 export function resolveCardRoutingPath(context) {
-  return context.taroRoot
-    ? path.join(context.taroRoot, 'config/card-routing.json')
+  const hostRoot = context.taroRoot ?? (context.target === 'taro' ? context.root : undefined)
+  return hostRoot
+    ? path.join(hostRoot, 'config/card-routing.json')
     : findRoutingPath(context.root)
 }
 
@@ -37,8 +38,14 @@ export function readCardRouting(context) {
   } catch (error) {
     throw new Error(`${file} must contain valid JSON: ${error.message}`)
   }
-  if (!['closed', 'open', 'none', undefined].includes(routing?.cardData?.serviceDomain)) {
-    throw new Error(`${file} cardData.serviceDomain must be none, open, or closed`)
+  const serviceDomain = routing?.cardData?.serviceDomain
+  const guidance = '请核对卡片接口所属服务及现有需求后补齐或修正该字段，并重新执行 verify。\n' +
+    '证据不明确或存在冲突时请询问用户；不要通过默认填入 open 或 closed 来绕过校验。'
+  if (serviceDomain === undefined) {
+    throw new Error(`${file} 缺少 cardData.serviceDomain。\n${guidance}`)
+  }
+  if (!['closed', 'open', 'none'].includes(serviceDomain)) {
+    throw new Error(`${file} cardData.serviceDomain must be none, open, or closed; got ${JSON.stringify(serviceDomain)}。\n${guidance}`)
   }
   return routing
 }

package/src/cli.mjs

@@ -10,6 +10,7 @@ import { runPack } from './commands/pack.mjs'
 import { runValidate } from './commands/validate.mjs'
 import { runVerify } from './commands/verify.mjs'
 import { runTurbo } from './commands/turbo.mjs'
+import { runDocs } from './commands/docs.mjs'
 
 const HELP = `Usage: vibecoding <command> [options]
 
@@ -22,6 +23,7 @@ Commands:
   validate <name>        Run feed-card, routes, empty or opencard-structure
   init-mysql-db          Initialize the Taro server database
   pack                   Build deployment archives
+  docs                   Locate the selected project's installed SDK reference
   turbo <args...>        Run Turbo with CLI defaults and project config
 
 Required:
@@ -38,7 +40,7 @@ Options:
   --static-only          Verify static phase only
   --ports-only           Verify listening ports only
   --auto-start           Start dev once when verify finds missing ports
-  --timeout <seconds>    Dev startup timeout (default: 90)
+  --timeout <seconds>    Dev startup / docs dependency wait timeout (default: 90)
   --frontend-url <url>   Override the primary runtime-check URL`
 
 function assertNoExtra(positionals, count, command) {
@@ -95,6 +97,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'lint': assertNoExtra(positionals, 1, command); return runLint(context, options)
     case 'verify': assertNoExtra(positionals, 1, command); return runVerify(context, options)
     case 'pack': assertNoExtra(positionals, 1, command); return runPack(context, options)
+    case 'docs': assertNoExtra(positionals, 1, command); return runDocs(context, options)
     case 'init-mysql-db': assertNoExtra(positionals, 1, command); return runDatabaseInit(context)
     case 'validate':
       assertNoExtra(positionals, 2, command)

package/src/commands/build.mjs

@@ -1,4 +1,4 @@
-import { openCardBuildEnvironment } from '../build/opencard-environment.mjs'
+import { openCardBuildEnvironment, readCardRouting } from '../build/opencard-environment.mjs'
 import { mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { readEnvFile } from '../core/environment.mjs'
@@ -33,6 +33,7 @@ export async function buildTaroFrontend(context, type, options = {}) {
 export async function buildOpenCard(context, options = {}) {
   const root = context.target === 'opencard' ? context.root : context.opencardRoot
   if (!root) return
+  const cardEnvironment = openCardBuildEnvironment(context)
   const args = ['build', '--type', 'tt']
   if (options.mode) args.push('--mode', options.mode)
   if (options.watch) args.push('--watch')
@@ -41,7 +42,7 @@ export async function buildOpenCard(context, options = {}) {
     env: taroEnvironment(root, {
       ...(options.watch ? { TT_OUTPUT_ROOT: 'dist-tt' } : {}),
       ...options.env,
-      ...openCardBuildEnvironment(context),
+      ...cardEnvironment,
     }),
     label: 'opencard tt build',
   })
@@ -78,6 +79,7 @@ export function buildClosedDomainServer(context, options = {}) {
  * exposes only the stable `pack.sh` entrypoint.
  */
 export async function buildPackInputs(context, options = {}) {
+  readCardRouting(context)
   const tasks = [
     { name: 'taro-tt', run: () => buildTaroFrontend(context, 'tt', { ...options, mode: 'prod' }) },
     { name: 'server', run: () => buildServer(context, { ...options, production: true }) },
@@ -92,6 +94,7 @@ export async function buildPackInputs(context, options = {}) {
 }
 
 export async function runBuild(context, options = {}) {
+  readCardRouting(context)
   const buildOptions = {
     ...options,
     env: resolveBuildEnvironment(context.root, options.env),

package/src/commands/dev.mjs

@@ -232,8 +232,7 @@ export async function runDev(context, options = {}) {
         env,
         onExit: handlePreviewExit,
       })
-      children.push({ child: preview.child, name: 'opencard watch' })
-      runtimes.push(preview.runtime)
+      runtimes.push(preview)
     } else {
       const baseline = env.HAS_CALLED_DATABASE_INIT_TOOL
       await runDatabaseInit(context, { env })
@@ -268,8 +267,7 @@ export async function runDev(context, options = {}) {
       )
       const startManagedPreview = async (previewOptions) => {
         const preview = await startPreview(previewOptions)
-        children.push({ child: preview.child, name: previewOptions.cardMode ? 'opencard watch' : 'taro watch' })
-        runtimes.push(preview.runtime)
+        runtimes.push(preview)
       }
       const previewTasks = [
         startManagedPreview({ root: context.root, env, onExit: handlePreviewExit }),

package/src/commands/docs.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { CliError } from '../core/errors.mjs'
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+const isFile = file => existsSync(file) && statSync(file).isFile()
+
+function targets(value) {
+  if (typeof value === 'string') return [value]
+  if (!value || typeof value !== 'object') return []
+  return Object.values(value).flatMap(targets)
+}
+
+// Limit lookup to project/ancestor node_modules, including pnpm hoisting.
+// NODE_PATH and global packages are not evidence of this project's install.
+function installedPackage(root, dependency) {
+  const require = createRequire(path.join(root, 'package.json'))
+  for (const directory of require.resolve.paths(dependency) ?? []) {
+    const relative = path.relative(path.dirname(directory), root)
+    if (path.basename(directory) !== 'node_modules' || relative === '..'
+      || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue
+    const manifest = path.join(directory, dependency, 'package.json')
+    if (isFile(manifest)) return realpathSync(path.dirname(manifest))
+  }
+  return null
+}
+
+function packageFile(root, target) {
+  if (!target.startsWith('./') || target.includes('*')) return null
+  const file = path.resolve(root, target)
+  const relative = path.relative(root, file)
+  return !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) && isFile(file) ? file : null
+}
+
+/** Resolve the selected project's declared SDK and its installed documentation.
+ * This also handles npm aliases and pnpm symlinks without a package.json export.
+ */
+export function resolveSdkDocumentation(context) {
+  const manifest = JSON.parse(readFileSync(path.join(context.root, 'package.json'), 'utf8'))
+  const dependencies = { ...manifest.devDependencies, ...manifest.dependencies }
+  const suffix = context.target === 'opencard' ? 'opencard' : 'taro'
+  const expected = `@open-dy/vibecoding-sdk-${suffix}`
+  const aliasPattern = new RegExp(`^npm:@[^/]+/vibecoding-sdk-${suffix}(?:@|$)`)
+  const dependency = Object.hasOwn(dependencies, expected) ? expected
+    : Object.keys(dependencies).find(key => aliasPattern.test(dependencies[key]))
+      ?? (Object.hasOwn(dependencies, '@open-dy/vibecoding-sdk') ? '@open-dy/vibecoding-sdk'
+        : Object.keys(dependencies).find(key => /^npm:@[^/]+\/vibecoding-sdk(?:@|$)/.test(dependencies[key])))
+  if (!dependency) throw new CliError(`[SDK_NOT_DECLARED] ${expected} is not declared in ${context.root}/package.json`)
+  const root = installedPackage(context.root, dependency)
+  if (!root) return { status: 'not-installed', dependency, projectRoot: context.root }
+  const sdk = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'))
+  const exports = sdk.exports && typeof sdk.exports === 'object' && !Array.isArray(sdk.exports)
+    && Object.keys(sdk.exports).some(key => key.startsWith('.')) ? sdk.exports : { '.': sdk.exports }
+  const docTargets = targets(exports['./reference/llms.txt'] ?? exports['./reference/*'])
+    .map(target => target.replaceAll('*', 'llms.txt'))
+  const index = [...docTargets, './dist/reference/llms.txt'].map(target => packageFile(root, target)).find(Boolean) ?? null
+  const types = Object.entries(exports).flatMap(([key, value]) => {
+    if (key.includes('*')) return []
+    const candidates = targets(value).filter(target => /\.d\.[cm]?ts$/.test(target))
+    // Root-level `types` is also used by older packages with a JS root export.
+    if (key === '.' && sdk.types) candidates.push(sdk.types.startsWith('./') ? sdk.types : `./${sdk.types}`)
+    const file = candidates.map(target => packageFile(root, target)).find(Boolean)
+    return file ? [{ importPath: key === '.' ? dependency : `${dependency}/${key.slice(2)}`, file }] : []
+  })
+  return { status: index ? 'ready' : 'docs-missing', dependency, name: sdk.name, version: sdk.version,
+    projectRoot: context.root, packageRoot: root, index, exports: sdk.exports ?? null,
+    imports: Object.keys(exports).filter(key => exports[key] != null || (key === '.' && sdk.exports === undefined))
+      .map(key => key === '.' ? dependency : `${dependency}/${key.slice(2)}`), types }
+}
+
+/** Wait only for this project's SDK package; never install or start services. */
+export async function waitForSdkDocumentation(context, { timeoutSeconds = 90, sleepFn = sleep } = {}) {
+  const deadline = Date.now() + timeoutSeconds * 1000
+  while (true) {
+    const result = resolveSdkDocumentation(context)
+    if (result.status !== 'not-installed') return result
+    if (Date.now() >= deadline) {
+      throw new CliError(`[SDK_NOT_INSTALLED] ${result.dependency} was not available after ${timeoutSeconds}s in ${context.root}. ` +
+        'Check the current project dependency installation result; do not search other projects or rebuild the SDK for documentation.')
+    }
+    await sleepFn(Math.min(500, Math.max(0, deadline - Date.now())))
+  }
+}
+
+/** Print machine-readable SDK documentation paths for Agent lookup. */
+export async function runDocs(context, options = {}) {
+  const result = await waitForSdkDocumentation(context, options)
+  console.log(JSON.stringify(result, null, 2))
+  return result
+}

package/src/commands/pack.mjs

@@ -16,6 +16,7 @@ import { spawn } from 'node:child_process'
 import { CliError } from '../core/errors.mjs'
 import { resolveProjectContext } from '../core/context.mjs'
 import { buildOpenCard, buildPackInputs } from './build.mjs'
+import { readCardRouting } from '../build/opencard-environment.mjs'
 
 const DEFAULT_ARTIFACTS = '/tmp/microapp_artifacts'
 
@@ -135,6 +136,8 @@ export async function packTaroArtifacts(context, artifacts) {
 }
 
 export async function runPack(context, options = {}) {
+  // Validate before cleaning old artifacts, including projects with a legacy build:pack hook.
+  readCardRouting(context)
   const artifacts = resolveArtifactsDirectory(context.root,
     options.artifactsDir ?? process.env.ARTIFACTS_DIR ?? DEFAULT_ARTIFACTS)
   if (context.target === 'opencard') {

package/src/commands/verify.mjs

@@ -6,8 +6,10 @@ 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 { devProcessMatches, inspectDevProcess } from '../core/dev-process.mjs'
 import { packageUses, validateDependencies } from '../validators/dependencies.mjs'
 import { validateFeedCard } from '../validators/feed-card.mjs'
+import { readCardRouting } from '../build/opencard-environment.mjs'
 import { runBuild } from './build.mjs'
 import { runDatabaseInit } from './db.mjs'
 import { runLint } from './lint.mjs'
@@ -59,14 +61,32 @@ export function startDevDetached(context, spawnProcess = spawn) {
   })
 }
 
-export function resolveDevLogPath(context, env = process.env) {
-  if (env.LOG_FILE) return env.LOG_FILE
-  const runtimeRoot = env.VIBECODING_RUNTIME_ROOT || (
+function resolveDevRuntimeRoot(context, env = process.env) {
+  // Match the supervisor: standalone OpenCard shares its host's runtime files.
+  const root = context.taroRoot ?? (context.target === 'opencard' ? path.dirname(context.root) : context.root)
+  return env.VIBECODING_RUNTIME_ROOT || (
     process.platform === 'linux'
       ? '/workspace/tmp'
-      : path.join(context.root, '.tmp/microapp-dev')
+      : path.join(root, '.tmp/microapp-dev')
   )
-  return path.join(runtimeRoot, 'microapp-logs/dev.log')
+}
+
+export function resolveDevLogPath(context, env = process.env) {
+  return env.LOG_FILE || path.join(resolveDevRuntimeRoot(context, env), 'microapp-logs/dev.log')
+}
+
+function readDevLog(context) {
+  try { return readFileSync(resolveDevLogPath(context), 'utf8') } catch { return '' }
+}
+
+function hasRunningDev(context) {
+  return ['microapp-dev-script.pid', 'microapp-dev-run.pid'].some(name => {
+    let pid
+    try { pid = readFileSync(path.join(resolveDevRuntimeRoot(context), name), 'utf8').trim() } catch { return false }
+    if (!/^[1-9][0-9]*$/.test(pid) || !Number.isSafeInteger(Number(pid))) return false
+    try { process.kill(Number(pid), 0) } catch (error) { if (error.code !== 'EPERM') return false }
+    return devProcessMatches(context, inspectDevProcess(Number(pid)))
+  })
 }
 
 function printLastRunErrors(logFile, log) {
@@ -88,7 +108,15 @@ export async function waitForDevInstall(context, timeoutSeconds, options = {}) {
   const sleepFn = options.sleepFn ?? sleep
   const deadline = Date.now() + timeoutSeconds * 1000
   while (Date.now() < deadline) {
-    if (readLog().includes('Dependencies installed successfully')) return
+    // Exclude previous runs, including the old log before a new supervisor has
+    // appended its separator. A newly launched run supplies its starting offset.
+    const newLog = readLog().slice(options.logOffset ?? 0)
+    const sections = newLog.split('--- DEV_RUN_START ---')
+    const section = options.logOffset !== undefined && sections.length === 1 ? '' : sections.at(-1) || ''
+    const failure = section.split('\n').find(line =>
+      /(?:pnpm install failed|Dependency installation failed|CLI installation did not create)/i.test(line))
+    if (failure) throw new CliError(`Dev dependency installation failed: ${failure.trim()}. Full log: ${logFile}`)
+    if (section.includes('Dependencies installed successfully')) return
     await sleepFn(options.pollMs ?? 1_000)
   }
   printLastRunErrors(logFile, readLog())
@@ -98,19 +126,25 @@ export async function waitForDevInstall(context, timeoutSeconds, options = {}) {
   )
 }
 
-async function verifyPorts(context, options, frontendUrl) {
+async function prepareDev(context, options, frontendUrl) {
+  if (!options.autoStart || options.staticOnly) return {}
   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 status = await waitForPorts(ports, 1)
+  if (status.every(entry => entry.listening) || hasRunningDev(context)) return {}
+  const logOffset = readDevLog(context).length
   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)
+  console.log(`[vibecoding:verify] started dev (PID ${pid}); waiting for dependency installation`)
+  return { logOffset }
+}
+
+async function verifyPorts(context, options, frontendUrl) {
+  const ports = targetPorts(context, frontendUrl, options.full)
+  const status = await waitForPorts(ports, options.autoStart ? options.timeoutSeconds : 1)
   const missing = status.filter((entry) => !entry.listening)
   if (missing.length > 0) {
+    if (!options.autoStart) {
+      throw new CliError(`Ports not listening: ${missing.map(entry => `${entry.label}:${entry.port}`).join(', ')}`)
+    }
     printLastRunErrors(resolveDevLogPath(context))
     throw new CliError(`Ports not ready after ${options.timeoutSeconds}s: ${missing.map((entry) => `${entry.label}:${entry.port}`).join(', ')}`)
   }
@@ -578,12 +612,15 @@ export async function runVerify(context, options = {}) {
   if (options.staticOnly && options.portsOnly) {
     throw new CliError('--static-only cannot be combined with --ports-only')
   }
+  // Fail before waiting for dev/install or starting build/runtime checks, for both targets.
+  readCardRouting(context)
   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)
+  const installOptions = await prepareDev(context, options, frontendUrl)
+  if (full && !options.staticOnly) await waitForDevInstall(context, options.timeoutSeconds, installOptions)
   if (full || options.staticOnly) await runStatic(context)
   if (options.staticOnly) return
 

package/src/core/dev-process.mjs

@@ -0,0 +1,53 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync, readlinkSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+import { resolveProjectContext } from './context.mjs'
+
+/** Read only the recorded PID; never search processes or other projects. */
+export function inspectDevProcess(pid) {
+  try {
+    const command = execFileSync('ps', ['-ww', '-p', String(pid), '-o', 'args='],
+      { encoding: 'utf8', timeout: 1_000 }).trim()
+    const cwd = process.platform === 'linux' ? readlinkSync(`/proc/${pid}/cwd`)
+      : execFileSync('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'],
+        { encoding: 'utf8', timeout: 1_000 }).split('\n').find(line => line.startsWith('n'))?.slice(1)
+    // Bootstrap may override its script's default root. Read just that field
+    // from Linux process metadata; never expose process environment contents.
+    let workspacePath
+    if (process.platform === 'linux') {
+      try { workspacePath = readFileSync(`/proc/${pid}/environ`, 'utf8')
+        .split('\0').find(entry => entry.startsWith('WORKSPACE_PATH='))?.slice('WORKSPACE_PATH='.length) } catch {}
+    }
+    return { command, cwd, workspacePath }
+  } catch { return null }
+}
+
+const flag = (command, name) => command.match(new RegExp(
+  `(?:^|\\s)--${name}(?:=|\\s+)(.*?)(?=\\s+--[\\w-]+(?:[=\\s]|$)|$)`,
+))?.[1]?.trim().replace(/^(['"])(.*)\1$/, '$2')
+const canonical = directory => {
+  try { return realpathSync(directory) } catch { return path.resolve(directory) }
+}
+
+/** A live PID is reusable only when its dev entry, project and target match. */
+export function devProcessMatches(context, state) {
+  if (!state?.cwd) return false
+  const { command, cwd } = state
+  const launcher = /(?:^|\s)(?:\S*\/)?vibecoding(?:-dev|\.mjs)?\s/.test(command)
+    && /(?:^|\s)dev(?:\s|$)/.test(command)
+  const bootstrap = command.match(/^(?:\S*\/)?bash\s+(.*?scripts\/dev_run\.sh)(?:\s|$)/)
+  if (!launcher && !bootstrap) return false
+  const target = launcher ? flag(command, 'target') : 'taro'
+  if (!['taro', 'opencard'].includes(target)) return false
+  let root = path.resolve(cwd, launcher ? flag(command, 'cwd') || '.'
+    : state.workspacePath || path.join(path.dirname(bootstrap[1]), '..'))
+  if (launcher) {
+    // The public CLI can start from a project subdirectory without --cwd.
+    try { root = resolveProjectContext({ cwd: root, target }).root } catch {}
+  }
+  root = canonical(root)
+  const expected = canonical(context.root)
+  return root === expected && target === context.target
+    || context.target === 'opencard' && target === 'taro'
+      && canonical(path.join(root, 'opencard')) === expected
+}