@vibecuting/component-project-helper 0.1.17 → 0.1.19

package/README.md

@@ -9,11 +9,10 @@ NPM 地址：
 职责：
 
 - 作为可发布的 npm 包承载组件工程辅助逻辑。
-- 提供组件注解、schema、发现器、Markdown 生成和安装期生命周期逻辑。
+- 提供组件注解、schema、发现器、元数据生成、技能说明生成和安装期生命周期逻辑。
 - 安装时会优先把当前工程识别为包含 `src/components` 或 `src/video/chapters` 的独立项目，再扫描 `src/components/**/*.tsx`、`src/video/chapters/**/*.tsx` 以及 `node_modules/@vibecuting/*/src/**/*.tsx`，把组件元数据生成到 `.agents/skills/project-allow-component/components/`。
-- 通过 `postinstall` / `preuninstall` 维护生成文件和清理清单。
-- 安装时会给宿主工程的 `package.json` 补上 `update-component-skills`，它会调用同一套 `postinstall` 逻辑。
-- 宿主工程也可以直接运行 `pnpm update-component-skills` 手动刷新同一套生成结果。
+- 宿主工程的 `update-component-skills` 会基于 `.vibecuting/video-resource-meta.generated.ts` 生成技能说明，不再执行模板源码文件本身。
+- 宿主工程也可以直接运行 `pnpm run update-component-skills` 手动刷新同一套生成结果。
 - 作为主工程之外的独立 helper 包，避免把辅助逻辑重新塞回主站代码里。
 
 目录结构：
@@ -21,7 +20,7 @@ NPM 地址：
 - `src/decorators`：注解定义和元数据读写
 - `src/schemas`：zod schema
 - `src/discovery`：组件发现与解析
-- `src/markdown`：Markdown 渲染
+- `src/meta`：元数据和技能说明生成
 - `src/runtime`：安装根与输出路径解析
 - `src/lifecycle`：postinstall / preuninstall 生命周期逻辑
 
@@ -29,7 +28,6 @@ NPM 地址：
 
 - `pnpm typecheck`
 - `pnpm test`
-- `node ./bin/component-project-helper.mjs postinstall`
 - `pnpm update-component-skills`
 
 发布与安装：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecuting/component-project-helper",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./src/index.ts",
@@ -21,10 +21,10 @@
   },
   "scripts": {
     "update-component-meta": "node ./scripts/update-component-meta.mjs",
-    "update-component-skills": "pnpm run update-component-meta",
+    "update-component-skills": "node ./scripts/update-component-skills.mjs",
     "lint": "node ../../../scripts/run-eslint.mjs .",
-    "typecheck": "node ../../../node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
-    "test": "node ../../../node_modules/vitest/vitest.mjs run"
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run"
   },
   "dependencies": {
     "reflect-metadata": "^0.2.2",
@@ -33,6 +33,8 @@
     "zod": "4.1.12"
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "@testing-library/jest-dom": "^6.8.0",
+    "@types/node": "20.12.2",
+    "vitest": "^4.1.0"
   }
 }

package/scripts/package-json.mjs

@@ -3,7 +3,7 @@ import path from 'node:path'
 
 export const componentProjectSkillsScriptName = 'update-component-skills'
 export const componentProjectSkillsScriptCommand =
