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

package/README.md

@@ -16,7 +16,9 @@ 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`。
+
+`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.4",
   "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.4",
+    "@open-dy/vibecoding-sdk-opencard": "0.0.1-beta.4"
   },
   "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

@@ -8,6 +8,7 @@ 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 { readCardRouting } from '../build/opencard-environment.mjs'
 import { runBuild } from './build.mjs'
 import { runDatabaseInit } from './db.mjs'
 import { runLint } from './lint.mjs'
@@ -578,6 +579,8 @@ 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 }