-  'node ./node_modules/@vibecuting/component-project-helper/scripts/update-component-meta.mjs'
+  'node ./node_modules/@vibecuting/component-project-helper/scripts/update-component-skills.mjs'
 
 async function readPackageJson(projectRoot) {
   const packageJsonPath = path.join(projectRoot, 'package.json')

package/scripts/update-component-skills.mjs

@@ -0,0 +1,63 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const require = createRequire(import.meta.url)
+
+function resolveLoaderPath() {
+  const candidates = [
+    path.resolve(process.cwd(), 'node_modules/tsx/dist/loader.mjs'),
+    path.resolve(process.cwd(), '../../../project-templates/video-project/node_modules/tsx/dist/loader.mjs'),
+    path.resolve(process.cwd(), '../../../project-templates/component-project/node_modules/tsx/dist/loader.mjs'),
+  ]
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate
+    }
+  }
+
+  return require.resolve('tsx')
+}
+
+const scriptPath = path.relative(process.cwd(), fileURLToPath(import.meta.url))
+const helperScriptPath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'src',
+  'meta',
+  'update-component-skills.ts',
+)
+
+if (!process.env.COMPONENT_PROJECT_HELPER_UPDATE_COMPONENT_SKILLS_LOADER) {
+  const loaderPath = resolveLoaderPath()
+  const result = spawnSync(
+    process.execPath,
+    ['--import', loaderPath, scriptPath, ...process.argv.slice(2)],
+    {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        COMPONENT_PROJECT_HELPER_UPDATE_COMPONENT_SKILLS_LOADER: '1',
+      },
+      stdio: 'inherit',
+    },
+  )
+
+  if (result.error) {
+    throw result.error
+  }
+
+  process.exit(result.status ?? 1)
+}
+
+const helperModule = await import(
+  pathToFileURL(helperScriptPath).href
+)
+
+await helperModule.updateComponentSkills(
+  process.cwd(),
+  process.argv.includes('--check'),
+)

package/src/discovery/index.ts

@@ -56,6 +56,13 @@ const metadataFactoryMap: DescriptorMap = {
     themeResourceDescriptor as VideoResourceDescriptor<VideoResourceMetadata>,
 }
 
+const staticMetadataFactoryNames = new Set([
+  sceneResourceDescriptor.metadataFactoryName,
+  transitionResourceDescriptor.metadataFactoryName,
+  themeResourceDescriptor.metadataFactoryName,
+  'defineComponentProjectComponentMetadata',
+])
+
 function toScriptKind(filePath: string): ts.ScriptKind {
   if (filePath.endsWith('.tsx')) {
     return ts.ScriptKind.TSX
@@ -111,7 +118,7 @@ function unwrapExpression(node: ts.Expression): ts.Expression {
   }
 }
 
-function evaluateStaticExpression(node: ts.Expression, filePath: string): unknown {
+export function evaluateStaticExpression(node: ts.Expression, filePath: string): unknown {
   const expression = unwrapExpression(node)
 
   if (ts.isStringLiteralLike(expression)) {
@@ -193,6 +200,17 @@ function evaluateStaticExpression(node: ts.Expression, filePath: string): unknow
     return result
   }
 
+  if (ts.isCallExpression(expression)) {
+    const factoryName = getIdentifierName(expression.expression)
+    if (factoryName && staticMetadataFactoryNames.has(factoryName)) {
+      const firstArgument = expression.arguments[0]
+      if (!firstArgument || !ts.isExpression(firstArgument)) {
+        throw new Error(`${filePath}: static metadata factory ${factoryName} requires a single object literal argument`)
+      }
+      return evaluateStaticExpression(firstArgument, filePath)
+    }
+  }
+
   if (ts.isIdentifier(expression) && expression.text === 'undefined') {
     return undefined
   }

package/src/index.ts

@@ -38,6 +38,9 @@ export {
 export {
   updateComponentMeta,
 } from './meta/update-component-meta'
+export {
+  updateComponentSkills,
+} from './meta/update-component-skills'
 export {
   VideoComponent,
   defineComponentProjectComponentMetadata,

package/src/meta/update-component-skills.test.ts

@@ -0,0 +1,66 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+
+import { expect, test } from 'vitest'
+
+import { updateComponentSkills } from './update-component-skills'
+
+test('writes and checks the skill docs from generated metadata', async () => {
+  const projectRoot = await fs.mkdtemp(path.join(tmpdir(), 'component-project-helper-skills-'))
+  const generatedDir = path.join(projectRoot, '.vibecuting')
+  const generatedFilePath = path.join(generatedDir, 'video-resource-meta.generated.ts')
+
+  await fs.mkdir(generatedDir, { recursive: true })
+  await fs.writeFile(
+    generatedFilePath,
+    `
+      export const videoResourceMeta = {
+        packageFingerprint: 'sha256:demo',
+        packages: [{ packageName: '@vibecuting/demo-pack', packageVersion: '1.0.0' }],
+        resources: [
+          {
+            packageName: '@vibecuting/demo-pack',
+            exportName: 'DemoScene',
+            metadata: {
+              resourceKind: 'scene',
+              name: 'DemoScene',
+              description: 'Demo scene resource',
+              sourceFile: 'src/index.ts',
+              pluginKey: 'demo.scene',
+              tags: ['demo'],
+              aspectRatio: '16:9',
+              sceneType: 'scene',
+              sceneFamily: 'custom',
+              rootLayout: 'absolute-fill',
+              propsTypeName: 'DemoSceneProps',
+              slots: ['title'],
+            },
+          },
+        ],
+      } as const
+    `,
+    'utf8',
+  )
+
+  await updateComponentSkills(projectRoot)
+
+  const docsDir = path.join(projectRoot, '.agents', 'skills', 'project-allow-component', 'components')
+  const generatedDocPath = path.join(docsDir, 'DemoScene.md')
+  const generatedDocContents = await fs.readFile(generatedDocPath, 'utf8')
+  const generatedManifestPath = path.join(
+    projectRoot,
+    '.agents',
+    'skills',
+    'project-allow-component',
+    'component-project-helper.manifest.json',
+  )
+  const generatedManifestContents = await fs.readFile(generatedManifestPath, 'utf8')
+
+  expect(generatedDocContents).toContain('Demo scene resource')
+  expect(generatedDocContents).toContain('resourceKind: scene')
+  expect(generatedManifestContents).toContain('video-resource-meta.generated.ts')
+  expect(generatedManifestContents).toContain('DemoScene.md')
+
+  await expect(updateComponentSkills(projectRoot, true)).resolves.toBeUndefined()
+})

package/src/meta/update-component-skills.ts

@@ -0,0 +1,310 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import ts from 'typescript'
+
+import { evaluateStaticExpression } from '../discovery/index.ts'
+import {
+  resolveComponentProjectGeneratedDocsDir,
+  resolveComponentProjectGeneratedManifestPath,
+} from '../runtime/index.ts'
+
+type VideoResourceMetaRecord = {
+  packageName: string
+  exportName: string
+  metadata: {
+    resourceKind: 'scene' | 'transition' | 'theme'
+    name: string
+    description: string
+    sourceFile: string
+    pluginKey: string
+    tags: string[]
+    aspectRatio?: '9:16' | '16:9'
+    sceneType?: 'intro' | 'scene' | 'outro'
+    sceneFamily?: string
+    themePreset?: string
+    slots?: Array<string | {
+      name: string
+      description?: string
+      required?: boolean
+      accepts?: 'text' | 'image' | 'video' | 'component' | 'any'
+    }>
+    propsTypeName?: string
+    rootLayout?: 'absolute-fill'
+    transitionKind?: 'transition' | 'overlay'
+    supportedSceneFamilies?: string[]
+    cssVariables?: string[]
+  }
+}
+
+type VideoResourceMetaFile = {
+  videoResourceMeta?: {
+    packageFingerprint?: string
+    packages?: Array<{
+      packageName: string
+      packageVersion: string
+    }>
+    resources: VideoResourceMetaRecord[]
+  }
+}
+
+type GeneratedSkillDoc = {
+  filePath: string
+  contents: string
+}
+
+function stringifyFrontmatterList(items: readonly string[]): string {
+  return items.map((item) => `  - ${item}`).join('\n')
+}
+
+function stringifySlots(
+  slots: NonNullable<VideoResourceMetaRecord['metadata']['slots']>,
+): string {
+  if (slots.length === 0) {
+    return '[]'
+  }
+
+  return slots
+    .map((slot) => {
+      if (typeof slot === 'string') {
+        return `  - ${slot}`
+      }
+
+      const lines = [
+        `  - name: ${slot.name}`,
+        slot.description ? `    description: ${slot.description}` : undefined,
+        slot.required !== undefined ? `    required: ${slot.required}` : undefined,
+        slot.accepts ? `    accepts: ${slot.accepts}` : undefined,
+      ].filter(Boolean)
+
+      return lines.join('\n')
+    })
+    .join('\n')
+}
+
+function sanitizeFileName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9._-]+/g, '-')
+}
+
+function toRelativePath(projectRoot: string, absolutePath: string): string {
+  return path.relative(projectRoot, absolutePath) || '.'
+}
+
+function getMetaFilePath(projectRoot: string): string {
+  return path.join(projectRoot, '.vibecuting', 'video-resource-meta.generated.ts')
+}
+
+async function readGeneratedVideoResourceMeta(projectRoot: string): Promise<NonNullable<VideoResourceMetaFile['videoResourceMeta']>> {
+  const metaFilePath = getMetaFilePath(projectRoot)
+  const sourceText = await fs.readFile(metaFilePath, 'utf8')
+  const sourceFile = ts.createSourceFile(metaFilePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+      continue
+    }
+
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== 'videoResourceMeta') {
+        continue
+      }
+
+      if (!declaration.initializer) {
+        throw new Error(`${metaFilePath}: missing videoResourceMeta initializer`)
+      }
+
+      const videoResourceMeta = evaluateStaticExpression(declaration.initializer, metaFilePath) as VideoResourceMetaFile['videoResourceMeta']
+      if (!videoResourceMeta) {
+        throw new Error(`${metaFilePath}: missing videoResourceMeta export`)
+      }
+
+      return videoResourceMeta
+    }
+  }
+
+  throw new Error(`${metaFilePath}: missing videoResourceMeta export`)
+}
+
+function renderSceneMetadata(record: VideoResourceMetaRecord): string {
+  const { metadata } = record
+  const slots = metadata.slots ? stringifySlots(metadata.slots) : '[]'
+
+  return [
+    `- resourceKind: ${metadata.resourceKind}`,
+    `  aspectRatio: ${metadata.aspectRatio ?? ''}`,
+    `  sceneType: ${metadata.sceneType ?? ''}`,
+    `  sceneFamily: ${metadata.sceneFamily ?? ''}`,
+    `  themePreset: ${metadata.themePreset ?? ''}`,
+    `  rootLayout: ${metadata.rootLayout ?? ''}`,
+    `  propsTypeName: ${metadata.propsTypeName ?? ''}`,
+    `  slots:`,
+    slots,
+  ].join('\n')
+}
+
+function renderTransitionMetadata(record: VideoResourceMetaRecord): string {
+  const { metadata } = record
+
+  return [
+    `- resourceKind: ${metadata.resourceKind}`,
+    `  transitionKind: ${metadata.transitionKind ?? ''}`,
+  ].join('\n')
+}
+
+function renderThemeMetadata(record: VideoResourceMetaRecord): string {
+  const { metadata } = record
+  const supportedSceneFamilies = metadata.supportedSceneFamilies ?? []
+  const cssVariables = metadata.cssVariables ?? []
+
+  return [
+    `- resourceKind: ${metadata.resourceKind}`,
+    `  supportedSceneFamilies:`,
+    supportedSceneFamilies.length > 0 ? stringifyFrontmatterList(supportedSceneFamilies) : '  []',
+    `  cssVariables:`,
+    cssVariables.length > 0 ? stringifyFrontmatterList(cssVariables) : '  []',
+  ].join('\n')
+}
+
+function buildDocContents(record: VideoResourceMetaRecord): string {
+  const { metadata, exportName } = record
+  const tags = metadata.tags ?? []
+  const bodyMetadata =
+    metadata.resourceKind === 'scene'
+      ? renderSceneMetadata(record)
+      : metadata.resourceKind === 'transition'
+        ? renderTransitionMetadata(record)
+        : renderThemeMetadata(record)
+
+  return [
+    '---',
+    `name: ${metadata.name}`,
+    `resourceKind: ${metadata.resourceKind}`,
+    `description: ${metadata.description}`,
+    `sourceFile: ${metadata.sourceFile}`,
+    `pluginKey: ${metadata.pluginKey}`,
+    `tags:`,
+    tags.length > 0 ? stringifyFrontmatterList(tags) : '  []',
+    '---',
+    '',
+    `# ${exportName}`,
+    '',
+    metadata.description,
+    '',
+    '## 元数据',
+    '',
+    `- 资源类型: \`${metadata.resourceKind}\``,
+    `- 源文件: \`${metadata.sourceFile}\``,
+    `- 插件键: \`${metadata.pluginKey}\``,
+    `- 标签: ${tags.length > 0 ? tags.map((tag) => `\`${tag}\``).join(', ') : '[]'}`,
+    '',
+    bodyMetadata,
+    '',
+  ].join('\n')
+}
+
+async function writeTextFile(filePath: string, contents: string): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  const tempPath = `${filePath}.tmp`
+  await fs.writeFile(tempPath, `${contents}\n`, 'utf8')
+  await fs.rename(tempPath, filePath)
+}
+
+async function readOptionalFile(filePath: string): Promise<string | undefined> {
+  try {
+    return await fs.readFile(filePath, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined
+    }
+
+    throw error
+  }
+}
+
+export async function updateComponentSkills(
+  projectRoot: string,
+  checkOnly = false,
+): Promise<void> {
+  const videoResourceMeta = await readGeneratedVideoResourceMeta(projectRoot)
+  const docsDir = resolveComponentProjectGeneratedDocsDir(projectRoot)
+  const manifestPath = resolveComponentProjectGeneratedManifestPath(projectRoot)
+  const resources = [...videoResourceMeta.resources].sort((left, right) => {
+    return (
+      left.metadata.resourceKind.localeCompare(right.metadata.resourceKind) ||
+      left.metadata.pluginKey.localeCompare(right.metadata.pluginKey) ||
+      left.exportName.localeCompare(right.exportName)
+    )
+  })
+
+  const generatedDocs: GeneratedSkillDoc[] = resources.map((record) => {
+    const filePath = path.join(docsDir, `${sanitizeFileName(record.exportName)}.md`)
+    return { filePath, contents: buildDocContents(record) }
+  })
+
+  const manifestContents = JSON.stringify(
+    {
+      projectRoot: '.',
+      docsDir: toRelativePath(projectRoot, docsDir),
+      sourceMetaFile: toRelativePath(projectRoot, getMetaFilePath(projectRoot)),
+      packageFingerprint: videoResourceMeta.packageFingerprint ?? null,
+      files: generatedDocs.map((doc) => toRelativePath(projectRoot, doc.filePath)),
+      resources: resources.map((resource) => ({
+        packageName: resource.packageName,
+        exportName: resource.exportName,
+        resourceKind: resource.metadata.resourceKind,
+        pluginKey: resource.metadata.pluginKey,
+      })),
+    },
+    null,
+    2,
+  )
+
+  if (checkOnly) {
+    const currentManifest = await readOptionalFile(manifestPath)
+    if (currentManifest?.trimEnd() !== `${manifestContents}\n`.trimEnd()) {
+      throw new Error('Generated component skill manifest is stale. Run pnpm run update-component-skills')
+    }
+
+    for (const doc of generatedDocs) {
+      const currentDoc = await readOptionalFile(doc.filePath)
+      if (currentDoc?.trimEnd() !== doc.contents.trimEnd()) {
+        throw new Error(`Generated component skill doc is stale: ${doc.filePath}`)
+      }
+    }
+
+    return
+  }
+
+  await writeTextFile(manifestPath, manifestContents)
+  await fs.mkdir(docsDir, { recursive: true })
+
+  const desiredFiles = new Set(generatedDocs.map((doc) => doc.filePath))
+
+  await Promise.all(
+    generatedDocs.map((doc) => writeTextFile(doc.filePath, doc.contents)),
+  )
+
+  const existingEntries = await fs.readdir(docsDir, { withFileTypes: true })
+  await Promise.all(
+    existingEntries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+      .map(async (entry) => {
+        const filePath = path.join(docsDir, entry.name)
+        if (desiredFiles.has(filePath)) {
+          return
+        }
+
+        await fs.unlink(filePath)
+      }),
+  )
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const checkOnly = process.argv.includes('--check')
+  const cwd = process.cwd()
+
+  updateComponentSkills(cwd, checkOnly).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(message)
+    process.exitCode = 1
+  })
+}